read_contract_multicall

Executes a table of encoded contract reads through Multicall3 and returns one diagnostic row per input call. Results separately report batch execution and target-call success.

Example

Needs RPC · RPC required

1
-- Decode WETH and USDC decimals from one Multicall3 batch
2
WITH erc20_abi AS (
3
SELECT '[{
4
"type": "function",
5
"name": "decimals",
6
"stateMutability": "view",
7
"inputs": [],
8
"outputs": [{ "name": "decimals", "type": "uint8" }]
9
}]'::JSON AS abi
10
),
11
calls AS (
12
SELECT
13
token.symbol AS source_id,
14
$client AS client,
15
token.address AS to_address,
16
encode_function_data(erc20_abi.abi, 'decimals') AS call_data,
17
'finalized' AS block_tag
18
FROM erc20_abi,
19
(VALUES
20
('weth-decimals', '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'::ADDRESS),
21
('usdc-decimals', '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'::ADDRESS)
22
) AS token(symbol, address)
23
),
24
raw_results AS (
25
SELECT source_id, return_data
26
FROM read_contract_multicall((
27
SELECT source_id, client, to_address, call_data, block_tag
28
FROM calls
29
), max_calls_per_batch := 100)
30
WHERE ok AND call_success AND status = 'ok'
31
)
32
SELECT source_id, decoded.decimals::UTINYINT AS decimals
33
FROM raw_results
34
CROSS JOIN LATERAL call_decode(
35
'[{"type":"function","name":"decimals","inputs":[],"outputs":[{"name":"decimals","type":"uint8"}]}]'::JSON,
36
'decimals',
37
return_data
38
) AS decoded
39
ORDER BY source_id;
Notebook ready in readonly mode.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

read_contract_multicall(TABLE) # RPC required

Accepts a relation of encoded calls and applies named or JSON batching options to the complete input.

Inputs

NameTypeUse
calls_tableTABLE

Relation containing one encoded contract read per row.

requiredpositional
max_calls_per_batchUBIGINT

Maximum number of input calls in one Multicall3 aggregate3 request.

optionalnamed
multicall3_addressADDRESS

Override the default Multicall3 contract address for the selected chain.

optionalnamed
max_calldata_bytesUBIGINT

Maximum encoded aggregate3 calldata size before a batch is split.

optionalnamed
allow_failureBOOLEAN

Default aggregate3 allowFailure value when an input row does not provide allow_failure.

optionalnamed
Showing fewer

Input relation columns

NameType
source_idVARCHAR

Stable caller-provided identifier for the input row. Optional

clientCLIENT

Readable EVM state for the batch. Required

to_addressADDRESS

Contract address to call. Required

call_dataBYTES

ABI-encoded call data. Required

block_numberBIGINT

Optional block number for historical reads. Optional

Showing fewer

Each row describes one raw contract read. source_id is optional but recommended for stable result joins.

Result columns

NameType
source_idVARCHAR

Caller-provided identifier copied from the input row.

input_row_indexUBIGINT

Zero-based position of the call in the input relation.

okBOOLEAN

Whether client resolution and batch execution completed for this input.

call_successBOOLEAN

Whether the target contract call itself succeeded.

return_dataBYTES

Raw return bytes for a successful target call.

Showing fewer

One diagnostic row per input call. Returns raw success or revert bytes, batch diagnostics, the resolved block parameter, and identifiers that correlate each result with its input row.

Guidance

Prepare and decode batched reads

Provide encoded call_data and a CLIENT for every input row. Use source_id to join results back to the source relation.

Decode return_data only after filtering on both ok and call_success. Keep status, error_message, and revert_data when investigating failures.

  • Use read_contract when one ABI-decoded scalar read is sufficient.
  • Use call_decode to turn successful raw return_data into typed columns.
  • Provide block_number, block_tag, or block_parameter to pin the state read.

Understand client execution

Live clients execute Multicall3 against the selected RPC state. Attached pinned clients use a hash-pinned remote batch with a canonicality requirement.

Detached pinned clients and execution clients evaluate each read against their isolated local state.

Control retries and fallback

Batch limits split large inputs before execution. chunk_retry controls retries of failed batches, while fallback controls whether failed batches are retried as individual calls.

By default, batches execute without a code-presence preflight. Set verify_code := true to require deployed code before use; verification does not authenticate the Multicall3 bytecode.

Related functions

Category and tags

Category
Chain reads
Tag
EVM
Tag
RPC
Tag
Live
Tag
Multicall