# 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`](https://github.com/dgb-tools/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](https://dgbinsights.com/lookup).

## Install

```bash
npm install
npm test                       # 19 offline tests against bundled fixtures
```

## Use

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

```json
{ "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](https://github.com/orgs/DigiByte-Core/discussions/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](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](https://github.com/dgb-tools) — independent community tooling, not
affiliated with the DigiByte Foundation. MIT.