Querying the Outcome

After a transaction is submitted, propagated, included in a block, finalized, and executed locally, users often need to verify the outcome of the transaction. This final step ensures that the transaction was successful and allows users to retrieve relevant data such as gas usage, status, and event logs.


1. Checking Transaction Status

Users can check the outcome of a transaction by querying an RPC node using the transaction hash. This can be done using two primary JSON-RPC methods:

Method

Description

eth_getTransactionByHash

Returns information about a transaction by hash.

eth_getTransactionReceipt

Returns the receipt containing the execution result.

The most common method for checking the final outcome is eth_getTransactionReceipt.


2. Transaction Receipt Structure

A transaction receipt is a data structure containing the execution result of a transaction:

Field

Description

transactionHash

Hash of the transaction.

blockNumber

Block number in which the transaction was included.

status

1 for success, 0 for failure.

from

Address of the sender.

to

Address of the recipient (or contract creation address).

gasUsed

Total gas used by the transaction.

logs

Array of logs generated during execution (events).

contractAddress

Address of the contract created, if applicable.

effectiveGasPrice

Actual gas price paid after execution.


3. Example: Querying a Transaction Outcome

Web3.js Example

const Web3 = require('web3');
const web3 = new Web3('https://rpc-private-testnet.celestium.network');

async function getTransactionReceipt(txHash) {
  const receipt = await web3.eth.getTransactionReceipt(txHash);

  if (receipt) {
    console.log('Transaction Receipt:', receipt);
    if (receipt.status) {
      console.log('Transaction Successful!');
    } else {
      console.log('Transaction Failed!');
    }
  } else {
    console.log('Transaction is pending or not found');
  }
}

getTransactionReceipt('0xYOUR_TRANSACTION_HASH');

cURL Example

curl -X POST https://rpc-private-testnet.celestium.network \
-H "Content-Type: application/json" \
--data '{
  "jsonrpc":"2.0",
  "method":"eth_getTransactionReceipt",
  "params":["0xYOUR_TRANSACTION_HASH"],
  "id":1
}'

4. Interpreting the Results

Scenario

Meaning

Receipt is null

Transaction is pending or not found.

status == 1

Transaction was successful.

status == 0

Transaction failed (e.g., out of gas or revert).

logs contains events

Smart contract emitted events during execution.

contractAddress != null

Contract was successfully deployed.


5. Common Use Cases

  • Verifying Token Transfers: Check logs for Transfer events from ERC-20 contracts.

  • Contract Deployment: Retrieve the contractAddress after a successful deployment.

  • Gas Estimation: Analyze gasUsed and effectiveGasPrice for future transactions.


6. Handling Pending Transactions

If the transaction is still pending, users can also query:

Method

Description

eth_getTransactionByHash

Returns transaction details even if it is still pending.


7. Best Practices

  • Always check status in the receipt before assuming success.

  • Monitor gas usage (gasUsed) to estimate costs more accurately.

  • Handle pending transactions gracefully in applications by implementing retries.


8. Final Notes

Querying transaction outcomes is a critical step in the transaction lifecycle. It provides clarity to users and developers, ensuring that transactions are executed as intended. Celestium’s Ethereum RPC compatibility allows seamless integration with existing Ethereum tools, making this process familiar and efficient for developers.

Last updated