Index a Virtual Environment with The Graph

To index contracts on a Virtual Environment, run your own Graph Node and point it at the Virtual Environment’s Public RPC URL. Graph Node reads the Virtual Environment over standard JSON-RPC. Blocks before the fork come from the parent network, and later blocks contain your Virtual Environment transactions. New transactions are indexed within a few seconds, because Graph Node polls the RPC for new blocks every second (ETHEREUM_POLLING_INTERVAL, default 1000 ms). Common setups:

Contracts you deploy on the Virtual Environment (development, CI): follow the setup below.
Staging or demo environments with production history: index a contract that already exists on the parent network.
Parent-network activity after the fork: use Network Mirror Mode.
A subgraph on a public network: run Graph Node on Tenderly Node RPC.

This guide was tested with Graph CLI 0.98.1 and Graph Node 0.45.0. The examples index DemoToken, a minimal ERC-20 that emits Transfer(address indexed from, address indexed to, uint256 value), deployed on a Virtual Environment forked from Ethereum mainnet.

Before you begin

Node.js 20.18.1 or later (required by Graph CLI) and npm
Docker with Docker Compose
A Virtual Environment and its Public RPC URL, listed in the Integrate Virtual RPC card on the Virtual Environment’s Home tab (see the dashboard reference)
A contract deployed on the Virtual Environment (see Deploy and verify contracts), with:
- its address
- its ABI as a JSON file
- the block number of its deployment transaction:

cast receipt <deployment-tx-hash> blockNumber --rpc-url <public-rpc-url>

The subgraph indexes the logs emitted at the contract address on the Virtual Environment, so the contract must exist there: deployed on the Virtual Environment, or deployed on the parent network before the fork. Adding the contract in the Tenderly dashboard doesn’t change what the subgraph indexes.

Set up Graph Node and the subgraph

Install the Graph CLI

npm install -g @graphprotocol/graph-cli
graph --version

Scaffold the subgraph from your contract

graph init demo-token demo-token \
  --protocol ethereum \
  --from-contract 0xEfD569DA63EE9190ea2a1eCf318c0153914aB2f0 \
  --abi ./DemoToken.json \
  --contract-name DemoToken \
  --start-block 26205837 \
  --network mainnet \
  --index-events

Flag	Value
`--from-contract`	The contract address on the Virtual Environment.
`--abi`	Path to the contract ABI JSON file.
`--start-block`	The block of the deployment transaction. Graph Node starts scanning at this block.
`--network`	The Virtual Environment’s parent network, named as in The Graph’s networks registry (`mainnet`, `base`, `arbitrum-one`). Graph Node’s configuration in the next step must use the same name.
`--index-events`	Generates an entity and a handler for every event in the ABI.

graph init creates the demo-token directory with subgraph.yaml, schema.graphql, an event mapping in src/demo-token.ts, and a docker-compose.yml that runs Graph Node, IPFS, and Postgres.In subgraph.yaml, change indexerHints.prune from auto to never. Graph Node needs the full entity history to roll back reverted blocks.

subgraph.yaml

specVersion: 1.3.0
indexerHints:
  prune: never

Point Graph Node at the Virtual Environment

In the generated docker-compose.yml, edit the environment of the graph-node service:

Set ethereum to <network>:<Public RPC URL>. The network name before the first colon must match network in subgraph.yaml.
Add ETHEREUM_REORG_THRESHOLD: "1" so Graph Node can roll back reverted blocks.
Add GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true" so Graph Node refuses an RPC URL from a different Virtual Environment instead of stalling.

docker-compose.yml (graph-node service)

services:
  graph-node:
    image: graphprotocol/graph-node
    ports:
      - "8000:8000"
      - "8001:8001"
      - "8020:8020"
      - "8030:8030"
      - "8040:8040"
    depends_on:
      - ipfs
      - postgres
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      postgres_host: postgres
      postgres_user: graph-node
      postgres_pass: let-me-in
      postgres_db: graph-node
      ipfs: "ipfs:5001"
      ethereum: "mainnet:https://virtual.mainnet.eu.rpc.tenderly.co/<public-rpc-id>"
      GRAPH_LOG: info
      ETHEREUM_REORG_THRESHOLD: "1"
      GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true"

Leave the ipfs and postgres services as generated. Graph Node only reads chain data, so use the Public RPC rather than the Admin RPC.

Start Graph Node

cd demo-token
docker compose up -d
docker compose logs -f graph-node

Graph Node is ready when the log shows Starting GraphQL HTTP server at: http://localhost:8000.

Port	Service
`8000`	GraphQL queries
`8020`	Admin JSON-RPC, used by `graph create` and `graph deploy`
`8030`	Indexing status API
`5001`	IPFS

Create and deploy the subgraph

graph create --node http://localhost:8020/ demo-token
graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 --version-label v0.0.1 demo-token

graph deploy builds the subgraph, uploads it to IPFS, and prints the query URL:

Deployed to http://localhost:8000/subgraphs/name/demo-token/graphql

The generated package.json runs the same commands as npm run create-local and npm run deploy-local. Run graph codegen again after you edit schema.graphql or the ABI.

Query the subgraph

curl -s http://localhost:8000/subgraphs/name/demo-token \
  -H 'content-type: application/json' \
  -d '{"query":"{ transfers(orderBy: blockNumber) { from to value blockNumber } }"}'

{
  "data": {
    "transfers": [
      {
        "from": "0x0000000000000000000000000000000000000000",
        "to": "0x8b2d8555dc6e6e37a66ca16059cf8c04b301e6c4",
        "value": "1000000000000000000000000",
        "blockNumber": "26205837"
      },
      {
        "from": "0x8b2d8555dc6e6e37a66ca16059cf8c04b301e6c4",
        "to": "0xd5de3d8fabf86c587f7cf348f09846d760a1e41a",
        "value": "2500000000000000000000",
        "blockNumber": "26205838"
      }
    ]
  }
}

Check indexing status

Query the indexing status API on port 8030:

curl -s http://localhost:8030/graphql \
  -H 'content-type: application/json' \
  -d '{"query":"{ indexingStatusForCurrentVersion(subgraphName: \"demo-token\") { health synced fatalError { message } chains { chainHeadBlock { number } latestBlock { number } } } }"}'

latestBlock is the last block the subgraph processed and chainHeadBlock is the Virtual Environment’s latest block. Compare the two instead of relying on health. In every failure case on this page, the subgraph keeps reporting healthy while latestBlock stops advancing. To see the requests Graph Node sends, open the JSON-RPC Calls tab of the Virtual Environment. Set the Status filter to Failed to find methods the Virtual Environment rejects, such as trace_filter from call handlers. Expand a row to see the request parameters and the error response.

Run the subgraph with gnd instead of Docker

gnd (Graph Node Dev) runs Graph Node as a native binary, needs no local IPFS node, and deploys the subgraph from its build directory without graph create or graph deploy. It stores entities in Postgres; the postgres service from the generated docker-compose.yml works.

graph node install
docker compose up -d postgres
gnd build
ETHEREUM_REORG_THRESHOLD=1 gnd dev \
  --postgres-url postgresql://graph-node:let-me-in@localhost:5432/graph-node \
  --ethereum-rpc mainnet:https://virtual.mainnet.eu.rpc.tenderly.co/<public-rpc-id>

graph node install installs gnd to ~/.local/bin; add that directory to your PATH. gnd dev serves the subgraph at http://localhost:8000/subgraphs/name/subgraph-0. Add --watch to redeploy whenever the build directory changes.

How does Graph Node handle a Virtual Environment revert?

Graph Node treats a revert as a chain reorganization. Once the Virtual Environment’s latest block number passes the last block the subgraph indexed, Graph Node rolls back the entities from the removed blocks and indexes the replacement blocks. Until then, Graph Node ignores the shorter chain (the log shows Provider went backwards - ignoring this latest block) and keeps serving entities from the reverted blocks. After a revert from the dashboard or with evm_revert (see Revert Virtual Environment state), mine past the old latest block: send transactions, click Mine in the dashboard, or call evm_mine over the Admin RPC. The rollback depends on the two settings from the setup:

Setting	Effect
`ETHEREUM_REORG_THRESHOLD: "1"`	Graph Node rolls a subgraph back only to a block at least `ETHEREUM_REORG_THRESHOLD` blocks above the subgraph’s earliest indexed block. With the default of `250`, a revert to any block within 250 blocks of `startBlock` fails with `No rows affected. This could be due to an attempt to revert beyond earliest_block + reorg_threshold`, and the subgraph stays on the reverted block.
`prune: never`	`prune: auto` keeps entity history for only 2 × `ETHEREUM_REORG_THRESHOLD` blocks. `never` keeps all of it, so Graph Node can roll back reverts deeper than two blocks.

Index a contract that already exists on the parent network

To include a contract’s history from before the fork, set startBlock to a block before the fork block. Graph Node reads those blocks from the parent network through the Virtual Environment RPC, then continues with the Virtual Environment’s blocks, so the subgraph contains both the parent network’s events and the events from your Virtual Environment transactions. Graph Node scans every block from startBlock onward through the RPC and sizes each eth_getLogs range to the contract’s event density, so a busy contract is scanned a few blocks per request. Backfilling 1,000 blocks of USDC history (about 97,000 Transfer events) took about 7 minutes with the Docker setup on this page. Keep startBlock close to the fork block unless you need the full history. Contract calls in mappings (ethereum.call, for example Token.bind(address).balanceOf(holder)) work on both sides of the fork. Graph Node sends eth_call at the event’s block hash, and the Virtual Environment answers calls for pre-fork blocks with the parent network’s state. Admin RPC cheatcodes that write state directly, such as tenderly_setBalance and tenderly_setErc20Balance, emit no events, so event handlers don’t record them. To fund wallets with ERC-20 tokens in a way the subgraph records, use tenderly_addErc20Balance, which emits a synthetic Transfer event for each funded wallet. Graph Node indexes it like any other Transfer.

Which Virtual Environment modes index parent-network events?

Only Network Mirror Mode adds the parent network’s new blocks, with their logs, to a Virtual Environment. In the other modes, a subgraph sees only the events from your own transactions after the fork.

Mode	Parent-network events after the fork	Contract calls in mappings
Standard	Not indexed. The Virtual Environment mines blocks only for your transactions.	Return the fork-block state plus your changes.
State Sync	Not indexed. The Virtual Environment mines blocks only for your transactions.	Return the parent network’s values for storage you haven’t written, as of when each Virtual Environment block was mined.
Network Mirror Mode	Indexed. Each synced block arrives with its transactions and logs, and the subgraph records the parent network’s events plus the events from your transactions.	Return the Virtual Environment’s state at that block.

Switch to a different Virtual Environment

Reset Graph Node’s data before you point it at another Virtual Environment. Graph Node stores indexed blocks per network name and, by default, doesn’t check whether the RPC behind that name changed. With the old database, the subgraph points at blocks that the new Virtual Environment doesn’t have. Graph Node retries Ethereum node did not find block <hash> and keeps serving the old entities while reporting synced: true.

docker compose down
rm -rf data

Then update ethereum in docker-compose.yml and the contract address and startBlock in subgraph.yaml, and run docker compose up -d, graph create, and graph deploy again. Keep network set to the parent network’s name (mainnet, not a custom name like virtual_mainnet), so the same subgraph.yaml works against any Virtual Environment forked from that network and against the network itself. With GRAPH_NODE_GENESIS_VALIDATION_ENABLED: "true", Graph Node detects the switch when the two Virtual Environments have different chain IDs and refuses the new RPC with

Genesis hash validation failed on provider 'mainnet-rpc-0': net version mismatch on chain 'mainnet'; expected '73574', found '73575'

. Virtual Environments forked from the same network share its genesis hash, so a switch between two with the same chain ID passes validation.

Index with event handlers

Index the events your contract emits with eventHandlers. Call handlers (callHandlers) and block handlers with a call filter read traces through the trace_filter RPC method, which Virtual Environment RPCs don’t serve. A subgraph that uses them stays at startBlock - 1, and Graph Node logs Trying again after trace_filter RPC call ... failed with Access forbidden by access rules, try Admin RPC URL from the Public RPC or not supported from the Admin RPC. On public networks, call handlers work with Graph Node on Node RPC.

Troubleshooting

Symptom	Cause	Fix
`Bind for 0.0.0.0:5432 failed: port is already allocated` on `docker compose up`	Another Postgres on the host uses port 5432.	Change the `postgres` port mapping to `"5433:5432"`. Graph Node connects to Postgres over the Compose network, so the host port doesn’t matter.
`The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)`	The `graphprotocol/graph-node` image is amd64-only.	Expected on Apple silicon: Docker runs the image under emulation. To run natively, use gnd.
`network not supported by registrar: no network base found on chain ethereum` on `graph deploy`	`network` in `subgraph.yaml` doesn’t match the network name in `ethereum`.	Use the same name in both.
The subgraph has no parent-network events after the fork	Standard and State Sync Virtual Environments don’t import parent-network blocks.	Use Network Mirror Mode. See Which Virtual Environment modes index parent-network events?
Queries still return entities from reverted blocks	The Virtual Environment’s latest block is at or below the last block the subgraph indexed.	Mine past it. See How does Graph Node handle a Virtual Environment revert?
`No rows affected. This could be due to an attempt to revert beyond earliest_block + reorg_threshold`	`ETHEREUM_REORG_THRESHOLD` is at its default of 250.	Set `ETHEREUM_REORG_THRESHOLD: "1"`, run `docker compose down` and `rm -rf data`, then start Graph Node and deploy the subgraph again.
`latestBlock` stays at `startBlock - 1` and the log shows `trace_filter` errors	The subgraph uses call handlers or a `call` block filter.	Use event handlers. See Index with event handlers.
`Ethereum node did not find block` or `net version mismatch on chain` after changing the RPC URL	Graph Node’s database holds blocks from the previous Virtual Environment.	Reset Graph Node’s data. See Switch to a different Virtual Environment.

Deploy and verify contracts on a Virtual Environment
Revert Virtual Environment state with snapshots or the dashboard
Network Mirror Mode and State Sync
Graph Node on Tenderly Node RPC for subgraphs on public networks
Admin RPC reference for evm_snapshot, evm_revert, and balance cheatcodes

Getting Started

Simulator

Console

Monitor

Node RPC

AI Tools

Account & Settings

Index a Virtual Environment with The Graph

Before you begin

Set up Graph Node and the subgraph

Check indexing status

Run the subgraph with gnd instead of Docker

How does Graph Node handle a Virtual Environment revert?

Index a contract that already exists on the parent network

Which Virtual Environment modes index parent-network events?

Switch to a different Virtual Environment

Index with event handlers

Troubleshooting

​Before you begin

​Set up Graph Node and the subgraph

​Check indexing status

​Run the subgraph with gnd instead of Docker

​How does Graph Node handle a Virtual Environment revert?

​Index a contract that already exists on the parent network

​Which Virtual Environment modes index parent-network events?

​Switch to a different Virtual Environment

​Index with event handlers

​Troubleshooting

​Related

Before you begin

Set up Graph Node and the subgraph

Check indexing status

Run the subgraph with gnd instead of Docker

How does Graph Node handle a Virtual Environment revert?

Index a contract that already exists on the parent network

Which Virtual Environment modes index parent-network events?

Switch to a different Virtual Environment

Index with event handlers

Troubleshooting

Related