Skip to content

development.md

Latest commit

 

History

History
168 lines (115 loc) · 3.87 KB

development.md

File metadata and controls

168 lines (115 loc) · 3.87 KB

Developing on TFChain GraphQL

Install

yarn
yarn build

Local Network

Run TFChain

See https://github.com/threefoldtech/tfchain

Create the shared Docker network

Both compose stacks use a shared external network. Create it once:

docker network create tfgrid_bknd

Run Indexer

Check indexer/.env and adjust the websocket endpoint to your local TFChain address.

cd indexer
docker compose up -d

Indexer services should now be started. Check if it's syncing properly by streaming the ingest logs:

docker logs indexer-ingest-1 -f

You should see TFChain blocks being processed:

Indexer logs

Run Processor (local, outside Docker)

Check .env and adjust the settings. When running the processor locally (not in Docker) while the indexer runs in Docker, change INDEXER_ENDPOINT_URL to use the published port:

# .env — for local development (processor outside Docker):
INDEXER_ENDPOINT_URL=http://localhost:8888/graphql

# .env — for Docker deployment (processor inside Docker, shared network):
# INDEXER_ENDPOINT_URL=http://gateway:8000/graphql

Start the local PostgreSQL container and run the processor:

yarn build
yarn db:up
yarn process

You should see TFChain blocks being processed by the processor:

Processor logs

If you make changes, stop the containers before restarting:

docker compose down

Run GraphQL UI

At this step, running docker ps should show the indexer containers running:

Docker containers

Start the query node:

yarn api

Now you can use the GraphQL playground at http://localhost:4000/graphql

Adding New Runtime Versions

When TFChain has a new spec version with type changes, see typeChanges.md for the full workflow. The short version:

# Point at your local chain (or a remote network via WS_URL=wss://...)
make typegen-add

# Check what changed in src/types/, add handler branches if needed
yarn build

Modifying the GraphQL Schema

If you need to add new entities or fields to the GraphQL API:

  1. Edit schema.graphql
  2. Regenerate models and create a migration: 
    yarn codegen
yarn build
yarn db:create-migration
  3. Add or update event handlers in src/mappings/
  4. Register new events in src/processor.ts if needed
  5. Test locally: 
    yarn db:up
yarn db:migrate
yarn process

Resetting the Processor Database

Option A: Volume wipe (recommended)

The simplest and safest approach. Wipes the entire PostgreSQL data directory:

# Stop processor and DB
docker compose down processor db

# Wipe postgres data
rm -rf /path/to/postgres-data/*

# Restart - processor will run migrations and start from block 0
docker compose up -d

Option B: Script (local dev)

./scripts/reset-db.sh
yarn process

Debugging

Debug logging

Use SQD_DEBUG=sqd:processor:mapping for event processing visibility. Avoid sqd:processor:* which floods logs with serialization errors from a known node-fetch bug.

# In .env or docker-compose.yml environment:
SQD_DEBUG=sqd:processor:mapping

Check processor progress

# Current height
docker exec db-container psql -U postgres -d tfgrid-graphql \
  -c 'SELECT height FROM squid_processor.status;'

# Entity counts
docker exec db-container psql -U postgres -d tfgrid-graphql -c "
  SELECT 'farms' AS entity, count(*) FROM farm
  UNION ALL SELECT 'nodes', count(*) FROM node
  UNION ALL SELECT 'twins', count(*) FROM twin
  UNION ALL SELECT 'contracts', count(*) FROM node_contract;
"