---
title: "Flashblocks Specification"
description: "JSON-RPC methods, parameters, and return types exposed by the Flashblocks RPC provider."
source: https://basehub.org/specifications/flashblocks/
---
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.

:::note
This document serves as a reference for the current implementation and may differ from the full Flashblocks specification in terms of scope and methods implemented. The canonical source is [`docs/specs/flashblocks.md`](https://github.com/base/base/blob/main/docs/specs/flashblocks.md) in the base/base repository.
:::

## 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

```json
// 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

```json
// 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

```json
// 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

```json
// 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](https://github.com/base/base/blob/main/docs/specs/flashblocks.md)