ETHEREUM_POLLING_INTERVAL,默认 1000 ms)。
常见设置:
- 您在 Virtual Environment 上部署的合约(开发、CI):按照下面的设置操作。
- 带有生产历史的预发布或演示环境:索引父网络上已存在的合约。
- fork 之后的父网络活动:使用 Network Mirror Mode。
- 公共网络上的 subgraph:在 Tenderly Node RPC 上运行 Graph Node。
DemoToken,这是一个会发出 Transfer(address indexed from, address indexed to, uint256 value) 事件的最小 ERC-20 合约,部署在从 Ethereum Mainnet fork 出的 Virtual Environment 上。
开始之前
- Node.js 20.18.1 或更高版本(Graph CLI 的要求)以及 npm
- Docker 及 Docker Compose
- 一个 Virtual Environment 及其 Public RPC URL,该 URL 列在 Virtual Environment Home 选项卡的 Integrate Virtual RPC 卡片中(参见仪表板参考)
- 一个部署在该 Virtual Environment 上的合约(参见部署和验证合约),并准备好:
- 合约地址
- JSON 文件格式的合约 ABI
- 部署交易所在的区块号:
设置 Graph Node 和 subgraph
1
安装 Graph CLI
2
根据合约生成 subgraph 脚手架
graph init 会创建 demo-token 目录,其中包含 subgraph.yaml、schema.graphql、位于 src/demo-token.ts 的事件映射,以及一个运行 Graph Node、IPFS 和 Postgres 的 docker-compose.yml。在 subgraph.yaml 中,将 indexerHints.prune 从 auto 改为 never。Graph Node 需要完整的实体历史,才能回退被回滚的区块。subgraph.yaml
3
将 Graph Node 指向 Virtual Environment
在生成的
docker-compose.yml 中,编辑 graph-node 服务的 environment:- 将
ethereum设置为<network>:<Public RPC URL>。第一个冒号之前的网络名称必须与subgraph.yaml中的network一致。 - 添加
ETHEREUM_REORG_THRESHOLD: "1",使 Graph Node 能够回退被回滚的区块。 - 添加
GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true",使 Graph Node 拒绝来自另一个 Virtual Environment 的 RPC URL,而不是停滞。
docker-compose.yml(graph-node 服务)
ipfs 和 postgres 服务保持生成时的配置即可。Graph Node 只读取链数据,因此请使用 Public RPC,而不是 Admin RPC。4
启动 Graph Node
Starting GraphQL HTTP server at: http://localhost:8000 时,Graph Node 即已就绪。5
创建并部署 subgraph
graph deploy 会构建 subgraph,将其上传到 IPFS,并打印查询 URL:package.json 通过 npm run create-local 和 npm run deploy-local 运行相同的命令。编辑 schema.graphql 或 ABI 后,请再次运行 graph codegen。6
查询 subgraph
检查索引状态
查询端口8030 上的索引状态 API:
latestBlock 是 subgraph 已处理的最后一个区块,chainHeadBlock 是 Virtual Environment 的最新区块。请比较这两个值,而不要依赖 health。在本页列出的所有失败情形中,subgraph 都会持续报告 healthy,而 latestBlock 停止前进。
要查看 Graph Node 发送的请求,请打开 Virtual Environment 的 JSON-RPC Calls 选项卡。将 Status 筛选器设置为 Failed,即可找到 Virtual Environment 拒绝的方法,例如调用处理器发出的 trace_filter。展开某一行可查看请求参数和错误响应。
使用 gnd 代替 Docker 运行 subgraph
gnd(Graph Node Dev)以原生二进制文件的形式运行 Graph Node,不需要本地 IPFS 节点,并直接从 subgraph 的 build 目录部署,无需 graph create 或 graph deploy。它将实体存储在 Postgres 中;可以使用生成的 docker-compose.yml 中的 postgres 服务。
graph node install 会将 gnd 安装到 ~/.local/bin;请将该目录添加到您的 PATH。gnd dev 在 http://localhost:8000/subgraphs/name/subgraph-0 提供该 subgraph。添加 --watch 可在 build 目录发生变化时重新部署。
Graph Node 如何处理 Virtual Environment 回滚
Graph Node 将回滚视为链重组。一旦 Virtual Environment 的最新区块号超过 subgraph 已索引的最后一个区块,Graph Node 就会回退被移除区块中的实体,并索引替换后的区块。 在此之前,Graph Node 会忽略较短的链(日志显示Provider went backwards - ignoring this latest block),并继续提供来自已回滚区块的实体。从仪表板或使用 evm_revert 回滚后(参见回滚 Virtual Environment 状态),请继续挖出区块,直到超过原来的最新区块:发送交易、在仪表板中点击 Mine,或通过 Admin RPC 调用 evm_mine。
回退依赖于设置步骤中的两项配置:
索引父网络上已存在的合约
要包含合约在 fork 之前的历史,请将startBlock 设置为 fork 区块之前的某个区块。Graph Node 会通过 Virtual Environment RPC 从父网络读取这些区块,然后继续读取 Virtual Environment 的区块,因此 subgraph 既包含父网络的事件,也包含您的 Virtual Environment 交易产生的事件。
Graph Node 会通过 RPC 扫描从 startBlock 开始的每个区块,并根据合约的事件密度确定每个 eth_getLogs 请求的区块范围,因此对于繁忙的合约,每个请求只扫描几个区块。使用本页的 Docker 设置回填 1,000 个区块的 USDC 历史(约 97,000 个 Transfer 事件)大约需要 7 分钟。除非需要完整历史,否则请让 startBlock 尽量接近 fork 区块。
映射中的合约调用(ethereum.call,例如 Token.bind(address).balanceOf(holder))在 fork 前后都能正常工作。Graph Node 会在事件所在区块的哈希上发送 eth_call,对于 fork 之前区块的调用,Virtual Environment 会使用父网络的状态作答。
直接写入状态的 Admin RPC 作弊码(例如 tenderly_setBalance 和 tenderly_setErc20Balance)不会发出事件,因此事件处理器不会记录它们。要以 subgraph 能够记录的方式为钱包注资 ERC-20 代币,请使用 tenderly_addErc20Balance,它会为每个被注资的钱包发出一个合成的 Transfer 事件。Graph Node 会像索引其他任何 Transfer 一样索引该事件。
哪些 Virtual Environment 模式会索引父网络事件
只有 Network Mirror Mode 会将父网络的新区块及其日志添加到 Virtual Environment 中。在其他模式下,fork 之后 subgraph 只能看到您自己的交易产生的事件。切换到另一个 Virtual Environment
在将 Graph Node 指向另一个 Virtual Environment 之前,请重置 Graph Node 的数据。Graph Node 按网络名称存储已索引的区块,并且默认不会检查该名称背后的 RPC 是否已更改。如果沿用旧数据库,subgraph 会指向新 Virtual Environment 中不存在的区块。Graph Node 会以Ethereum node did not find block <hash> 不断重试,并在报告 synced: true 的同时继续提供旧实体。
docker-compose.yml 中的 ethereum 以及 subgraph.yaml 中合约的 address 和 startBlock,并再次运行 docker compose up -d、graph create 和 graph deploy。将 network 保持为父网络的名称(mainnet,而不是 virtual_mainnet 之类的自定义名称),这样同一个 subgraph.yaml 既适用于从该网络 fork 出的任何 Virtual Environment,也适用于该网络本身。
启用 GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true" 后,如果两个 Virtual Environment 的链 ID 不同,Graph Node 会检测到切换,并以 Genesis hash validation failed on provider 'mainnet-rpc-0': net version mismatch on chain 'mainnet'; expected '73574', found '73575' 拒绝新的 RPC。从同一网络 fork 出的 Virtual Environment 共享该网络的创世哈希,因此在链 ID 相同的两个 Virtual Environment 之间切换时可以通过验证。
使用事件处理器进行索引
使用eventHandlers 索引合约发出的事件。调用处理器(callHandlers)以及带有 call 过滤器的区块处理器通过 trace_filter RPC 方法读取 trace,而 Virtual Environment RPC 不提供该方法。使用它们的 subgraph 会停留在 startBlock - 1,Graph Node 会记录 Trying again after trace_filter RPC call ... failed,并附带错误:使用 Public RPC 时为 Access forbidden by access rules, try Admin RPC URL,使用 Admin RPC 时为 not supported。在公共网络上,调用处理器可以配合 Node RPC 上的 Graph Node 使用。
故障排除
相关内容
- 在 Virtual Environment 上部署和验证合约
- 使用快照或仪表板回滚 Virtual Environment 状态
- Network Mirror Mode 和 State Sync
- Tenderly Node RPC 上的 Graph Node,用于公共网络上的 subgraph
- Admin RPC 参考,涵盖
evm_snapshot、evm_revert和余额作弊码