ETHEREUM_POLLING_INTERVAL, по умолчанию 1000 мс).
Типичные сценарии:
- Контракты, которые вы деплоите в Virtual Environment (разработка, CI): следуйте инструкции по настройке ниже.
- Staging- или демо-окружения с историей из production: индексируйте контракт, который уже существует в родительской сети.
- Активность родительской сети после форка: используйте Network Mirror Mode.
- Subgraph в публичной сети: запустите Graph Node на Tenderly Node RPC.
DemoToken, минимальный ERC-20, который эмитирует Transfer(address indexed from, address indexed to, uint256 value) и задеплоен в Virtual Environment, форкнутой от Ethereum Mainnet.
Прежде чем начать
- Node.js 20.18.1 или новее (требуется для Graph CLI) и npm
- Docker с Docker Compose
- Virtual Environment и её URL Public RPC, указанный в карточке Integrate Virtual RPC на вкладке Home Virtual Environment (см. справочник по панели)
- Контракт, задеплоенный в Virtual Environment (см. Деплой и верификация контрактов), а также:
- его адрес
- его ABI в виде JSON-файла
- номер блока его транзакции деплоя:
Настройка Graph Node и subgraph
1
Установите Graph CLI
2
Создайте каркас subgraph на основе контракта
graph init создаёт директорию demo-token с файлами subgraph.yaml, schema.graphql, маппингом событий в src/demo-token.ts и файлом docker-compose.yml, который запускает Graph Node, IPFS и Postgres.В subgraph.yaml измените indexerHints.prune с auto на never. Graph Node нужна полная история сущностей, чтобы отменять изменения из откаченных блоков.subgraph.yaml
3
Направьте Graph Node на Virtual Environment
В сгенерированном Оставьте сервисы
docker-compose.yml отредактируйте переменные окружения сервиса graph-node:- Задайте для
ethereumзначение<network>:<Public RPC URL>. Имя сети перед первым двоеточием должно совпадать сnetworkвsubgraph.yaml. - Добавьте
ETHEREUM_REORG_THRESHOLD: "1", чтобы Graph Node могла отменять изменения из откаченных блоков. - Добавьте
GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true", чтобы Graph Node отклоняла URL RPC другой Virtual Environment, а не зависала.
docker-compose.yml (сервис graph-node)
ipfs и postgres в сгенерированном виде. Graph Node только читает данные цепочки, поэтому используйте Public RPC, а не Admin RPC.4
Запустите Graph Node
Starting GraphQL HTTP server at: http://localhost:8000.5
Создайте и задеплойте subgraph
graph deploy собирает subgraph, загружает его в IPFS и выводит URL для запросов:package.json те же команды доступны как npm run create-local и npm run deploy-local. Запускайте graph codegen повторно после изменения schema.graphql или ABI.6
Выполните запрос к subgraph
Проверка статуса индексации
Отправьте запрос к API статуса индексации на порту8030:
latestBlock показывает последний блок, который обработал subgraph, а chainHeadBlock показывает последний блок Virtual Environment. Сравнивайте эти два значения, а не полагайтесь на health. Во всех случаях сбоев, описанных на этой странице, subgraph продолжает сообщать healthy, а latestBlock перестаёт расти.
Чтобы увидеть запросы, которые отправляет Graph Node, откройте вкладку JSON-RPC Calls вашей Virtual Environment. Установите фильтр Status в значение Failed, чтобы найти методы, которые Virtual Environment отклоняет, например trace_filter от обработчиков вызовов. Разверните строку, чтобы увидеть параметры запроса и ответ с ошибкой.
Запуск subgraph с помощью gnd вместо Docker
gnd (Graph Node Dev) запускает Graph Node как нативный бинарный файл, не требует локального узла IPFS и деплоит subgraph из директории build без graph create и graph deploy. Сущности gnd хранит в Postgres; подойдёт сервис postgres из сгенерированного docker-compose.yml.
graph node install устанавливает gnd в ~/.local/bin; добавьте эту директорию в PATH. gnd dev отдаёт subgraph по адресу http://localhost:8000/subgraphs/name/subgraph-0. Добавьте --watch, чтобы subgraph деплоился заново при каждом изменении директории сборки.
Как 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 в панели или вызовите evm_mine через Admin RPC.
Откат зависит от двух параметров, заданных на этапе настройки:
Индексация контракта, который уже существует в родительской сети
Чтобы включить историю контракта до форка, задайте дляstartBlock блок, предшествующий блоку форка. Graph Node читает эти блоки из родительской сети через RPC Virtual Environment, а затем продолжает с блоками Virtual Environment, поэтому subgraph содержит как события родительской сети, так и события из транзакций вашей Virtual Environment.
Graph Node сканирует через RPC каждый блок начиная со startBlock и подбирает размер диапазона каждого запроса eth_getLogs под плотность событий контракта, поэтому активный контракт сканируется по несколько блоков за запрос. Загрузка истории USDC за 1 000 блоков (около 97 000 событий Transfer) заняла около 7 минут с конфигурацией Docker, описанной на этой странице. Держите startBlock близко к блоку форка, если вам не нужна полная история.
Вызовы контрактов в маппингах (ethereum.call, например Token.bind(address).balanceOf(holder)) работают по обе стороны от форка. Graph Node отправляет eth_call с хешем блока, в котором произошло событие, а Virtual Environment отвечает на вызовы для блоков до форка состоянием родительской сети.
Чит-коды Admin RPC, которые записывают состояние напрямую, например tenderly_setBalance и tenderly_setErc20Balance, не эмитируют событий, поэтому обработчики событий их не фиксируют. Чтобы subgraph фиксировал пополнение кошельков токенами ERC-20, используйте tenderly_addErc20Balance, который эмитирует синтетическое событие Transfer для каждого пополненного кошелька. Graph Node индексирует его так же, как любое другое событие Transfer.
В каких режимах Virtual Environment индексируются события родительской сети?
Только Network Mirror Mode добавляет в Virtual Environment новые блоки родительской сети вместе с их логами. В остальных режимах subgraph видит после форка только события из ваших собственных транзакций.Переключение на другую Virtual Environment
Сбросьте данные Graph Node, прежде чем направить её на другую Virtual Environment. Graph Node хранит проиндексированные блоки по имени сети и по умолчанию не проверяет, изменился ли RPC, стоящий за этим именем. При старой базе данных subgraph ссылается на блоки, которых нет в новой Virtual Environment. Graph Node повторяет попытки с ошибкойEthereum node did not find block <hash> и продолжает отдавать старые сущности, сообщая synced: true.
ethereum в docker-compose.yml, а также address контракта и startBlock в subgraph.yaml, и снова выполните docker compose up -d, graph create и graph deploy. Оставьте в network имя родительской сети (mainnet, а не пользовательское имя вроде virtual_mainnet), чтобы один и тот же subgraph.yaml работал с любой Virtual Environment, форкнутой от этой сети, и с самой сетью.
При GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true" Graph Node обнаруживает переключение, если у двух Virtual Environment разные chain ID, и отклоняет новый RPC с ошибкой Genesis hash validation failed on provider 'mainnet-rpc-0': net version mismatch on chain 'mainnet'; expected '73574', found '73575'. Virtual Environment, форкнутые от одной и той же сети, имеют её genesis-хеш, поэтому переключение между двумя Virtual Environment с одинаковым chain ID проходит проверку.
Индексация с помощью обработчиков событий
Индексируйте события, которые эмитирует ваш контракт, с помощьюeventHandlers. Обработчики вызовов (callHandlers) и обработчики блоков с фильтром call читают трассировки через RPC-метод trace_filter, который RPC Virtual Environment не обслуживают. Subgraph, который их использует, остаётся на startBlock - 1, а Graph Node пишет в лог Trying again after trace_filter RPC call ... failed с ошибкой Access forbidden by access rules, try Admin RPC URL от Public RPC или not supported от Admin RPC. В публичных сетях обработчики вызовов работают с Graph Node на Node RPC.
Устранение неполадок
См. также
- Деплой и верификация контрактов в Virtual Environment
- Откат состояния Virtual Environment с помощью снимков или панели
- Network Mirror Mode и State Sync
- Graph Node на Tenderly Node RPC для subgraph в публичных сетях
- Справочник Admin RPC для
evm_snapshot,evm_revertи чит-кодов балансов