dd-explain-mcp

DigiDollar transaction explainer — a read-only MCP server (stdio) and CLI that tells an AI agent what a DigiDollar transaction recorded in DigiByte actually did: mint, transfer, or redemption; amounts in cents; lock tier and maturity; what was burned; whether collateral was released. Built on dgb-digidollar-codec, the same decoder that reconciled DigiDollar's first mainnet week to the node to the cent. Zero other dependencies. Node 18+.

Human version of the same thing: dgbinsights.com/lookup.

Install

npm install
npm test                       # 19 offline tests against bundled fixtures

Use

node bin/dd-explain.js <txid>                      # offline: bundled fixtures only
ALLOW_NETWORK=1 node bin/dd-explain.js <txid>      # live: digiexplorer.info
node bin/dd-explain.js --decode 6a0244440103021027 # decode an OP_RETURN script
node bin/dd-explain.js <txid> --json

MCP (stdio) — add to your client's server list:

{ "dd-explain": { "command": "node", "args": ["/path/to/dd-explain-mcp/bin/dd-explain-mcp.js"], "env": { "ALLOW_NETWORK": "1" } } }

Tools: explain_digidollar_tx(txid) and decode_dd_opreturn(scriptPubKeyHex). Network access is off by default; the source field of every answer says whether it came from a bundled fixture or the live explorer.

What it computes that an explorer does not

The DigiDollar record in a redemption declares the change the redemption re-creates, not the burn. This tool values the consumed DD inputs one hop back — from the records of the transactions that created them — and reports burn = consumed − change, with the creating transactions listed. Fixtures for the creating transactions of the bundled redemption are included, so the example below computes fully offline; where a creating transaction is unreachable, the burn is reported as Unverified rather than guessed. Example:

34c67c35…  consumed $201.00 · change $100.00 · burn $101.00   (explorer shows "Burn $100.00")
58f910ce…  consumed $520.00 · change $100.00 · burn $420.00   (explorer shows "Burn $100.00")

That discrepancy is raised with DigiByte Core in Discussion #446.

Vocabulary

Output uses only factual phrasing — "recorded in DigiByte transaction", "included in block N", "timestamped commitment", "consensus type byte" — and marks every inference Unverified. The words proof, verified, notarized, immutable, authentic are refused by a check on the emitted text. Facts and hashes only; no address, entity, or reputation labels.

Layout

See ARCHITECTURE.md. The codec owns every decoding rule; src/explain.js owns the explanation, the burn math, and the fence.

Provenance

Scaffolded by Michael Emery's Grok-based build agent from a written spec, then reviewed, patched (one-hop burn valuation), and tested in the DGB Tools lane. Describes DigiByte Core v9.26.5 behaviour as of September 2026. Part of dgb-tools — independent community tooling, not affiliated with the DigiByte Foundation. MIT.