# KasGraph

> The Graph for Kaspa — AI-native subgraph indexer with GraphQL + MCP + KasStream + WebSocket. KIP-20 Covenant IDs first-class, native KRC-20/KRC-721, BlockDAG-aware reorgs.

- **Type:** MCP server
- **Install:** `agentstack add mcp-trillskillz-kasgraph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [trillskillz](https://agentstack.voostack.com/s/trillskillz)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [trillskillz](https://github.com/trillskillz)
- **Source:** https://github.com/trillskillz/KasGraph
- **Website:** https://kasgraph.com

## Install

```sh
agentstack add mcp-trillskillz-kasgraph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# KasGraph

> The Graph for Kaspa, AI-native from day one. A subgraph-style indexing protocol with GraphQL, MCP, and streaming, redesigned around Kaspa's UTXO model, KIP-20 Covenant IDs, native KRC-20 / KRC-721, and the agent era.

[](https://github.com/trillskillz/KasGraph/actions/workflows/ci.yml)
[](LICENSE)
[](crates/)
[](sdk/)
[](mcp/)
[](docs/references/KIP20_COVENANT_ID_QUERIES.md)

**Why this exists**: Kaspa's own developer docs list structured data querying as missing. The community API is best-effort with no SLA. Kasplex covers inscription-style KRC-20 (legacy); krc721.stream covers legacy NFTs. With Toccata landing covenants, native KRC-20, and ZK opcodes, every serious dApp needs structured data querying, plus an MCP surface so AI agents can use it without writing GraphQL.

KIP-20 Covenant IDs make this dramatically easier than EVM indexing: stable, consensus-tracked identifiers for stateful contracts mean lineage queries are a primary-key lookup. No recursive UTXO walking. No event-log parsing heuristics.

## Four interfaces, one data plane

```
                  +----------------------------+
                  |  Your dApp / wallet / LLM  |
                  +----------------------------+
                              |
       +--------------+-------+---------+--------------+
       v              v                 v              v
   GraphQL          MCP            KasStream        WebSocket
  subgraph     AI natural     sub-second event   push subscriptions
   queries     language         streaming
       +--------------+--------+--------+--------------+
                               v
                       KasGraph Node (Rust)
                  ingest -> detect -> map -> POI
                               |
                          PostgreSQL
                               |
                  Rusty Kaspa RPC (multi-source, failover)
```

All four interfaces ship together. MCP is a first-class surface, not a future addition.

## What it does

- **Subgraph indexing for Kaspa.** Author a `subgraph.yaml` + `schema.graphql` + an AssemblyScript mapping, then `build` and `deploy`. The node indexes matching on-chain activity into typed entities you query over GraphQL.
- **KIP-20 Covenant ID lineage** as a first-class entity, including the fork-aware DAG that a per-UTXO token model produces (each lineage row records its parent edge and forward children).
- **Built-in pattern detection.** 17 covenant fingerprints captured from real `silverc` compiles (the OpenSilver core patterns + the native KCC20 asset and its four controllers), plus legacy KRC-20 / KRC-721 inscription parsing and ledger state machines. Subgraphs subscribe to typed detector events; they do not write detection code.
- **Typed per-subgraph GraphQL.** Each deployed subgraph gets its own schema generated from its `schema.graphql`, with relation and `@derivedFrom` resolution.
- **MCP server** over the same data plane: `list_subgraphs`, `get_schema`, `execute_query`, `search_by_pattern`, `get_covenant_lineage`. An agent can explore and query a subgraph without writing GraphQL by hand.
- **BlockDAG-aware ingestion.** Multi-RPC failover, continuous wRPC subscription with backoff reconnect and gap recovery, probabilistic-vs-committed block buffering, and reorg-safe unwind.
- **Proof of Indexing.** A blake2b-256 hash chain over each block's dispatched entity state, with an independent third-party verifier, so two honest indexers produce a byte-identical, verifiable chain.

## Status

The indexer is **feature-complete core infrastructure**: `build -> deploy -> index -> query` is multi-tenant, hot-reloadable, and verified end-to-end against a real Postgres. Hosted deploy writes support bearer-token auth, and the API exposes `/healthz`, `/health`, `/status`, and `/metrics` for operators. A 24-hour testnet soak artifact is published; remaining pre-public work is operational validation for hosted topology, published benchmarks, mainnet readiness, and protected log streaming. See [`STATUS.md`](STATUS.md) for the live per-phase block.

## Quick start

```bash
git clone https://github.com/trillskillz/KasGraph && cd KasGraph
npm install
npm run verify        # tsc -b  +  vitest  +  cargo test --workspace
```

Scaffold, build, and deploy a subgraph with the CLI:

```bash
npx kasgraph init my-subgraph
cd my-subgraph
# edit schema.graphql + src/mapping.ts
npx kasgraph codegen                                   # generate types from schema.graphql
npx kasgraph build                                     # compile the AssemblyScript mapping to wasm
npx kasgraph deploy --database-url "$DATABASE_URL"     # or: --node https://your-node
npx kasgraph status my-subgraph
```

Run the indexer node against the deployed set:

```bash
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
```

The node reads its active subgraph set from the registry, materializes each deployed mapping, fans every block out to all of them, and picks up new `deploy`/`remove` calls on the reload interval without a restart.

## CLI

| Command | What it does |
| --- | --- |
| `kasgraph init ` | Scaffold a new subgraph (manifest, schema, mapping, README) |
| `kasgraph codegen` | Generate TypeScript types from `schema.graphql` + the manifest |
| `kasgraph build` | Compile the AssemblyScript mapping to ABI-compliant wasm + a `build/manifest.json` |
| `kasgraph deploy` | Package the built subgraph and register it (`--database-url` direct, or `--node ` over HTTP) |
| `kasgraph status ` | Report a deployed subgraph's registry state |
| `kasgraph remove ` | Soft-remove a subgraph (the gateway stops serving it) |
| `kasgraph mcp-config` | Emit an MCP server config for Claude / Cursor / OpenClaw |

## Subgraph model

Same developer experience as The Graph, with Kaspa-native primitives:

```yaml
specVersion: 0.1.0
name: my-kasbonds-subgraph
schema:
  file: ./schema.graphql
dataSources:
  - name: KasBonds
    network: kaspa-mainnet
    kind: covenant_id
    source:
      ids:
        - "0xabc..."
        - pattern: "opensilver.escrow.milestone"
    mapping:
      file: ./src/mapping.ts
      handlers:
        - event: CovenantLocked
          handler: handleLock
        - event: CovenantSpent
          handler: handleSpent
```

`kind: covenant_id` and `kind: krc721` are native Kaspa primitives. Also supported: `kind: krc20`, `kind: address`, `kind: utxo`.

## Configuration

The indexer node is configured by environment variable. The most common:

| Env var | Purpose |
| --- | --- |
| `DATABASE_URL` | Postgres connection string (migrations, registry, per-subgraph schemas, POI) |
| `KASGRAPH_INGEST_MODE` | `bootstrap` (default) or `continuous` |
| `KASGRAPH_NOTIFICATION_WS_URL` | Kaspa wRPC websocket endpoint for continuous ingestion |
| `KASGRAPH_RPC_PRIMARY_URL` / `KASGRAPH_RPC_BACKUP_URLS` | Primary + comma-separated failover RPC endpoints |
| `KASGRAPH_RELOAD_INTERVAL_SECS` | Re-read the registry every N seconds to pick up deploys without a restart (`0` = off) |
| `KASGRAPH_WORK_DIR` | Where deployed mappings are materialized from the registry |
| `KASGRAPH_SUBGRAPH` | Single-subgraph fallback id when the registry is empty (dev) |
| `KASGRAPH_SUBGRAPH_DIR` | Single-subgraph fallback: load a locally-built dir instead of the registry (dev) |
| `KASGRAPH_DEPLOY_TOKEN` | Bearer token required for hosted `POST /subgraphs` and `DELETE /subgraphs/:id`; leave unset only for local/dev |
| `KASGRAPH_ENVIRONMENT` | Operational label returned from `/status`, for example `local` or `testnet` |
| `KASGRAPH_NETWORK` | Kaspa network label returned from `/status`, for example `kaspa-testnet-10` |
| `KASGRAPH_API_VERSION` | Optional API version override returned from `/status` |
| `KASGRAPH_CORS_ORIGINS` | Comma-separated browser origins allowed by the API wrapper |
| `KASGRAPH_RATE_LIMIT_PER_MINUTE` | Simple per-IP HTTP request cap for hosted API deployments (`0` disables) |

The gateway / CLI deploy target accepts `--database-url` (direct) or `--node ` / `KASGRAPH_NODE_URL` (hosted HTTP endpoint). Public hosted nodes must set `KASGRAPH_DEPLOY_TOKEN`; clients send `Authorization: Bearer ` for deploy/remove writes. The continuous driver exposes additional `KASGRAPH_CONTINUOUS_*` backoff/channel knobs; see `crates/kasgraph-node` for the full set.

Hosted API operators should expose only intended read routes publicly and keep write routes protected. Endpoint docs and production gates live in [`docs/hosted-api.md`](docs/hosted-api.md), [`docs/mainnet-readiness.md`](docs/mainnet-readiness.md), [`docs/runbook.md`](docs/runbook.md), and [`docs/monitoring.md`](docs/monitoring.md).

Live testnet soak monitoring is prepared through `/soak/status`, `/soak/metrics`, `/soak/events`, `/soak/logs`, and `/soak/summary`; see [`docs/live-soak-dashboard.md`](docs/live-soak-dashboard.md) and [`docs/sustained-run-operator-guide.md`](docs/sustained-run-operator-guide.md).

Operational inspection commands:

```bash
npx kasgraph health --node http://localhost:4000
npx kasgraph index status --node http://localhost:4000 --json
npx kasgraph poi latest --database-url "$DATABASE_URL"
npx kasgraph db stats --database-url "$DATABASE_URL" --json
npx kasgraph rpc status --node http://localhost:4000
```

`kasgraph logs tail`, `kasgraph poi verify`, `kasgraph poi compare`, and detailed `kasgraph index inspect` remain pending until protected hosted log and checkpoint-range backends exist.

## Repo map

| Path | What's in it |
| --- | --- |
| `crates/kasgraph-node/` | The indexer binary: ingest, detect, map, persist, POI, multi-subgraph fan-out, registry reload |
| `crates/kasgraph-rpc/` | Multi-RPC client: failover, health probes, continuous wRPC subscription + recovery |
| `crates/kasgraph-store/` | Postgres adapter: migrations, per-subgraph schemas, deployed-subgraph registry, reorg-safe unwind |
| `crates/kasgraph-detectors/` | Built-in pattern detectors (OpenSilver, KCC20, KRC-20/721) + ledgers |
| `crates/kasgraph-mapping/` | wasmtime mapping runtime for AssemblyScript handlers |
| `crates/kasgraph-poi/` | Proof of Indexing: blake2b-256 per-block hash chain + verifier |
| `crates/kasgraph-stream/` | KasStream streaming primitive |
| `sdk/` · `cli/` · `api/` · `mcp/` | `@kasgraph/{sdk,cli,api,mcp}` TypeScript packages |
| `as-mapping/` | `@kasgraph/as-mapping` AssemblyScript SDK for subgraph mappings |
| `examples/` | Six reference subgraphs (KasBonds, OpenSilver patterns, KRC-20, KRC-721, network stats, ZK proofs) |
| `docs/references/` | Reference docs: Kaspa RPC, KIP-20, KRC-20/721, BlockDAG reorgs, The Graph compatibility |
| `tests/` | Vitest workspace test suite |
| [`PLAN.md`](PLAN.md) · [`STATUS.md`](STATUS.md) | Implementation framework + live status |

## Documentation

| Topic | Doc |
| --- | --- |
| Index by Covenant ID | [`docs/references/KIP20_COVENANT_ID_QUERIES.md`](docs/references/KIP20_COVENANT_ID_QUERIES.md) |
| Reorg semantics on a BlockDAG | [`docs/references/BLOCKDAG_REORG_SEMANTICS.md`](docs/references/BLOCKDAG_REORG_SEMANTICS.md) |
| The Graph manifest compatibility | [`docs/references/THEGRAPH_REFERENCE.md`](docs/references/THEGRAPH_REFERENCE.md) |
| Native KRC-20 / KRC-721 shape | [`docs/references/KRC20_KRC721_REFERENCE.md`](docs/references/KRC20_KRC721_REFERENCE.md) |
| Kaspa RPC layer | [`docs/references/KASPA_RPC_REFERENCE.md`](docs/references/KASPA_RPC_REFERENCE.md) |

## Testing

```bash
npm run verify                # full suite: typecheck + vitest + cargo test --workspace
npm run typecheck             # tsc -b across sdk/cli/api/mcp
npx vitest run                # TypeScript tests
cargo test --workspace        # Rust tests
```

Real-Postgres integration coverage is feature-gated so the default suite needs no database. To run it against a local Postgres:

```bash
# Rust (per crate): cargo test -p kasgraph-store --features integration-pg
# TS end-to-end:    DATABASE_URL=postgres://... npx vitest run e2e-deploy-query
DATABASE_URL=postgres://kasgraph:kasgraph@127.0.0.1:5434/kasgraph npm run verify
```

## Design principles

- Core indexer in **Rust** for performance; **TypeScript** SDK + CLI for developer experience.
- Subgraph manifests compatible with **The Graph** where reasonable; schemas in standard **GraphQL SDL**.
- Storage on **PostgreSQL**; real-time updates over **WebSocket** subscriptions and the **KasStream** primitive.
- **MCP server live simultaneously with GraphQL**, not a future addition.
- **MIT licensed, public from the first commit.**

## Performance targets

These are design targets, not yet benchmarked under production load:

- Indexing latency: within **30 seconds** of chain tip at p99.
- GraphQL query latency: p95 under **200 ms**, p99 under **500 ms**.
- Streaming latency: **sub-second** from chain tip to consumer.
- Concurrent subgraphs per node: **100+**.

## Contributing

PRs welcome. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) first; [`PLAN.md`](PLAN.md) lists every phase's deliverables. Security reports: see [`SECURITY.md`](SECURITY.md).

## License

[MIT](LICENSE).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [trillskillz](https://github.com/trillskillz)
- **Source:** [trillskillz/KasGraph](https://github.com/trillskillz/KasGraph)
- **License:** MIT
- **Homepage:** https://kasgraph.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-trillskillz-kasgraph
- Seller: https://agentstack.voostack.com/s/trillskillz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.