Supported RPC Methods
All modifications done to the existing Ethereum JSON RPC methods are confined to overloading the existing pending tag except a few JSON RPC methods which become inherently aware of the preconfirmation state. Originally, this tag was designed to return block data being processed by the node's internal miner It's fitting that we now use it for a similar purpose: exposing blocks in their preconfirmation stage. When queried with the pending tag, the endpoint uses the preconfirmation state to construct the response. The response might include not only transactions but also block metadata like state root and receipt root.
The tag is currently in a soft-deprecated state due to inconsistent implementations across clients, particularly after The Merge. However, it's worth noting that it's still actively used for certain endpoints, particularly eth_getTransactionCount where it serves the important function of returning the next available nonce for an account (including transactions in the memepool). This presents an opportunity: the tag is well-defined enough to be supported by client libraries, yet loosely defined enough to allow for our preconfirmation use case. While there's a possibility of the tag being removed in the future (see EIP discussions), the design could adapt by introducing a realtime block specific tag if needed.
We repurpose the pending tag in the following RPC calls to enable consuming preconfirmed state:
eth_call
eth_estimateGas
eth_getBlockByNumber
eth_getBalance
eth_getTransactionCount
eth_subscribe
Note: not all RPC methods explicitly require a "pending" tag to tap into the real time state's awareness.
The following RPC methods implicitly incorporate realtime block awareness like that whenever possible:
eth_getTransactionReceipt
eth_getTransactionByHash
eth_getTransactionReceipt
{
"method": "eth_getTransactionReceipt",
"params": ["0x..."],// Transaction hash
"id": 1,
"jsonrpc": "2.0"
}
{
"transactionHash": "0x...",
"blockHash": "0x0", // Empty hash as placeholder
"blockNumber": "0x...", // Current pending block number
"transactionIndex": "0x0",
"from": "0x...",
"to": "0x...",
"gasUsed": "0x...",
"status": "0x1",
"cumulativeGasUsed": "0x...",
"effectiveGasPrice": "0x...",
"contractAddress": "0x...", // For contract creations
"logs": [],
"logsBloom": "0x..."
}
When queried, this endpoint first checks the preconfirmation state for the requested transaction hash before falling back to the standard chain lookup. Some fields in the response cannot be final at the preconfirmation stage and require placeholder values:
blockHash: Uses empty hash as placeholder
blockNumber: Can be set to the current block number being processed
eth_getTransactionsByHash
When queried, this endpoint first checks the preconfirmation state for the requested transaction hash before falling back to the standard chain state lookup. Some fields in the response cannot be final at the preconfirmation stage and require placeholder values:
blockHash: Uses the block hash of the pending blocks at the time the transaction was preconfirmed
blockNumber: Can be set to the curent block number being processed
eth_getBlockByNumber
The endpoing implements an append-only pattern - multiple queries during the sam eblock's preconfirmation phase will show an expanding list of transactions as new realtime blocks are processed. Each query reflects the current state of all preconfirmed transactions at that moment.
eth_getBalance
When queried with the pending tag, the endpoint uses the preconfirmation state to return the account balance. If the requested account appears in the AccountMetadata of a received realtime block with a non-null balance field, the RPC provider can directly return this value without needing toa ccess the full state. The response reflects all changes from preconfirmed trnasactions that affect the requested account's balance.
eth_call
When queried with the pending tag, the endpoint uses the preconfirmation state to return the call result. For this endpoint to work, the preconfirmation stream needs to include state differences for both accounts and storage after each realtime block.
Similar to current override functionality in eth_call where EVM transitions are executed on top of modified state, this implementation executes the call on top of the preconfirmation state changes.
eth_estimateGas
Generates and returns an estimate of how much gas is necessary to allow the transaction to complete considering the latest pre-confirmed state.
eth_getTransactionCount
When queried with the pending tag, the endpoint returns the transaction count (nonce) of the account from the preconfirmation state. If the requested account appears in the AccountMetadata of a received realtime block, the RPC provider can directly use the nonce field without additional state access.
eth_subscribe - newFlashblocks
Subscribe to receive notifications each time a new flashblock is processed.
Description
Fires a notification with the current pending block state whenever a new flashblock arrives. Each flashblock represents an incremental update to the pending block, so multiple notifications may be emitted for the same block height as new flashblocks are processed.
Parameters
0
Subscription type
string
Must be "newFlashblocks"
Returns
A unique identifier for the subscription, returned as a 32-byte hex string.
eth_subscribe - pendingLogs
Subscribe to receive logs from flashblocks pending state that match specified filter criteria.
Description
Returns logs from the current pending flashblock state. Unlike the standard logs subscription which only includes logs from confirmed blocks, this subscription provides logs from preconfirmed transactions in flashblocks, giving users earlier visibility into contract events.
Parameters
0
Subscription type
string
Must be "pendingLogs"
1
Filter
object (optional)
Log filter criteria (same as eth_getLogs)
Filter Object
address
string or string[] (optional)
Contract address or array of addresses to filter
topics
array (optional)
Array of topic filters (32-byte hex strings or arrays for OR logic)
If no filter is provided, all logs from pending flashblocks will be returned.
Returns
A unique identifier for the subscription, returned as a 32-byte hex string.
eth_subscribe - newFlashblockTransactions
Subscribe to receive preconfirmed transasctions
Description
Returns transactions from flashblocks that have been included by the realtime block builder and are effectively preconfirmed.
Parameters
0
Subscription type
string
Must be "newFlashblockTransactions"
1
Full transactions
boolean (optional)
true for full transaction objects, false or omitted for hashes only (default)
Returns
A unique identifier for the subscription, returned as a 32-byte hex string.
Example - Hash Mode (Default)
Example - Full Transaction Mode
eth_unsubscribing
All subscription types can be unsubscribed using the standard eth_unsubscribe method with the subscription ID.
Last updated