Flashblocks Specification

The Flashblocks RPC provider extends standard Ethereum JSON-RPC methods to query preconfirmed flashblock state via the pending tag. The methods, parameters, and return types are specified below.

Type Definitions

All types used in these RPC methods are identical to the standard OP Stack RPC types. No modifications have been made to the existing type definitions.

Modified Ethereum JSON-RPC Methods

The following standard Ethereum JSON-RPC methods are enhanced to support the pending tag for querying preconfirmed state.

`eth_getBlockByNumber`

Returns block information for the specified block number.

Parameters

Name	Type	Description
`blockNumber`	`String`	Block number (hex) or tag. Use `"pending"` for preconfirmed state.
`fullTransactions`	`Boolean`	If `true`, returns full transaction objects; if `false`, returns transaction hashes.

Returns

Object — Block object, or null if the block does not exist.

Example

// Request
{
  "method": "eth_getBlockByNumber",
  "params": ["pending", false],
  "id": 1,
  "jsonrpc": "2.0"
}

// Response
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "parentHash": "0x...",
    "stateRoot": "0x...",
    "transactionsRoot": "0x...",
    "receiptsRoot": "0x...",
    "number": "0x123",
    "gasUsed": "0x5208",
    "gasLimit": "0x1c9c380",
    "timestamp": "0x...",
    "extraData": "0x",
    "mixHash": "0x...",
    "nonce": "0x0",
    "transactions": ["0x..."]
  }
}

Response Fields

Field	Description
`hash`	Block hash calculated from the current flashblock header.
`parentHash`	Hash of the parent block.
`stateRoot`	Current state root from the latest flashblock.
`transactionsRoot`	Transactions trie root.
`receiptsRoot`	Receipts trie root.
`number`	Block number being built.
`gasUsed`	Cumulative gas used by all transactions.
`gasLimit`	Block gas limit.
`timestamp`	Block timestamp.
`extraData`	Extra data bytes.
`mixHash`	Mix hash value.
`nonce`	Block nonce value.
`transactions`	Array of transaction hashes or full transaction objects.

`eth_getTransactionReceipt`

Returns the receipt for a transaction. When the transaction exists only in the preconfirmed (flashblock) state, the receipt is still returned — enabling callers to confirm inclusion before the block is finalized.

Parameters

Name	Type	Description
`transactionHash`	`String`	Hash of the transaction.

Returns

Object — Transaction receipt, or null if the transaction is not found.

Example

// Request
{
  "method": "eth_getTransactionReceipt",
  "params": ["0x..."],
  "id": 1,
  "jsonrpc": "2.0"
}

// Response
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "transactionHash": "0x...",
    "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "blockNumber": "0x123",
    "transactionIndex": "0x0",
    "from": "0x...",
    "to": "0x...",
    "gasUsed": "0x5208",
    "cumulativeGasUsed": "0x5208",
    "effectiveGasPrice": "0x...",
    "status": "0x1",
    "contractAddress": null,
    "logs": [],
    "logsBloom": "0x..."
  }
}

Response Fields

Field	Description
`transactionHash`	Hash of the transaction.
`blockHash`	Zero hash (`0x000...000`) for preconfirmed transactions.
`blockNumber`	Block number containing the transaction.
`transactionIndex`	Index of the transaction in the block.
`from`	Sender address.
`to`	Recipient address.
`gasUsed`	Gas used by this transaction.
`cumulativeGasUsed`	Total gas used up to and including this transaction.
`effectiveGasPrice`	Effective gas price paid.
`status`	`0x1` for success, `0x0` for failure.
`contractAddress`	Address of created contract (for contract creation transactions), otherwise `null`.
`logs`	Array of log objects emitted by the transaction.
`logsBloom`	Bloom filter for the logs.

`eth_getBalance`

Returns the balance of an account.

Parameters

Name	Type	Description
`address`	`String`	Address to query.
`blockNumber`	`String`	Block number (hex) or tag. Use `"pending"` for preconfirmed state.

Returns

String — Account balance in wei, hex-encoded.

Example

// Request
{
  "method": "eth_getBalance",
  "params": ["0x...", "pending"],
  "id": 1,
  "jsonrpc": "2.0"
}

// Response
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x1bc16d674ec80000"
}

`eth_getTransactionCount`

Returns the number of transactions sent from an address (the account nonce).

Parameters

Name	Type	Description
`address`	`String`	Address to query.
`blockNumber`	`String`	Block number (hex) or tag. Use `"pending"` for preconfirmed state.

Returns

String — Transaction count (nonce), hex-encoded.

Example

// Request
{
  "method": "eth_getTransactionCount",
  "params": ["0x...", "pending"],
  "id": 1,
  "jsonrpc": "2.0"
}

// Response
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": "0x5"
}

Behavior Notes

Pending Tag Usage

When "pending" is used as the block tag, the method queries preconfirmed state from the flashblocks cache.
If no preconfirmed data is available, the method falls back to the latest confirmed state.
For non-pending queries (e.g., "latest", "finalized", or a specific block number), the method behaves identically to standard Ethereum JSON-RPC.

Error Handling

Standard JSON-RPC error responses are returned for invalid requests.
null is returned for non-existent transactions or blocks.
When flashblocks are disabled or unavailable, the RPC falls back to standard behavior transparently.

Source

Canonical specification: docs/specs/flashblocks.md