docs/api-and-services.mdpinned to impactium@637886d

API & services

Impactium's read surface lives off-chain: two services — Karma and the resource gateway — that a dApp, dashboard, or AI agent talks to instead of the consensus nodes. Neither is a source of truth. The chain's committed state is the authority. Independent verification is the design: the store can produce ICS23 proofs and Karma can verify supplied proofs, but the node's query API does not yet deliver them. A successful read is not, by itself, a cryptographically verified answer.

Karma — the GraphQL read API

Karma exposes the Hive-Knowledge Graph through a single typed endpoint (POST /graphql) whose schema mirrors the graph ontology. It is a disposable projection: delete it and it rebuilds byte-for-byte by replaying the chain's event stream, so it is free to evolve and free to move fast — nothing of value lives only in it.

Its read queries expose records and their provenance:

  • memberHistory(entityId) — a member's full impact history: the capsules they minted, all of their claims (failed claims kept as first-class, queryable nodes — never filtered out), and the 0TRUECOST resources they delivered. Filter with scope (INWARD | OUTWARD), verificationTier (SELF_LOGGED | NOTARIZED), and schemaVersionMin, so a consumer — especially an AI — can weight what it reads by how it was verified.
  • downline(entityId) — the referral walk Entity → SPAWNED* → capsules: every descendant reachable through the Chain of Impact, depth-ordered, each carrying the capsules it minted. This is the question the referral model exists to answer.
  • capsuleLookup(id, lookupParty) — the second valuation event. Minting records what the minter guessed a capsule was worth, frozen at mint; a lookup asks what it is worth now, to a particular party. lookupParty is not a label: it gates which walk detail you may see, so the same capsule can read differently to different askers. Returns the record, the valuation (its bonus components, the paramVersion and graphHeight it was computed at, and whether the walk was truncated — a truncated reading is a lower bound, not the whole graph), the scopeMatrix, and the Impact-Stamp: an SVG portrayal of the walk, with v0Flags naming the inputs not yet wired so a provisional stamp never reads as a finished one.
  • provenance(kind, id) — for any fact, its four provenance properties (root, blockHash, txHash, schemaVersion): the anchor you escalate to a proof.

The scope filter is the perspectival knob: inward (impact on self) versus outward (impact on society). What a record is worth is relational and temporal, so a lookup is always answered from the asking party's vantage — and a scope you are not permitted to walk returns the total without the detail rather than failing or lying.

proofPath(kind, id) identifies the on-chain storageKey and partition root for a supported record. It locates the state to verify; it does not return a proof. Today /abci_query serves state values but does not honor prove=true: its responses contain no proof operations. The store's proof-generation capability has not yet been connected to that query path.

The standalone verifier — ledgerd verify <root_hex> <storageKey> <value> <proof_file> — can check an ICS23 proof supplied separately against a trusted committed state root. Until query proof delivery is wired, this is not a complete API flow from a Karma fact to a node-supplied proof.

Covered kinds today are capsule and release; anything else, including entity and product, returns null rather than a fabricated path, because a plausible-looking key the chain never wrote would fail verification while looking like a Karma bug. Note the two shapes differ — capsule/{root}/{id} carries a partition root and resource/release/{product}/{version} does not — because that is what the chain actually committed: partitioning is not yet universal across modules.

Supporting queries back the dashboard and catalog: entities, articles and articleHistory (the Constitution's K-ladder and its deliberation record), resources and resourceRelease, a generic node(kind, id), and indexedHeight for freshness. Depth and complexity caps guard against the deep traversals agents naturally compose.

The resource gateway

The same service serves Chain Resources — the bytes behind on-chain release manifests. The graph answers what exists; the gateway serves the content, and every chunk is verified against its on-chain content hash before it leaves the process, then verified again by the consumer against the chain-committed manifest.

  • GET /resource/{product}/{version} — a whole artifact, reassembled and chunk-verified.
  • GET /resource/chunk/{hash} — one verified chunk by content id.

The gateway also speaks npm. Point a scope at it in .npmrc:

@your-scope:registry=http://<gateway>/npm/

npm install then resolves the packument (/npm/{name}) and tarball (/npm/{name}/-/{file}.tgz) straight from the chain. Package identity is read from each artifact's own package.json (the chain stays npm-agnostic), integrity (sha512) and shasum are recomputed over the chunk-verified bytes so npm re-verifies every install end-to-end, and on-chain deprecation flags surface as npm deprecation warnings — visible, never hidden.