leafage-py

Leafage 按指定链和区块读取链上状态。以下示例在 Chaintable Notebook 中运行，Function 中同样可用；Function 中的使用方式见数据访问。源码提供完整实现。

创建区块上下文

from leafage import EVM

block = EVM('eth').get_block_by_height(25939934)
evm = EVM('eth', block['id'])

`EVM(chain_id, block_id='latest')`

参数	类型	说明
`chain_id`	`str`	链 ID，例如以太坊主网为 `eth`
`block_id`	`str`	要读取状态的区块 ID；默认 `'latest'`，即最新区块

账户状态和合约调用都在该区块上读取。需要一致的多次读取时，先确定区块 ID，再复用同一个对象。

区块查询

接口	参数	返回值
`evm.get_latest_block()`	无	最新区块字典
`evm.get_block_by_height(block_height)`	整数高度	对应区块字典
`evm.get_block_by_id(block_id)`	区块 ID	对应区块字典
`evm.block_exists()`	无	对象指定的区块是否有效，`bool`

区块字典包含 id、height、timestamp 等字段；timestamp 为 Unix 秒数。不同链可能包含不同的附加字段。查询其他区块不会改变对象自身的区块。

账户状态

wallet = '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
balance_wei = evm.get_balance(wallet)
print(balance_wei)

接口	参数	返回值
`evm.get_balance(addr)`	地址	`int`，原生代币余额，ETH 为 wei
`evm.get_nonce(addr)`	地址	`int`，该区块时的 nonce 值
`evm.get_code(addr)`	地址	`0x` 开头的字节码字符串；无代码时为 `'0x'`
`evm.get_storage(addr, slot=0)`	地址、存储槽；槽位可写整数或 `0x` 开头的十六进制字符串	`0x` 开头的 32 字节存储值

合约调用

`evm.call(contract, method, args=None, *, from_addr=None)`

参数	说明
`contract`	合约地址
`method`	含输入和输出类型的签名，如 `balanceOf(address)(uint256)`
`args`	位置参数列表；无参数时可省略
`from_addr`	可选的调用者地址，用于模拟调用上下文；默认零地址

单个输出值直接返回，多个输出值返回元组，无输出返回 ()；整数为 Python int。调用失败时抛出异常。

pool = '0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc'
reserve_usdc, reserve_weth, timestamp = evm.call(
    pool, 'getReserves()(uint112,uint112,uint32)'
)

这是读取或模拟合约调用，不会向链上发送交易。

批量合约调用

from leafage import Call

usdc = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
symbol, decimals = evm.call_many([
    Call(usdc, 'symbol()(string)'),
    Call(usdc, 'decimals()(uint8)'),
])
print(symbol, decimals)

输出为 USDC 6。

`Call(contract, method, args=None, *, from_addr=None)`

描述一次调用，参数与 evm.call() 相同。构造时在本地校验地址、签名和参数，不合法时抛出 ContractCallInvalidInputError，不发请求。同一个 Call 可以交给不同的 EVM 对象执行。

`evm.call_many(calls, *, raise_on_error=True)`

按输入顺序返回结果列表，每项的形式与 evm.call() 相同；空列表直接返回 []。默认任一调用执行或解码失败就抛出异常，异常带 call_index 指出是第几个调用。传入 raise_on_error=False 时，失败的调用在对应位置返回 None，其他结果不变；参数错误、区块不存在和服务错误仍会抛出。

状态覆盖

set_block_overrides(value) 和 set_state_overrides(value) 设置模拟调用的区块和账户状态覆盖；对应的 get_*_overrides() 返回当前设置。覆盖只影响合约调用，不影响余额、nonce、代码和存储查询，也不修改链上状态。字段规范与完整示例见 Leafage 源码。

概览

快速开始

使用指南

参考