origintrail/dkg/dkg-node

DKG V10 Node Skill

You are connected to an OriginTrail Decentralized Knowledge Graph (DKG) V10 node. Use the agent context pack for task procedures and completion evidence. For exact operations, use this installed skill and your runtime's discovered tool schemas; the website may describe newer features.

1. Node Info

This section is dynamically generated from node state at serve-time.

• Node version: {{nodeVersion}}
• Base URL: {{baseUrl}}
• Peer ID: {{peerId}}
• Node role: {{nodeRole}}
• Available extraction pipelines: {{extractionPipelines}}

If the Node UI injects a target context graph for the turn, use that target directly. If no target is injected or configured, call dkg_list_context_graphs / GET /api/context-graph/list; agent tool surfaces default that list to the caller's created/joined context graphs, with scope: "all" for every graph the node knows about.

Context Graph IDs

For write or mutation routes, always pass the injected target context graph id, an exact existing context graph id from dkg_list_context_graphs / GET /api/context-graph/list, or the full did:dkg:context-graph:<id> URI.

• A context graph created locally can have a bare canonical id, for example

local-notes, with full URI did:dkg:context-graph:local-notes.

• A joined or curated context graph can have a curator-scoped canonical id, for

example 0x1234567890abcdef1234567890abcdef12345678/team-notes, with full URI did:dkg:context-graph:0x1234567890abcdef1234567890abcdef12345678/team-notes.

Do not guess from the display name, shorten a curator-scoped id, or pass only a suffix slug such as team-notes when the listed id is 0x.../team-notes. Write routes reject unknown, ambiguous, or non-canonical targets before writing so they cannot accidentally create shadow context graphs.

1a. Operating the node (install, update, troubleshoot)

Before reasoning about install state, run `dkg doctor`. Detects orphan repository clones, version skew between the daemon and the global dkg CLI, served-UI / source mismatch, broken plugin install roots, and other install-layout anomalies. Use dkg doctor --json for a machine-parsable report; the state field always carries the full diagnostic snapshot (daemon entry point, install mode, node role, dkg-home, current version + commit, auto-update settings) independent of any anomaly findings.

Updating DKG:

• The canonical update verb is dkg update. It resolves the next release from the npm registry and applies it.
• Do not `git pull`. Do not clone the repository. Do not edit files under ~/.dkg/releases/ (on Core nodes — Edge nodes have no ~/.dkg/releases/ at all under RFC-41).
• If dkg doctor reports orphan clones at ~/dkg/, ~/Projects/dkg/, or similar, ask the operator before touching them — they are not the running daemon.
• dkg update --check previews the available version without applying.
• dkg update --allow-prerelease allows published prerelease channels when the network policy permits.
• dkg rollback reverts to the previous version (Edge: re-installs the prior npm version recorded in ~/.dkg/previous-version; Core: flips the blue-green slot symlink).

Detecting current install state:

• dkg --version — the global CLI's version.
• curl http://127.0.0.1:9200/api/status | jq '{version, commit, commitShort, buildTime, distTag, installMode, nodeRole}' — the running daemon's version, commit, and install mode. Mismatch between dkg --version and the daemon's version is the §1a version-skew condition; dkg doctor reports it explicitly.
• cat ~/.dkg/config.json | jq .nodeRole — edge (default; daemon runs from npm-global install, no release slots) or core (operator opted into blue-green slots via dkg init --role core).

Troubleshooting common confusion:

• "There seem to be multiple DKG installations on this machine" → run dkg doctor; the state.cli.globalPath, state.daemon.entryPoint, and orphan-repos check together identify the canonical install and any stray clones.
• "The UI shows an old version even after I updated" → run dkg doctor; the served-UI / source-mismatch check flags stale browser / PWA / service-worker caches.
• "I ran npm install -g @origintrail-official/dkg@latest but the daemon still reports the old version" → on Edge nodes, run dkg stop and then dkg start so the daemon picks up the new install. On Core nodes, the slot mechanism gates the visible version on dkg update's atomic swap, not on npm install -g directly — use dkg update for Core nodes.
• "Publishing or context-graph registration intermittently fails with an RPC/503 error" → the node uses multiple chain RPC endpoints with automatic failover. Each supported network ships a curated set of public RPCs: chain.rpcUrl is the primary and chain.rpcUrls is an ordered list of backups. A transient failure (rate-limit/timeout/network) on one endpoint silently fails over to the next; on-chain reverts and other application errors do not trigger failover. A 503/504 from a publish/register/identity/PCA route means every configured endpoint was exhausted — retry, or add a faster/private endpoint. Configure backups via chain.rpcUrls in ~/.dkg/config.json or the "Backup RPC URLs" prompt in dkg init. Precedence: an operator-set chain.rpcUrls replaces the network defaults; setting only a private chain.rpcUrl keeps the public defaults as failover (set "rpcUrls": [] to opt out). A wrong-chain backup fails the node loudly at startup (provider network-mismatch), never silently. Inspect failover activity at GET /api/status → chain.rpcFailovers / chain.rpcExhaustions / chain.rpcFailoversByClass, and per-endpoint reachability at GET /api/chain/rpc-health.
• "Background catalog work is consuming too much RPC capacity" → every outbound request, retry, and fallback is governed by one process-wide budget shared by the agent and publisher wallets. The defaults are 10 requests/second total, an 80% foreground reserve (2 requests/second maximum for background RFC-64 work), a 20-request burst, a 256-request bounded queue, and up to 30 seconds of background startup jitter. Override individual values under chain.rpcRequestBudget in ~/.dkg/config.json: maxRequestsPerSecond, foregroundReservePercent, burstRequests, maxQueueSize, and startupJitterMs. Inspect the minutely rpc_request_governor structured log for allowances, queues, deferrals, rejections, and admissions; inspect GET /api/status → rfc64Catalog.authorityRpcCircuit and rfc64Catalog.contextGraphs for authority cooldown and per-CG freshness.

The current operator guidance lives in Updates & Rollback.

2. Capabilities Overview

Note: This skill describes the current DKG V10 API surface. Availability

can vary with the installed node version. Call GET /api/status to check the

version, use dkg <command> --help for its CLI surface, and rely on explicit

error responses when a route is unavailable.

This node provides a three-layer verifiable memory system for AI agents:

What you can do: create knowledge assertions, import files (PDF, DOCX, Markdown), share knowledge with peers, publish to the blockchain, endorse others' knowledge, propose M-of-N consensus verification, query across all memory layers, and discover other agents on the network.

3. Quick Start

Before writing in production, read §6 "Routing: Turn Context Override" — it governs which context graph each turn's operations target.

Canonical Knowledge Asset lifecycle: create a context graph, create an assertion, write triples to WM, finalize (seal) the draft, share to SWM, then publish the sealed assertion to VM — which mints it on chain and returns its UAL (see §5 VM for the response body). Data must be in SWM before VM publishing; the on-chain transaction is a finality signal for data peers already received via gossip.

A full swm/share (entities: "all") seals by default and is then publish-ready, so the explicit wm/finalize step is optional on the happy path. There is no unsealed share: "skipSeal": true is refused with 400 UNSEALED_SHARE_UNSUPPORTED. Sealing no longer needs the CG registered on-chain — finalize/share are entirely off-chain (see §5 "Verifiable Memory").

Registration happens at publish, automatically. A project created with

/api/context-graph/create is local-only; you can create → write → seal → share it

entirely off-chain. The FIRST vm/publish transparently registers the CG on-chain

(costs gas/TRAC) and then mints — no separate register step is required. (You may still

register explicitly via /api/context-graph/register if you prefer.)

curl -X POST $BASE_URL/api/context-graph/create -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"id":"my-project","name":"My Project"}'
curl -X POST $BASE_URL/api/context-graph/register -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"id":"my-project"}'   # OPTIONAL — vm/publish auto-registers on first publish (costs gas/TRAC). finalize/share work without it.
curl -X POST $BASE_URL/api/knowledge-assets -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"contextGraphId":"my-project","name":"notes"}'
curl -X POST $BASE_URL/api/knowledge-assets/notes/wm/write -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"contextGraphId":"my-project","quads":[{"subject":"https://example.org/alice","predicate":"https://schema.org/name","object":"\"Alice\""}]}'
curl -X POST $BASE_URL/api/knowledge-assets/notes/wm/finalize -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"contextGraphId":"my-project"}'
curl -X POST $BASE_URL/api/knowledge-assets/notes/swm/share -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"contextGraphId":"my-project","entities":"all"}'
curl -X POST $BASE_URL/api/knowledge-assets/notes/vm/publish -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"contextGraphId":"my-project"}'   # → { "kaId": "...", "ual": "did:dkg:<chainId>/<kasAddress>/<number>", "txHash": "0x...", ... }
curl -X POST $BASE_URL/api/query -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"sparql":"SELECT * WHERE { ?s ?p ?o } LIMIT 10","contextGraphId":"my-project","view":"working-memory","agentAddress":"YOUR_PEER_ID"}'

CLI equivalents for shell-driving agents:

dkg context-graph create my-project
 
# RDF payload source: <name> is the Knowledge Asset name; --input-file is the local source.
dkg ka create notes -c my-project --input-file ./notes.ttl --share
 
# Document extraction source: import into WM, then finalize/share explicitly.
dkg ka import-file notes-doc -c my-project --input-file ./notes.md
dkg ka finalize notes-doc -c my-project
dkg ka share notes-doc -c my-project
 
# VM publish is always explicit and operates on a named KA already shared to SWM.
dkg ka publish notes-doc -c my-project
dkg ka publish-async notes-doc -c my-project
 
# Recovery/edit loop.
dkg ka pull-from notes-doc -c my-project --layer swm --on-conflict replace
dkg ka query notes-doc -c my-project
dkg ka history notes-doc -c my-project