bag.watch home

Documentation

Loading

read_contract

Scalar function

Invokes eth_call with ABI-aware argument encoding. Returns a single value if the ABI function has one output, or a STRUCT with named fields if multiple outputs.

Overloads

read_contract(TRANSPORT, ADDRESS, JSON, VARCHAR, ABI-dependent argument(s))

Calls contract function and returns typed result (single value or STRUCT based on ABI outputs). ABI must be constant.

Parameters

Name Type
transport TRANSPORT
to ADDRESS
abi JSON
function_name VARCHAR
... ABI-dependent argument(s)

Returns

Name Type
result ANY
1
-- Read WETH balance (returns typed result: UBIGINT for uint256)
2
SELECT read_contract(
3
$transport,
4
'0x4200000000000000000000000000000000000006'::ADDRESS,
5
'[
6
{
7
"type": "function",
8
"name": "balanceOf",
9
"stateMutability": "view",
10
"inputs": [{ "name": "account", "type": "address" }],
11
"outputs": [{ "name": "", "type": "uint256" }]
12
}
13
]'::JSON,
14
'balanceOf',
15
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS -- function arguments
16
) AS balance;
17
 
18
-- -- Alternative: Function with multiple outputs returns STRUCT
19
-- SELECT read_contract(
20
-- $transport,
21
-- '0xContractAddress'::ADDRESS,
22
-- '[{"type":"function","name":"getInfo","outputs":[{"type":"uint256"},{"type":"address"}]}]'::JSON,
23
-- 'getInfo'
24
-- ) AS info_struct; -- Returns STRUCT(output0: UBIGINT, output1: ADDRESS)
Notebook ready in readonly mode.

read_contract(TRANSPORT, ADDRESS, JSON, VARCHAR, JSON, VARCHAR, ABI-dependent argument(s))

Adds block_tag/block_number override (via options parameter) and explicit return type specification (via return_schema parameter). DYNAMIC ABI SUPPORT: When return_schema is provided, the ABI parameter can be non-constant (column reference from CTEs, subqueries, joins, etc.), allowing different ABIs per row. This is required because DuckDB needs return types at query planning time, and non-constant ABIs cannot be inspected during planning. The return_schema parameter explicitly specifies output types: 'raw' for BLOB, 'uint256' for UINT256, or 'uint256,address' for STRUCT with comma-separated field types. The options parameter can be NULL or '{}'::JSON if block pinning is not needed.

Parameters

Name Type
transport TRANSPORT
to ADDRESS
abi JSON
function_name VARCHAR
options JSON
return_schema VARCHAR
... ABI-dependent argument(s)

Returns

Name Type
result ANY
1
-- Dynamic ABI from CTE with explicit return_schema
2
WITH abis AS (
3
SELECT '[
4
{
5
"type": "function",
6
"name": "balanceOf",
7
"stateMutability": "view",
8
"inputs": [{ "name": "account", "type": "address" }],
9
"outputs": [{ "name": "", "type": "uint256" }]
10
}
11
]'::JSON AS abi
12
)
13
SELECT read_contract(
14
$transport,
15
'0x4200000000000000000000000000000000000006'::ADDRESS,
16
abi, -- abi is a column reference (non-constant)
17
'balanceOf',
18
'{}'::JSON, -- options (use NULL or {} if not needed)
19
'uint256', -- return_schema: 'raw' | 'uint256' | 'uint256,address'
20
'0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'::ADDRESS -- function arguments
21
) AS balance FROM abis; -- Returns: UINT256 (exact type you specify)
Notebook ready in readonly mode.