tutorial

Build your first KasGraph subgraph.

A local-first walkthrough for defining, building, deploying, indexing, and querying a simple KRC-style subgraph without pretending hosted commands exist before validation.

Step 1 - Install repo dependencies

The CLI package is in this monorepo. Until npm publishing is confirmed, use the repo-local toolchain.

step 1 - install repo dependencies

git clone https://github.com/trillskillz/KasGraph
cd KasGraph
npm install
npm run typecheck
npm test

Step 2 - Initialize a subgraph

This command is implemented and scaffolds manifest, schema, mapping, and README files.

step 2 - initialize a subgraph

npx kasgraph init krc20-tracker
cd krc20-tracker

Step 3 - Define entities

Edit schema.graphql to model the application data you want to query.

step 3 - define entities

type Token @entity {
  id: ID!
  ticker: String!
  totalSupply: BigInt!
  holdersCount: Int!
}

type Holder @entity {
  id: ID!
  token: Token!
  balance: BigInt!
}

type Transfer @entity {
  id: ID!
  token: Token!
  from: String
  to: String
  amount: BigInt!
  txHash: String!
}

Step 4 - Add a mapping

The scaffolded mapping is editable. This transfer handler is a tutorial preview, not a copied production handler.

step 4 - add a mapping

// Preview mapping shape. Adjust handler names to match your manifest.
export function handleTransfer(event: Krc20Transfer): void {
  const token = Token.load(event.ticker) ?? new Token(event.ticker);
  token.ticker = event.ticker;

  const from = event.from ? loadHolder(event.ticker, event.from) : null;
  const to = loadHolder(event.ticker, event.to);

  if (from) from.balance = from.balance.minus(event.amount);
  to.balance = to.balance.plus(event.amount);

  token.save();
  from?.save();
  to.save();
}

Step 5 - Build

Generate TypeScript types and compile the AssemblyScript mapping to WASM.

step 5 - build

npx kasgraph codegen
npx kasgraph build

Step 6 - Deploy locally

Direct database deployment is implemented. Hosted-node deployment also exists behind --node once a node is available.

step 6 - deploy locally

# Direct local registry write, requires Postgres.
npx kasgraph deploy --database-url "$DATABASE_URL"
npx kasgraph status krc20-tracker

Step 7 - Run the indexer node

There is no implemented kasgraph index CLI command yet; run the Rust node with the documented environment variables.

step 7 - run the indexer node

DATABASE_URL="$DATABASE_URL" \
KASGRAPH_INGEST_MODE=continuous \
KASGRAPH_NOTIFICATION_WS_URL=wss://your-kaspa-node/wrpc/json \
KASGRAPH_RELOAD_INTERVAL_SECS=30 \
  cargo run -p kasgraph-node

Step 8 - Query with GraphQL

Run the API/gateway against the same Postgres-backed registry, then query the generated schema.

step 8 - query with graphql

query {
  tokens(first: 10) {
    id
    ticker
    holdersCount
    totalSupply
  }
}

Step 9 - Inspect status and checkpoints

Use the operational CLI for public API status, latest POI checkpoint, and database counts. Range verification remains pending.

step 9 - inspect status and checkpoints

# POI inspection is implemented in the core verifier/checkpoint path.
# Latest checkpoint inspection is available against Postgres.
npx kasgraph poi latest --database-url "$DATABASE_URL"
npx kasgraph db stats --database-url "$DATABASE_URL" --json
npx kasgraph health --node http://localhost:4000