Ethereum, as a leading blockchain platform, relies on a set of remote procedure call (RPC) methods for developers to interact with the network. These methods, following the JSON-RPC specification, allow applications to read blockchain data, execute transactions, and manage network operations programmatically. Understanding these methods is fundamental for building decentralized applications (dApps), wallets, and other blockchain tools.
This guide provides a detailed reference for core Ethereum JSON-RPC methods, explaining their purposes, common use cases, and how they facilitate seamless communication with the Ethereum network.
Core Ethereum JSON-RPC Methods
Blockchain Data Retrieval Methods
These methods are used to fetch information about the state of the blockchain, including blocks, transactions, and account details.
eth_blockNumber
Returns the number of the most recently mined block. This is essential for checking the current state of the blockchain and ensuring your application is synced.
eth_getBalance
Returns the balance of a given Ethereum address, specified in wei. This method is crucial for wallets and exchanges to display user funds.
eth_getBlockByHash & eth_getBlockByNumber
These methods return information about a specific block. You can query a block using its unique hash or its block number. The returned data includes details like timestamps, transaction lists, and difficulty.
eth_getTransactionByHash
Fetches the detailed information of a transaction when provided with its transaction hash. This is used to track and verify transaction details.
eth_getTransactionReceipt
Returns the receipt of a transaction by its hash. The receipt contains crucial execution details, such as gas used, status (success/failure), and any logs generated—particularly important for smart contract interactions.
Account and State Methods
These methods interact with account information and the state of smart contracts at specific addresses.
eth_getCode
Returns the compiled smart contract code stored at a given address. If the address is a contract, it returns the bytecode; for externally owned accounts, it returns "0x".
eth_getStorageAt
Returns the value from a specific storage position at a given Ethereum address. This is a low-level method primarily used for debugging smart contracts.
eth_getTransactionCount
Returns the number of transactions sent from a specific address, also known as the nonce. This value is critical for creating new transactions to prevent replay attacks.
Gas and Fee Estimation Methods
Accurately estimating transaction costs is vital for a good user experience. These methods help calculate required fees.
eth_gasPrice
Returns the current average gas price in wei. This provides an estimate of the cost required to get a transaction included in a block in a timely manner.
eth_estimateGas
Generates an estimate of the gas required to execute a transaction. This helps prevent transactions from failing due to out-of-gas errors and allows for more accurate fee calculations.
eth_feeHistory
Returns a range of historical gas information for previous blocks. This data can be analyzed to understand network congestion trends and make informed fee predictions.
eth_maxPriorityFeePerGas
Returns the current suggested maximum priority fee per gas (in wei) for transactions using the EIP-1559 fee market. This tip incentivizes miners to prioritize a transaction.
Filter and Event Log Methods
Ethereum allows applications to listen for specific on-chain events. These methods are used to create and manage filters for logging and subscription purposes.
eth_newFilter
Creates a filter object based on specified filter options, such as address or topics, to notify when matching state changes (logs) occur.
eth_getFilterChanges & eth_getFilterLogs
These are polling methods for filters. eth_getFilterChanges returns an array of logs that occurred since the last poll, while eth_getFilterLogs returns all logs matching the filter.
eth_getLogs
Returns an array of all logs matching a provided filter object. This is useful for querying historical event data without setting up a persistent filter.
Transaction Methods
These methods are used to send transactions and query their status.
eth_sendRawTransaction
Broadcasts a signed, raw transaction to the network for execution. This is the primary method for submitting transactions you have signed offline.
eth_call
Executes a new message call immediately without creating a transaction on the blockchain. It is used to read data from smart contracts without spending gas.
Network and Chain Methods
Methods that provide information about the network itself.
eth_chainId
Returns the current chain ID, used to identify the specific Ethereum network (e.g., 1 for Mainnet, 5 for Goerli) and prevent replay attacks across chains.
eth_syncing
Returns data on the synchronization status of the node. If the node is syncing, it provides progress details; if synced, it returns false.
Uncle Block Methods
Ethereum's previous Proof-of-Work consensus mechanism included uncle blocks. These methods retrieve information about them.
eth_getUncleCountByBlockHash & eth_getUncleCountByBlockNumber
Return the number of uncle blocks in a specified block.
eth_getUncleByBlockHashAndIndex & eth_getUncleByBlockNumberAndIndex
Return information about a specific uncle block using the block identifier and the uncle's index position.
WebSocket Subscription Methods
For real-time updates, WebSocket connections can be used instead of HTTP polling.
eth_subscribe
Creates a subscription for specific real-time blockchain events through a WebSocket connection, such as listening for new heads (blocks) or pending transactions.
eth_unsubscribe
Cancels an existing subscription created via eth_subscribe.
Filter Management Methods
Methods to manage the lifecycle of filters created for monitoring events.
eth_newBlockFilter
Creates a filter in the node to notify when a new block is mined.
eth_newPendingTransactionFilter
Creates a filter to notify when a new pending transaction is submitted to the network.
eth_uninstallFilter
Uninstalls a filter with the given ID. It should be called to clean up filters that are no longer needed to free up node resources.
Practical Applications and Use Cases
Developers use these JSON-RPC methods in various scenarios. Building a wallet application requires eth_getBalance to show funds and eth_sendRawTransaction to send payments. A decentralized exchange might use eth_call to get token prices from smart contracts and eth_getLogs to track swap events. Blockchain explorers heavily rely on methods like eth_getBlockByNumber and eth_getTransactionByHash to populate their data.
đŸ‘‰ Explore more advanced blockchain interaction strategies
Understanding these methods allows developers to fully leverage the power of the Ethereum network. The key is to choose the right method for the task, whether it's reading data, executing a transaction, or listening for real-time events.
Frequently Asked Questions
What is the primary use of the eth_call method?eth_call is primarily used to execute a message call or query a smart contract function without modifying the blockchain state. It does not consume gas and is ideal for reading data from contracts, such as token balances or configuration settings, without sending a transaction.
How do I estimate the cost of a transaction before sending it?
Use the eth_estimateGas method. It executes the transaction virtually and returns an estimate of the gas units required. You can then multiply this by the current gas price (from eth_gasPrice) to calculate the total transaction fee in wei.
What is the difference between eth_getFilterChanges and eth_getFilterLogs?eth_getFilterChanges is used for polling and only returns the new logs that have been generated since the last time this method was called for that filter ID. In contrast, eth_getFilterLogs returns all the logs that match the filter's criteria from the beginning, regardless of previous polls.
Why is the eth_chainId method important?
The eth_chainId method returns the chain ID of the current network. This is crucial for transaction signing, as it ensures that a transaction signed for one network (e.g., Ethereum Mainnet) cannot be replayed on another network (e.g., a testnet), enhancing security.
When should I use WebSocket subscriptions instead of filters?
WebSocket subscriptions (via eth_subscribe) are preferable for applications requiring real-time, push-based notifications, as they provide immediate updates without the need for continuous HTTP polling. This reduces latency and network overhead for live dashboards or trading bots.
How can I get the receipt for a transaction I sent?
After broadcasting a transaction, use the eth_getTransactionReceipt method with the transaction hash. The receipt contains vital execution information, including the status (success or failure), gas used, and event logs, which is necessary to confirm the outcome of a contract interaction.