# create_access_list

Builds an EIP-2930 access list for a transaction request. Each result row identifies an accessed account or storage slot and includes request status.

Canonical HTML: <https://determica.com/docs/functions/create_access_list>

- Kind: table function
- Category: [Chain reads](/docs/category/chain-reads.md)
- Tags: EVM, RPC, Access List, Prefetch

Builds an EIP-2930 access list for a transaction request. Each result row identifies an accessed account or storage slot and includes request status.

## Overload 1: create_access_list(CLIENT, ADDRESS, BYTES, BIGINT)

```sql
create_access_list(CLIENT, ADDRESS, BYTES, BIGINT)
```

Builds one access list from the required transaction fields at an exact block height.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Relation
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain and block used for the access-list request.
- `to_address` (ADDRESS; required; positional) — Contract or account that receives the simulated transaction.
- `data` (BYTES; required; positional) — Transaction input bytes, usually produced by encode_function_data.
- `block_number` (BIGINT; required; positional) — Exact block height used to discover accessed accounts and storage slots.

### Relation input

One eth_createAccessList request per row. Optional columns may be omitted only from the trailing end.

### Relation columns

- `client` (CLIENT) — Attached live client for eth_createAccessList. Required
- `to_address` (ADDRESS) — Transaction target address. Required
- `data` (BYTES) — Transaction call data. Required
- `block_number` (BIGINT) — Block number for deterministic access-list discovery. Required
- `source_id` (VARCHAR) — Stable caller-provided identifier for emitted rows. Optional
- `from_address` (ADDRESS) — Optional transaction sender. Optional
- `value` (UINT256) — Optional transaction value. Optional
- `gas` (UBIGINT) — Optional gas limit. Optional
- `block_hash` (BYTES32) — Optional canonical block hash guard. Optional
- `options` (JSON; default: {}) — Per-row on_error/canonical/rpc_batch_size options. Optional. Default: {}

```sql
SELECT client, to_address, data, block_number, source_id, from_address, value, gas, block_hash, options FROM requests
```

### Result columns

Access-list state rows plus RPC status

Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

- `source_kind` (VARCHAR) — Output row class: access_list_code, access_list_storage, or rpc_error.
- `source_id` (VARCHAR) — Stable caller-provided source id, or a generated row id when omitted.
- `state_kind` (VARCHAR) — State kind emitted for prefetch planning.
- `address` (ADDRESS) — Account or contract address from the access list.
- `slot` (BYTES32) — Storage slot for storage-key rows, or zero for code/account rows.
- `bytecode` (BYTES) — Reserved bytecode payload column for planner compatibility.
- `payload` (JSON) — Structured row payload for downstream planning.
- `input_row_index` (UBIGINT) — Zero-based input request row index.
- `rpc_status` (VARCHAR) — RPC status for the input row.
- `rpc_error` (VARCHAR) — RPC error message when on_error emits an error row.
- `gas_used` (UBIGINT) — Gas used reported by eth_createAccessList when available.
- `canonical` (BOOLEAN) — Whether the block hash guard accepted the response as canonical.
- `block_parameter_kind` (VARCHAR) — Block parameter kind used for the request.
- `access_list_address_count` (UBIGINT) — Number of account addresses in the returned access list.
- `access_list_storage_key_count` (UBIGINT) — Number of storage keys in the returned access list.

Access-list state rows plus RPC status. Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

## Overload 2: create_access_list(CLIENT, ADDRESS, BYTES, BIGINT, JSON)

```sql
create_access_list(CLIENT, ADDRESS, BYTES, BIGINT, JSON)
```

Builds one access list and applies the supplied error, canonicality, fallback, and batching options.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Relation
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain and block used for the access-list request.
- `to_address` (ADDRESS; required; positional) — Contract or account that receives the simulated transaction.
- `data` (BYTES; required; positional) — Transaction input bytes, usually produced by encode_function_data.
- `block_number` (BIGINT; required; positional) — Exact block height used to discover accessed accounts and storage slots.
- `options` (JSON; required; positional) — Caller-provided identifier copied to every result row for this request.

### Relation input

One eth_createAccessList request per row. Optional columns may be omitted only from the trailing end.

### Relation columns

- `client` (CLIENT) — Attached live client for eth_createAccessList. Required
- `to_address` (ADDRESS) — Transaction target address. Required
- `data` (BYTES) — Transaction call data. Required
- `block_number` (BIGINT) — Block number for deterministic access-list discovery. Required
- `source_id` (VARCHAR) — Stable caller-provided identifier for emitted rows. Optional
- `from_address` (ADDRESS) — Optional transaction sender. Optional
- `value` (UINT256) — Optional transaction value. Optional
- `gas` (UBIGINT) — Optional gas limit. Optional
- `block_hash` (BYTES32) — Optional canonical block hash guard. Optional
- `options` (JSON; default: {}) — Per-row on_error/canonical/rpc_batch_size options. Optional. Default: {}

```sql
SELECT client, to_address, data, block_number, source_id, from_address, value, gas, block_hash, options FROM requests
```

### Result columns

Access-list state rows plus RPC status

Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

- `source_kind` (VARCHAR) — Output row class: access_list_code, access_list_storage, or rpc_error.
- `source_id` (VARCHAR) — Stable caller-provided source id, or a generated row id when omitted.
- `state_kind` (VARCHAR) — State kind emitted for prefetch planning.
- `address` (ADDRESS) — Account or contract address from the access list.
- `slot` (BYTES32) — Storage slot for storage-key rows, or zero for code/account rows.
- `bytecode` (BYTES) — Reserved bytecode payload column for planner compatibility.
- `payload` (JSON) — Structured row payload for downstream planning.
- `input_row_index` (UBIGINT) — Zero-based input request row index.
- `rpc_status` (VARCHAR) — RPC status for the input row.
- `rpc_error` (VARCHAR) — RPC error message when on_error emits an error row.
- `gas_used` (UBIGINT) — Gas used reported by eth_createAccessList when available.
- `canonical` (BOOLEAN) — Whether the block hash guard accepted the response as canonical.
- `block_parameter_kind` (VARCHAR) — Block parameter kind used for the request.
- `access_list_address_count` (UBIGINT) — Number of account addresses in the returned access list.
- `access_list_storage_key_count` (UBIGINT) — Number of storage keys in the returned access list.

Access-list state rows plus RPC status. Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

## Overload 3: create_access_list(CLIENT, ADDRESS, BYTES, BIGINT, VARCHAR, ADDRESS, UINT256, UBIGINT, BYTES32, JSON)

```sql
create_access_list(CLIENT, ADDRESS, BYTES, BIGINT, VARCHAR, ADDRESS, UINT256, UBIGINT, BYTES32, JSON)
```

Accepts a relation with full transaction context and returns correlated access-list rows for every request.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Relation
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT for the chain and block used for the access-list request.
- `to_address` (ADDRESS; required; positional) — Contract or account that receives the simulated transaction.
- `data` (BYTES; required; positional) — Transaction input bytes, usually produced by encode_function_data.
- `block_number` (BIGINT; required; positional) — Exact block height used to discover accessed accounts and storage slots.
- `source_id` (VARCHAR; required; positional) — Caller-provided identifier copied to every result row for this request.
- `from_address` (ADDRESS; required; positional) — Optional transaction sender used during access-list discovery.
- `value` (UINT256; required; positional) — Optional native-token value in Wei.
- `gas` (UBIGINT; required; positional) — Optional transaction gas limit.
- `block_hash` (BYTES32; required; positional) — Optional block hash used as a canonicality guard.
- `options` (JSON; required; positional) — JSON object controlling errors, canonicality checks, fallback, and RPC batching.

### Relation input

One eth_createAccessList request per row. Optional columns may be omitted only from the trailing end.

### Relation columns

- `client` (CLIENT) — Attached live client for eth_createAccessList. Required
- `to_address` (ADDRESS) — Transaction target address. Required
- `data` (BYTES) — Transaction call data. Required
- `block_number` (BIGINT) — Block number for deterministic access-list discovery. Required
- `source_id` (VARCHAR) — Stable caller-provided identifier for emitted rows. Optional
- `from_address` (ADDRESS) — Optional transaction sender. Optional
- `value` (UINT256) — Optional transaction value. Optional
- `gas` (UBIGINT) — Optional gas limit. Optional
- `block_hash` (BYTES32) — Optional canonical block hash guard. Optional
- `options` (JSON; default: {}) — Per-row on_error/canonical/rpc_batch_size options. Optional. Default: {}

```sql
SELECT client, to_address, data, block_number, source_id, from_address, value, gas, block_hash, options FROM requests
```

### Result columns

Access-list state rows plus RPC status

Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

- `source_kind` (VARCHAR) — Output row class: access_list_code, access_list_storage, or rpc_error.
- `source_id` (VARCHAR) — Stable caller-provided source id, or a generated row id when omitted.
- `state_kind` (VARCHAR) — State kind emitted for prefetch planning.
- `address` (ADDRESS) — Account or contract address from the access list.
- `slot` (BYTES32) — Storage slot for storage-key rows, or zero for code/account rows.
- `bytecode` (BYTES) — Reserved bytecode payload column for planner compatibility.
- `payload` (JSON) — Structured row payload for downstream planning.
- `input_row_index` (UBIGINT) — Zero-based input request row index.
- `rpc_status` (VARCHAR) — RPC status for the input row.
- `rpc_error` (VARCHAR) — RPC error message when on_error emits an error row.
- `gas_used` (UBIGINT) — Gas used reported by eth_createAccessList when available.
- `canonical` (BOOLEAN) — Whether the block hash guard accepted the response as canonical.
- `block_parameter_kind` (VARCHAR) — Block parameter kind used for the request.
- `access_list_address_count` (UBIGINT) — Number of account addresses in the returned access list.
- `access_list_storage_key_count` (UBIGINT) — Number of storage keys in the returned access list.

Access-list state rows plus RPC status. Returns one row per discovered account or storage key. With on_error set to row, failed requests emit an rpc_error row instead of failing the query.

## Guidance

### Choose error and canonicality behavior

The options JSON accepts on_error, require_canonical, retry_by_block_number_on_blockhash_error, and rpc_batch_size.

- on_error="throw" fails the query; on_error="row" emits an rpc_error row.
- require_canonical defaults to true when block_hash is supplied.
- retry_by_block_number_on_blockhash_error defaults to true and retries with the corresponding block number.
- rpc_batch_size limits requests grouped into one provider batch.

```sql
SELECT '{"on_error":"row","require_canonical":true,"retry_by_block_number_on_blockhash_error":true,"rpc_batch_size":100}'::JSON AS options;
```

## Additional examples

```sql
WITH requests AS (
  WITH erc20_abi AS (
    SELECT '[{"type":"function","name":"balanceOf","inputs":[{"name":"account","type":"address"}],"outputs":[{"name":"balance","type":"uint256"}]}]'::JSON AS abi
  )
  SELECT
    $client AS client,
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'::ADDRESS AS to_address,
    encode_function_data(
      abi,
      'balanceOf',
      '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS
    ) AS data,
    25433824::BIGINT AS block_number,
    'usdc-balance'::VARCHAR AS source_id,
    '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS AS from_address,
    0::UINT256 AS value,
    NULL::UBIGINT AS gas,
    NULL::BYTES32 AS block_hash,
    '{"on_error":"row"}'::JSON AS options
  FROM erc20_abi
),
access_rows AS (
  SELECT source_id, source_kind, state_kind, address, slot, rpc_status
  FROM create_access_list((SELECT * FROM requests))
)
SELECT source_id, source_kind, state_kind, address, slot, rpc_status
FROM access_rows
WHERE rpc_status = 'ok' AND state_kind IN ('code', 'storage')
ORDER BY state_kind, address, slot;
```