进阶功能

需要自行控制触发时机、任务输入或结果处理时，可以在 Notebook 中组合 BlockDB 和 BlockX。

订阅区块事件

Subscribe 接收表 ID 列表，listen() 持续返回已就绪区块的事件对象。下面订阅以太坊事件表，收到一个新区块后退出；30 秒内没有事件也会结束，适合先验证连接。

from threading import Timer
from blockdb import Subscribe

sub = Subscribe(tables=['chain.event.eth'])
timer = Timer(30, sub.close)
timer.start()
try:
    for event in sub.listen():
        print(event.block_id, event.block_height, event.block_timestamp)
        break
finally:
    sub.close()
    timer.cancel()

事件提供 block_id、block_height 和 block_timestamp，分别表示区块 ID、高度和时间。订阅用于持续消费新事件，不能替代完整的历史回填。需要长期监听时，移除示例中的计时器和 break，再按创建持续运行调度完成配置。

自定义任务输入和结果

先按创建 Function创建并保存 demo.usdc_amount。在 Notebook 中提交两组位置参数：

from blockx import DirectCallConfig, ReturnValueHandler, TaskBuilder

config = DirectCallConfig(
    func_id='demo.usdc_amount',
    args_list=[[1500000], [2000000]],
)
result = TaskBuilder.build(config, ReturnValueHandler()).submit(timeout=30)

if not result.task_result.success:
    raise RuntimeError(result.error)
print(sorted(result.handler_result))

输出为 [1.5, 2.0]。args_list 的每个子列表对应一次函数调用；ReturnValueHandler 收集返回值，不写入数据表。结果顺序不保证与输入一致；需要关联输入时，让函数在返回值中携带业务 ID。要把结果交给数据表，选择对应的结果处理器：

处理器	用途
`ReturnValueHandler()`	把计算结果返回给 Notebook
`NormalTableWriteHandler(target=...)`	写入普通表
`TimeTableWriteHandler(target=...)`	写入含 `id`、`time_at`、`value` 的时间点
`BlockTableWriteHandler(target=...)`	配合区块或区块包任务，将结果写入相应区块表

读取运行变量

切换到 Notebook 所属账户，在账户菜单打开 Variables。
点击 New Variable，输入名称 DOCS_NETWORK 和值 eth。
点击 Add variable，然后在 Notebook 中读取：

from chaintable import variables

network = variables.get('DOCS_NETWORK', 'eth')
print(network)

变量属于账户，由运行环境确定可访问的账户。名称不存在时返回第二个参数指定的默认值；省略默认值时返回 None。涉及密钥的变量不要打印到日志中。

概览

快速开始

使用指南

参考

订阅区块事件

自定义任务输入和结果

读取运行变量