local-network

A local Graph network for debugging & integration tests.

Epochs are set up to be 554 blocks long, use scripts/mine-block.sh to advance (foundry installation required)

Notes

• The network id for manifests is hardhat.

Usage

Requires Docker & Docker Compose. Install foundry on the host for mining blocks.

# Start (or resume) the network — skips already-completed setup steps
docker compose up -d

# Re-initialise from scratch (removes all persisted state)
docker compose down -v && docker compose up -d

State (chain, postgres, ipfs) is persisted in named volumes, so the network restarts where it left off. Use down -v only when you want a clean slate.

Add --build to rebuild after changes to Docker build context, including modifying run.sh or Dockerfile, or changed source code.

Useful commands

• docker compose up -d --build ${service} — rebuild a single service after code changes
• docker compose logs -f ${service}
• scripts/clean.sh — interactive cleanup (volumes + generated config)
• source .env

Components

chain

• Foundry docs: https://book.getfoundry.sh/
• Automine: blocks are mined instantly on each transaction
• Chain state persists across restarts via --state flag
• Use scripts/mine-block.sh to manually advance blocks if needed

block-explorer

• esplr block explorer available at: http://localhost:3000

ipfs

• cat file via curl:

  curl -X POST "http://localhost:5001/api/v0/cat?arg=f1220d6b169dcf83bfe0f615baa2d83e9adf77d520b52faf18a759eb7277b6d66fa7f"

• cat file via CLI:

  ipfs --api=/ip4/127.0.0.1/tcp/5001 cat QmagRyTMp4qcRb8fJufk7urNwCQmmUEB9mC6nxHQuKwydb

• note: if you have a hex digest, a valid CID for it is the hex digits prefixed by f1220. For example, 0xd6b169dcf83bfe0f615baa2d83e9adf77d520b52faf18a759eb7277b6d66fa7f -> f1220d6b169dcf83bfe0f615baa2d83e9adf77d520b52faf18a759eb7277b6d66fa7f

postgres

• psql -h localhost -U postgres

graph-node

• GraphiQL interface: http://localhost:8000/subgraphs/name/${subgraph_name}/graphql
• Status endpoint: http://localhost:8030/graphql/playground

graph-contracts / subgraph-deploy

• network subgraph: http://localhost:8000/subgraphs/name/graph-network

  {
    indexers {
      id
      url
      geoHash
    }
    provisions {
      id
      indexer {
        id
        stakedTokens
      }
      tokensProvisioned
      thawingPeriod
      maxVerifierCut
      dataService {
        id
        totalTokensProvisioned
      }
    }
    subgraphs {
      id
      versions {
        subgraphDeployment {
          ipfsHash
          indexerAllocations {
            id
            status
            indexer {
              id
            }
          }
        }
      }
    }
    _meta {
      block {
        number
      }
      deployment
    }
  }

block-oracle

• subgraph: http://localhost:8000/subgraphs/name/block-oracle

  {
    networks {
      id
    }
    _meta {
      block {
        number
      }
      deployment
    }
  }

indexer-agent

• graph indexer connect http://localhost:7600
• graph indexer --network=hardhat status

indexer-service

• docker compose up --build indexer-service
• docker compose down indexer-service
• docker compose logs -f indexer-service

curl "http://localhost:7601/subgraphs/id/QmRcucmbxAXLaAZkkCR8Bdj1X7QGPLjfRmQ5H6tFhGqiHX" \
  -H 'content-type: application/json' -H "Authorization: Bearer freestuff" \
  -d '{"query": "{ _meta { block { number } } }"}'

gateway

curl "http://localhost:7700/api/subgraphs/id/BFr2mx7FgkJ36Y6pE5BiXs1KmNUmVDCnL82KUSdcLW1g" \
  -H 'content-type: application/json' -H "Authorization: Bearer deadbeefdeadbeefdeadbeefdeadbeef" \
  -d '{"query": "{ _meta { block { number } } }"}'

redpanda

docker exec -it redpanda rpk topic consume gateway_client_query_results --brokers="localhost:9092"

TAP subgraph

• subgraph: http://localhost:8000/subgraphs/name/semiotic/tap

  {
    escrowAccounts {
      balance
      sender {
        id
      }
      receiver {
        id
      }
    }
    _meta {
      block {
        number
      }
      deployment
    }
  }

Optional: Indexing Payments

To enable payments for indexing work (alternative to TAP allocations):

# Start with indexing payments
docker compose -f docker-compose.yaml -f overrides/indexing-payments/docker-compose.yaml up

# Or use helper script
./overrides/indexing-payments/start.sh

See overrides/indexing-payments/README.md for details.

Building components from source

docker compose overrides

The following components allow building from source by overriding docker-compose.yml:

• graph-node
• graph-contracts (contracts)
• indexer-agent

Please refer to overrides/README.md for instructions.

git submodules source

The following components allow building from source by cloning them with submodules:

• indexer-service
• tap-agent

Building from source requires the Git submodules to be initialized first:

• git submodule update --init --recursive

And then select the wrapper-dev target when building the Docker image in the docker-compose.yaml file.

  indexer-service:
    container_name: indexer-service
    build: {
-     target: "wrapper", # Set to "wrapper-dev" for building from source
+     target: "wrapper-dev", # Set to "wrapper-dev" for building from source
      context: indexer-service,
    }

  tap-agent:
    container_name: tap-agent
    build: {
-     target: "wrapper", # Set to "wrapper-dev" for building from source
+     target: "wrapper-dev", # Set to "wrapper-dev" for building from source
      context: tap-agent,
    }

Common issues

too far behind

Gateway error:

ERROR graph_gateway::network::subgraph_client: network_subgraph_query_err="response too far behind"

This happens when subgraphs fall behind the chain head. With automine (default), this is a harmless warning during startup. Run scripts/mine-block.sh 10 to advance blocks manually if needed.