Skip to content

feat(spec): add Decred chain spec - #186

Merged
AnnaR-prog merged 8 commits into
mainfrom
decred-spec
Nov 8, 2026
Merged

AnnaR-prog merged 8 commits into
mainfrom
decred-spec

Conversation

@magmadevs-bot

@magmadevs-bot magmadevs-bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

New chain spec: Decred

Phases 1-7 (research → spec draft) are complete. The smart-router
boot/probe and the spec reviews run automatically after this PR opens
(spec_pipeline.yml) and are posted as PR comments.

Field Value
Chain name Decred
Mainnet index DCR
Testnet index DCRT
Spec file dcr.json

Revisions after the 2026-10-07 review

  • ticketvwap, getheaders and gettreasurybalance → deterministic: false. With no arguments each reads the tip: ticketvwap defaults to end = bestHeight, getheaders with an empty hashStop returns headers up to the tip, and gettreasurybalance with no hash reads BestSnapshot() (dcrd internal/rpcserver/rpcserver.go). A true would raise false cross-validation outliers between providers at different heights. gettxoutsetinfo stays true to match btc.json; the two specs should change together.
  • gettreasurybalance and gettreasuryspendvotes: "default_value": "latest" added to block_parsing. Without it a no-argument call parses as NOT_APPLICABLE (ParseRawBlock, smart-router protocol/parser/parser.go), not latest.
  • Body corrected: the CU histogram, auto-decision 10, and the NOWNodes 405 count (33 methods, not 5).

Revisions after the 2026-10-07 Phase 11 review (7d1673c)

  • ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions: compute_units 20 → 500 and timeout_ms: 180000 (Phase 11 MEDIUM-1). Each scans a block range the caller chooses, and dcrd caps none of them (the range can be the whole chain). That is the same class of work as livetickets, ticketsforaddress and getticketpoolvalue.
  • validateaddress, verifymessage, decodescript, createrawtransaction, createrawsstx, getcurrentnet, version, estimatefee: block_parsing DEFAULT ["latest"] → EMPTY [""] (Phase 11 MEDIUM-3). None of them reads chain state. Their deterministic flags are unchanged.
  • createrawssrtx: deterministic true → false (Phase 11 MEDIUM-2, second half). dcrd builds the revocation from the current tip (BestSnapshot().Hash, then HeaderByHash), and that header seeds the PRNG that places the remainder (stake.CalculateRevocationRewards), so the output moves with the tip. btc.json has no such method, so the parity argument below does not apply.
  • Re-tested 2026-11-08 with smart-router v1.6.7 through the keyed NOWNodes mainnet endpoint (key withheld): chain-id verified, chain tracker failed=0. Of the 13 changed methods, validateaddress, decodescript, createrawtransaction and estimatefee answered, and verifymessage returned dcrd's own error for a junk signature. The other 8 get NOWNodes' HTTP 405, like the 33 gated methods below. The router bound all 13 relays to their spec method (no Default-* metric labels).

Revisions after the 2026-11-08 Phase 11 review (d02718a)

  • getnetworkhashps (10 CU), gettreasuryspendvotes (20) and getstakeversioninfo (20) → 500 CU and timeout_ms: 180000, the same rule as the four methods above. dcrd caps none of their scans: getnetworkhashps can walk the whole chain, gettreasuryspendvotes reads up to 3456 full blocks per tspend in a list with no length limit, and getstakeversioninfo can walk about 1.09M block-index nodes.

Human decision: gettxoutsetinfo stays deterministic: true. DO NOT REVERT

Phase 11 MEDIUM-2 (at ce03338) is right that the result carries height and bestblock. The 2026-10-07 human review kept true anyway: the method mirrors btc.json, so both specs change together or neither. That change belongs in a PR that edits btc.json and dcr.json together, outside this PR's scope. This is a settled decision for this PR: a reviewer who still disagrees should record it as advisory for that joint change, not as a finding against this PR.

Inputs provided

Jira: MAG-2961 "Add Decred spec (the customer)" (epic MAG-2888). The ticket asks for mainnet only. DCRT (testnet3) is included because new_chain mode requires a testnet index.

Chain

Decred (DCR): hybrid proof-of-work / proof-of-stake (each block calls 5 tickets; a block needs at least 3 votes approving its parent). Node: dcrd (latest release v2.1.6, 2026-08-18; JSON-RPC API semver 8.3.0). Source: https://github.com/decred/dcrd. RPC docs: https://github.com/decred/dcrd/blob/master/docs/json_rpc_api.mediawiki
Transport: JSON-RPC over HTTP POST / (JSON-RPC 1.0 and 2.0 both accepted; 2.0 batches supported) and WebSocket /ws. Ports: mainnet 9109, testnet3 19109. dcrd serves chain RPCs only; wallet RPCs live in the separate dcrwallet process (out of scope).

Spec shape: standalone, NOT an import of BTC. DO NOT REVERT (record in the PR body)

dcrd is a btcd descendant, but its RPC surface diverges from bitcoind's:

  • 12 of btc.json BTC's 34 methods do not exist in dcrd: getblockstats, getchaintxstats, getindexinfo, getmemoryinfo, getmempoolancestors, getmempooldescendants, getmempoolentry, gettxoutproof, verifytxoutproof, submitpackage, testmempoolaccept, getblockfilter (dcrd has getcfilterv2 instead).
  • Parameter shapes differ on shared methods (rpc/jsonrpc/types/chainsvrcmds.go):
    • getblock(hash, verbose bool = true, verbosetx bool = false), not an integer verbosity.
    • getrawtransaction(txid, verbose int = 0), at most 2 params; BTC's PARSE_BY_ARG ["2"] block parsing points at a param dcrd does not have.
    • gettxout(txid, vout, tree int8 REQUIRED, includemempool).
    • sendrawtransaction(hex, allowhighfees bool).
    • getrawmempool(verbose, txtype string).
  • BTC's REST collections, the blockdaemon add-on and BTC's chain-id value ("main") do not apply.
  • dcrd has about 55 methods BTC lacks; the ones worth declaring include getbestblock, getcurrentnet, getinfo, version, getnetworkinfo, existsaddress, existsaddresses, existsmempooltxs, existsliveticket(s), getcfilterv2, getheaders, getcoinsupply, getblocksubsidy, txfeeinfo, ticketfeeinfo, estimatefee, getstakedifficulty, estimatestakediff, getstakeversions, getstakeversioninfo, getvoteinfo, livetickets, ticketsforaddress, ticketvwap, gettreasurybalance, gettreasuryspendvotes, getmixmessage, getmixpairrequests. Take the authoritative list and param shapes from chainsvrcmds.go.
  • Verbose getblock has two transaction trees (tx and stx) plus powhash, which differs from hash since DCP0011 moved PoW to BLAKE3.

Status: honoured in full. DCR ships with no imports and 59 of its own apis. None of the 12 absent methods was emitted. getrawtransaction carries DEFAULT ["latest"], not BTC's PARSE_BY_ARG ["2"]. No REST collection, no blockdaemon add-on, and the chain-id value is the genesis hash rather than "main". DCRT carries imports: ["DCR"] — the canonical mainnet→testnet pattern (btc.json's BTCT, iota.json, the whole catalog); the standalone mandate is about not importing BTC, which is honoured.

Live-verified 2026-10-06 (mainnet, through a keyed NOWNodes endpoint; the key is NOT part of this spec or PR)

  • getblockchaininfo: chain = "mainnet", blocks 1,121,269, syncheight = blocks, initialblockdownload false.
  • getblockhash [0] = 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980 (the mainnet genesis).
  • getblockcount, getrawmempool and estimatesmartfee (result field feerate) answer normally.
  • The NOWNodes gateway answers "Method Not Allowed" (HTTP 405) for 33 of the 59 declared methods, among them version, getbestblock, getstakedifficulty, existsaddress, getcurrentnet and all the ticket-pool scans (corrected 2026-10-07; this line first named only 5). That is the provider's whitelist, not absence: dcrd registers all of them. Never disable a method because of it. Those 33 have no live answer.
  • No public dcrd JSON-RPC works without a key (drpc, publicnode, Tatum, Ankr, GetBlock: none serve Decred), and the public testnet services (testnet.dcrdata.org, testnet.decred.org) were down. CI's Phase 8 therefore has no public endpoint for either network. A maintainer will post a local verification run against the keyed provider (key withheld) as a PR comment. Do not invent endpoints, and do not list an explorer API in the PR body's ENDPOINTS block as if it were an RPC.

Status: honoured. All 33 whitelisted-out methods ship enabled and are carried on the watch-list below. Zero methods are disabled anywhere in the file. The ENDPOINTS block below is intentionally empty on both lines — no endpoint was invented and no explorer API is listed as an RPC. The two reachable dcrdata mirrors were used only to corroborate the genesis hash and block timing, and are labelled as explorer corroboration, never as RPC.

Chain identity (DO NOT REVERT)

  • Use the genesis hash: getblockhash [0] → mainnet 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980, testnet3 a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac (testnet value from source: decred/tinydecred nets/testnet.py and dcrdata rpcclient tests). getblockchaininfo.chain = "mainnet" is not unique: btcd (Go Bitcoin) also reports "mainnet".
  • getcurrentnet returns mainnet 3652452601 / testnet3 2979310197 (wire/protocol.go). The RPC docs list mainnet as 3652501241, which is Bitcoin's magic copied from btcd: do not use that value.

Status: honoured. The chain-id verification pins on getblockhash [0], not on getblockchaininfo.chain. Both magics were independently re-confirmed against wire/protocol.go (mainnet MainNet CurrencyNet = 0xd9b400f9 = 3652452601; testnet3 TestNet3 = 0xb194aa75 = 2979310197), and the mediawiki's 3652501241 was confirmed to be Bitcoin's btcd-inherited magic. No getcurrentnet verification was added — one identity pin suffices, and getcurrentnet is one of the methods the only reachable gateway refuses, so it is unverifiable today.

Parse directives

  • GET_BLOCKNUM: getblockcount → result. GET_BLOCK_BY_NUM: getblockhash [%d] → result (same shapes as BTC).
  • GET_EARLIEST_BLOCK and archive: decide from dcrd's storage model.

Status: honoured. Both directives ship with PARSE_BY_ARG ["0"]; their function_template strings hash byte-identical to btc.json's (verified by compare_spec_directives.sh — getblockcount and getblockhash are the two methods where dcrd and bitcoind agree on both name and arity). GET_EARLIEST_BLOCK is omitted, resolved from dcrd's storage model — see auto-decision #1.

Ticket-mandated and measured values: DO NOT REVERT (record each one in the PR body's do-not-revert section)

  1. DCR block_distance_for_finalized_data = 6. The customer's table gives a fixed depth of 6 blocks, which also matches the customer's public deposit page ("6 confirmations, 30 min"). A fixed customer depth maps 1:1 onto the field (open PR chore(specs): raise block_distance_for_finalized_data and apply operator finality windows #111's convention).
  2. DCRT block_distance_for_finalized_data = 6 as well (same rule; the testnet is not a customer requirement).
  3. blocks_in_finalization_proof = 3 on both. Finality is probabilistic: chain selection is most-work, dcrd deliberately reorgs a vote-starved tip by one block, and 167 one-block side chains are recorded on dcrdata. There is nothing like Dash's ChainLocks.
  4. average_block_time: DCR 300000 (5 min target; measured mean 313.3 s over 2,000 blocks), DCRT 120000 (testnet3 targets 2 min per chaincfg/testnetparams.go; not measurable today). allowed_block_lag_for_qos_sync = 1 on both.

Status: all four shipped verbatim. jq confirms on both entries: block_distance_for_finalized_data: 6, blocks_in_finalization_proof: 3, allowed_block_lag_for_qos_sync: 1; average_block_time 300000 (DCR) / 120000 (DCRT). Corroborated from source this run: chaincfg/mainnetparams.go TargetTimePerBlock: time.Minute * 5 and chaincfg/testnetparams.go TargetTimePerBlock: time.Minute * 2. An independent lifetime-mean check (genesis ts 1454954400 → height 1,121,271 @ ts 1791288638) gives 299.96 s/block, agreeing with the 300000 ms target to within 0.02%; the 313.3 s 2,000-block mean and two 100-block samples (321.4 s, 353.1 s) all sit modestly above target, as expected for Decred. No >20% disagreement, so no block-time gate was triggered.

Category rules

  • sendrawtransaction is the transaction submit: category stateful: 1 and hanging_api: true (same rule as MAG-4035). submitblock and sendrawmixmessage are also writes; mark them stateful.
  • WebSocket-only notification methods (notifyblocks, notifynewtransactions, loadtxfilter, rescan, notifywinningtickets, notifynewtickets, notifytspend, notifymixmessages, session, authenticate) are not HTTP methods; model them only as subscriptions if you model subscriptions at all.

Status: honoured. Exactly three apis carry stateful: 1 — sendrawtransaction, submitblock, sendrawmixmessage — each with hanging_api: true and an explicit timeout_ms: 10000 (the flag alone only adds 2 * average_block_time; btc.json's own sendrawtransaction ships this gap and it was deliberately not copied). Every other api is stateful: 0. The WebSocket-only family is omitted entirely — see auto-decision #2.

Gateway gating is not absence

These errors are gateway gating, NOT evidence that a method is absent: -32601 on one provider while another serves it, -32401 "auth required", -32005 rate limits, drpc code 35 "not available on free plan". Never disable anything because of them; record which provider serves each method.

Status: honoured — zero disabled entries in the file (<!-- disabled-count: 0 -->). Provider coverage: the keyed NOWNodes mainnet endpoint is the only RPC known to serve Decred at all, and it serves getblockchaininfo, getblockhash, getblockcount, getrawmempool and estimatesmartfee while whitelisting out version, getbestblock, getstakedifficulty, existsaddress and getcurrentnet. No other provider serves Decred.

Sources used

  • Upstream parent spec: none. DCR is standalone (imports absent) per the do-not-revert mandate. btc.json was used as a convention template only — CU bands (10 / 20 / 500+timeout_ms), category-flag conventions, the PARSE_BY_ARG idiom, the 2-directive shape and the spec-entry key order — never as an import and never as an api-list source. kaspa.json (the repo's only standalone non-EVM spec) was the reference for pinning identity on a block hash. DCRT imports DCR.

Calculations table

Parameter Source Formula Computed value
average_block_time docs canonical, tie-broken against empirical (rule 1: single docs value, empirical within 20%) — chaincfg/mainnetparams.go TargetTimePerBlock: time.Minute * 5; chaincfg/testnetparams.go time.Minute * 2 — DCR 300000 ms / DCRT 120000 ms
block_distance_for_finalized_data ticket-mandated (the customer's fixed depth, "6 confirmations, 30 min"); consistent with the PoW band 6–12 — 6 (both)
blocks_in_finalization_proof finality-typed: probabilistic — most-work chain selection, dcrd deliberately reorgs a vote-starved tip by one block, ~167 one-block side chains on dcrdata, no ChainLocks-style gadget 3 (probabilistic) 3 (both)
allowed_block_lag_for_qos_sync derived; also ticket-mandated, and the two agree max(ceil(10000 / 300000), 1) = 1; max(ceil(10000 / 120000), 1) = 1 1 (both)

Empirical corroboration of average_block_time (mainnet): lifetime mean from genesis ts 1454954400 → height 1,121,271 @ ts 1791288638 = 299.96 s/block (0.02% from the 300 s target); 2,000-block mean 313.3 s; two 100-block samples 321.4 s and 353.1 s. All above-target drift, which is normal for Decred. Deviation from docs < 20%, so the docs value was locked and no disagreement gate fired. DCRT was not measurable (no reachable testnet endpoint) so its 2-minute protocol target was used.

⚠️ Auto-decisions made (review these)

No human was available, so every gate below was auto-resolved with the conservative default and is recorded here.

  1. Archive extension: OMITTED on both DCR and DCRT — and with it the whole indivisible triplet (no archive extension, no pruning verification, no GET_EARLIEST_BLOCK directive; extensions: []). The archive-researcher returned status: OK (not NEEDS_HUMAN_DECISION), so this was a researched conclusion rather than a coin-flip, but it resolves the ticket's open question "GET_EARLIEST_BLOCK and archive: decide from dcrd's storage model". Evidence: dcrd's config.go contains no block-pruning flag of any kind (the only storage flags are --txindex, --droptxindex, --noexistsaddrindex, --dropexistsaddrindex); the README states dcrd "maintains the entire past transactional ledger of Decred" with disk use only growing (~2.5 GB/yr); docs.decred.org's full-node page documents no pruning or archive tier; and NOWNodes offers only one Decred node tier. Archive-vs-full is therefore not a meaningful Decred distinction. Both live probes were honestly recorded as skipped (no keyless endpoint) rather than faked. Deliberately not copied: the uncalibrated rule.block: 42600 that doge.json, litecoin.json, dash.json and bch.json all carry.
  2. Subscriptions: NOT modelled; the 17 WebSocket-only methods are omitted. The ticket says to model them "only as subscriptions if you model subscriptions at all", and a method is a subscription IFF it carries a FUNCTION_TAG_SUBSCRIBE directive. Declaring a ws interface that cannot be probed (there is no reachable endpoint, keyed or otherwise, for ws) is the riskier option, so the conservative default was taken: no ws collection, no SUBSCRIBE/UNSUBSCRIBE directives, and the 17 names absent from apis. Omission reason: platform-specific — each is registered UFWebsocketOnly in chainsvrwscmds.go and present in wsHandlersBeforeInit, but absent from the HTTP handler map rpcHandlersBeforeInit, so none is reachable over the HTTP POST collection this spec declares. Names: authenticate, loadtxfilter, notifyblocks, stopnotifyblocks, notifywork, stopnotifywork, notifytspend, stopnotifytspend, notifynewtransactions, stopnotifynewtransactions, notifynewtickets, notifywinningtickets, notifymixmessages, stopnotifymixmessages, rebroadcastwinners, rescan, session. If Lava wants Decred subscriptions, this is the decision to revisit — the surface is real and fully enumerated above.
  3. 18 operator/admin methods omitted (reason: admin-only, an allowed omission under the skill's scope rule). 17 of the 18 are absent from dcrd's rpcLimited map, i.e. they need full rpcuser credentials rather than the rpclimituser tier a Lava provider would expose. Node control: stop, node, addnode, getaddednodeinfo, debuglevel, startprofiler, stopprofiler, ping. Chain surgery: invalidateblock, reconsiderblock, regentemplate, verifychain. Legacy solo-CPU-mining control: generate, setgenerate, getgenerate, getwork, gethashespersec. Introspection: help. An add_on: "admin" collection was considered and rejected — omitting a surface we cannot probe is the conservative choice.
  4. Seven read-only informational methods KEPT in the base collection despite being outside rpcLimited: getconnectioncount, getmempoolinfo, getmininginfo, getpeerinfo, getticketpoolvalue, gettreasuryspendvotes, gettxoutsetinfo. They are reads, not node control, and btc.json keeps its equivalents (getconnectioncount, getmempoolinfo, gettxoutsetinfo) in its base collection. A provider running limited-tier credentials may see these rejected — worth a reviewer's eye.
  5. getrawtransaction kept in the BASE collection, not behind a txindex add-on. dcrd's --txindex defaults to false and gates getrawtransaction for confirmed non-mempool txs (handler returns "the transaction index must be enabled to query the blockchain (specify --txindex)"), which is a genuine argument for an add-on. Rejected because bitcoind has the identical -txindex requirement and btc.json keeps the method in base; gating the chain's primary transaction read would leave the base spec unable to read a transaction at all. Treated as a provider node-configuration requirement (providers must run --txindex) rather than an opt-in API tier. This is the most debatable call in the spec.
  6. No add-on collections at all. Beyond --txindex, dcrd's other capability gates do not warrant one: the exists-address index is on by default (defaultNoExistsAddrIndex = false, opt out via --noexistsaddrindex) so existsaddress/existsaddresses are base; getcfilterv2 has no gating flag (GCS v2 filters are structurally mandatory post-DCP0005) so it is base; mixing (getmixmessage, getmixpairrequests, sendrawmixmessage) and treasury (gettreasurybalance, gettreasuryspendvotes) have zero gating flags in config.go and are chain-state gated only, so they are base.
  7. DCRT carries imports: ["DCR"]. The ticket's standalone mandate is explicit about not importing BTC but silent on the mainnet→testnet self-import. The canonical catalog pattern (btc.json's BTCT, iota.json, and the lean-testnet shape the skill documents) was taken as the conservative default: DCRT declares apis: [], parse_directives: [], and overrides only the chain-id expected_value.
  8. The chain-id live-curl pre-flight was skipped on both networks — no keyless endpoint exists, and inventing one is forbidden. Mainnet's value is nonetheless live-verified: getblockhash [0] through the keyed NOWNodes endpoint on 2026-10-06 returned the shipped hash, independently corroborated by two dcrdata mirrors. Testnet3's a649dce5… is source-derived only (decred/tinydecred nets/testnet.py, dcrdata rpcclient tests), partially corroborated by chaincfg/testnetparams.go's genesis timestamp 1533513600 = 2018-08-06 (the current testnet3 reset). Confidence: medium — this is the single value most worth a maintainer's live check. Note testnet3 has been reset before while keeping its name and magic, so a future reset would change this hash.
  9. Zero methods disabled. No method has positive documentary evidence of absence, so nothing was set enabled: false — in particular not the 33 the keyed gateway whitelists out (first counted as five; corrected 2026-10-07). Watch-list (re-probe against a fully-permissioned node): all 33 gated methods, including the five first seen, version, getbestblock, getstakedifficulty, existsaddress, getcurrentnet, and the ticket-pool scans.
  10. CU deviations from the mechanical table, each anchored to an in-production value (flagged so the expected Phase-6 advisory is not mistaken for a defect): gettxoutsetinfo → 500 + timeout_ms: 180000 (btc.json ships exactly this for the identical method; full UTXO-set scan); livetickets, ticketsforaddress and getticketpoolvalue → 500 + timeout_ms: 180000 (each walks the full live-ticket pool, ~41,000 entries; raised from 20 in c6a1592 and 0d4a613 to match gettxoutsetinfo); getblockhash → 10 rather than 20 despite PARSE_BY_ARG (btc.json ships this identical method at 10); four set-scan / range-aggregate methods parsed DEFAULT ["latest"] rated 20 rather than 10 on the getrawmempool precedent (getrawmempool, getheaders, existsaddresses, existslivetickets); and seven uncapped range scans → 500 + timeout_ms: 180000: ticketvwap, ticketfeeinfo, txfeeinfo and getstakeversions (from 20, in 7d1673c), then getnetworkhashps (from 10), gettreasuryspendvotes and getstakeversioninfo (from 20, in d02718a). Two brief-suggested values were reverted to the mechanical table where btc.json offered no same-shaped precedent: getblocksubsidy and gettreasurybalance, both 10 → 20.
  11. Writes given timeout_ms: 10000 (the repo's dominant hanging-api value). dcrd returns on mempool/validation acceptance rather than block inclusion, so this is ample; btc.json's own sendrawtransaction ships hanging_api: true with no timeout_ms and that gap was deliberately not copied.

No STOP-and-ask gate fired beyond these. Archive returned status: OK; the block-time disagreement was 0.02% (far under the 20% threshold); no existing dcr.json or decred.json was present (confirmed across all 131 root spec files, none of which claims DCR or DCRT), so there was no existing-file prompt.

Phase 6 — static gate results

All nine gates PASS; no fixer pass was needed.

Gate Result Note
methods-coverage PASS MISSING set is exactly the 35 pre-justified omissions, no more and no fewer; 0 EXTRA (no hallucinated method)
parse-directive PASS Layers 1–2 run; Layer 2 hashes byte-identical to btc.json's; Layer 3 skipped (no endpoint)
chain-metadata PASS all four network params verified on both entries
verifications PASS both genesis-hash pins well-formed, distinct, lowercase 64-hex
extensions PASS extensions: []; triplet uniformly absent (not mixed)
cu-semantic PASS Layer 0 clean (no subscriptions to violate); one Layer-1 advisory, the deliberate gettxoutsetinfo=500
pruning PASS INFO: retention unknown — no finite window exists; no stray rule.block/latest_distance/cu_multiplier
enabled PASS 0 disabled; 5-method watch-list; none of the 7 non-existent names present
method-schema PASS all 59 apis structurally well-formed; 59/59 unique

Phase 7 gates: jq exit 0; check_unused_fields.sh → RESULT: PASS (no removed fields); check_disabled_count.sh → 0 distinct disabled methods (matches the marker above); internal-path guard N/A (every internal_path is "").

Methods named in earlier briefing material that DO NOT EXIST in current dcrd and were never emitted (source-verified absent from both chainsvrcmds.go and the handler map): getblocktemplate (dcrd has no getblocktemplate and no stratum; mining is legacy getwork), searchrawtransactions (removed with the legacy txbyaddridx index), existsexpiredtickets, existsmissedtickets, notifystakedifficulty, notifyspentandmissedtickets, and estimatepriority (in dcrd's rpcUnimplemented map — errors on every call). The real name is getnettotals, not getnetworktotals.

Supporting evidence (INLINE — do NOT reference file paths)

Parse directives

The DCR collection declares exactly two parse_directives. getblockcount and getblockhash are the two methods where dcrd and bitcoind agree on both name and arity, so these are byte-identical in shape to btc.json's (confirmed by compare_spec_directives.sh: both rows PRESENT, hashes match, no MISSING / EXTRA / HASH-MISMATCH).

"parse_directives": [
    {
        "function_tag": "GET_BLOCKNUM",
        "function_template": "{\"jsonrpc\":\"2.0\",\"method\":\"getblockcount\",\"params\":[],\"id\":1}",
        "result_parsing": {
            "parser_arg": [
                "0"
            ],
            "parser_func": "PARSE_BY_ARG"
        },
        "api_name": "getblockcount"
    },
    {
        "function_tag": "GET_BLOCK_BY_NUM",
        "function_template": "{\"jsonrpc\":\"2.0\",\"method\":\"getblockhash\",\"params\":[%d],\"id\":1}",
        "result_parsing": {
            "parser_arg": [
                "0"
            ],
            "parser_func": "PARSE_BY_ARG"
        },
        "api_name": "getblockhash"
    }
]

GET_BLOCK_BY_NUM returns a genuine block identifier (the block hash), not an echoed height, so data-reliability cross-checks are meaningful. Decred is not a slot-based chain, so no empty-slot handling applies. No GET_EARLIEST_BLOCK — omitted with the rest of the archive triplet (auto-decision #1). No SUBSCRIBE/UNSUBSCRIBE — no declared api name contains ubscribe (auto-decision #2).

chain-id verifications (genesis-hash identity pin)

getblockchaininfo.chain returns "mainnet" on Decred, which btcd also returns — it cannot distinguish a Decred node from a Go-Bitcoin node, so it is unusable as an identity pin. The verification pins on getblockhash [0] instead (kaspa.json is the in-repo precedent for pinning identity on a block hash).

DCR:

"verifications": [
    {
        "name": "chain-id",
        "parse_directive": {
            "function_tag": "VERIFICATION",
            "function_template": "{\"jsonrpc\":\"2.0\",\"method\":\"getblockhash\",\"params\":[0],\"id\":1}",
            "result_parsing": {
                "parser_arg": [
                    "0"
                ],
                "parser_func": "PARSE_BY_ARG"
            },
            "api_name": "getblockhash"
        },
        "values": [
            {
                "expected_value": "298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980"
            }
        ]
    }
]

DCRT (lean inherited form — imports: ["DCR"] merge semantics supply the directive; btc.json's BTCT pattern):

"verifications": [
    {
        "name": "chain-id",
        "values": [
            {
                "expected_value": "a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac"
            }
        ]
    }
]
Spec shape, network params, and the three write methods
DCR  | Decred Mainnet   | enabled=true | imports=none     | collections=1 | apis=59 | unique=59
DCRT | Decred Testnet3  | enabled=true | imports=["DCR"]  | collections=1 | apis=0  | unique=0

Top-level keys: proposal → specs only. Spec-entry key set mirrors btc.json exactly
(index, name, enabled, [imports], block_distance_for_finalized_data, blocks_in_finalization_proof, average_block_time, allowed_block_lag_for_qos_sync, api_collections). Collection: api_interface: "jsonrpc", internal_path: "",
type: "POST", add_on: "", headers: [], inheritance_apis: [], extensions: [].

Archive triplet, both entries — uniformly absent, as intended:

{"index":"DCR","archive_ext":false,"pruning_ver":false,"earliest_directive":false}
{"index":"DCRT","archive_ext":false,"pruning_ver":false,"earliest_directive":false}

The only stateful apis (the chain's three writes), each with an explicit timeout:

sendrawtransaction  stateful=1 hanging=true timeout=10000
submitblock         stateful=1 hanging=true timeout=10000
sendrawmixmessage   stateful=1 hanging=true timeout=10000

Query for hanging_api: true with no timeout_ms returns empty. CU histogram across the 59 apis: 39×10, 9×20, 11×500 (the 500s are gettxoutsetinfo, livetickets, ticketsforaddress, getticketpoolvalue, ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions, getnetworkhashps, gettreasuryspendvotes and getstakeversioninfo, each with timeout_ms: 180000).

The 59 declared methods

One jsonrpc POST collection, add_on: "":

createrawssrtx, createrawsstx, createrawtransaction, decoderawtransaction, decodescript, estimatefee, estimatesmartfee, estimatestakediff, existsaddress, existsaddresses, existsliveticket, existslivetickets, existsmempooltxs, getbestblock, getbestblockhash, getblock, getblockchaininfo, getblockcount, getblockhash, getblockheader, getblocksubsidy, getcfilterv2, getchaintips, getcoinsupply, getconnectioncount, getcurrentnet, getdifficulty, getheaders, getinfo, getmempoolinfo, getmininginfo, getmixmessage, getmixpairrequests, getnettotals, getnetworkhashps, getnetworkinfo, getpeerinfo, getrawmempool, getrawtransaction, getstakedifficulty, getstakeversioninfo, getstakeversions, getticketpoolvalue, gettreasurybalance, gettreasuryspendvotes, gettxout, gettxoutsetinfo, getvoteinfo, livetickets, sendrawmixmessage, sendrawtransaction, submitblock, ticketfeeinfo, ticketsforaddress, ticketvwap, txfeeinfo, validateaddress, verifymessage, version

Methods carrying a block identifier at arg 0, with PARSE_BY_ARG ["0"]: getblock (hash), getblockhash (height), getblockheader (hash), getblocksubsidy (height), getcfilterv2 (hash), getstakeversions (hash), gettreasurybalance (optional hash), gettreasuryspendvotes (optional block hash). Those two carry "default_value": "latest", so a call without the optional hash parses as latest. Eight methods that read no chain state use EMPTY [""]: validateaddress, verifymessage, decodescript, createrawtransaction, createrawsstx, getcurrentnet, version, estimatefee. All others use DEFAULT ["latest"].

Two param-shape traps avoided, both verified by the parse-directive gate: getrawtransaction uses DEFAULT ["latest"] — not btc.json's PARSE_BY_ARG ["2"], which points at a 3rd positional blockhash param that dcrd's 2-param getrawtransaction(txid string, verbose *int = 0) does not have; and gettxout is given no block param, since dcrd's gettxout(txid, vout, tree int8 REQUIRED, includemempool) reads only the live UTXO set.

Why dcrd has no archive tier (storage-model evidence)
  • config.go — no --prune flag or analogue exists. The only storage-related flags are --txindex (default false), --droptxindex, --noexistsaddrindex (default false, i.e. the exists-address index is on), --dropexistsaddrindex.
  • sample-dcrd.conf — zero mentions of prune, filter, or index beyond txindex; pruning is not even offered as a commented-out operator option.
  • README — "dcrd maintains the entire past transactional ledger of Decred"; "30 GB disk space (as of January 2026, increases over time, ~2.5 GB/yr)".
  • docs.decred.org/advanced/full-node/ — "The size of the blockchain is continually increasing… a good rule of thumb is to have ~3X the current raw blockchain size in hard disk space." No archive tier documented.
  • docs/json_rpc_api.mediawiki §8.1.2 — "Using getblock to Retrieve the Genesis Block" is presented as a normal operation on a default node.
  • NOWNodes' Decred page offers only "RPC Full Node" and "BlockBook" — no DCR archive tier. GetBlock's "archive mode" copy is generic cross-chain boilerplate with no Decred-specific detail.
  • Corroboration (explorer, not a probe): https://explorer.dcrdata.org/api/block/1 → HTTP 200 with full block-1 data.

The only historical-access limiters are the optional indexes, which fail identically at any height rather than only old ones — a node-configuration concern, not an archive-extension concern.

🤖 Generated with Claude Code


🤖 Generated by create_spec.yml · workflow run · full transcript in run artifacts

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Spec pipeline started on PR open — running Phase 8 → 11. Results post here as comments. View run

@AnnaR-prog

Copy link
Copy Markdown
Contributor

Manual smart-router run — Decred mainnet through a keyed provider (2026-10-06)

Booted dcr.json at bd26b37 with a native smart-router v1.5.8 build (--use-static-spec <branch checkout>/). The only upstream was a keyed NOWNodes dcrd mainnet endpoint (dcr.nownodes.io, key withheld, never committed or posted). No public dcrd JSON-RPC exists, so CI's Phase 8 has nothing to probe and this run supplies the live evidence. I relayed all 59 declared methods through the router, then cross-checked with smartrouter health.

Results (mainnet; the live run and health agree)

Surface Result Evidence (via router)
Boot / chain-id ✅ PASS [+] verified successfully … verification=chain-id rawData=298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980 (getblockhash [0] = mainnet genesis). ChainTracker initialization complete chainID=DCR failed=0 success=1.
GET_BLOCKNUM / GET_BLOCK_BY_NUM ✅ PASS getblockcount → 1121278. getblockhash [1121258] → ccfd43bd…6dbd. The tracker polled getblockcount all session.
Node answered (23 methods) ✅ PASS getblockcount, getblockhash, getblock (verbose: hash + powhash, tx/stx trees; raw hex with verbose=false), getblockheader, getbestblockhash, getblockchaininfo (chain: "mainnet"), getchaintips, getdifficulty, getnetworkinfo (version 2010600, subversion "2.1.6"), getconnectioncount, getnetworkhashps, getmininginfo, getrawtransaction [txid, 1], gettxout [txid, 0, 0, true], getrawmempool, getmempoolinfo, gettxoutsetinfo, validateaddress, verifymessage, decodescript, createrawtransaction, estimatefee, estimatesmartfee ({"feerate": 0.00039125, "blocks": 6}).
Node-originated errors on junk input (2 methods) ✅ PASS (existence) decoderawtransaction ["00"] and sendrawtransaction ["00", false] → -22 "Could not decode Tx: unexpected EOF" from dcrd. Nothing was broadcast.
Gateway-whitelisted (31 methods) ⚠️ untestable through this provider NOWNodes answers HTTP 405 Method Not Allowed for getbestblock, getblocksubsidy, getcfilterv2, getheaders, getcoinsupply, getcurrentnet, getinfo, getnettotals, getpeerinfo, version, existsmempooltxs, existsaddress(es), createrawsstx, createrawssrtx, estimatestakediff, getstakedifficulty, getstakeversions, getstakeversioninfo, getvoteinfo, livetickets, existsliveticket, ticketsforaddress, getticketpoolvalue, ticketvwap, ticketfeeinfo, txfeeinfo, gettreasurybalance, gettreasuryspendvotes, getmixmessage, getmixpairrequests. A deliberately nonexistent method gets the same 405, so this is the gateway's allow-list and says nothing about dcrd. All are registered in dcrd (rpc/jsonrpc/types/chainsvrcmds.go). Not a spec defect; do not disable.
Gateway-whitelisted writes (2 methods) ⚠️ untestable through this provider submitblock and sendrawmixmessage → 405 (same allow-list).
Rate limit (1 method) ⚠️ untestable this run existslivetickets → HTTP 429 "retry after 1m0s" from the free tier during the burst.
Method binding ✅ PASS All 59 methods report their own function= label on :metrics. Only the deliberate nonexistent probe fell to Default-*.
DCRT (testnet3) inheritance ✅ inheritance validated / ⚠️ network untestable No testnet endpoint exists (public testnet services are down, and NOWNodes has no Decred testnet). An expected-fail scratch boot pointed DCRT at the mainnet origin: verify failed expected and received are different … Method=getblockhash Verification=chain-id rawParsedBlock=298e5cc3…d980 verification.Value=a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac. So DCRT resolves the chain-id check through imports and applies its own testnet genesis. The testnet value itself remains source-verified only.

Run notes (operational, not spec issues)

  • Flags: --chain-tracker-poll-divisor 0.25 --set-relay-retry-limit 0 --min-relay-timeout 15s (free tier, about 100k requests/month and a burst limit). One provider block, base leg only: the spec declares no add-ons or extensions.
  • health exit 0, ok: true, leg DCR dcr-mainnet http OK latestBlock 1121279 chain-id=true. It mirrors the live boot.
  • Residual log noise is the expected startup set (invalid adaptive … bounds, using defaults, provider data not found, using default).
  • For providers: NOWNodes' shared tier exposes about half of dcrd's RPC surface. A dedicated dcrd (or a provider without an allow-list) is needed to serve the stake, treasury, mix and address methods.

🤖 Generated with Claude Code

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 8 — smart-router boot + method probe (resumable run, Phases 8–11)

Ran in spec-load-only mode: no reachable dcrd JSON-RPC upstream exists on either network, re-verified independently this run. Verdicts: SPEC_LOAD: OK / SPEC_LOAD_TESTNET: OK, zero class-A spec-defect signatures. PARSE / VERIFY / all 56 non-stateful methods are NOT_TESTABLE — an endpoint gap, not a spec defect.


Method Probe Report — dcr

Generated: 2026-10-06T12:46:36Z
Router image: ghcr.io/magma-devs/smart-router:main (digest sha256:2149de60c3ed1687e6eea10b73f7aeaa0c4981e0ccf226d192a161ad60cc41c3)
Router config: /tmp/sr_dcr.yml, /tmp/sr_dcr_testnet.yml
Spec variant: DCR (jsonrpc), DCRT (jsonrpc, imports: ["DCR"])
Upstreams probed: none — no reachable public dcrd JSON-RPC upstream exists; see below.

Endpoint availability — Phase 8 ran in SPEC-LOAD-ONLY mode

Decred has no reachable public dcrd JSON-RPC endpoint on either mainnet or testnet. This was established independently twice — once across Phases 1–7, and again this run by a dedicated endpoint-discovery agent that probed and re-probed the full source ladder immediately before this phase started:

Source Result
NOWNodes signup/API-key gated — auth required, no demo key
GetBlock signup/API-key gated
BlockDaemon signup/API-key gated
Tatum (https://decred-mainnet.gateway.tatum.io/) live HTTP 404 — Decred not onboarded
Ankr, drpc.org, publicnode.com, Chainstack no Decred entry at all
chainlist.org EVM-only, N/A for a UTXO chain
comparenodes.com HTTP 403
testnet.dcrdata.org, testnet.decred.org both live HTTP 503 on 2026-10-06
dcrdata.decred.org / explorer.dcrdata.org reachable, but an explorer REST API, not dcrd JSON-RPC — corroboration only, never configured as a smart-router upstream
dcrd itself requires rpcuser/rpcpass by default — no anonymous public dcrd nodes exist in the wild

This is an endpoint gap, not a spec defect. Per the orchestrator's explicit instruction for this run, no further endpoint search was performed (that work is done and redoing it wastes budget), no endpoint was invented/guessed/constructed, and the dcrdata explorer REST API was never substituted for the jsonrpc upstream.

Because there is no upstream, the only thing Phase 8 can still exercise is the router's static spec-graph resolution — loading dcr.json and its imports closure, registering the DCR/DCRT chain IDs and their jsonrpc api collection, and attempting (and reporting on) the verification compiled from the spec. This happens entirely before upstream I/O succeeds or fails, so it is a genuine spec-level signal and the reason this phase still ran rather than being skipped outright.

Each direct-rpc block below was deliberately configured with the unreachable placeholder http://127.0.0.1:1/ — this is not a real or guessed endpoint, it exists only to give the router something to dial so its startup verification path executes and logs its outcome.

Router spec-load check

Mechanically confirmed inputs:

  • jq -e '[.proposal.specs[].api_collections[]?.parse_directives[]? | select(.function_tag == "SUBSCRIBE")] | any' dcr.json' → false. No SUBSCRIBE directives anywhere in DCR/DCRT → the hard ws/wss requirement does not apply; no ws upstream was configured.
  • Addon/extension inventory (jq over .add_on / .extension fields across the whole document) → both empty lists. ADDONS: none declared.
  • Only api_interface in use across DCR/DCRT's collections → jsonrpc. No <EXTRA_INTERFACES>.
  • dcrt.json does not exist as a separate file — DCRT lives inside dcr.json as a second proposal.specs[] entry with imports: ["DCR"].

SPEC_LOAD (mainnet, chain-id DCR)

Verdict: SPEC_LOAD: OK

Evidence from docker logs sr_dcr (container sr_dcr, image digest above):

{"level":"info","source_index":"1","total_sources":"1","source":"specs/","message":"Loading specs from source"}
{"level":"info","spec_count":"298","directory":"specs/","spec_ids":"... DCR ... DCRT ...","message":"Loaded specs from local directory"}
{"level":"info","chain_id":"DCR","total_sources":"1","total_specs_loaded":"298","message":"Successfully loaded and expanded spec from aggregated sources"}
{"level":"info","chainID":"DCR","apiInterface":"jsonrpc","addons":"","extensions":"","message":"Auto-derived policy from static providers"}
{"level":"info","chain":"DCR","apiInterface":"jsonrpc","tier":"static","providerCount":"1","message":"Validating providers"}
{"level":"warn","error":"...verification\":\"chain-id\"...","message":"failed verification on provider startup"}
{"level":"info","chainID":"DCR","apiInterface":"jsonrpc","hint":"Add ws:// or wss:// URLs to static-providers-list to enable subscriptions","message":"No WebSocket endpoints configured for direct subscriptions"}
{"level":"info","chainID":"DCR","apiInterface":"jsonrpc","averageBlockTime":"5m0s","divisor":"2","pollInterval":"2m30s","overridden":"false","message":"per-endpoint chain tracker poll cadence resolved"}
{"level":"info","endpoints":"DCR:jsonrpc Network Address:0.0.0.0:3360","message":"RPCSmartRouter Listening"}
{"level":"info","message":"RPCSmartRouter done setting up all endpoints, ready for requests"}

The spec graph parsed, DCR resolved to a registered jsonrpc chain with providerCount:1, the chain-id verification compiled and was attempted (getblockhash against block 0, expecting 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980), averageBlockTime resolved to the spec's 300000ms (5m0s), and the listener bound. The only failure in the whole run is the expected class-B upstream dial failure:

{"level":"error","error":"Post \"http://127.0.0.1:1/\": dial tcp 127.0.0.1:1: connect: connection refused", ...}
{"level":"warn", ..., "message":"provider validation failed — excluding from provider list"}
{"level":"warn","chain":"DCR","apiInterface":"jsonrpc","staticConfigured":"1","backupConfigured":"0", "message":"ATTENTION: no healthy providers for endpoint — serving unavailable until one recovers"}

Note: against this smart-router build the container does not exit to FATAL on a fully-dead provider set — it logs ATTENTION: no healthy providers for endpoint — serving unavailable until one recovers, keeps retrying the dead placeholder in the background every 2s/4s, and answers live requests with {"Error":"No pairings available."} rather than crashing. This is a looser failure mode than the reference doc's literal "FATAL" expectation, but it is still unambiguously class B (connection-refused on the placeholder), and no class-A signature appeared anywhere in the 133-line log.

Class-A grep (failed to load any specs|spec not found for chainId|Bad verification definition|failed to unmarshal|invalid spec|duplicate|panic|missing api|CraftChainMessage|failed to parse|parse_directives|unsupported parser|invalid parser|api_interface): zero hits.

SPEC_LOAD_TESTNET (chain-id DCRT, imports ["DCR"])

Verdict: SPEC_LOAD_TESTNET: OK

{"level":"info","chain_id":"DCRT","total_sources":"1","total_specs_loaded":"298", "message":"Successfully loaded and expanded spec from aggregated sources"}
{"level":"info","chainID":"DCRT","apiInterface":"jsonrpc","addons":"","extensions":"", "message":"Auto-derived policy from static providers"}
{"level":"info","chain":"DCRT","apiInterface":"jsonrpc","tier":"static","providerCount":"1", "message":"Validating providers"}
{"level":"warn", ..., "verification":"chain-id", "message":"failed verification on provider startup"}
{"level":"info","chainID":"DCRT","apiInterface":"jsonrpc","averageBlockTime":"2m0s","divisor":"2","pollInterval":"1m0s","overridden":"false", "message":"per-endpoint chain tracker poll cadence resolved"}
{"level":"info","endpoints":"DCRT:jsonrpc Network Address:0.0.0.0:3360", "message":"RPCSmartRouter Listening"}

This is the key signal the orchestrator flagged: DCRT's imports: ["DCR"] closure resolved correctly inside the router — the jsonrpc api-interface/collection came through from the imported DCR base spec (nothing in DCRT declares its own api_collections apis), providerCount:1 registered, and the DCRT-specific chain-id verification (expected_value = a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac, the testnet3 genesis hash) compiled and was attempted rather than erroring as "spec not found for chainId" or booting with an empty api set. averageBlockTime also correctly resolved to DCRT's own override (120000ms / 2m0s) rather than inheriting DCR's 300000ms — confirming the override path through the import closure works too.

Class-A grep: zero hits on sr_dcr_testnet's 132-line log, same pattern as mainnet (only the expected connection-refused class-B failure against the http://127.0.0.1:1/ placeholder).

Verification inventory

Both DCR and DCRT declare exactly one verification, chain-id, each with its own 64-hex-char expected_value:

chain-id index expected_value (genesis block-0 hash via getblockhash(0))
DCR (mainnet) DCR 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980
DCRT (testnet3) DCRT a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac

Both values are well-formed (64 hex chars, verified mechanically). Neither could be verified against a live node in this run — see VERIFY below — the testnet3 value in particular is source-derived and has never been live-confirmed by any phase of this pipeline.

Parse-directive & verification runtime check (Step 3.5)

Check Verdict Evidence
GET_BLOCKNUM (router latest_block) NOT_TESTABLE tracker never started a successful cycle — zero smartrouter_latest_block/lava_rpcsmartrouter_latest_block metric samples on either :7779 or :7879; no upstream ever answered
GET_BLOCK_BY_NUM (log hash-reads ∥ fetch_block counters) NOT_TESTABLE zero Chain Tracker Updated block hashes / Chain Tracker read a block Hash lines on either container
Parse-signature log lines none grep for failed to parse response|failed formatResponseForParsing|failed ParseBlockHashFromReplyAndDecode|failed CraftChainMessage|... → 0 hits on both containers
Verification Verdict Providers OK/failed Notes
chain-id (DCR) NOT_TESTABLE 0/1 compiled and attempted (getblockhash(0)), but failed only on dial tcp 127.0.0.1:1: connect: connection refused against the placeholder — never reached a real node, so the expected_value itself was never exercised
chain-id (DCRT) NOT_TESTABLE 0/1 same — compiled, attempted, connection-refused only

PARSE: NOT_TESTABLE and VERIFY: NOT_TESTABLE per the orchestrator's explicit instruction — the chain tracker never ran and the chain-id genesis-hash check never reached a real node on either network. This is distinct from FAIL: nothing in the spec's directive/verification definitions was shown to be wrong; the test apparatus simply had no live chain to check it against.

Addon & extension coverage (Step 1c)

ADDONS: none declared. Mechanically confirmed:

jq -r '[.. | objects | .add_on? // empty] | map(select(. != "")) | unique[]' dcr.json   # → empty
jq -r '[.. | objects | .extension? // empty] | map(select(. != null and . != "")) | unique[]' dcr.json   # → empty

No addon/extension table applies to this spec.

Per-method probe table (Step 4) — NOT_TESTABLE, no upstream

The router could not route any request to a real dcrd node on either network, so none of DCR's 59 apis could be functionally probed through the router. No per-method probes were fabricated and no third-party service was probed directly in place of the router. All 59 methods are classified NOT_TESTABLE with reason no reachable dcrd JSON-RPC upstream, except the 3 category.stateful: 1 methods, which keep the endpoint-independent SKIP (stateful) classification per the reference.

Method Classification Notes
createrawssrtx NOT_TESTABLE no reachable dcrd JSON-RPC upstream
createrawsstx NOT_TESTABLE no reachable dcrd JSON-RPC upstream
createrawtransaction NOT_TESTABLE no reachable dcrd JSON-RPC upstream
decoderawtransaction NOT_TESTABLE no reachable dcrd JSON-RPC upstream
decodescript NOT_TESTABLE no reachable dcrd JSON-RPC upstream
estimatefee NOT_TESTABLE no reachable dcrd JSON-RPC upstream
estimatesmartfee NOT_TESTABLE no reachable dcrd JSON-RPC upstream
estimatestakediff NOT_TESTABLE no reachable dcrd JSON-RPC upstream
existsaddress NOT_TESTABLE no reachable dcrd JSON-RPC upstream — watch-list: needs a fully-permissioned node to re-test
existsaddresses NOT_TESTABLE no reachable dcrd JSON-RPC upstream
existsliveticket NOT_TESTABLE no reachable dcrd JSON-RPC upstream
existslivetickets NOT_TESTABLE no reachable dcrd JSON-RPC upstream
existsmempooltxs NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getbestblock NOT_TESTABLE no reachable dcrd JSON-RPC upstream — watch-list
getbestblockhash NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getblock NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getblockchaininfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getblockcount NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getblockhash NOT_TESTABLE no reachable dcrd JSON-RPC upstream — this is the chain-id verification's own method
getblockheader NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getblocksubsidy NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getcfilterv2 NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getchaintips NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getcoinsupply NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getconnectioncount NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getcurrentnet NOT_TESTABLE no reachable dcrd JSON-RPC upstream — watch-list
getdifficulty NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getheaders NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getmempoolinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getmininginfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getmixmessage NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getmixpairrequests NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getnettotals NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getnetworkhashps NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getnetworkinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getpeerinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getrawmempool NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getrawtransaction NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getstakedifficulty NOT_TESTABLE no reachable dcrd JSON-RPC upstream — watch-list
getstakeversioninfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getstakeversions NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getticketpoolvalue NOT_TESTABLE no reachable dcrd JSON-RPC upstream
gettreasurybalance NOT_TESTABLE no reachable dcrd JSON-RPC upstream
gettreasuryspendvotes NOT_TESTABLE no reachable dcrd JSON-RPC upstream
gettxout NOT_TESTABLE no reachable dcrd JSON-RPC upstream
gettxoutsetinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
getvoteinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
livetickets NOT_TESTABLE no reachable dcrd JSON-RPC upstream
sendrawmixmessage SKIP (stateful) would broadcast a mix message
sendrawtransaction SKIP (stateful) would broadcast a transaction
submitblock SKIP (stateful) would submit a block
ticketfeeinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
ticketsforaddress NOT_TESTABLE no reachable dcrd JSON-RPC upstream
ticketvwap NOT_TESTABLE no reachable dcrd JSON-RPC upstream
txfeeinfo NOT_TESTABLE no reachable dcrd JSON-RPC upstream
validateaddress NOT_TESTABLE no reachable dcrd JSON-RPC upstream
verifymessage NOT_TESTABLE no reachable dcrd JSON-RPC upstream
version NOT_TESTABLE no reachable dcrd JSON-RPC upstream — watch-list

59 total methods: 3 SKIP (stateful), 56 NOT_TESTABLE.

Log-scan findings (probe window)

No probe window — Step 4 did not run (no upstream to route to). The entire boot-window log for both containers was reviewed instead (above); the only non-benign warn/error lines are the expected class-B connection-refused / failed-verification / excluded-provider lines against the deliberate placeholder http://127.0.0.1:1/. No fatal/panic appeared on either container.

Level Associated method error excerpt
— — (clean — only expected placeholder-dial errors, documented above)

Testnet verification pass (Step 7)

TESTNET_VERIFY: SKIPPED (no testnet inputs — no reachable testnet dcrd RPC; testnet.dcrdata.org and testnet.decred.org both 503 on 2026-10-06)

The boot in "SPEC_LOAD_TESTNET" above is a stand-in that confirms the DCRT import closure resolves inside the router, but it is explicitly not a substitute for Step 7's live expected_value check — no testnet node ever answered the chain-id verification.

Verification Verdict Providers OK/failed Notes
chain-id (DCRT) NOT_TESTABLE 0/1 never reached a live node; expected_value unverified

Empirical block time (Step 8)

BLOCK_TIME: mainnet=skipped testnet=skipped — no RPC available on either network, so no live measurement was taken, and none was synthesized from the dcrdata explorer to avoid misrepresenting it as a probe measurement.

Inherited evidence (from Phases 1–7, NOT a measurement taken in this phase): the dcrdata explorer's lifetime mean block interval was previously recorded as 299.96 s/block, against the spec's mainnet average_block_time of 300000ms (300s) — a ~0.01% difference, i.e. consistent, but this is explorer corroboration carried forward, not a Phase 8 probe result.

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet — (none reachable) skipped 300000 — skipped
testnet — (none reachable) skipped 120000 — skipped

What a maintainer must do to close this gap

  1. Supply one keyed dcrd mainnet JSON-RPC endpoint (and ideally a testnet3 one too) — e.g. a self-hosted dcrd --rpcuser=... --rpcpass=... reachable over HTTPS, or a paid-tier provider that actually onboards Decred (none of NOWNodes/GetBlock/BlockDaemon/Tatum/Ankr currently do on a free tier).
  2. Re-run /rerun-probe mainnet=<url> testnet=<url> to redo Phase 8 for real: router boot, chain-id verification against both genesis hashes, the chain-tracker's GET_BLOCKNUM/GET_BLOCK_BY_NUM directives, and the full 59-method probe loop.
  3. On the mainnet probe, pay particular attention to this watch-list of methods that need a fully-permissioned (non-rate-limited, non-pruned) node to validate properly: version, getbestblock, getstakedifficulty, existsaddress, getcurrentnet.
  4. On the testnet probe, live-confirm the testnet3 genesis hash currently in the spec as DCRT's chain-id expected_value:
    a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac
    
    This value is source-derived (from Decred's published testnet3 parameters) and has never been live-confirmed by any phase of this pipeline — it should be the very first thing checked once a testnet3 RPC exists, via getblockhash(0).

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 9 — parallel reviewers (3 independent fresh-context reviews)

Three reviewers ran /review-spec on dcr.json independently, each writing its own report path (no shared-file race). All three digests differ, and no finding cites a line beyond the file's 1053 lines — no reviewer reviewed stale state.

Reviewer CRITICAL MEDIUM MINOR
1 0 1 1
2 0 1 0
3 0 0 1
merged (deduplicated) 0 1 2

What all three agreed was correct

  • Method existence: exact 1:1 match. All 59 declared api names are real dcrd HTTP commands in chainsvrcmds.go + rpcHandlersBeforeInit — zero hallucinated, zero misnamed, zero gaps. Independently confirmed by all three reviewers against the authoritative Go source.
  • Parameter shapes / block_parsing: PASS. No arg points at a parameter dcrd does not have. The dcrd-vs-bitcoind divergences (getblock bool verbosity, getrawtransaction 2-param max, gettxout's required tree, sendrawtransaction(hex, allowhighfees), getrawmempool(verbose, txtype)) are all handled correctly.
  • Parse directives: PASS. GET_BLOCKNUM/GET_BLOCK_BY_NUM, both PARSE_BY_ARG ["0"], templates and api_name coherent, referenced apis present.
  • Verifications: PASS. Both chain-id genesis-hash pins well-formed, distinct, lowercase 64-hex; no verification references a function_tag without a matching directive.
  • Network parameters: PASS on both entries, matched against chaincfg/mainnetparams.go and chaincfg/testnetparams.go.
  • Structure: PASS. 59/59 unique api names, no malformed or incomplete entries, removed-field guard clean.

Merged findings

MEDIUM-1 — version is marked category.deterministic: true but returns per-node software build info (found independently by reviewers 1 and 2 — the one convergent finding). dcrd's version returns the node's own JSON-RPC API/build version, not chain state, so two providers on different dcrd releases legitimately return different results. Marking it deterministic invites spurious data-reliability mismatches and provider penalties. Fix: deterministic: false.

MINOR-1 — existsmempooltxs priced compute_units: 10 despite being a batch call (reviewer 1). ExistsMempoolTxsCmd is {TxHashes []string} — structurally identical to existsaddresses and existslivetickets, both priced 20 in this same collection, while the singular existsaddress/existsliveticket are priced 10. An internal economic-modeling inconsistency, no functional break. Fix: compute_units: 20.

MINOR-2 — category.deterministic divergence from btc.json convention (reviewer 3, self-labelled low confidence). Eight methods btc.json marks deterministic (getblockcount, getbestblockhash, getblockchaininfo, getchaintips, getconnectioncount, getdifficulty, gettxout, estimatesmartfee) are false here. The reviewer judged this defensible and arguably more conservative — several genuinely are node-local or moving-target values (getconnectioncount is peer count; getchaintips is a node's local view of alternate tips) — rather than a defect.

Note on scope

No reviewer raised a finding about the missing live probe data; all three correctly treated the Phase 8 endpoint gap as infrastructure, not a spec defect. Zero methods are disabled anywhere in the file, so there were no disable justifications to verify.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 10 — synthesize gaps + fix pass, and Phase 10b — smoke re-probe

Consolidation

Three review reports plus the Phase 8 probe report were consolidated into a deduplicated fix list (docs/dcr/FIX_LIST.md), keyed on (gap_title, evidence_line_number):

  • 0 CRITICAL, 1 MEDIUM survived.
  • 0 disable-suggestions stripped — no reviewer proposed disabling anything, so the free-tier disable filter had nothing to catch. The spec disabled zero methods before this pass and disables zero after.
  • 2 other strips, both MINOR and dropped per the consolidation rule: the existsmempooltxs batch-CU inconsistency, and reviewer 3's low-confidence category.deterministic-vs-btc.json convention note (deliberately not merged into the version finding — different methods, different evidence).

Fix applied — 1 line

File:line Change Gap
dcr.json:378 version → category.deterministic: true → false MEDIUM, "version API incorrectly marked category.deterministic: true"

dcrd's VersionResult (rpc/jsonrpc/types/chainsvrresults.go) is {VersionString, Major, Minor, Patch, Prerelease, BuildMetadata} — the responding node's own software build, not chain state, and its block_parsing is DEFAULT/"latest", so there is no mechanism to pin it to a point in chain history even in principle. Two honest, fully-synced providers on different valid dcrd point releases legitimately return different payloads; marking it deterministic would make Lava's cross-provider reliability check read that normal variance as a mismatch signal against an honest provider. Repo convention agrees: 11 of the 12 other specs exposing an equivalent node/client-version RPC mark it deterministic: false.

Guards after the fix

Guard Result
jq empty dcr.json valid
check_unused_fields.sh RESULT: PASS (no removed fields)
Explicit forbidden-15 scan (governance / envelope / api-level) FORBIDDEN_FIELDS: none
Canonical envelope { "proposal": { "specs": [ … ] } } true
check_disabled_count.sh 0 distinct disabled methods — still matches the body's <!-- disabled-count: 0 --> marker, no update needed
Diff size 1 insertion, 1 deletion — surgical, no reformatting
Api count 59, unchanged

No new disabled APIs, so the Disabled-API Justifications ledger stays empty and needs no entry.

Phase 10b — smoke re-probe: SMOKE: OK, no regressions

Re-booted the router against the fixed spec, same shape as the Phase 8 baseline (the fix is a category field, which the router parses at spec-load time, so this is a real if narrow regression test). The staged copy was confirmed to carry version.category.deterministic == false before booting.

Check Phase 8 baseline Phase 10b Verdict
SPEC_LOAD (DCR) OK OK — chainID:DCR, jsonrpc, spec_count:298, averageBlockTime:5m0s, chain-id verification compiles, listener ready no change
SPEC_LOAD_TESTNET (DCRT) OK OK — resolves through imports: ["DCR"], averageBlockTime:2m0s override correct vs DCR's 5m no change
Class-A spec-defect log signatures none none (both containers, full boot log) no change
PARSE / VERIFY NOT_TESTABLE NOT_TESTABLE (carried forward) not a regression — same known endpoint gap
ADDONS none declared none declared (re-confirmed mechanically) no change
7-item minimal probe set n/a 7/7 NOT_TESTABLE (no reachable upstream) per reference Step 3, an item with no data is never a regression

Teardown clean, both containers removed. The smoke pass ran image tag :latest (digest 0b4c806…) where Phase 8 ran :main (digest 2149de6…), per the reference's preference for :latest when pullable; every checked signal behaved identically across the two tags, so the comparison holds.

The Phase 10 edit is left uncommitted in the working tree for the workflow's commit step.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=1 MEDIUM=0 MINOR=0)

The final reviewer confirmed the Phase 10 fix is correct and complete, re-verified every earlier PASS, and found one new CRITICAL defect that Phase 9's three reviewers all missed: txfeeinfo is marked category.deterministic: true.

I independently confirmed the finding against the file before reporting it:

ticketfeeinfo: deterministic=false  cu=20  stateful=0
txfeeinfo:     deterministic=true   cu=20  stateful=0   <-- dcr.json:835

Two structurally identical dcrd RPCs, same CU tier, opposite determinism flags. dcrd's handleTxFeeInfo unconditionally embeds FeeInfoMempool — a live mempool fee-distribution snapshot — in every response, with no parameter combination that removes it; handleTicketFeeInfo has the identical pattern and is correctly marked false. So two honest providers answering the same call a second apart return different payloads, and the deterministic flag makes Lava's cross-provider data-reliability check read that normal variance as a fraud signal and penalize an honest provider. This is the same bug class the Phase 10 pass just fixed for version.

Required fix (one line): dcr.json:835 — txfeeinfo → category.deterministic: true → false.

This was not applied. Phase 11 is the verdict phase and this run's span ends here; the skill forbids looping back into another fix pass, so the defect is reported rather than silently patched. Retry with /rerun-from 10 to run the fix pass, the 10b smoke re-probe and a fresh final review over it.

Full final review report (docs/dcr/SPEC_REVIEW_GAPS_final.md)

Spec Review — dcr.json (Decred, final pass)

Reviewed: DCR (mainnet, standalone, 59 apis in 1 jsonrpc collection) and DCRT (testnet3, imports: ["DCR"], 0 of its own apis, overrides chain-id + network-timing fields only).

Method: Phase 8/10b live probing was impossible (no reachable public dcrd JSON-RPC endpoint on either network — see docs/dcr/METHOD_PROBE_REPORT.md; this is an endpoint/infrastructure gap and is not treated as a spec defect). This review instead statically cross-checks every method, parameter shape, verification and category flag in dcr.json against dcrd's authoritative source at decred/dcrd@master:

  • rpc/jsonrpc/types/chainsvrcmds.go (command registry / param shapes)
  • internal/rpcserver/rpcserver.go (rpcHandlersBeforeInit, rpcAskWallet, rpcUnimplemented, rpcLimited, and the handle* implementations themselves)
  • rpc/jsonrpc/types/chainsvrwscmds.go (17 WebSocket-only commands)
  • chaincfg/mainnetparams.go, chaincfg/testnetparams.go
  • live corroboration of the mainnet genesis hash via https://dcrdata.decred.org/api/block/0 (reachable; testnet equivalents are all 503, matching the probe report — not re-flagged here)

Phase 0 — Removed-field guard

bash .claude/skills/create-spec/scripts/check_unused_fields.sh dcr.json
RESULT: PASS (no removed fields)

Canonical envelope confirmed: { "proposal": { "specs": [...] } }, no title/description/deposit, no extra_compute_units/category.local/category.subscription anywhere in the file.

Method existence (all 59 names)

jq extraction of all 59 DCR api names, diffed against rpcHandlersBeforeInit in rpcserver.go (the live HTTP command-dispatch map):

  • rpcHandlersBeforeInit registers 77 HTTP commands.
  • 59 match 1:1 to the spec's apis (case-correct lowercase method names against the map's keys) — zero hallucinated or misnamed methods.
  • The remaining 18 are exactly the operator/admin set the author recorded as deliberately omitted: addnode, debuglevel, generate, getaddednodeinfo, getgenerate, gethashespersec, getwork, help, invalidateblock, node, ping, reconsiderblock, regentemplate, setgenerate, startprofiler, stop, stopprofiler, verifychain. This matches settled decision (d) exactly (18/18).
  • None of the 59 spec methods appear in rpcUnimplemented ({"estimatepriority"} only) or in rpcAskWallet as a missing dcrd implementation — every spec method has a live handle* function in rpcHandlersBeforeInit.
  • chainsvrwscmds.go defines exactly 17 WS-only *Cmd structs (Authenticate, LoadTxFilter, NotifyBlocks, NotifyWork, NotifyTSpend, NotifyWinningTickets, NotifyNewTickets, RebroadcastWinners, StopNotifyBlocks, StopNotifyWork, StopNotifyTSpend, NotifyNewTransactions, NotifyMixMessages, StopNotifyMixMessages, Session, StopNotifyNewTransactions, Rescan) — none overlap the spec's 59, confirming settled decision (d) on the WS-only exclusion.

Verdict: PASS — all 59 method names are real, currently-registered dcrd JSON-RPC HTTP commands.

Parameter shapes / block_parsing

Cross-checked every position-dependent block_parsing entry against the corresponding *Cmd struct in chainsvrcmds.go:

API dcrd param shape Spec block_parsing Verdict
getblock Hash string @0 PARSE_BY_ARG @0, BLOCK_HASH correct
getblockhash Index int64 @0 PARSE_BY_ARG @0, BLOCK_LATEST correct (height, not hash — matches btc.json's identical convention)
getblockheader Hash string @0 PARSE_BY_ARG @0, BLOCK_HASH correct
getblocksubsidy Height int64 @0, Voters uint16 @1 PARSE_BY_ARG @0, BLOCK_LATEST correct
getcfilterv2 BlockHash string @0 PARSE_BY_ARG @0, BLOCK_HASH correct
getstakeversions Hash string @0, Count int32 @1 PARSE_BY_ARG @0, BLOCK_HASH correct
gettreasurybalance Hash *string @0 (optional) PARSE_BY_ARG @0, BLOCK_HASH correct
gettreasuryspendvotes Block *string @0 (optional) PARSE_BY_ARG @0, BLOCK_HASH correct
getrawtransaction Txid string, Verbose *int — max 2 params, no blockhash arg (dcrd diverges from bitcoind's 3-param form) DEFAULT/latest correct — the spec does not copy bitcoind's PARSE_BY_ARG @2 pattern (seen in btc.json), which would be out-of-bounds for dcrd. This is the one case the review brief flagged as a likely divergence trap, and the spec gets it right.
gettxout Txid string, Vout uint32, Tree int8 (required), IncludeMempool *bool DEFAULT/latest correct — none of dcrd's params are a block reference, Tree is a UTXO-tree selector, not a height/hash
sendrawtransaction HexTx string, AllowHighFees *bool DEFAULT, stateful:1, hanging_api:true, timeout_ms:10000 correct
getrawmempool Verbose *bool, TxType *string DEFAULT correct — no block ref

All other apis (struct-less *Cmd{} commands, or commands whose params are never block references — e.g. getvoteinfo(Version), existsaddress(Address), getnetworkhashps(Blocks,Height)) correctly use DEFAULT/latest.

Verdict: PASS — no parameter-shape defects found; the known dcrd/bitcoind divergence points are handled correctly.

Parse directives

GET_BLOCKNUM (getblockcount → PARSE_BY_ARG[0]) and GET_BLOCK_BY_NUM (getblockhash(%d) → PARSE_BY_ARG[0]) are byte-for-byte identical to the established btc.json pattern for the same dcrd/bitcoind-family RPC shape. No SUBSCRIBE/UNSUBSCRIBE directives exist and none are needed (no WS commands in the base collection, confirmed above).

Verdict: PASS.

Verifications

  • Mainnet chain-id (DCR, line 1005): expected_value = 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980. Independently corroborated live against https://dcrdata.decred.org/api/block/0 (reachable explorer REST API, used here only for read-only corroboration, never as a smart-router upstream): returns "hash":"298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980" for block 0 — exact match.
  • Testnet3 chain-id (DCRT, line 1043): expected_value = a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac. testnet.dcrdata.org, testnet.decred.org, and dcrdata.decred.org/testnet/... are all unreachable (503/404) as of this run, consistent with the probe report — this is the same pre-documented endpoint gap, not re-raised here as a new finding.
  • Both verification pin on getblockhash(0) (genesis hash) rather than getblockchaininfo.chain — per settled decision (d), this is correct for dcrd (whose chain field semantics mirror btcd's generic "mainnet" string, same reasoning already accepted for BTC-family specs in this repo).

Verdict: PASS (mainnet live-confirmed; testnet unverifiable due to endpoint gap, not a spec defect).

Network parameters

Checked against chaincfg/mainnetparams.go / testnetparams.go:

Param Mainnet spec dcrd source Testnet spec dcrd source Verdict
average_block_time 300000ms TargetTimePerBlock: 5*time.Minute 120000ms TargetTimePerBlock: 2*time.Minute correct both
block_distance_for_finalized_data 6 — (PoW, within guide's 6–12 range) 6 same correct
blocks_in_finalization_proof 3 — (probabilistic finality) 3 same correct
allowed_block_lag_for_qos_sync 1 10000/300000=0.03→min 1 1 10000/120000=0.08→min 1 correct both

Verdict: PASS.

CU + category flags

  • jq confirms exactly 3 apis with category.stateful == 1: sendrawtransaction, submitblock, sendrawmixmessage — each has category.hanging_api: true and an explicit timeout_ms: 10000. No read method is marked stateful.
  • jq confirms 0 apis/collections with enabled: false anywhere in the file, and check_disabled_count.sh reports 0 distinct method(s) — matches the empty Disabled-API Justifications ledger exactly. This check passes trivially, confirmed mechanically rather than assumed.
  • CU values spot-checked against btc.json's equivalents for the shared bitcoind-family RPCs (getblock=20, getblockhash=10, getblockheader=20, gettxout=10, getrawmempool=20, gettxoutsetinfo=500/timeout_ms=180000) — all identical, consistent with the repo-wide convention.

Verdict: PASS.

Phase 10 fix verification

git diff -- dcr.json

shows exactly one hunk, at the version api:

-                                    "deterministic": true,
+                                    "deterministic": false,

Nothing else in the 1053-line file changed. version's dcrd handler (handleVersion) returns a static map of the node's own build/semver info — not chain state — so deterministic: false is correct, consistent with 11/12 comparable specs in this repo. The Phase 10 fix is correct and complete; no further edits are needed or were made to verify it.

New finding

CRITICAL — txfeeinfo incorrectly marked deterministic: true (dcr.json:825-838)

txfeeinfo's category block (line 834-836) sets "deterministic": true. Comparing dcrd's own handleTxFeeInfo against its structural twin handleTicketFeeInfo (which the spec correctly marks deterministic: false, lines 810-823):

// handleTxFeeInfo (rpcserver.go)
func handleTxFeeInfo(...) (any, error) {
    ...
    // Memory pool first.
    feeInfoMempool := feeInfoForMempool(s, stake.TxTypeRegular)   // ALWAYS included, unconditionally
    ...
    if c.RangeStart == nil {
        // defaults to a window ending at the CURRENT chain tip (bestHeight)
        ...
    }
    return &types.TxFeeInfoResult{
        FeeInfoMempool: *feeInfoMempool,   // live mempool snapshot embedded in every response
        FeeInfoBlocks:  feeInfoBlocks,
        FeeInfoRange:   feeInfoRange,
    }, nil
}

Every single txfeeinfo response unconditionally embeds FeeInfoMempool, a live snapshot of the current mempool's fee distribution — there is no parameter combination that removes it. ticketfeeinfo has the identical structural pattern (feeInfoForMempool embedded unconditionally in TicketFeeInfoResult) and is correctly marked deterministic: false. txfeeinfo should be too.

Failure scenario: two honest providers answer the same txfeeinfo request one second apart (or with a slightly different mempool state due to normal propagation jitter). Because the api is flagged deterministic, Lava's cross-provider data-reliability check will treat the differing FeeInfoMempool sub-objects as a fraud/mismatch signal, incorrectly penalizing one or both honest providers. This is the exact same bug class the Phase 10 fix corrected for version (a response field that reflects live/local state, not reproducible chain state, flagged as if it were).

Fix: change dcr.json:835 from "deterministic": true to "deterministic": false, matching ticketfeeinfo's category block.

Summary

  • Endpoints/methods reviewed: 59 (all of DCR's base collection; DCRT inherits all 59 via imports and adds none of its own).
  • Gaps found: 1 CRITICAL, 0 MEDIUM, 0 MINOR.
  • Cleanup findings (Phase 0 removed-field guard): none — check_unused_fields.sh exits 0 clean.
  • Disabled-API justification audit: 0 disabled apis/collections found (jq + check_disabled_count.sh), matching the ledger's "none" entry exactly — passes trivially, confirmed not assumed.
  • Phase 10 fix: confirmed correct and complete via git diff (single-line version determinism flip, nothing else touched).
  • Readiness: the spec is deployment-ready for mainnet DCR and DCRT modulo the one new txfeeinfo determinism fix above, which should be applied before merge to avoid spurious cross-provider reliability penalties. The mainnet chain-id genesis hash is independently live-confirmed correct; the testnet3 chain-id value remains unverified only due to the pre-documented endpoint-availability gap (not a spec defect) and should be the first thing checked once any testnet3 RPC becomes reachable.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 8–11)

Final verdict: CHANGES REQUESTED — 1 CRITICAL (txfeeinfo determinism, dcr.json:835). See the Phase 11 comment.

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10 post-fix `jq empty` → valid)
- ✓ All required fields present                          (Phase 9 ×3 + Phase 11 structural audits)
- ✓ No duplicate API names within any collection         (59/59 unique, Phase 9 + Phase 11)
- ✓ Proper indentation/formatting                        (1-line surgical diff; no reformatting, trailing-newline convention preserved)
- ✓ No removed-model fields                              (check_unused_fields.sh PASS + explicit forbidden-15 scan → none; canonical envelope confirmed)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 11 matched all 4 params on both entries against chaincfg/{mainnet,testnet}params.go)
- ☐ All APIs tested and working                           (Phase 8 degraded: no reachable dcrd JSON-RPC on either network — 56 methods NOT_TESTABLE, 3 stateful SKIP; see docs/dcr/METHOD_PROBE_REPORT.md)
- ~ Block parsing validated for each API                 (statically verified against chainsvrcmds.go param shapes incl. every dcrd/bitcoind divergence point; NOT live-executed)
- ☐ Parse directives executed by live router              (PARSE: NOT_TESTABLE — chain tracker never ran, no upstream. Spec-load-only boot: SPEC_LOAD=OK, SPEC_LOAD_TESTNET=OK, zero class-A signatures; Phase 10b re-check SMOKE: OK)
- ✓ Addons & extensions tested                            (none declared — mechanically confirmed in Phase 8 and re-confirmed in Phase 10b; nothing to test)
- ~ Verifications pass on live nodes                     (VERIFY: NOT_TESTABLE through the router. Both chain-id verifications compile; mainnet genesis hash independently live-corroborated via the dcrdata explorer REST API in Phase 11 — explorer corroboration, never used as an RPC upstream)
- ☐ Compute units benchmarked under expected load        (user to measure; CU values cross-checked against btc.json convention only)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                (single file, both entries; 59 apis in 1 jsonrpc collection)
- ✓ Testnet spec inherits correctly                      (router resolved DCRT through its imports:["DCR"] closure in both Phase 8 and 10b, with average_block_time override 2m vs DCR's 5m confirmed live in the router's own resolution)
- ~ Chain IDs verified for mainnet AND testnet           (mainnet genesis hash confirmed; TESTNET3 value a649dce5… is SOURCE-DERIVED ONLY and has never been live-confirmed — the single highest-value item for a maintainer to check)
- ☐ Both tested on respective networks                    (TESTNET_VERIFY: SKIPPED — testnet.dcrdata.org and testnet.decred.org both 503 on 2026-10-06)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (file ships the `{ "proposal": { "specs": [ … ] } }` wrapper — no title/description/deposit)
- ☐ Community feedback gathered (if applicable)

Auto-decisions taken this run (no human was available)

  1. Phase 8 zero-endpoint gate → did not skip Phase 8. MAINNET_URLS/TESTNET_URLS were empty and a dedicated endpoint-discovery agent independently re-walked the full source ladder and confirmed 0/2 interfaces reachable (NOWNodes/GetBlock/BlockDaemon key-gated; Tatum live-404; Ankr/drpc/publicnode/Chainstack carry no Decred entry; chainlist.org EVM-only; comparenodes.com 403; both Decred testnet services 503). Conservative default: run Phase 8 in spec-load-only mode to capture the router's static spec-resolution signal, which needs no upstream, and record every probe honestly as NOT_TESTABLE. No endpoint was invented and no explorer REST API was substituted as an RPC upstream.
  2. ws gate did not fire. dcr.json declares zero SUBSCRIBE parse directives, so the "subscriptions present but no ws node" STOP condition does not apply and no ws-node request comment was warranted.
  3. Phase 11 CHANGES REQUESTED was not upgraded. The verdict is reported as the reviewer returned it and the CRITICAL fix was not silently applied — Phase 11 is the verdict phase, the span ends there, and the skill forbids looping into another fix pass.

Governance-field compliance

The Phase 10 fix pass introduced none of the 15 fields smart-router removed in #218. Verified post-fix by check_unused_fields.sh (RESULT: PASS) plus an explicit key scan for all 15 names (FORBIDDEN_FIELDS: none), with the canonical envelope { "proposal": { "specs": [ … ] } } confirmed. compute_units remains the only compute-unit input; no category.subscription anywhere.

What a maintainer must do to close the real gap

Supply one keyed dcrd mainnet RPC (and ideally a testnet3 one) and re-run /rerun-probe mainnet=<url> testnet=<url>. That unlocks the 56 untested methods, both chain-id verifications, the parse directives, and the five watch-list methods the only known keyed gateway whitelists out (version, getbestblock, getstakedifficulty, existsaddress, getcurrentnet). To fix the outstanding CRITICAL and re-review, use /rerun-from 10.

Run stats — this pipeline run only (Phases 8–11)

Elapsed:         00h 50m 12s  (first→last logged activity)
Transcripts:     1 main + 9 subagent
API round-trips: 560  (main=75, subagents=485)
Fresh tokens:    input=1120  output=313054  (sum=314174)
Cached tokens:   cache_read=41675034  cache_write=1782895
Total billed:    43772103 tokens
Split:           main=8411530  subagents=35360573
Models:          claude-sonnet-5 485 calls / 35360573 billed
                 claude-opus-5    76 calls /  8571888 billed

These figures cover only Phases 8–11 in this workflow run. The Phases 1–7 time and tokens live in the separate create_spec run and its PR body; the true end-to-end total is the two runs added together.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

📦 Committed pipeline fixes to decred-spec (c6a1592): dcr.json — the branch now matches the spec that Phase 10b/11 verified.

dcrd's handleTxFeeInfo always embeds the live mempool fee distribution
(FeeInfoMempool), so two providers can answer the same call
differently, exactly like ticketfeeinfo, which is already
deterministic: false. Clears the Phase 11 CRITICAL on #186.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of 5e48b29:

  1. The Phase 11 CRITICAL is fixed: txfeeinfo is now deterministic: false (dcrd's handleTxFeeInfo always embeds the live mempool snapshot, the same as ticketfeeinfo). That is the only change since c6a1592.
  2. Live evidence for this spec is in the manual smart-router run comment above (2026-10-06, keyed NOWNodes dcrd mainnet, key withheld). It covers chain-id verified by genesis hash, a clean chain tracker, 23 methods answering, and 2 node-originated errors. 33 methods sat behind NOWNodes' 405 allow-list (a nonexistent method gets the same 405, so it says nothing about dcrd). health OK, and the DCRT inheritance was proven by an expected-fail boot. Do not disable anything over the 405s.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=1 MEDIUM=2 MINOR=2)

Resumable run, Phase 11 only (/rerun-final, START_PHASE == END_PHASE == 11). Reviewed dcr.json at 5e48b29 with a fresh-context reviewer bumped to opus — Phase 9's three reviewers all missed the round-1 txfeeinfo CRITICAL, which qualifies this chain as hard under the skill's model table.

The two landed fixes are both confirmed present AND correct

The reviewer re-derived both from dcrd source rather than taking them on trust:

Fix Status Source basis
txfeeinfo → deterministic: false (round-1 CRITICAL, 5e48b29) ✅ cleared handleTxFeeInfo opens with feeInfoMempool := feeInfoForMempool(s, stake.TxTypeRegular) and returns FeeInfoMempool: *feeInfoMempool unconditionally — no argument suppresses it. Structurally identical to handleTicketFeeInfo, already false. The stated reasoning in the commit message is exactly right.
version → deterministic: false (Phase 10 MEDIUM) ✅ cleared handleVersion builds its reply from version.Major/Minor/Patch, version.PreRelease, version.BuildMetadata and runtime.Version() — all properties of the provider's own binary. Corroborated by the live run's version 2010600 / subversion "2.1.6".

So the round-1 CRITICAL is genuinely closed. The verdict is CHANGES REQUESTED because the deeper audit this pass performed — a full source-level re-check of category.deterministic on all 59 apis, done precisely because this chain has now been wrong about that field twice — turned up a third instance of the same defect class, plus two adjacent issues.

CRITICAL-1 — gettreasuryspendvotes is deterministic: true but its default call reads the live mempool

dcr.json:861 → category.deterministic: true. Verified against the file on disk this run.

Both parameters are optional (GetTreasurySpendVotesCmd{ Block *string; TSpends *[]string }), and handleGetTreasurySpendVotes takes a mempool path whenever tspends is absent — which is the documented default invocation:

mempool := s.cfg.TxMempooler
...
if c.TSpends != nil && len(*c.TSpends) > 0 {
        ...   // client-specified tspends
} else {
        // Fetch vote counts for all mempool tspends.
        hashes := mempool.TSpendHashes()

The set of rows in the returned Votes array is therefore the node's mempool contents. Separately, when block is absent the handler echoes its own tip (best := s.cfg.Chain.BestSnapshot()) into Hash/Height.

Failure scenario. A consumer sends {"method":"gettreasuryspendvotes","params":[]} while a treasury spend is circulating. Provider A has the tspend in its mempool and returns a one-element Votes array with live tallies; provider B has not received it yet and returns Votes: []. Both answer HTTP 200 with a valid result, so data reliability sees two successful, conflicting bodies on an API it was told is deterministic — and penalises an honest provider. block_parsing: PARSE_BY_ARG ["0"] does not save it: params[0] is the optional block hash, so a no-arg call has no index 0 and is never anchored to a block.

Fix: set category.deterministic: false on gettreasuryspendvotes. Its sibling gettreasurybalance correctly stays true — handleGetTreasuryBalance reads only Chain.TreasuryBalance(&hash) and never touches the mempool.

Why no probe could have caught this: gettreasuryspendvotes is one of the 33 methods NOWNodes' shared tier answered with HTTP 405, so no live body was ever observed. Per the standing reading rule that 405 is gateway gating (a deliberately nonexistent method got the identical 405), this is a spec classification defect found in dcrd source — not a question about the method's existence, and not grounds to disable anything.

MEDIUM-1 — getmixmessage is deterministic: true but reads only the node-local mixpool

dcr.json:882. handleGetMixMessage's only backing store is MixPooler: mp := s.cfg.MixPooler; msg, err := mp.Message(msgHash), with no chain-backed fallback — a message this node never received, or already pruned, simply errors. The mixpool is to mix messages what the mempool is to transactions, and this spec already marks the sibling reader of that same pool, getmixpairrequests, deterministic: false. The two are inconsistent.

Rated MEDIUM rather than CRITICAL because the payload is hash-addressed, so the realistic divergence is success-vs-error rather than two conflicting successful bodies. Still a misclassification. Fix: deterministic: false, matching getmixpairrequests.

MEDIUM-2 — livetickets is 20 CU with no timeout_ms, but it serialises the whole live ticket pool

dcr.json:720. handleLiveTickets takes no arguments and has no pagination — it scans the ticket db, then string-encodes every hash. Mainnet params (TicketPoolSize: 8192, TicketsPerBlock: 5) target a live pool of 40,960 tickets, i.e. roughly 2.7 MB of JSON per call, billed the same 20 CU as a single getblock. The guide's CU table puts full-scan ops at 500–5000 CU + timeout_ms, and this spec already applies exactly that to the comparable gettxoutsetinfo (500 / 180000). livetickets is the one full-scan method that did not get the same treatment; no api in the spec is overpriced.

The two MINORs are informational — no change required

  • MINOR-1: PARSE_BY_ARG ["0"] on both treasury methods targets an optional parameter. There is in-repo precedent (btc.json does the same on getchaintxstats); adding "default_value": "latest" would merely make the fallback explicit.
  • MINOR-2: no SUBSCRIBE coverage, so dcrd's WebSocket notification API (notifyblocks, notifynewtransactions, …) is unserved. The omission is defensible and should not be "fixed" as written: Lava's model is one SUBSCRIBE api plus an UNSUBSCRIBE templating a subscription-id handle, whereas dcrd uses one notify<topic>/stopnotify<topic> pair per topic with no handle to carry — there is nothing to put in a single api_name. Serving it needs a router-side mapping, not a spec edit. (Mechanically re-confirmed: zero FUNCTION_TAG_SUBSCRIBE directives in the file, so the run's hard ws-endpoint requirement does not apply.)

Everything else re-verified clean this pass

Nothing was carried over on the strength of an earlier PASS.

Area Result
Removed-field guard (check_unused_fields.sh) RESULT: PASS (no removed fields), exit 0 — none of the forbidden 15
Internal-path guard (check_internal_paths.sh) RESULT: PASS (0 warning(s), no errors); the only internal_path in the file is ""
Canonical envelope { "proposal": { "specs": [ … ] } } exactly; no title/description/deposit, no governance fields — correct per the settled shape, not reported as missing
Other mechanical guards check_network_params / check_verifications / check_directive_presence / check_extensions / check_archive_value / check_disabled_count / check_method_schema / check_node_admin_rpcs — all PASS, 0 FAIL
Disabled-API ledger audit 0 enabled: false apis and 0 disabled collections; ledger is (none — no disabled APIs) — matches exactly, no unjustified disable. The body's <!-- disabled-count: 0 --> marker is still true against the file; no correction needed
Network params Source-confirmed both networks: TargetTimePerBlock 5m (DCR) / 2m (DCRT testnet3) → 300000/120000; block_distance_for_finalized_data: 6 and blocks_in_finalization_proof: 3 correct for probabilistic PoW/PoS finality; allowed_block_lag_for_qos_sync: 1 on both per the formula floor
Parse directives Both live-proven — getblockcount → 1121278 with failed=0 success=1 on the tracker; getblockhash [1121258] → ccfd43bd…6dbd. GET_EARLIEST_BLOCK correctly absent (dcrd has no pruning, so no archive extension applies)
Chain-ids DCR live-verified (rawData=298e5cc3…b21d980). DCRT newly cross-corroborated against two client sources outside dcrd — decred/tinydecred nets/testnet.py and trezor/trezor-common decred_testnet.json, both a649dce5…49bac
DCRT inheritance Correct — overrides only the chain-id expected_value (and average_block_time); apis/headers/parse_directives merge via CombineUnique(), so all 59 apis come through. Proven in-router by the expected-fail boot
Method coverage 0 phantom methods — all 59 are registered dcrd handlers. 18 dcrd methods correctly excluded as node-admin/mining/debug (stop, addnode, generate, getwork, invalidateblock, …). No public read method missing
Block parsing All 59 index-checked against each *Cmd struct. Notably: dcrd's getrawtransaction has no third blockhash param unlike Bitcoin Core, so btc.json's PARSE_BY_ARG ["2"] is correctly not copied here
deterministic: false on the other 38 All correct, and stricter than btc.json — this spec marks estimatesmartfee, getblockcount, getblockchaininfo, getconnectioncount and getchaintips false where btc.json marks them true. That is the right call
Stateful writes sendrawtransaction / submitblock / sendrawmixmessage: stateful: 1, hanging_api: true, 10 CU, timeout_ms: 10000 — matches the guide's tx-submission pattern
405/429 handling Nothing disabled over gateway gating. All 33 HTTP-405 methods and the HTTP-429 existslivetickets re-confirmed as registered dcrd handlers; none reported as unverified or as a disable candidate

Accepted limitations (documented, not findings): DCRT's genesis hash has never been live-confirmed because no Decred testnet RPC exists anywhere (now corroborated against two independent client sources); CI Phase 8 could only run spec-load-only, as no public dcrd JSON-RPC endpoint exists; 34 methods were untestable through the one keyed provider owing to its allow-list and rate limit.

Required action

This run's span was Phase 11 only, so no fix pass ran and dcr.json is untouched — the working tree is clean at 5e48b29. The three edits below are all one-liners and none of them is a disable:

  1. gettreasuryspendvotes → category.deterministic: false (CRITICAL — blocks deployment)
  2. getmixmessage → category.deterministic: false
  3. livetickets → compute_units: 500 + timeout_ms: 180000 (the spec's own gettxoutsetinfo precedent)

To apply them through the pipeline and get a fresh verdict on top, comment:

/rerun-from 10

That runs the Phase 10 fix pass (+ 10b smoke re-probe) and then Phase 11 again. Full report: docs/dcr/SPEC_REVIEW_GAPS_final.md.

TALLY: CRITICAL=1 MEDIUM=2 MINOR=2

🤖 Generated with Claude Code

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Final verdict: ⚠️ CHANGES REQUESTED — TALLY: CRITICAL=1 MEDIUM=2 MINOR=2. The round-1 txfeeinfo CRITICAL is confirmed closed; the deeper all-59-api determinism audit this pass surfaced a third instance of the same defect class (gettreasuryspendvotes). See the Phase 11 comment for the required edits and the /rerun-from 10 retry.

dcr.json is unmodified by this run — the span was Phase 11 only, so no fix pass ran and the working tree is clean at 5e48b29.

#### File Validation
- ✓ JSON syntax valid                                    (Phase 11 `jq -e .` on 5e48b29; 1053 lines)
- ✓ All required fields present                          (Phase 11 re-ran every mechanical guard; 0 FAIL)
- ✓ No duplicate API names within any collection         (Phase 11 re-check; 59 unique apis)
- ✓ Proper indentation/formatting                        (jq-formatted; the 5e48b29 fix was 1 insertion / 1 deletion, no reformatting)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 11 re-derived all 8 from chaincfg source: 5m/2m block times, 6, 3, 1)
- ~ All APIs tested and working                          (manual keyed-node run: 23/59 answered with data, 2 proven by node-originated -22 on junk input, 59/59 bound to their own `function=` label on :metrics. 33 sat behind NOWNodes' HTTP-405 allow-list and 1 hit HTTP 429 — gateway gating, not absence; all 34 re-confirmed as registered dcrd handlers. See docs/dcr/METHOD_PROBE_REPORT.md)
- ~ Block parsing validated for each API                 (all 59 PARSE_BY_ARG indexes checked against each *Cmd struct this pass; 2 directives live-proven. Full per-API parse validation still needs production traffic)
- ✓ Parse directives executed by live router             (GET_BLOCKNUM: getblockcount → 1121278, tracker failed=0 success=1. GET_BLOCK_BY_NUM: getblockhash [1121258] → ccfd43bd…6dbd. Phase 10b re-check: PARSE/VERIFY NOT_TESTABLE in CI — no public endpoint — carried by the manual run instead)
- ✓ Addons & extensions tested                           (none declared; re-confirmed mechanically by check_extensions.sh. dcrd has no pruning, so no archive extension applies and GET_EARLIEST_BLOCK is correctly absent)
- ✓ Verifications pass on live nodes                     (DCR chain-id live-verified: rawData=298e5cc3…b21d980 = mainnet genesis. `smartrouter health` exit 0 / ok: true / chain-id=true)
- ☐ Compute units benchmarked under expected load        (user to measure — and note MEDIUM-2: `livetickets` is 20 CU for a ~2.7 MB full ticket-pool scan)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                (both entries in the single dcr.json; 59 apis, 0 disabled)
- ✓ Testnet spec inherits correctly                      (Phase 11 confirmed: DCRT overrides only the chain-id expected_value and average_block_time; apis/headers/parse_directives merge via CombineUnique(). Proven in-router by an expected-fail boot)
- ~ Chain IDs verified for mainnet AND testnet           (DCR live-verified through the router. DCRT is source-verified only — no Decred testnet RPC exists anywhere — but newly cross-corroborated this pass against two clients outside dcrd: decred/tinydecred nets/testnet.py and trezor/trezor-common decred_testnet.json, both a649dce5…49bac)
- ~ Both tested on respective networks                   (mainnet live through the one keyed provider; testnet network untestable — public testnet services down, NOWNodes has no Decred testnet)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (envelope is exactly { "proposal": { "specs": [ … ] } } — no title/description/deposit, none of the removed 15; verified by check_unused_fields.sh → PASS)
- ☐ Community feedback gathered (if applicable)

Governance / removed-field compliance

check_unused_fields.sh → RESULT: PASS (no removed fields) (exit 0) and check_internal_paths.sh → RESULT: PASS (0 warning(s), no errors), both run as the hard entry gate before any phase work and again inside the reviewer's Phase 0. None of the 15 fields removed in smart-router#218 is present: no spec-level governance fields, no proposal.title/description/top-level deposit, no extra_compute_units/category.local/category.subscription. compute_units is the only compute-unit input, and the file carries zero FUNCTION_TAG_SUBSCRIBE directives — so there are no subscription methods and the run's ws-endpoint requirement did not apply.

Auto-decisions taken at STOP-and-ask gates (unattended run)

  1. Reviewer model bumped to opus (the skill's documented escalation) rather than the default sonnet, because Phase 9's three reviewers all missed the round-1 CRITICAL — the conservative choice at a judgment gate. It found a third defect of that same class.
  2. docs/dcr/METHOD_PROBE_REPORT.md reconstructed from the PR thread (docs/ is gitignored and absent from this checkout) rather than skipping the reviewer's probe-report read. It composes both sources, with the keyed-node manual run as the authoritative live evidence and CI's spec-load-only Phase 8 second, and states the 405-is-gateway-gating reading rule up front.
  3. Nothing disabled over the 33 HTTP-405s or the HTTP-429, per the standing instruction and the settled rule that probe errors never justify disabling. Disabled count stays 0 and the body's <!-- disabled-count: 0 --> marker remains true against the file.
  4. No fix applied for the new CRITICAL. The span was START == END == 11, so Phase 10 did not run and the spec was left byte-identical at 5e48b29. The fix is handed back as /rerun-from 10 rather than being smuggled into a review-only phase.
  5. Verdict reported honestly as CHANGES REQUESTED — not upgraded to APPROVED despite the round-1 CRITICAL being genuinely closed. Per the CI contract the run records the verdict and does not halt, and the Phase-12 summary is still posted.

Run stats — this pipeline run (Phase 11 only)

=== create-spec run stats ===
Elapsed:         00h 18m 29s  (first→last logged activity)
Transcripts:     1 main + 1 subagent
API round-trips: 123  (main=34, subagents=89)

Fresh tokens:    input=246  output=103577  (sum=103823)
Cached tokens:   cache_read=9657862  cache_write=423612
Total billed:    10185297 tokens

Split (total billed):  main=1506877  subagents=8678420

Models used:
  claude-opus-5           123 calls   10185297 billed

These numbers cover Phase 11 only — they are not a 1–11 grand total. Phases 1–7 ran in the original create_spec job (stats in the PR body), and Phases 8–11 ran in the earlier resumable run (run 37464394195). The true end-to-end cost is all three runs added together.

🤖 Generated with Claude Code

…-2961)

- gettreasuryspendvotes: deterministic false. Called without tspends,
  handleGetTreasurySpendVotes reads the live mempool's tspend set.
- getmixmessage: deterministic false. It reads only the node-local
  mixpool, like getmixpairrequests.
- livetickets: 500 CU and a 180 s timeout. It serialises the whole live
  ticket pool (about 41k hashes, about 2.7 MB), like gettxoutsetinfo.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of 81404f9, which applies exactly the three edits the previous Phase 11 verdict listed under "Required action" and nothing else:

  1. gettreasuryspendvotes → deterministic: false (CRITICAL: the default call reads the mempool's tspend set). gettreasurybalance stays true.
  2. getmixmessage → deterministic: false (MEDIUM: node-local mixpool, matching getmixpairrequests).
  3. livetickets → compute_units: 500, timeout_ms: 180000 (MEDIUM: full live-ticket-pool serialisation, matching gettxoutsetinfo).

The two MINORs were informational, with no change required, and stay as is. Everything the previous pass re-verified clean is unchanged. Live evidence remains the manual smart-router run comment above.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=0 MEDIUM=2 MINOR=2)

Resumable run, Phase 11 only (/rerun-final, START_PHASE == END_PHASE == 11). Reviewed dcr.json at 81404f9 with a fresh-context reviewer on opus — kept at the top tier because this chain has now been wrong about category.deterministic twice, which is what the skill's model table calls hard.

All three required edits landed, and all three are correct

The reviewer re-derived each one from dcrd source (internal/rpcserver/rpcserver.go, internal/blockchain/stakeext.go, rpc/jsonrpc/types/chainsvrcmds.go, chaincfg) rather than taking the previous verdict's reasoning on trust:

Required edit Present Correct Source basis
gettreasuryspendvotes → deterministic: false (was CRITICAL) ✅ dcr.json:872 ✅ With tspends absent, handleGetTreasurySpendVotes takes the else branch and enumerates mempool.TSpendHashes() — the default no-arg call returns the node's own mempool tspend set. Two providers at the same tip can legitimately return different votes[].
gettreasurybalance stays deterministic: true ✅ dcr.json:851 ✅ handleGetTreasuryBalance calls only Chain.TreasuryBalance(&hash); no TxMempooler reference anywhere in the handler. The asymmetry with its sibling is deliberate and right.
getmixmessage → deterministic: false (was MEDIUM) ✅ dcr.json:893 ✅ mp := s.cfg.MixPooler; msg, err := mp.Message(msgHash) — node-local gossip state, no chain-backed fallback. Now consistent with the sibling getmixpairrequests (dcr.json:908).
livetickets → 500 CU + timeout_ms: 180000 (was MEDIUM) ✅ dcr.json:727–728 ✅ handleLiveTickets stringifies every hash from Chain.LiveTickets(). Pool size re-measured this pass: dcrdata.decred.org/api/stake/pool → size: 41005 at height 1121490 ≈ 2.7 MB JSON/call. Matches the spec's own gettxoutsetinfo and btc.json's.

Collateral change: none. 81404f9 is 4 insertions, 3 deletions in dcr.json only, confined to those three api objects; working tree clean, so the file on disk is exactly the commit. The round-2 CRITICAL is genuinely closed.

Why the verdict is still CHANGES REQUESTED

The independent re-sweep of the four defect classes across all 59 apis — run precisely because each of the last two passes found a fresh instance — turned up two more methods in the same class the livetickets fix just addressed. Both were verified against the file on disk this run: compute_units: 20, no timeout_ms key at all.

MEDIUM-1 — getticketpoolvalue is a 41k-entry UTXO scan at 20 CU with no timeout

dcr.json:781 (name), CU at dcr.json:788. handleGetTicketPoolValue is a one-liner onto Chain.TicketPoolValue(), which in internal/blockchain/stakeext.go walks the live pool and hits the UTXO layer per ticket:

for _, hash := range sn.LiveTickets() {
        outpoint := wire.OutPoint{Hash: hash, Index: 0, Tree: wire.TxTreeStake}
        utxo, err := b.utxoCache.FetchEntry(outpoint)
        ...
        amt += utxo.Amount()
}

This is strictly more work than livetickets — the method this very commit repriced. Chain.LiveTickets() returns sn.LiveTickets() and stops; it never touches the UTXO layer. TicketPoolValue() walks the same 41,005 entries plus one utxoCache.FetchEntry each, and utxoCache is a bounded in-memory cache in front of the utxo database — on a cold or memory-constrained node a large share of those become database reads. The handler takes no arguments, so there is no cheap invocation.

Failure scenario. A consumer calls getticketpoolvalue against a provider whose utxo cache is cold (fresh restart, wide working set). The node issues ~41,000 utxo-db reads. Lava bills 20 CU — the same as getblockheader — and applies the collection's default relay timeout rather than the 180 s the spec grants the cheaper livetickets. The provider absorbs an uncompensated multi-second-to-minutes operation, and if it overruns the default timeout the relay is scored as a provider failure rather than an expensive-but-successful call.

Fix: compute_units: 500, add timeout_ms: 180000.

MEDIUM-2 — ticketsforaddress is the same scan, with worse amplification

dcr.json:766 (name), CU at dcr.json:773. handleTicketsForAddress → Chain.TicketsWithAddress(stakeAddr). There is no address-index short-circuit: the address is used only as a comparison target inside the loop, so the scan is always the whole 41,005-entry pool with a utxoCache.FetchEntry plus script compare per entry, no matter how many tickets the address owns.

Failure scenario. A wallet backend polls ticketsforaddress once per staking address. Each call is ~41,000 utxo reads to return what is typically an empty or one-element array: N addresses cost N × 41,000 reads for 20N CU, each call individually at risk of a default-timeout abort attributed to the provider. The small response is misleading — the cost is in the scan, not the serialisation, which is why CU has to move and not just timeout_ms.

Fix: compute_units: 500, add timeout_ms: 180000.

Both methods fall inside the 33 HTTP-405 gateway-gated set, so no probe could have surfaced them; both findings come from dcrd source plus a public explorer measurement, and neither is grounds to disable anything.

The two MINORs are unchanged and still require no change

  • MINOR-1 — PARSE_BY_ARG ["0"] on gettreasurybalance (dcr.json:846) and gettreasuryspendvotes (dcr.json:867) targets an optional argument. On a no-arg call the parser yields no block and the request is treated as latest, which is exactly what both handlers do (BestSnapshot()). In-repo precedent: btc.json getchaintxstats. Informational.
  • MINOR-2 — no SUBSCRIBE coverage. Re-derived from internal/rpcserver/rpcwebsocket.go: dcrd's wsHandlersBeforeInit exposes per-topic notify*/stopnotify* handlers that take no params and return nil, nil, keying subscriptions on the websocket client. Lava needs an UNSUBSCRIBE templating a subscription-id handle, and there is no handle to template — this needs router-side mapping, not a spec edit. Mechanically re-confirmed: zero FUNCTION_TAG_SUBSCRIBE directives, so the run's hard ws-endpoint requirement does not apply. Informational.

Everything else re-verified clean this pass

Nothing carried over on the strength of an earlier PASS.

Area Result
category.deterministic, all 19 true apis Each re-derived against its handler: either pure computation (validateaddress, verifymessage, decoderawtransaction, decodescript, createrawtransaction, createrawsstx, getcurrentnet) or block-keyed committed state (getblock, getblockhash, getblockheader, getblocksubsidy, getcfilterv2, getheaders, getstakeversions, gettreasurybalance, gettxoutsetinfo, ticketvwap, createrawssrtx). No true api reads the mempool or mixpool. getrawtransaction noted explicitly: it is mempool-first, but btc.json sets the identical flag at the same 10 CU for Core's identically mempool-first handler — a cross-chain policy question, not a dcr.json defect
deterministic: false on the other 40 All correct and stricter than btc.json, which marks getblockcount/getbestblockhash/getblockchaininfo/getchaintips/getdifficulty true
Missing timeout_ms sweep MEDIUM-1/-2 are the only remaining instances. gettxoutsetinfo + livetickets covered; the three stateful: 1 broadcasts each carry timeout_ms: 10000. Four range-taking methods (ticketfeeinfo, txfeeinfo, getstakeversions, ticketvwap) deliberately not flagged — their default invocation is cheap, so they are consumer-bounded. dcrd has no long-polling read method (no getblocktemplate in its handler map at all), so nothing needs hanging_api: true and lacks it
block_parsing All 8 PARSE_BY_ARG apis checked field-by-field against their *Cmd structs — every one resolves to argument 0 with a matching parse_type. The 51 DEFAULT apis swept for a missed block arg: only getnetworkhashps has one (height at index 1, defaults -1), and btc.json sets DEFAULT/latest for the identical method. getheaders takes an array of locators, which PARSE_BY_ARG cannot address
stateful stateful: 1 + hanging_api: true + timeout_ms: 10000 on exactly the three broadcasts (sendrawtransaction, submitblock, sendrawmixmessage); cross-checked against the full dcrd handler map — nothing else mutates state
Method coverage 0 phantom methods — all 59 names present in dcrd's rpcHandlersBeforeInit. The 18 omissions are all admin/mining/node-control (stop, addnode, generate, getwork, invalidateblock, verifychain, …). No public read method missing
Network params Re-derived by compiling chaincfg/v3 this pass: target=5m0s (DCR) / 2m0s (DCRT testnet3) → 300000/120000 exact; block_distance_for_finalized_data: 6 (dcrd itself hardcodes 6 as max reorg depth), blocks_in_finalization_proof: 3 for probabilistic PoW/PoS, allowed_block_lag_for_qos_sync: 1 per the formula floor on both. Corroborated empirically at 299.96 s/block
Chain-ids DCR source + live + router-verified (chaincfg → 298e5cc3…b21d980, matched by dcrdata/api/block/0 and the router's rawData). DCRT newly source-verified by executing chaincfg.TestNet3Params().GenesisHash → a649dce5…4a49bac, upgrading it past the prior two-client-source corroboration; still not live-confirmed (testnet3 RPC + testnet.dcrdata.org + testnet.decred.org all re-probed this pass → HTTP 503)
DCRT inheritance Correct — CollectionData matches on all four fields, apis/headers/parse_directives/extensions all [] so they inherit via CombineUnique rather than zeroing out, and the chain-id verification carries no parse_directive, adopting DCR's and overriding only expected_value. Proven in-router: DCRT booted with its own averageBlockTime: 2m0s, and the deliberate expected-fail boot showed the testnet value being applied
Parse directives GET_BLOCKNUM/GET_BLOCK_BY_NUM (dcr.json:967–988) byte-for-byte btc.json's shape; both live-proven (getblockcount → 1121278, getblockhash [1121258] → ccfd43bd…6dbd, tracker polling all session). GET_EARLIEST_BLOCK correctly absent — extensions: [], no archive extension, so no pruning verification applies
Headers headers: [] correct for native JSON-RPC/POST — the NOWNodes key travels in the URL path (provider endpoint config, not spec content) and all 59 methods are application/json
Removed-field + internal-path guards check_unused_fields.sh → RESULT: PASS (no removed fields), exit 0 — none of the forbidden 15; no extra_compute_units, category.local or category.subscription. Canonical envelope { "proposal": { "specs": [ … ] } } exactly. The only internal_path in the file is "", so the internal-path guard's four findings cannot arise
Disabled-API ledger audit 0 enabled: false apis and 0 disabled collections; ledger is (none — no disabled APIs) — matches exactly, no unjustified disable. check_disabled_count.sh → 0 distinct method(s), RESULT: PASS. The body's <!-- disabled-count: 0 --> marker is still true; no correction needed
405/429 handling Nothing disabled over gateway gating. All 33 HTTP-405 methods and the HTTP-429 existslivetickets re-confirmed as registered dcrd handlers; a deliberately nonexistent method got the identical 405, so 405 is NOWNodes' allow-list, not dcrd capability. None reported as unverified or as a disable candidate

Accepted limitations (documented, not findings): DCRT's genesis hash has never been live-confirmed because no Decred testnet RPC exists anywhere (now source-verified by executing dcrd's own chaincfg); CI Phase 8 could only run spec-load-only, as no public dcrd JSON-RPC endpoint exists; 34 methods were untestable through the one keyed provider owing to its allow-list and rate limit.

Required action

This run's span was Phase 11 only, so no fix pass ran and dcr.json is untouched — the working tree is clean at 81404f9. Two one-line edits remain, neither of them a disable, both the same pattern this commit already applied to livetickets:

  1. dcr.json:788 — getticketpoolvalue: "compute_units": 20 → 500, add "timeout_ms": 180000
  2. dcr.json:773 — ticketsforaddress: "compute_units": 20 → 500, add "timeout_ms": 180000

To apply them through the pipeline and get a fresh verdict on top, comment:

/rerun-from 10

That runs the Phase 10 fix pass (+ 10b smoke re-probe) and then Phase 11 again. Full report: docs/dcr/SPEC_REVIEW_GAPS_final.md.

Not deployment-blocking — zero CRITICAL, zero disabled apis, and no defect that breaks routing, parsing or verification. Both MEDIUMs are economic/QoS: a provider absorbs an uncompensated ~41,000-read scan priced at 20 CU, and the default relay timeout can abort a correctly-functioning provider mid-scan and score it as a failure.

TALLY: CRITICAL=0 MEDIUM=2 MINOR=2

🤖 Generated with Claude Code

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Reviewed dcr.json at 81404f9. Verdict: ⚠️ CHANGES REQUESTED (CRITICAL=0 MEDIUM=2 MINOR=2) — see the Phase 11 comment above.

Annotations: ✓ verified this run · ~ partially verified · ☐ out of skill scope or blocked.

#### File Validation
- ✓ JSON syntax valid                                    (Phase 11: `jq -e .` parses; file is exactly 81404f9, working tree clean)
- ✓ All required fields present                           (Phase 11 full-spec audit, all 59 apis + both spec entries)
- ✓ No duplicate API names within any collection          (Phase 11 mechanical check)
- ✓ Proper indentation/formatting                         (4-space, no trailing newline — root-spec convention)
- ✓ Removed-field guard                                   (`check_unused_fields.sh` → PASS, exit 0: none of the forbidden 15; no extra_compute_units / category.local / category.subscription)
- ✓ Canonical envelope                                    ({ "proposal": { "specs": [ … ] } } exactly; no title/description/deposit, no governance fields)
- ✓ Internal-path guard                                   (only internal_path in the file is ""; the four path findings cannot arise)

#### Configuration Verification
- ✓ Network parameters calculated per formulas            (Phase 11 re-derived by COMPILING chaincfg/v3: target 5m0s/2m0s → 300000/120000 exact; 6 / 3 / 1 all correct; corroborated empirically at 299.96 s/block)
- ~ All APIs tested and working                           (23 of 59 answered live through the keyed NOWNodes endpoint + 2 proved existent via node-originated -22; 33 gateway-gated at HTTP 405, 1 rate-limited at 429 — allow-list artefacts, NOT spec defects, nothing disabled over them)
- ~ Block parsing validated for each API                  (all 8 PARSE_BY_ARG apis checked field-by-field against their *Cmd structs; the 51 DEFAULT apis swept for a missed block arg — full per-API parse validation needs production traffic)
- ~ Parse directives executed by live router              (manual run: GET_BLOCKNUM → 1121278, GET_BLOCK_BY_NUM [1121258] → ccfd43bd…6dbd, tracker polling all session. CI Phase 8 was PARSE: NOT_TESTABLE — no public dcrd JSON-RPC endpoint exists)
- ✓ Addons & extensions tested                            (ADDONS: none declared — jq over every add_on/extension field returns empty on both entries; nothing to test)
- ~ Verifications pass on live nodes                      (DCR chain-id source + live + router-verified: chaincfg → 298e5cc3…b21d980, matched by dcrdata/api/block/0 and the router's rawData. DCRT source-verified only — see Testnet below)
- ☐ Compute units benchmarked under expected load         (user to measure — and note the two open MEDIUMs are exactly CU/timeout findings)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                 (DCR: 59 apis, 2 parse directives, 1 verification, no extensions)
- ✓ Testnet spec inherits correctly                       (DCRT CollectionData matches on all four fields; apis/headers/parse_directives/extensions all [] so they inherit via CombineUnique; chain-id verification carries no parse_directive, adopting DCR's and overriding only expected_value. Proven in-router — DCRT booted with its own averageBlockTime 2m0s)
- ~ Chain IDs verified for mainnet AND testnet            (DCR verified three ways. DCRT NEWLY source-verified this pass by executing chaincfg.TestNet3Params().GenesisHash → a649dce5…4a49bac, upgrading it past the prior two-client corroboration — but still never live-confirmed)
- ☐ Both tested on respective networks                    (mainnet only. No Decred testnet RPC exists anywhere: testnet3 RPC, testnet.dcrdata.org and testnet.decred.org all re-probed this pass → HTTP 503. TESTNET_VERIFY: SKIPPED)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                     (the file carries the { "proposal": { "specs": [ … ] } } wrapper — no title/description/deposit)
- ☐ Community feedback gathered (if applicable)

Phases run this invocation

Phase Status
8 — smart-router boot + probe not in span (reused the Phase 8 comment of 2026-10-06 + the manual keyed-provider run as live evidence)
9 — parallel reviewers not in span
10 / 10b — fix pass + smoke re-probe not in span — so no fix ran and dcr.json is untouched at 81404f9; nothing uncommitted was left in the working tree
11 — final reviewer verdict ✅ ran (opus) → CHANGES REQUESTED, CRITICAL=0 MEDIUM=2 MINOR=2
12 — closing summary ✅ this comment

Open items

  1. dcr.json:788 — getticketpoolvalue: compute_units 20 → 500, add timeout_ms: 180000 (MEDIUM)
  2. dcr.json:773 — ticketsforaddress: compute_units 20 → 500, add timeout_ms: 180000 (MEDIUM)

Both are the same full-live-ticket-pool-scan pattern this commit already applied to livetickets; both methods are strictly heavier than it (they add a utxoCache.FetchEntry per ticket over ~41,005 entries). Neither is deployment-blocking and neither is a disable. To apply them and re-verify, comment /rerun-from 10.

The two MINORs (optional-parameter PARSE_BY_ARG ["0"] on the treasury methods; no SUBSCRIBE coverage for dcrd's handle-less per-topic WebSocket notifications) are informational and require no change.

Run stats — this pipeline run only (Phases 11–11)

=== create-spec run stats ===
Elapsed:         00h 17m 06s  (first→last logged activity)
Transcripts:     1 main + 1 subagent
API round-trips: 112  (main=26, subagents=86)

Fresh tokens:    input=224  output=88468  (sum=88692)
Cached tokens:   cache_read=9551311  cache_write=378574
Total billed:    10018577 tokens

Split (total billed):  main=1775398  subagents=8243179

Models used:
  claude-opus-5           112 calls   10018577 billed

These figures cover only this run (Phase 11). They are not a Phases 1–11 grand total: the Phases 1–7 time and tokens live in the original create_spec run and its PR body, and the earlier Phase 8–11 and Phase 11 re-runs each have their own. The true total is the sum across all of those runs.

🤖 Generated with Claude Code

…961)

getticketpoolvalue and ticketsforaddress both walk the whole live ticket
pool (about 41k entries, one utxo read each). Give them 500 CU and a
180 s timeout, matching livetickets and gettxoutsetinfo. These were the
two remaining MEDIUMs from the Phase 11 review on #186.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of the latest commit, which applies exactly the two fixes the previous Phase 11 verdict listed and nothing else:

  1. getticketpoolvalue → compute_units: 500, timeout_ms: 180000 (MEDIUM-1).
  2. ticketsforaddress → compute_units: 500, timeout_ms: 180000 (MEDIUM-2).

Both now match livetickets / gettxoutsetinfo. The previous pass swept the whole file and called these the only remaining missing-timeout instances; all 59 determinism flags were already re-derived as correct. The two MINORs were informational and stay as is.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED (TALLY: CRITICAL=0 MEDIUM=0 MINOR=3)

Resumable run, Phase 11 only (/rerun-final, START_PHASE == END_PHASE == 11). Reviewed dcr.json at 0d4a613 with a fresh-context reviewer on opus — held at the top tier for a fourth pass because this chain surfaced a new defect on each of the three previous ones (wrong category.deterministic twice, then a missing-timeout_ms class the earlier sweeps had called closed). Ground truth: github.com/decred/dcrd cloned at 83beff12 (2026-10-05).

Both required edits landed, and both are correct

The reviewer re-derived each from dcrd source rather than taking the previous verdict's reasoning on trust:

Required edit Present Correct Source basis
getticketpoolvalue → 500 CU + timeout_ms: 180000 (was MEDIUM-1) ✅ dcr.json:789–790 ✅ handleGetTicketPoolValue (rpcserver.go:3260) → Chain.TicketPoolValue(), which in stakeext.go:140–158 iterates every sn.LiveTickets() hash with one utxoCache.FetchEntry each. No arguments, no short-circuit
ticketsforaddress → 500 CU + timeout_ms: 180000 (was MEDIUM-2) ✅ dcr.json:773–774 ✅ handleTicketsForAddress (rpcserver.go:4897) → TicketsWithAddress (stakeext.go:80–103): the address filter is applied after the per-ticket UTXO read, so there is no index and no early exit — same work plus a script compare

The values were checked too, not just their presence: pool size re-derived from chaincfg (TicketPoolSize = 8192 × TicketsPerBlock = 5 → ≈40,960 live entries, matching the ~41,005 measured last pass), and 500 CU / 180000 ms is exactly what livetickets (dcr.json:720–734) and gettxoutsetinfo (dcr.json:458–472) carry in this same file — gettxoutsetinfo at those values being the in-repo anchor for a full-set scan, and btc.json the only other spec in the repo that sets timeout_ms at all, on exactly that one method with exactly those numbers.

Collateral change: none. 0d4a613 is 4 insertions, 2 deletions in dcr.json only, confined to those two api objects; no reformatting, no other file. Working tree clean, so the file on disk is exactly the commit. Both round-3 MEDIUMs are genuinely closed.

The missing-timeout_ms class is now provably closed

This is the finding that reopened the review twice, so the reviewer closed it by enumeration rather than by sweep. Grepping dcrd for every RPC call site of Chain.LiveTickets(), TicketsWithAddress, TicketPoolValue and FetchUtxoStats yields exactly four entry points — there is no fifth member:

Method Scan CU timeout_ms
livetickets full live-ticket treap 500 ✅ 180000
ticketsforaddress full pool + 1 UTXO read/ticket 500 ✅ 180000 (this commit)
getticketpoolvalue full pool + 1 UTXO read/ticket 500 ✅ 180000 (this commit)
gettxoutsetinfo full UTXO set (FetchUtxoStats) 500 ✅ 180000

Five range-taking methods were checked and deliberately not flagged, with the reasoning recorded: txfeeinfo (default range = last WorkDiffWindowSize = 144 blocks), ticketfeeinfo (default = mempool only, blocks/windows default 0), ticketvwap (default 20 × 144 = 2880 headers, served from the in-memory block index), getstakeversions/getstakeversioninfo (same in-memory index), getheaders (hard-bounded at 2000 by wire.MaxBlockHeadersPerMsg), existsaddresses/existslivetickets (bounded by the caller's own list). All are consumer-bounded at their default invocation, and argument-widened range scans priced in the default band are established in-repo precedent — btc.json prices the structurally identical getchaintxstats at 10 CU with no timeout, so dcr.json at 20 is already the more conservative of the two.

Everything else re-derived from scratch this pass

Explicitly not carried over on the strength of an earlier PASS:

Area Result
category.deterministic, all 59 apis Every handler body extracted and grepped for node-local state (TxMempooler, MixPooler, ConnMgr, SyncMgr, AddrManager, CPUMiner, NetTotals, BestSnapshot), then each hit read in context. Every handler touching mempool, mixpool or peer/gossip state is false, with no exception — 8 mempool, 2 mixpool, 6 peer/connmgr, 2 fee-estimator, 2 node-local-index, 17 tip-pinned. All 19 true apis individually justified: pure computation, or state keyed by the block in the argument. The two earlier fixes confirmed still in place (txfeeinfo at 5e48b29, gettreasuryspendvotes/getmixmessage at 81404f9)
Method coverage rpcHandlersBeforeInit registers 77 methods. 0 phantom — all 59 spec names resolve to a real handler. The 18 omissions are all admin/mining/profiling/meta (stop, addnode, generate, getwork, invalidateblock, verifychain, help, …). Cross-checked against dcrd's own rpcLimited read-only allow-list: its only absent members beyond help live in rpcwebsocket.go, not the JSON-RPC handler map, so they cannot belong to a jsonrpc/POST collection. The 7 spec methods outside rpcLimited are all read-only and merely full-auth-gated; 3 of them answered live
block_parsing All 8 PARSE_BY_ARG apis re-checked field-by-field against their *Cmd structs in chainsvrcmds.go — every one resolves to argument 0 with a matching type. The 51 DEFAULT apis take no block reference. No api needs EMPTY, PARSE_CANONICAL or PARSE_DICTIONARY_OR_ORDERED
stateful / hanging_api stateful: 1 + hanging_api: true + 10 CU + timeout_ms: 10000 on exactly the three broadcasts (sendrawtransaction, submitblock, sendrawmixmessage) — the only three handlers in the spec that call a broadcast path. No read method carries either flag; the createraw* family builds hex locally and is correctly stateful: 0
Network params Re-derived from chaincfg TargetTimePerBlock: 5m0s (DCR) / 2m0s (DCRT testnet3) → 300000/120000 exact. 6 sits in the PoW band and matches dcrd's own max-reorg-depth guard; 3 per the probabilistic-finality rule; 1 is the formula floor on both. Corroborated at 299.96 s/block lifetime mean (≈0.01% drift)
Chain-ids Both expected_values recomputed by executing chaincfg at dcrd HEAD: DCR → 298e5cc3…b21d980, DCRT → a649dce5…4a49bac. Both match the spec. DCR additionally live-confirmed by the manual router run's verified successfully … rawData=298e5cc3…d980
DCRT inheritance Textbook Scenario-B override — CollectionData matches on all four fields; apis/headers/inheritance_apis/parse_directives/extensions all [] so the 59 parent apis and both directives merge through via CombineUnique; the chain-id verification carries no parse_directive, adopting DCR's and replacing only expected_value. All four network params set explicitly rather than inherited. Empirically confirmed twice: CI Phase 8 loaded DCRT with its own averageBlockTime 2m0s, and the deliberate expected-fail boot showed the testnet genesis being applied
Parse directives GET_BLOCKNUM/GET_BLOCK_BY_NUM byte-for-byte btc.json's shape, both referencing apis that exist in the collection; both live-proven (getblockcount → 1121278, getblockhash [1121258] → ccfd43bd…6dbd, tracker polling all session). GET_EARLIEST_BLOCK correctly absent — no archive extension anywhere, so no pruning verification applies
Headers headers: [] correct for a native JSON-RPC POST spec — no auth header to pass_send (the NOWNodes key travels in the URL path, which is provider endpoint config, not spec content) and no content-type to pass_override
Removed-field + internal-path guards check_unused_fields.sh → RESULT: PASS (no removed fields), exit 0 — none of the forbidden 15, no extra_compute_units / category.local / category.subscription. Canonical envelope { "proposal": { "specs": [ … ] } } exactly. The only internal_path in the file is "", so the four internal-path findings cannot arise
Disabled-API ledger audit 0 enabled: false apis and 0 disabled collections — matches the empty ledger exactly, so no unjustified disable. check_disabled_count.sh → 0 distinct method(s), RESULT: PASS. The body's <!-- disabled-count: 0 --> marker is still true; no correction needed
405/429 handling Nothing disabled over gateway gating. All 33 HTTP-405 methods and the HTTP-429 existslivetickets re-confirmed as registered dcrd handlers; a deliberately nonexistent method returns the identical 405, so 405 is NOWNodes' allow-list, not dcrd capability. None reported as unverified or as a disable candidate

The three MINORs are informational — no edit recommended on any

  • MINOR-1 (carried forward, re-verified) — PARSE_BY_ARG ["0"] on gettreasurybalance (dcr.json:848) and gettreasuryspendvotes (dcr.json:869) targets an optional *string. Re-read of both handlers confirms they fall back to Chain.BestSnapshot() when the argument is omitted, so on a no-arg call the parser yields no block, Lava treats the request as latest, and that is exactly what the handler does — correct in both branches. In-repo precedent: btc.json getchaintxstats.
  • MINOR-2 (carried forward, re-verified) — no SUBSCRIBE coverage. rpcwebsocket.go:83–98 exposes notify*/stopnotify* per topic, but those handlers take no parameters and return no subscription handle (handleNotifyBlocks → nil, nil; stopnotifyblocks is addressed by connection, not by id). Lava has no %s handle to template an UNSUBSCRIBE on — router-side mapping, not a spec edit. Mechanically re-confirmed: zero FUNCTION_TAG_SUBSCRIBE directives and nothing inherited, so this run's hard ws-endpoint requirement does not apply.
  • MINOR-3 (new this pass, informational) — determinism asymmetry inside the tip-pinned full-scan family: gettxoutsetinfo is true (dcr.json:469) while livetickets/ticketsforaddress/getticketpoolvalue are false (:731, :777, :793), despite all four being structurally identical (no block argument, DEFAULT ["latest"], result read off whatever tip the serving node is at). Both readings are defensible, and no edit is recommended in either direction: gettxoutsetinfo: true is a verbatim btc.json match, and false on the three ticket methods is the safe direction — it only forgoes a cross-provider reliability check, whereas the reverse error would manufacture spurious reliability failures. Recorded for the record, not for action.

Accepted limitations (documented, not findings)

  • No public dcrd JSON-RPC endpoint exists on any network, so CI's Phase 8 could only run spec-load-only. The live evidence for this chain is the human-supplied manual smart-router v1.5.8 run (keyed NOWNodes mainnet, key withheld): boot, chain-id, both parse directives, per-method function= binding for all 59 methods, and 25 methods answering end-to-end (23 with data + 2 proved existent via node-originated -22).
  • 34 methods were untestable through that one keyed provider (33 × 405 allow-list, 1 × 429 rate limit) — provider artefacts, not dcrd gaps.
  • DCRT has never been live-confirmed, because no Decred testnet RPC exists anywhere (testnet3 RPC, testnet.dcrdata.org, testnet.decred.org → HTTP 503 on every prior probe). Its genesis hash is now source-confirmed by executing dcrd's own chaincfg; a live getblockhash(0) would be purely corroborative.

Required action

None. dcr.json at 0d4a613 is approved as-is. This run's span was Phase 11 only, so no fix pass ran and the working tree is clean — nothing uncommitted was left behind.

Deployment readiness: READY — zero CRITICAL, zero MEDIUM, zero disabled apis, and no defect affecting routing, parsing or verification. The one unverified value on the whole spec (DCRT's genesis hash) is blocked on Decred testnet infrastructure that does not exist, not on anything in this spec.

Full report: docs/dcr/SPEC_REVIEW_GAPS_final.md.

TALLY: CRITICAL=0 MEDIUM=0 MINOR=3

🤖 Generated with Claude Code

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Reviewed dcr.json at 0d4a613. Verdict: ✅ APPROVED (CRITICAL=0 MEDIUM=0 MINOR=3) — see the Phase 11 comment above.

Annotations: ✓ verified this run · ~ partially verified · ☐ out of skill scope or blocked.

#### File Validation
- ✓ JSON syntax valid                                    (Phase 11: `jq -e .` parses; file is exactly 0d4a613, working tree clean)
- ✓ All required fields present                          (Phase 11 full-spec audit, all 59 apis + both spec entries)
- ✓ No duplicate API names within any collection         (Phase 11 mechanical check: 59 apis, 59 unique names)
- ✓ Proper indentation/formatting                        (4-space, no trailing newline — root-spec convention; this commit added no reformatting)
- ✓ Removed-field guard                                  (`check_unused_fields.sh` → PASS, exit 0: none of the forbidden 15; no extra_compute_units / category.local / category.subscription)
- ✓ Canonical envelope                                   ({ "proposal": { "specs": [ … ] } } exactly; no title/description/deposit, no governance fields)
- ✓ Internal-path guard                                  (only internal_path in the file is ""; the four path findings cannot arise)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 11 re-derived from chaincfg TargetTimePerBlock: 5m0s/2m0s → 300000/120000 exact; 6 / 3 / 1 all correct; corroborated at 299.96 s/block lifetime mean)
- ~ All APIs tested and working                           (25 of 59 proved live through the keyed NOWNodes endpoint — 23 answering with data + 2 via node-originated -22; 33 gateway-gated at HTTP 405, 1 rate-limited at 429 — allow-list artefacts, NOT spec defects, nothing disabled over them)
- ~ Block parsing validated for each API                  (all 8 PARSE_BY_ARG apis re-checked field-by-field against their *Cmd structs; the 51 DEFAULT apis confirmed to take no block reference — full per-API parse validation needs production traffic)
- ~ Parse directives executed by live router              (manual run: GET_BLOCKNUM → 1121278, GET_BLOCK_BY_NUM [1121258] → ccfd43bd…6dbd, tracker polling all session. CI Phase 8 was PARSE: NOT_TESTABLE — no public dcrd JSON-RPC endpoint exists)
- ✓ Addons & extensions tested                            (ADDONS: none declared — jq over every add_on/extension field returns 0 on both entries; nothing to test)
- ~ Verifications pass on live nodes                      (DCR chain-id source + live + router-verified: chaincfg → 298e5cc3…b21d980, matched by the router's rawData. DCRT source-verified only — see Testnet below)
- ☐ Compute units benchmarked under expected load         (user to measure — note the four full-scan methods are now all priced at 500 CU / 180 s by source-derived reasoning, not by measurement)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                 (DCR: 59 apis, 2 parse directives, 1 verification, 0 addons, 0 extensions)
- ✓ Testnet spec inherits correctly                       (DCRT CollectionData matches on all four fields; apis/headers/inheritance_apis/parse_directives/extensions all [] so the 59 parent apis and both directives merge via CombineUnique; chain-id verification carries no parse_directive, adopting DCR's and overriding only expected_value. Proven in-router twice — DCRT booted with its own averageBlockTime 2m0s, and the expected-fail boot applied the testnet genesis)
- ~ Chain IDs verified for mainnet AND testnet             (BOTH expected_values recomputed this pass by executing chaincfg at dcrd HEAD 83beff12 — DCR 298e5cc3…b21d980, DCRT a649dce5…4a49bac, both match. DCR also live-confirmed; DCRT never live-confirmed)
- ☐ Both tested on respective networks                    (mainnet only. No Decred testnet RPC exists anywhere: testnet3 RPC, testnet.dcrdata.org and testnet.decred.org all returned HTTP 503 on every prior probe. TESTNET_VERIFY: SKIPPED)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                     (the file carries the { "proposal": { "specs": [ … ] } } wrapper — no title/description/deposit)
- ☐ Community feedback gathered (if applicable)

Phases run this invocation

Phase Status
8 — smart-router boot + probe not in span (reconstructed the Phase 8 report from its PR comment of 2026-10-06, with the manual keyed-provider run appended as the live evidence, and handed it to the reviewer)
9 — parallel reviewers not in span
10 / 10b — fix pass + smoke re-probe not in span — so no fix ran and dcr.json is untouched at 0d4a613; nothing uncommitted was left in the working tree
11 — final reviewer verdict ✅ ran (opus) → APPROVED, CRITICAL=0 MEDIUM=0 MINOR=3
12 — closing summary ✅ this comment

Open items

None blocking. Both MEDIUMs from the previous verdict are closed, and the missing-timeout_ms class that reopened this review twice is now closed by enumeration — grepping dcrd for every RPC call site of LiveTickets(), TicketsWithAddress, TicketPoolValue and FetchUtxoStats yields exactly four methods (livetickets, ticketsforaddress, getticketpoolvalue, gettxoutsetinfo), and all four now carry 500 CU + timeout_ms: 180000. There is no fifth member.

Three MINORs are informational and recommend no edit: the optional-parameter PARSE_BY_ARG ["0"] on the two treasury methods (correct in both the arg and no-arg branches); the absent SUBSCRIBE coverage (dcrd's notify* handlers return no subscription handle to template an UNSUBSCRIBE on — router-side work, not a spec edit); and a determinism asymmetry inside the tip-pinned full-scan family, where the current split is the safe direction and matches btc.json.

Two accepted limitations remain outside this spec's control: no public dcrd JSON-RPC endpoint exists on any network, so CI can never functionally probe this chain (the human-supplied manual router run is the live evidence); and DCRT cannot be live-confirmed because no Decred testnet RPC exists anywhere — its genesis hash is source-confirmed against dcrd's own chaincfg instead.

Run stats — this pipeline run only (Phases 11–11)

=== create-spec run stats ===
Elapsed:         00h 13m 31s  (first→last logged activity)
Transcripts:     1 main + 1 subagent
API round-trips: 113  (main=26, subagents=87)

Fresh tokens:    input=226  output=81092  (sum=81318)
Cached tokens:   cache_read=7944351  cache_write=401272
Total billed:    8426941 tokens

Split (total billed):  main=1210649  subagents=7216292

Models used:
  claude-opus-5           113 calls   8426941 billed

These figures cover only this run (Phase 11). They are not a Phases 1–11 grand total: the Phases 1–7 time and tokens live in the original create_spec run and its PR body, and the earlier Phase 8–11 run plus the two prior Phase-11 re-runs each have their own. The true total is the sum across all of those runs.

🤖 Generated with Claude Code

@avitenzer avitenzer left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested at 0d4a6131 with smart-router built from main against a keyed NOWNodes mainnet endpoint (key withheld). Not approving yet. The spec boots and routes correctly, but a few classifications and the body need another pass.

What passed

  • Boot: spec loads, and the chain tracker fetched a live tip with getblockcount.
  • chain-id (genesis hash 298e5cc3…b21d980) passes in smartrouter health.
  • I called 57 of the 59 methods both through the router and directly on the node. The router matched the node on all 57. 24 answered, or returned the node's own expected error: param errors, and sendrawtransaction rejecting junk hex with -22, which shows writes reach the node.
  • The other 33 got HTTP 405 from NOWNodes. The body says the gateway blocks only 5 methods (version, getbestblock, getstakedifficulty, existsaddress, getcurrentnet), but it actually blocks 33, including all the ticket-pool methods 0d4a613 re-priced. Those have no live answer.

Spec changes requested

1. deterministic: true on results that move with the tip. In smart-router this flag gates cross-validation mismatch alerting, so a wrong true reports a false outlier whenever two providers are at different heights.

  • ticketvwap: with no args dcrd uses end = bestHeight and start = tip − 2880, and the spec parses no block (DEFAULT).
  • getheaders: with an empty hashStop, LocateHeaders returns headers up to the tip.
  • gettreasurybalance with no argument reads BestSnapshot().

The Phase 11 approval says all 19 true apis are "pure computation, or state keyed by the block in the argument"; the first two have no block argument in the spec. Suggest false. gettxoutsetinfo has the same issue (its result carries height/bestblock), but it mirrors btc.json, so I'd fix both specs together or neither.

2. gettreasurybalance / gettreasuryspendvotes without an argument parse as NOT_APPLICABLE, not latest. parseByArg returns ValueNotSetError, and ParseRawBlock (protocol/parser/parser.go:107-125) falls back only when the spec sets default_value. These two don't, so a no-arg call is never cached or consistency-checked. That contradicts Phase 11's MINOR-1 reasoning ("Lava treats the request as latest"). Suggest adding "default_value": "latest" to both block_parsing objects.

PR body is out of date

  • "CU histogram across the 59 apis: 40×10, 18×20, 1×500": the file is 40×10, 15×20, 4×500 (gettxoutsetinfo, livetickets, ticketsforaddress, getticketpoolvalue, each with timeout_ms: 180000).
  • Auto-decision 10 ("Three CU deviations…") still lists the three ticket scans as rated 20. c6a1592 and 0d4a613 changed them.
  • The "Method Not Allowed for 5 methods" line, per above.

Router follow-up (not this PR's diff, but it blocks running this spec with the cache on)

protocol/rpcsmartrouter/node_bound_methods.go is the router's list of node-specific methods it refuses to cache. It has getrawmempool, getmempoolinfo and getconnectioncount, but none of the Decred node-local reads: existsmempooltxs, getmixpairrequests, getmixmessage, getpeerinfo, getnettotals, getnetworkinfo, getinfo, version. They are all DEFAULT ["latest"], so they are cached under the current tip, and the unfinalized TTL is averageBlockTime/8, which is 37.5 s at Decred's 300 s blocks. For example, a wallet polling existsmempooltxs after a send would read a stale "not present" for up to 37.5 s. This needs a smart-router ticket before Decred goes live behind a cache. I can open it.

Known gaps (not defects)

  • DCRT has never run live: no testnet RPC exists, and the genesis hash is checked against source only.
  • MAG-2961 asks for mainnet only and is still in Blocked status.

…lt treasury parsing to latest (MAG-2961)

- ticketvwap, getheaders, gettreasurybalance -> deterministic: false. With no
  arguments each reads the tip (bestHeight, LocateHeaders to the tip with an
  empty hashStop, BestSnapshot()), so providers at different heights would be
  reported as cross-validation outliers.
- gettreasurybalance, gettreasuryspendvotes: block_parsing default_value
  "latest". Without it a no-argument call parses as NOT_APPLICABLE
  (smart-router ParseRawBlock), so it is never cached or consistency-checked.

gettxoutsetinfo stays deterministic to match btc.json.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog
AnnaR-prog requested a review from avitenzer October 7, 2026 11:42
@avitenzer

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of ce03338, which applies the changes requested in the 2026-10-07 human review and nothing else:

  1. ticketvwap, getheaders, gettreasurybalance → deterministic: false (each reads the tip when called without a block argument).
  2. "default_value": "latest" on the block_parsing of gettreasurybalance and gettreasuryspendvotes, so a no-argument call parses as latest rather than NOT_APPLICABLE (smart-router protocol/parser/parser.go ParseRawBlock).

gettxoutsetinfo deliberately stays deterministic: true to match btc.json. The router caching follow-up for Decred's node-local reads is tracked in MAG-4207, outside this spec.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=0 MEDIUM=3 MINOR=3)

Resumable run, Phases 11–11 only (/rerun-final). Reviewed HEAD ce03338 on decred-spec. One fresh-context reviewer, model: opus — bumped from the default sonnet because the 2026-10-07 08:49 pass returned APPROVED and the human review that followed found two real defects it had missed, which is the skill's documented criterion for bumping.

The two requested changes are in and both are correct. The reviewer re-read the dcrd handlers and confirms all five edits in ce03338: ticketvwap (BestSnapshot().Height), getheaders (zero hashStop → LocateHeaders runs to the tip) and gettreasurybalance (BestSnapshot().Hash when no hash is supplied) genuinely read the tip and are now deterministic: false; default_value: "latest" on gettreasurybalance / gettreasuryspendvotes matches both handlers' if c.Hash == nil || *c.Hash == "" { … BestSnapshot() } fallback. The commit does what it claims and nothing else.

Why the verdict is still CHANGES REQUESTED. Zero CRITICAL and the reviewer's own readiness line is "ready to deploy; none of the three MEDIUMs blocks" — but Phase 11's gate is CRITICAL=0 MEDIUM=0, so three MEDIUMs is mechanically CHANGES REQUESTED and is recorded as such rather than upgraded. One of the three is a direct disagreement with this PR's stated rationale:

  • MEDIUM-2 disputes the gettxoutsetinfo decision. It was invited to disagree and does: handleGetTxOutSetInfo takes no parameters at all (_ any), calls BestSnapshot(), and returns height/bestblock in the body — so it fails the same tip-reading test ce03338 just applied to three siblings. On "match btc.json": dcr.json already overrides btc.json on six tip-reading methods (getblockcount, getbestblockhash, getblockchaininfo, getchaintips, getdifficulty, getnetworkhashps), so the parity argument holds for this one method only. It also found createrawssrtx in the same class (FetchUtxoEntry + BestSnapshot().Hash + HeaderByHash). This one needs a human call — it is the item the review comment marked deliberate.
  • MEDIUM-1 (the one with real exposure) — ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions are caller-controlled, uncapped range scans priced at 20 CU with no timeout_ms, while livetickets / ticketsforaddress / getticketpoolvalue sit at 500 CU + 180 000 ms. Verified in the file. This just extends the pricing rule 0d4a613 already established.
  • MEDIUM-3 — eight zero-chain-state methods use DEFAULT/["latest"] where the guide requires EMPTY/[""]. Verified: all eight are DEFAULT, and the file has zero EMPTY parsers across 59 methods.

Per the resumable contract this run does not halt on CHANGES REQUESTED and does not fix anything — START_PHASE == END_PHASE == 11, so no Phase-10 fix pass ran and dcr.json is untouched in the working tree. To act on these, run /rerun-fix (Phase 10 only) or /rerun-from 10.

Pre-flight gates re-run against HEAD: jq valid; check_unused_fields.sh → RESULT: PASS (no removed fields); check_disabled_count.sh → 0 distinct disabled methods, matching the body's <!-- disabled-count: 0 -->; internal-path guard N/A (every internal_path is ""); no SUBSCRIBE directive, so the ws gate does not apply. Disabled-API Justifications ledger is empty because there are no disabled entries — nothing to justify.

Full reviewer report (docs/dcr/SPEC_REVIEW_GAPS_final.md)

Decred (DCR / DCRT) — Spec Review Gaps (final pass)

  • Spec under review: /home/runner/work/lava-specs/lava-specs/dcr.json
  • HEAD commit reviewed: ce03338 (fix(spec): mark Decred's tip-reading methods non-deterministic, default treasury parsing to latest (MAG-2961))
  • Review date: 2026-10-07
  • Review mode: mode, / OPEN (no live DCR endpoint supplied; see "Probe status")
  • Specs in proposal: 2 — DCR (Decred Mainnet, 59 apis), DCRT (Decred Testnet3, imports: ["DCR"], 0 own apis)
  • API interface: jsonrpc only, one collection per spec (internal_path: "", type: POST, add_on: "")
  • Endpoints reviewed: 59 methods + 2 parse directives + 2 chain-id verifications

Probe status (context, not a finding)

docs/dcr/METHOD_PROBE_REPORT.md reports PARSE: NOT_TESTABLE, VERIFY: NOT_TESTABLE,
ADDONS: none declared, TESTNET_VERIFY: SKIPPED, BLOCK_TIME: mainnet=skipped testnet=skipped.
No public dcrd JSON-RPC upstream was reachable, so nothing was live-probed. Per the review
charter this is an endpoint gap, not a spec defect, and it is not reported as one.

To compensate, every value this review relied on was re-grounded against primary sources
rather than taken on trust:

Claim How it was verified this pass Result
mainnet average_block_time: 300000 dcrd/chaincfg/mainnetparams.go → TargetTimePerBlock: time.Minute * 5 CONFIRMED
testnet average_block_time: 120000 dcrd/chaincfg/testnetparams.go → TargetTimePerBlock: time.Minute * 2, Name: "testnet3" CONFIRMED
DCR chain-id 298e5cc3…b21d980 live GET https://dcrdata.decred.org/api/block/0 → "hash":"298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980"; also decred/tinydecred dcr/nets/mainnet.py GenesisHash CONFIRMED (live)
DCRT chain-id a649dce5…4a49bac decred/tinydecred dcr/nets/testnet.py → GenesisHash = "a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac", Name = "testnet3" CORROBORATED (second independent Decred-org source; still not live-confirmed — testnet.dcrdata.org and testnet.decred.org both returned HTTP 503 again on 2026-10-07)
method inventory diffed spec names against the rpcHandlersBeforeInit map in dcrd/internal/rpcserver/rpcserver.go (master) CONFIRMED complete (see below)
the three HEAD-commit determinism flips read handleTicketVWAP, handleGetHeaders, handleGetTreasuryBalance in dcrd master CONFIRMED correct

The DCRT genesis hash remains the one value with no live confirmation anywhere in the
pipeline. It now has two independent Decred-org source-of-record agreements, which is
enough to leave it in place, but it is still the first thing a maintainer should check
once a testnet3 RPC exists (getblockhash 0).


Findings

CRITICAL

None.

Disable-justification audit — PASS

jq -r '.proposal.specs[] | .index as $i
   | (.api_collections[]? | (if (.enabled == false) then "COLLECTION_DISABLED \($i)" else empty end),
      (.apis[]? | select(.enabled == false) | "API_DISABLED \($i) \(.name)"))' dcr.json
→ (no output)

check_disabled_count.sh dcr.json → 0 distinct method(s), 0 row(s) / RESULT: PASS.
There are zero enabled: false apis and zero enabled: false collections in
dcr.json. The Disabled-API Justifications ledger is correspondingly empty and the PR body
carries <!-- disabled-count: 0 -->. Claim, ledger and file all agree — nothing to justify,
so no CRITICAL arises here.


MEDIUM

MEDIUM-1 — Four caller-controlled, uncapped range scans are priced as single-block reads (20 CU, no timeout_ms)

Location: dcr.json L798 (ticketvwap), L813 (ticketfeeinfo), L828 (txfeeinfo), L669 (getstakeversions)

Evidence (dcrd master, internal/rpcserver/rpcserver.go + internal/blockchain/chain.go):

Method Caller-controlled scan Upper bound in dcrd Per-iteration cost spec compute_units spec timeout_ms
ticketfeeinfo (blocks windows) blocks, windows none — both uint32, used raw in for i := start; i > end; i-- ticketFeeInfoForBlock → loads the full block and iterates its txs 20 absent
txfeeinfo (blocks start end) blocks, rangestart..rangeend none (default range = WorkDiffWindowSize = 144) ticketFeeInfoForBlock → full block load + tx iteration 20 absent
ticketvwap (start end) start..end only end <= bestHeight; start may be 1 Chain.HeaderByHeight(i) per block (default range = WorkDiffWindows * WorkDiffWindowSize = 20 × 144 = 2880) 20 absent
getstakeversions (hash count) count BlockChain.GetStakeVersions clamps count only to startNode.height + 1, i.e. the whole chain one index-node walk + votes slice copy per block 20 absent

Mainnet chain height on 2026-10-07 was 1,121,576 (https://dcrdata.decred.org/api/block/best/height).
So ticketvwap 1 1121576, txfeeinfo 1121576, ticketfeeinfo 1121576 and
getstakeversions <tip> 1121576 are all legal single relays. ticketfeeinfo/txfeeinfo are
the worst of the four because each iteration deserializes an entire block.

Why this is a defect and not a judgement call: the spec already recognises and prices this
exact class correctly. livetickets (L720), ticketsforaddress (L766) and getticketpoolvalue
(L782) are each compute_units: 500 with timeout_ms: 180000 — and commit 0d4a613
("price the Decred ticket-pool scans like livetickets") deliberately established that rule.
The four methods above are the same class of work (and ticketfeeinfo/txfeeinfo are heavier
per unit scanned, since the ticket-pool scans walk an in-memory set while these load blocks
from disk) yet sit at the getblock price of 20 CU. The guide's CU table puts
"Heavy ops (full scan)" at 500–5000 and tells you to attach timeout_ms to long-running ops.

Impact: CU is Lava's billing and rate-limiting unit, so a consumer obtains an arbitrarily
expensive dcrd operation — up to a full-chain block scan — for the price of one block read.
With no timeout_ms, each such relay also rides the router's default relay timeout rather
than a deliberately widened one, so on a large range the provider burns the work and then
the relay times out: the provider pays the full cost and still eats the QoS penalty. This is
the exact economic-imbalance failure mode the guide lists as pitfall #4.

Suggested fix: raise all four to the livetickets tier (compute_units: 500,
timeout_ms: 180000) to match the pricing rule the spec already applies to its other
full-scan methods.


MEDIUM-2 — gettxoutsetinfo (and createrawssrtx) stay deterministic: true while reading the chain tip, contradicting the criterion ce03338 itself applies

Location: dcr.json L458 (gettxoutsetinfo), L594 (createrawssrtx)

This is the item the triggering comment flagged as deliberate and invited disagreement on.
I disagree, with source evidence.

gettxoutsetinfo — evidence (dcrd master handleGetTxOutSetInfo):

func handleGetTxOutSetInfo(_ context.Context, s *Server, _ any) (any, error) {
	best := s.cfg.Chain.BestSnapshot()
	stats, err := s.cfg.Chain.FetchUtxoStats()
	...
	return types.GetTxOutSetInfoResult{
		Height:         best.Height,
		BestBlock:      best.Hash.String(),
		...

The handler takes no parameters at all (_ any), calls BestSnapshot(), and returns
height and bestblock inside the response body. There is no argument a caller can supply
to pin it to a block. Two honest providers one block apart therefore return provably
different bytes, always.

That is precisely the test ce03338 applied to flip ticketvwap (bestHeight), getheaders
(LocateHeaders to tip on empty hashStop) and gettreasurybalance (BestSnapshot()) to
deterministic: false — all three of which I re-read in dcrd master and confirm the commit
got right. gettxoutsetinfo fails the same test more plainly than any of them.

On the stated rationale ("to match btc.json"): btc.json is not positive evidence here,
because dcr.json already and deliberately departs from btc.json on the whole tip-reading
family. btc.json marks getblockcount, getbestblockhash, getblockchaininfo,
getchaintips, getdifficulty, getnetworkhashps and gettxout all deterministic: true;
dcr.json marks every one of those false. Invoking btc.json for gettxoutsetinfo alone
selects the single method where the sibling spec agrees with the status quo, while overriding
it everywhere else. The spec cannot be internally consistent and btc.json-consistent at the
same time, and it has already chosen internal consistency six times over.

createrawssrtx — same class, found during this pass (dcrd master handleCreateRawSSRtx):

ticketUtxo, err := s.cfg.Chain.FetchUtxoEntry(outpoint)   // line 33 of handler
...
prevBlkHash := s.cfg.Chain.BestSnapshot().Hash            // line 72
prevHeader, err := s.cfg.Chain.HeaderByHash(&prevBlkHash) // line 90

It fetches a live UTXO entry and embeds the current tip's header, so its output changes with
the tip and it starts erroring once the ticket is spent/revoked. It is currently
deterministic: true.

Explicitly NOT flagged, on evidence: decoderawtransaction also touches
s.cfg.Chain.BestSnapshot().Hash, but only to select the active script version for decoding;
its output is tip-invariant except across a consensus-agenda activation, so
deterministic: true there is defensible and should be left alone. Likewise
getrawtransaction (deterministic: true) defaults to verbose=0, which returns the bare
serialized tx with no confirmations field — also fine.

Impact: deterministic is the flag that tells the router a response is safe to treat as a
stable function of the requested block — for cross-provider comparison and for caching. A
500-CU, no-argument UTXO-set summary advertised as deterministic can be compared against, or
served from, a snapshot taken at a different tip, and the mismatch surfaces as a provider
fault rather than as the expected tip skew it actually is. (This is distinct from the
router-side caching work in MAG-4207, which is about adding caching for node-local reads
and is out of scope here; the issue is the flag's truth value, not the cache.)

Suggested fix: deterministic: false on gettxoutsetinfo and createrawssrtx.


MEDIUM-3 — Eight zero-chain-state methods use DEFAULT/["latest"] where the guide requires EMPTY/[""]

Location: dcr.json L504 validateaddress, L519 verifymessage, L549 decodescript,
L564 createrawtransaction, L579 createrawsstx, L233 getcurrentnet, L368 version,
L609 estimatefee

Evidence. The guide is explicit on both rows that apply here:

| No block parameter, static/immutable data | EMPTY with parser_arg: [""] |
| Pure computation, no chain state | EMPTY with parser_arg: [""] |

Every one of the eight was verified against dcrd master by grepping its handler body for
s.cfg.Chain (excluding ChainParams), BestSnapshot, TxMempooler, FeeEstimator,
TxIndexer and SubsidyCache — all eight came back with zero chain-state references:

  • validateaddress, verifymessage, decodescript, createrawtransaction, createrawsstx — pure crypto/serialization against ChainParams only
  • getcurrentnet — body is literally return s.cfg.ChainParams.Net, nil (a compile-time constant)
  • version — returns static build/API-version constants
  • estimatefee — body is return s.cfg.MinRelayTxFee.ToCoin(), nil; a node-config constant, and its numblocks parameter is documented in rpcserverhelp.go as literally "(unused)"

Two methods that look like they belong on this list were checked and deliberately
excluded
because they do read the tip: decoderawtransaction
(s.cfg.Chain.BestSnapshot().Hash) and createrawssrtx (FetchUtxoEntry + BestSnapshot +
HeaderByHash). DEFAULT/["latest"] is correct for those two.

Precedent inside the UTXO family is on the side of EMPTY, not against it: zcash.json
puts exactly this class on EMPTY — createmultisig, z_converttex, z_validateaddress,
z_listunifiedreceivers, z_validatepaymentdisclosure, getdeprecationinfo,
getexperimentalfeatures — and btc.json uses EMPTY for its bd_estimatefee. dcr.json
currently has zero EMPTY parsers across 59 methods, the only UTXO spec in the catalogue
besides doge.json and litecoin.json with none.

Impact. DEFAULT/["latest"] sets the relay's requested block to LATEST, which drags
these calls through sync-based provider gating: a provider that is healthy but lagging past
allowed_block_lag_for_qos_sync is deprioritised for a request that touches no chain data at
all. That bites harder on DCR than on a fast chain — allowed_block_lag_for_qos_sync is 1
against a 300 000 ms block time, so the tolerance window is a single 5-minute block. It also
forgoes cacheability: EMPTY yields NOT_APPLICABLE, which is indefinitely cacheable, whereas
a LATEST-bound response never is. Nothing breaks functionally, which is why this is MEDIUM
and not CRITICAL.

Suggested fix: "block_parsing": {"parser_arg": [""], "parser_func": "EMPTY"} on those
eight. Leave deterministic as-is in each case (version, getcurrentnet and estimatefee
are per-provider node config, so their current flags are already right).


MINOR

MINOR-1 — Two bounded-but-bulk reads also sit at 20 CU

Location: dcr.json L188 (getheaders), L865 (gettreasuryspendvotes)

Same class as MEDIUM-1 but with a real ceiling in dcrd, hence MINOR:

  • getheaders — Chain.LocateHeaders is capped by wire.MaxBlockHeadersPerMsg = 2000
    (dcrd/wire/msgheaders.go:15). The handler then serializes and hex-encodes each header, so
    a maximal response is 2000 × 180 B × 2 ≈ 720 KB of hex — against getblock's 20 CU for
    one block.
  • gettreasuryspendvotes — tallies votes over TreasuryVoteInterval ×
    TreasuryVoteIntervalMultiplier = 288 × 12 = 3456 blocks on mainnet
    (dcrd/chaincfg/mainnetparams.go:582,586), bounded and not caller-extendable.

60 CU (the guide's "complex queries" tier) would reflect these better than 20. No
timeout_ms change needed — both are bounded.

MINOR-2 — getrawtransaction silently depends on --txindex, which dcrd defaults to OFF, and nothing in the repo says so

Location: dcr.json L383

dcrd/config.go:83 → defaultTxIndex = false. With the index off,
handleGetRawTransaction falls through the mempool lookup and returns a hard error for any
confirmed transaction:

if txIndex == nil {
    err := errors.New("the transaction index must be enabled to " +
        "query the blockchain (specify --txindex)")
    return nil, rpcInternalErr(err, "Configuration")
}

So a provider running stock dcrd serves getrawtransaction for mempool txs only and fails
every historical lookup, while the spec enables it in the base add_on: "" collection at
10 CU with deterministic: true — i.e. every DCR provider implicitly commits to it.

Kept at MINOR rather than promoted, for two reasons: the whole UTXO family in this catalogue
takes the same position (btc.json, bch.json, dash.json, doge.json, litecoin.json,
zcash.json all enable getrawtransaction in the base collection even though Bitcoin Core
likewise requires -txindex), so treating it as a DCR defect would mean re-litigating six
other shipped specs; and a provider requirement is a documentation problem, not a wrong field
value. The actionable part is that there is nowhere in this repo that states the
requirement
— see MINOR-3.

Worth recording that this was checked and is not a problem for the two neighbouring
methods: existsaddress / existsaddresses also sit behind an optional index, but
dcrd/config.go:84 sets defaultNoExistsAddrIndex = false and the flag is the negative
--noexistsaddrindex, so the exists-address index is on by default and both methods work
on a stock node. getcfilterv2 has no nil guard on FiltererV2 at all (v2 filters are
header-committed since dcrd v1.7), so it is unconditionally available. No change needed for
those three, and the probe report's existsaddress watch-list entry can be closed on this
evidence.

MINOR-3 — docs/dcr/ carries only the probe report; the guide's Phase 5 doc set is absent

Location: /home/runner/work/lava-specs/lava-specs/docs/dcr/

find docs/dcr -type f returns exactly one file, METHOD_PROBE_REPORT.md. Guide Phase 5
calls for SPEC_IMPLEMENTATION.md, API_REFERENCE.md, TESTING_GUIDE.md and
QUICK_START.md. For a chain with no reachable public RPC this documentation matters more
than usual, not less — it is the only place the following can live:

  1. the dcrd --txindex provider requirement from MINOR-2;
  2. that dcrd requires rpcuser/rpcpass, so providers must carry credentials in their
    node_url (the spec's headers: [] is correct — this is deliberately not a finding, and
    matches btc.json — but it is undocumented and will surprise the first provider);
  3. the DCRT genesis-hash caveat (source-corroborated, never live-confirmed) so it is not lost
    when METHOD_PROBE_REPORT.md is eventually regenerated.

Verified correct (checked this pass, no finding)

  • Phase 0 removed-field guard. check_unused_fields.sh dcr.json → RESULT: PASS (no removed fields), exit 0. No extra_compute_units, category.local or category.subscription anywhere; compute_units is the sole CU input. Envelope is exactly {"proposal":{"specs":[…]}} — jq 'keys' → ["proposal"], jq '.proposal|keys' → ["specs"]. The nine governance fields and title/description/deposit are correctly absent (settled decision (a)).
  • Internal paths. internal_path is "" on both collections, so check_internal_paths.sh does not apply; no NAME_CARRIES_PATH / LABEL_AS_PATH / AMBIGUOUS_REST_* exposure (jsonrpc, no REST names).
  • API completeness — complete. Diffing the 59 spec names against the 77 entries of dcrd master's rpcHandlersBeforeInit map leaves zero spec methods that do not exist in dcrd and 18 dcrd methods omitted — every one of them node-operator control or introspection, correctly excluded per guide Step 3.3b: addnode, node, ping, getaddednodeinfo, debuglevel, startprofiler, stopprofiler, stop, generate, setgenerate, getgenerate, gethashespersec, getwork, regentemplate, invalidateblock, reconsiderblock, verifychain, help. check_node_admin_rpcs.sh agrees: "serves no new node-operator control from a base collection". searchrawtransactions, existsexpiredtickets, existsmissedtickets and getblocktemplate are not gaps — all four were removed from dcrd and are absent from master's handler map.
  • Parse directives — correct against source. GET_BLOCKNUM/getblockcount: handleGetBlockCount returns best.Height. GET_BLOCK_BY_NUM/getblockhash with params:[%d]: handleGetBlockHash returns BlockHashByHeight(index).String(). The two agree on height semantics, so the chain tracker's blocknum→hash round trip is sound, and both match btc.json's directives byte-for-byte in shape. check_directive_presence.sh → OK.
  • No GET_EARLIEST_BLOCK, no archive extension, no pruning verification — correct. dcrd implements no block pruning, so there is no archive/non-archive provider split to express. extensions: [] matches btc.json. check_extensions.sh → PASS.
  • No SUBSCRIBE/UNSUBSCRIBE — correct, and deliberately so. dcrd does have a websocket notification API (notifyblocks, notifynewtransactions, notifywinningtickets, …), but those live in the websocket-only extension command set, not in rpcHandlersBeforeInit, and they follow a notifyX/stopnotifyX pair-per-topic shape rather than the single subscribe/unsubscribe pair the directive expects. Declaring them would make a ws:///wss:// upstream a hard requirement for every DCR provider (the probe report confirms the router enforces this), rendering the spec unservable by the HTTP-only providers that are the realistic population for this chain. Omission is the right call; recorded here so it is visibly a decision rather than an oversight.
  • Network parameters. check_network_params.sh → PASS on all 8 values. average_block_time confirmed against chaincfg for both nets (above). block_distance_for_finalized_data: 6 sits in the guide's 6–12 PoW band and matches btc.json; Decred's hybrid PoW + ticket-voting consensus is probabilistic, so blocks_in_finalization_proof: 3 is right per settled decision (b) — the max(ceil(1000/abt),3) fallback does not apply because the finality model is not unclear. allowed_block_lag_for_qos_sync: 1 is correct on both nets (10000/300000 = 0.03 → min 1; 10000/120000 = 0.08 → min 1).
  • Verifications. check_verifications.sh → PASS; both expected_values are well-formed 64-hex and sourced as tabulated above. DCR carries the full parse_directive; DCRT supplies values only and no parse_directive, which is exactly the documented child-override idiom (guide Step 3.1a, "Verification special case") — the parent's directive is adopted automatically.
  • Collection inheritance (DCRT). Textbook. One collection whose collection_data matches DCR's on all four fields, apis: [], and headers/parse_directives/extensions all [] — which merges, inheriting DCR's values rather than zeroing them (guide Step 3.1a, "Empty arrays inherit everything"; pitfall feat(spec): add Sei chain spec #17). The probe report's router boot independently confirms the closure resolves: DCRT registered with DCR's jsonrpc apis and with its own averageBlockTime of 2m0s overriding DCR's 5m0s.
  • Stateful / hanging_api. Exactly three writes — sendrawtransaction, submitblock, sendrawmixmessage — each stateful: 1, hanging_api: true, deterministic: false, compute_units: 10, timeout_ms: 10000. check_hanging_api.sh → 3× PASS; check_stateful.sh → no FAIL. 10 CU for tx submission matches the ETH1/TENDERMINT baseline. The three createraw* constructors are correctly stateful: 0 (they build but never broadcast).
  • parsers / parse_type assignments. All eight are right against dcrd's actual signatures: BLOCK_HASH on .params.[0] for the hash-first methods (getblock, getblockheader, getcfilterv2, getstakeversions, gettreasurybalance, gettreasuryspendvotes) and BLOCK_LATEST for the height-first ones (getblockhash, getblocksubsidy). Matches the zcash.json/dash.json/bch.json convention.
  • default_value: "latest" on the two treasury methods (second half of ce03338) — correct. Both have an optional leading block argument and both fall back to BestSnapshot() when it is omitted, which I confirmed in handleGetTreasuryBalance (if c.Hash == nil || *c.Hash == "" { hash = s.cfg.Chain.BestSnapshot().Hash }) and handleGetTreasurySpendVotes (same pattern). Without default_value a no-argument call parses as NOT_APPLICABLE; with it, as latest. The PARSE_BY_ARG + default_value pairing is not novel — near.json's gas_price uses the identical shape. The six other hash-first methods correctly lack default_value because their argument is required.
  • The three determinism flips in ce03338 — all three confirmed in dcrd master. ticketvwap → bestHeight := s.cfg.Chain.BestSnapshot().Height, default window WorkDiffWindows * WorkDiffWindowSize. getheaders → zero hashStop when c.HashStop == "", so LocateHeaders runs to the tip. gettreasurybalance → BestSnapshot().Hash when no hash is supplied. The commit is right on all three; MEDIUM-2 is only that the same rule stops one method short.
  • Headers. headers: [] on both collections is correct. dcrd requires HTTP Basic auth, but providers carry credentials in their configured node_url, so no pass_send header is needed — identical to btc.json. (Documentation gap only; MINOR-3.)
  • Hygiene. jq -e . dcr.json valid; no duplicate api names within the collection; check_method_schema.sh → 59/59 schema ok; per-api type absent throughout, matching btc.json and every other jsonrpc spec (the collection-level type: POST governs).

Summary

Count
Endpoints reviewed 59 methods, 2 parse directives, 2 verifications (2 specs)
CRITICAL 0
MEDIUM 3
MINOR 3
Removed-field cleanup findings 0
Disabled apis/collections lacking justification 0 (there are no disabled entries at all)

Deployment readiness: ready to deploy; the three MEDIUMs are worth a follow-up but none of
them blocks.

Nothing in dcr.json is functionally broken. The structural half of the spec — envelope,
inheritance, parse directives, verifications, network parameters, write classification,
method inventory — came back clean against primary sources on every check, and the method
inventory is genuinely complete against dcrd master rather than approximately so. ce03338
does what it claims and nothing else, and all five of its changes are correct against the
dcrd handlers.

The three MEDIUMs are refinements of judgement calls, in descending order of real-world cost:
MEDIUM-1 (four uncapped scans at 20 CU) is the one with actual exposure, and it is a
one-line-per-method fix that simply extends the pricing rule commit 0d4a613 already
established. MEDIUM-2 finishes the determinism sweep ce03338 started — I do think
gettxoutsetinfo is wrong, and the "match btc.json" rationale does not survive the
observation that this spec already overrides btc.json on six sibling methods. MEDIUM-3
is guide conformance with a modest provider-availability cost.

Router-side caching for Decred's node-local reads (MAG-4207) is out of scope for this spec
and is not reported.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Verdict this run: ⚠️ CHANGES REQUESTED — TALLY: CRITICAL=0 MEDIUM=3 MINOR=3 against HEAD ce03338. Recorded honestly, not upgraded; the gate is CRITICAL=0 MEDIUM=0.

Annotation key: ✓ verified by evidence this pipeline produced · ~ partially verified · ☐ out of skill scope / not covered.

Read the ~ rows before treating this spec as tested. Phases 8/9/10/10b did not run in this invocation (span is 11–11); every probe-derived row below is inherited from the 2026-10-06 Phase 8 run, which found no reachable public Decred RPC on either network and so live-executed nothing.

#### File Validation
- ✓ JSON syntax valid                                    (re-run this phase: `jq` exit 0 on dcr.json @ ce03338)
- ✓ All required fields present                          (Phase 11 reviewer: check_network_params / check_verifications / check_method_schema 59/59 PASS)
- ✓ No duplicate API names within any collection         (Phase 11 reviewer, jq-confirmed)
- ✓ Proper indentation/formatting                        (4-space, matches catalogue convention)
- ✓ No removed-model fields                              (re-run this phase: check_unused_fields.sh → PASS; none of the 15 fields from #218; envelope is exactly {proposal:{specs:[…]}}; compute_units is the sole CU input)
- ✓ Internal-path guard N/A                              (every internal_path is "")

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 11: average_block_time 300000/120000 confirmed against dcrd chaincfg TargetTimePerBlock; block_distance 6, finalization 3, qos_lag 1 all re-derived)
- ~ All APIs tested and working                           (NOT live-tested. Phase 8 2026-10-06 found no reachable public dcrd RPC; the only known keyed upstream (NOWNodes) whitelists out 33 of the 59 methods. Method inventory was instead verified statically against dcrd master's rpcHandlersBeforeInit map: 59/59 exist, 0 phantom names)
- ~ Block parsing validated for each API                  (static only — parsers/parse_type re-checked against dcrd handler signatures. MEDIUM-3 is open: 8 zero-chain-state methods use DEFAULT/["latest"] where the guide requires EMPTY/[""])
- ~ Parse directives executed by live router              (Phase 8: PARSE: NOT_TESTABLE, VERIFY: NOT_TESTABLE — the chain tracker never reached a node. Distinct from FAIL: nothing was shown wrong. Phase 10b re-check: n/a, not in span. GET_BLOCKNUM/GET_BLOCK_BY_NUM verified by source reading only)
- ✓ Addons & extensions tested                            (Phase 8 ADDONS: none declared — mechanically confirmed, both lists empty; dcrd has no pruning, so the archive/pruning/GET_EARLIEST_BLOCK triplet is correctly all-absent)
- ~ Verifications pass on live nodes                      (DCR genesis hash 298e5cc3…b21d980 live-confirmed this phase via dcrdata block/0 + tinydecred mainnet.py. DCRT a649dce5…4a49bac is source-corroborated only — testnet.dcrdata.org and testnet.decred.org returned 503 again on 2026-10-07. Never live-confirmed anywhere in this pipeline)
- ☐ Compute units benchmarked under expected load         (user to measure — and MEDIUM-1 is open: ticketvwap/ticketfeeinfo/txfeeinfo/getstakeversions are uncapped caller-controlled scans at 20 CU with no timeout_ms, vs 500 CU + 180000 ms on the three sibling scans)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created                        (MINOR-3: docs/dcr/ holds only the probe report. For a chain with no public RPC this is where the dcrd --txindex requirement, the rpcuser/rpcpass provider requirement, and the DCRT genesis-hash caveat should live)
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                 (DCR: 59 apis, 1 jsonrpc collection)
- ✓ Testnet spec inherits correctly                       (DCRT imports ["DCR"], apis []; empty headers/parse_directives/extensions merge rather than zero — Phase 11 reviewer confirmed, and the 2026-10-06 router boot resolved the closure with DCRT's 2m0s overriding DCR's 5m0s)
- ~ Chain IDs verified for mainnet AND testnet            (mainnet live-confirmed; testnet NOT — TESTNET_VERIFY: SKIPPED. First thing to check once a testnet3 RPC exists: getblockhash 0)
- ~ Both tested on respective networks                    (neither was live-probed; BLOCK_TIME: mainnet=skipped testnet=skipped)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                     (wrapper is { "proposal": { "specs": [ … ] } } — no title/description/deposit)
- ☐ Community feedback gathered (if applicable)

Open items (what /rerun-fix would act on)

# Severity Item Needs
MEDIUM-1 fixable now ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions → 500 CU + timeout_ms: 180000 extends the rule 0d4a613 set
MEDIUM-2 human call gettxoutsetinfo (+ createrawssrtx) → deterministic: false contradicts this PR's stated btc.json-parity rationale; reviewer argues the parity already broke on 6 sibling methods
MEDIUM-3 fixable now 8 zero-chain-state methods → EMPTY/[""] guide conformance
MINOR-1 optional getheaders, gettreasuryspendvotes → 60 CU (bounded at 2000 headers / 3456 blocks) —
MINOR-2 docs getrawtransaction needs dcrd --txindex (default OFF) whole UTXO family shares this; doc it
MINOR-3 docs docs/dcr/ doc set absent out of skill scope

Nothing was committed or edited by this run — dcr.json is byte-for-byte ce03338 and the working tree is clean of spec changes. MAG-4207 (router-side caching for Decred's node-local reads) is out of scope and was excluded from the review.

Run stats — this pipeline run only (Phases 11–11)

Elapsed:         00h 19m 11s  (first→last logged activity)
Transcripts:     1 main + 1 subagent
API round-trips: 123  (main=28, subagents=95)

Fresh tokens:    input=246  output=88038  (sum=88284)
Cached tokens:   cache_read=9640339  cache_write=369159
Total billed:    10097782 tokens

Split (total billed):  main=1911401  subagents=8186381

Models used:
  claude-opus-5           123 calls   10097782 billed

These numbers cover Phases 11–11 of this invocation only. They are not a 1–11 total: Phases 1–7 ran in the original create_spec job (see the PR body), and Phases 8–11 ran in the 2026-10-06 pipeline run, with three further /rerun-final runs on 2026-10-06 and 2026-10-07. The true cost of this PR is all of those runs added together.

…ss methods as EMPTY (MAG-2961)

Applies the three items from the 2026-10-07 Phase 11 review of ce03338:

- ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions: compute_units
  20 -> 500 and timeout_ms 180000. Each scans a caller-chosen block range
  with no cap in dcrd (up to the whole chain), the same class of work as
  livetickets, ticketsforaddress and getticketpoolvalue.
- validateaddress, verifymessage, decodescript, createrawtransaction,
  createrawsstx, getcurrentnet, version, estimatefee: block_parsing
  DEFAULT ["latest"] -> EMPTY [""]. None reads chain state.
- createrawssrtx: deterministic true -> false. dcrd builds the revocation
  from the current tip (BestSnapshot().Hash, HeaderByHash), and the
  previous header seeds the PRNG that places the remainder
  (stake.CalculateRevocationRewards), so the output moves with the tip.

gettxoutsetinfo stays deterministic: true on purpose (2026-10-07 human
review): it mirrors btc.json, and the two specs should change together.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of 7d1673c, which applies the three items from the 2026-10-07 Phase 11 verdict on ce03338 and nothing else:

  1. MEDIUM-1: ticketvwap, ticketfeeinfo, txfeeinfo and getstakeversions → compute_units: 500 and timeout_ms: 180000, the livetickets tier.
  2. MEDIUM-3: the eight methods it listed (validateaddress, verifymessage, decodescript, createrawtransaction, createrawsstx, getcurrentnet, version, estimatefee) → block_parsing EMPTY [""]. deterministic is unchanged on all eight.
  3. MEDIUM-2, second half: createrawssrtx → deterministic: false. dcrd seeds the revocation's remainder PRNG with the tip header (stake.CalculateRevocationRewards).

Scope: these three edits only. gettxoutsetinfo is out of scope for this PR: it stays deterministic: true by human decision (PR body, "Human decision … DO NOT REVERT") and changes together with btc.json in a separate PR. Record any disagreement with it as advisory, not as a MEDIUM. The router caching follow-up for Decred's node-local reads is MAG-4207, also outside this spec.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=0 MEDIUM=3 MINOR=0)

Resumable run, Phases 11–11 only (/rerun-final, START_PHASE == END_PHASE == 11). Reviewed HEAD 7d1673c on decred-spec. One fresh-context reviewer, model: opus — held at the bump the 2026-10-07 passes established (sonnet returned APPROVED on 0d4a613 and the human review that followed found real defects, which is the skill's documented criterion).

All three requested items are in, and all three are correct. The reviewer re-derived each one from dcrd master rather than taking the commit message on trust:

  1. MEDIUM-1 — ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions are all now compute_units: 500 + timeout_ms: 180000. Each confirmed uncapped and caller-controlled: ticketvwap loops HeaderByHeight(i) over start..end; ticketfeeinfo/txfeeinfo call ticketFeeInfoForBlock → BlockByHeight/BlockByHash (a full block per iteration); GetStakeVersions clamps count only to startNode.height + 1. Determinism correctly left untouched on all four — the three tip-readers stay false, and getstakeversions stays true because its walk is a pure function of (hash, count).
  2. MEDIUM-3 — all eight methods are now EMPTY / [""], and all eight handlers were read in full: none touches s.cfg.Chain. getcurrentnet is literally return s.cfg.ChainParams.Net, estimatefee is return s.cfg.MinRelayTxFee.ToCoin(), version does not even receive the server. deterministic is unchanged on all eight, as stated. The reviewer specifically confirmed the boundary is right: decoderawtransaction was correctly excluded because it reads BestSnapshot().Hash for isTreasuryAgendaActive.
  3. MEDIUM-2, second half — createrawssrtx is deterministic: false, and the PRNG rationale holds end-to-end in source: handleCreateRawSSRtx → FetchUtxoEntry → BestSnapshot().Hash → HeaderByHash → prevHeaderBytes → stake.CreateRevocationFromTicket → CalculateRevocationRewards, where prng := NewHash256PRNG(prevHeaderBytes) places the remainder atoms. DCP0009 auto-revocations is active on both networks, so the branch is live.

Nothing else changed. 7d1673c touches one file, 25 insertions / 21 deletions, and the hunks are exactly 13 api entries: 8 × DEFAULT ["latest"] → EMPTY [""], 1 × determinism flip, 4 × 20 → 500 CU plus a new timeout_ms. No api added, removed, renamed, disabled or re-tagged; no collection, directive, verification, header, extension or network parameter touched. Scope is honoured exactly as the triggering comment described it.

gettxoutsetinfo was held out of scope, as instructed. The reviewer was told the PR body's "Human decision … DO NOT REVERT" is settled and that any disagreement must be advisory. It complied: gettxoutsetinfo appears only as Advisory note A, carries no severity, and is not in the tally. (Its technical position, for the future joint btc.json + dcr.json change, is recorded there: the handler takes no parameters, opens with BestSnapshot(), and returns height/bestblock plus a node-local DiskSize.) MAG-4207 router caching was likewise not reported.

Why the verdict is CHANGES REQUESTED. Zero CRITICAL, zero MINOR, and the reviewer's own readiness line is "Ready for deployment; the three CU/timeout alignments should follow in the next pricing pass." But Phase 11's gate is CRITICAL=0 MEDIUM=0, so three MEDIUMs is mechanically CHANGES REQUESTED and is recorded as such rather than upgraded.

Critically, none of the three new MEDIUMs is a regression from 7d1673c — all three are pre-existing mispricings on methods this commit never touched. They are the same category as the item it just fixed: heavy scans still sitting in the 10/20-CU tier with no timeout_ms while their structural siblings now sit at 500/180000. Fixing MEDIUM-1 raised the contrast enough to surface them.

New finding Location CU now dcrd scan extent Suggested
MEDIUM-1 gettreasuryspendvotes dcr.json:869 20, no timeout up to 3456 full blocks per tspend (TreasuryVoteInterval 288 × Multiplier 12), and the tspends array is uncapped and not de-duplicated 500 / 180000
MEDIUM-2 getnetworkhashps dcr.json:338 10, no timeout numBlocks taken raw from c.Blocks, clamped only at startHeight < 0 → whole chain; 2 index lookups + a big.Int CalcWork per block 500 / 180000
MEDIUM-3 getstakeversioninfo dcr.json:691 20, no timeout count clamped only to ceil(height/StakeVersionInterval) ≈ 556 intervals × 2016 blocks ≈ 1.09M index nodes, with per-block vote-map aggregation 500 / 180000

I re-fetched dcrd master and independently confirmed each of the three rather than relaying them: handleGetNetworkHashPS really does take numBlocks = int64(*c.Blocks) with no upper bound; handleGetTreasurySpendVotes really does iterate *c.TSpends with no length cap; handleGetStakeVersionInfo really does clamp count only to totalIntervals. mainnetparams.go confirms TreasuryVoteInterval: 288, TreasuryVoteIntervalMultiplier: 12 (= 3456) and StakeVersionInterval: 144 * 2 * 7 (= 2016). The sharpest internal inconsistency is the reviewer's own framing: ticketfeeinfo with blocks: 1 reads one full block and is now priced at 500 CU, while gettreasuryspendvotes reads up to 3456 full blocks at 20.

Two re-grades against the previous round, stated plainly. Last round's MINOR-1 paired getheaders with gettreasuryspendvotes at 20 CU and suggested 60. This round gettreasuryspendvotes is promoted to MEDIUM on stronger evidence (the uncapped tspends array multiplies the 3456-block window, which the earlier pass treated as a hard ceiling), and getheaders is dropped entirely as genuinely bounded — LocateHeaders caps at wire.MaxBlockHeadersPerMsg. Last round's MINOR-2 (getrawtransaction needs --txindex, which dcrd defaults off) and MINOR-3 (the docs/dcr/ doc set) were not re-raised this pass; MINOR-3 is the Phase-12 ☐ manual documentation block below, and MINOR-2 was previously judged a catalog-wide convention rather than a DCR defect. Neither was fixed — they were deliberately not re-reported, and that is why MINOR is 0 rather than evidence they went away.

Per the resumable contract this run does not halt on CHANGES REQUESTED and does not fix anything — START_PHASE == END_PHASE == 11, so no Phase-10 fix pass ran and dcr.json is untouched in the working tree. To act on the three MEDIUMs, run /rerun-fix (Phase 10 only) or /rerun-from 10.

Pre-flight gates re-run against HEAD (all exit 0, all FAIL sections empty): jq -e . valid · check_unused_fields.sh → RESULT: PASS (no removed fields) · check_internal_paths.sh → RESULT: PASS (every internal_path is "") · check_disabled_count.sh → 0 distinct disabled methods, matching the body's <!-- disabled-count: 0 --> · check_network_params.sh · check_verifications.sh · check_directive_presence.sh → OK · check_extensions.sh · check_method_schema.sh → 59/59 schema ok · check_node_admin_rpcs.sh · check_hanging_api.sh → 3/3 · check_stateful.sh. No SUBSCRIBE directive anywhere, so the ws gate does not apply and no ws-capable node was required. Disabled-API Justifications ledger is empty because there are zero disabled entries — nothing to justify, so the audit is vacuously satisfied.

Reviewer-anchoring sanity check passed. All three cited line numbers (869, 338, 691) resolve inside the 1062-line file and land on exactly the methods claimed, with exactly the CU values claimed — the reviewer read current state, not stale HEAD. No re-dispatch needed.

Full reviewer report (docs/dcr/SPEC_REVIEW_GAPS_final.md)

DCR / DCRT Spec Review — Final Pass (Phase 11)

  • Spec under review: dcr.json (DCR = Decred mainnet, DCRT = Decred testnet3)
  • Commit reviewed: 7d1673c on branch decred-spec (PR feat(spec): add Decred chain spec #186)
  • Baseline for the delta: ce03338 (the commit the previous Phase 11 verdict was written against)
  • API documentation supplied: none ($ARGUMENTS[1] empty) — completeness was instead diffed against the dcrd handler table in source
  • Credentials supplied: none ($ARGUMENTS[2] empty) — no live relay testing; Phase 9 live testing not performed
  • Probe input: docs/dcr/METHOD_PROBE_REPORT.md (Phase 8, spec-load-only mode: SPEC_LOAD: OK, SPEC_LOAD_TESTNET: OK, zero class-A signatures, all 56 non-stateful methods NOT_TESTABLE for want of a reachable dcrd upstream)
  • Mode: review-only. No file other than this report was written. No mutating git command was run.
  • Primary ground truth: dcrd master sources fetched this run — internal/rpcserver/rpcserver.go, internal/blockchain/chain.go, internal/blockchain/thresholdstate.go, internal/blockchain/treasury.go, blockchain/stake/staketx.go, chaincfg/mainnetparams.go, chaincfg/testnetparams.go, rpc/jsonrpc/types/chainsvrcmds.go

Part 1 — Verification of the three items this commit claims to apply

Each item was re-derived from dcrd source rather than accepted on assertion.

Item 1 (previous MEDIUM-1) — ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions → 500 CU / 180000 ms — CONFIRMED CORRECT

Method dcrd evidence Caller-controlled extent
ticketvwap handleTicketVWAP loops for i := start; i <= end; i++ { HeaderByHeight(i) }; start/end come straight from c.Start/c.End with only a start <= end <= bestHeight sanity check start=1, end=tip → full chain (~1.1M header reads)
ticketfeeinfo handleTicketFeeInfo loops blocks back from the tip calling ticketFeeInfoForBlock → Chain.BlockByHeight (full block); the windows loop clamps only at height 0 blocks/windows uncapped uint32 → full chain of full block reads
txfeeinfo handleTxFeeInfo → ticketFeeInfoForRange(start, end+1) → chain.HeightRange + chain.BlockByHash per block, over the caller's rangestart/rangeend full chain of full block reads
getstakeversions handleGetStakeVersions → Chain.GetStakeVersions(hash, c.Count); internal/blockchain/chain.go:310-348 clamps count only to startNode.height+1 and then walks prevNode = prevNode.parent count → whole chain, and the reply serialises one entry per block

All four are the same class of work as livetickets / ticketsforaddress / getticketpoolvalue (already 500/180000). 500 + timeout_ms: 180000 is applied to exactly these four and to nothing else. Determinism was correctly left untouched: the three tip-reading ones stay false (ticketfeeinfo/txfeeinfo unconditionally fold in feeInfoForMempool; ticketvwap defaults end to BestSnapshot().Height), and getstakeversions stays true because its walk is a pure function of (hash, count) over the block index with no tip input.

Item 2 (previous MEDIUM-3) — eight zero-chain-state methods → EMPTY / [""] — CONFIRMED CORRECT

Every one of the eight handlers was read in full. None touches s.cfg.Chain:

Method Handler body reduces to
validateaddress stdaddr.DecodeAddress(c.Address, s.cfg.ChainParams)
verifymessage ecdsa.RecoverCompact + stdaddr.Hash160 + address re-encode
decodescript txscript.DisasmString, stdscript.ExtractAddrs, stdaddr.NewAddressScriptHash
createrawtransaction wire.NewMsgTx assembly from params + address decode
createrawsstx wire.NewMsgTx assembly + stake.SStxNullOutputAmounts + stake.CheckSStx
getcurrentnet return s.cfg.ChainParams.Net
version build constants only (_ *Server — the handler does not even receive the server)
estimatefee return s.cfg.MinRelayTxFee.ToCoin()

s.cfg.ChainParams and s.cfg.MinRelayTxFee are static network/node configuration, not chain state, so EMPTY is right for all eight.

Determinism is unchanged and remains correct on all eight: true for the six pure functions, false for version (per-provider build string) and estimatefee (per-provider --minrelaytxfee).

The eight-method boundary is exactly right, and this is worth calling out. decoderawtransaction looks like a ninth pure decoder but was correctly left at DEFAULT ["latest"]: handleDecodeRawTransaction reads s.cfg.Chain.BestSnapshot().Hash and calls s.isTreasuryAgendaActive(&prevBlkHash) to decide treasurybase vin rendering. Its deterministic: true also survives scrutiny, because the treasury agenda is permanently latched active on both networks, so the tip read cannot move the output.

Item 3 (previous MEDIUM-2, second half) — createrawssrtx → deterministic: false — CONFIRMED CORRECT

The output genuinely moves with the tip. Chain from source:

  1. handleCreateRawSSRtx (rpcserver.go:1049) resolves the ticket with s.cfg.Chain.FetchUtxoEntry(outpoint) — a tip-relative UTXO-set read, so the call succeeds or 404s depending on the tip.
  2. prevBlkHash := s.cfg.Chain.BestSnapshot().Hash, then s.isAutoRevocationsAgendaActive(&prevBlkHash), then prevHeader, err := s.cfg.Chain.HeaderByHash(&prevBlkHash) → prevHeaderBytes.
  3. prevHeaderBytes is passed into stake.CreateRevocationFromTicket(..., prevHeaderBytes, isAutoRevocationsEnabled) (blockchain/stake/staketx.go:1349), which forwards it to CalculateRevocationRewards (staketx.go:648).
  4. CalculateRevocationRewards does, when auto-revocations is active and a remainder exists:
    prng := NewHash256PRNG(prevHeaderBytes)
    for i := int64(0); i < remainder; i++ {
        returnIndex := prng.UniformRandom(numReturnAmounts)
        returnAmounts[returnIndex]++
    }

The remainder atoms are placed by a PRNG seeded with the serialized current tip header, which changes every block. The auto-revocations agenda (DCP0009) is active on mainnet and testnet3, so this branch is live. deterministic: false is correct, and it is the right call for this method specifically while decoderawtransaction stays true — the distinction between "reads the tip" and "output moves with the tip" is drawn in the right place.

Nothing else changed

git show --stat 7d1673c → dcr.json | 46 +++---, one file, 25 insertions / 21 deletions. The hunk-by-hunk diff is exactly 13 api entries: 8 × DEFAULT ["latest"] → EMPTY [""], 1 × deterministic true → false (createrawssrtx), 4 × compute_units 20 → 500 plus a new timeout_ms: 180000. No api was added, removed, renamed, disabled or re-tagged; no collection, directive, verification, header, extension or network parameter was touched. No unintended change found.


Part 2 — Full-spec audit by phase

Phase 0 — Removed-field guard

  • check_unused_fields.sh dcr.json → RESULT: PASS (no removed fields), exit 0.
  • check_internal_paths.sh dcr.json → RESULT: PASS (0 warning(s), no errors); every internal_path is "", so no NAME_CARRIES_PATH, LABEL_AS_PATH, AMBIGUOUS_REST_NAME or AMBIGUOUS_REST_SHAPE exposure.
  • Envelope is exactly { "proposal": { "specs": [ DCR, DCRT ] } }. Per this run's standing decision, the absence of title/description/deposit and of the nine removed spec-level governance fields is correct and is not reported.
  • jq -e . dcr.json valid. No duplicate api names within the collection.

Phase 1 — Provider identification

Native dcrd JSON-RPC, not a third-party wrapper. Single api_interface: "jsonrpc", single type: "POST", single collection (add_on: "", internal_path: "") on DCR; DCRT imports ["DCR"]. Two specs in the proposal. No addons, no extensions — matching the probe report's mechanical ADDONS: none declared.

Phase 2 — Network parameters

Parameter DCR DCRT Verdict
average_block_time 300000 120000 OK. chaincfg/mainnetparams.go:105 TargetTimePerBlock: time.Minute * 5; chaincfg/testnetparams.go:103 time.Minute * 2. Corroborated by the probe report's inherited dcrdata lifetime mean of 299.96 s/block (~0.01% drift) and by the router resolving 5m0s / 2m0s.
block_distance_for_finalized_data 6 6 OK. Decred is hybrid PoW/PoS with probabilistic finality; the guide's band is 6–12.
blocks_in_finalization_proof 3 3 OK. Probabilistic finality → 3 per the finality-typed rule.
allowed_block_lag_for_qos_sync 1 1 OK. 10000/300000 = 0.03 and 10000/120000 = 0.08, both floored to the minimum 1.

Phase 3 — API completeness

No API-doc file, so completeness was established by diffing the spec's api names against dcrd's rpcHandlers dispatch table in internal/rpcserver/rpcserver.go.

  • Spec → dcrd: all 59 api names exist as dcrd handlers. Zero typos, zero phantom methods.
  • dcrd → spec: 18 handlers are absent from the spec: addnode, debuglevel, generate, getaddednodeinfo, getgenerate, gethashespersec, getwork, help, invalidateblock, node, ping, reconsiderblock, regentemplate, setgenerate, startprofiler, stop, stopprofiler, verifychain. Every one is node-operator control, mining-template, profiling or introspection — correctly excluded, and consistent with check_node_admin_rpcs.sh reporting (none) new node-admin exposure.

No chain-data method is missing. Coverage is complete.

Phase 4 — Method-by-method review

All 59 apis were reviewed. Block parsing, determinism, statefulness and CU were each checked against the corresponding dcrd handler.

  • Block parsing. Hash-argument methods (getblock, getblockheader, getcfilterv2, getstakeversions, gettreasurybalance, gettreasuryspendvotes) correctly pair PARSE_BY_ARG ["0"] with a parsers entry {".params.[0]", "BLOCK_HASH"}; the two treasury methods additionally carry default_value: "latest", which matches dcrd's "use BestSnapshot().Hash when the hash argument is omitted" behaviour. Height-argument methods (getblockhash, getblocksubsidy) use plain PARSE_BY_ARG ["0"]. Everything else is DEFAULT ["latest"] except the nine EMPTY entries (the eight from this commit plus none other), all of which are genuinely chain-state-free.
  • Determinism. DCR applies a stricter and more accurate rule than the Bitcoin-family precedent — gettxout, getchaintips, getdifficulty, getnetworkhashps and the tip-reading stake methods are false here where btc.json has them true. No api is deterministic: true whose output moves with the tip under its own parsing, with the single recorded exception noted in the advisory below.
  • Statefulness. Exactly three stateful: 1 entries — sendrawtransaction, submitblock, sendrawmixmessage — each hanging_api: true, deterministic: false, compute_units: 10, timeout_ms: 10000. This matches the guide's 10-CU transaction-submission rule, and check_stateful.sh / check_hanging_api.sh both pass with empty FAIL sections.
  • Compute units. The 10/20 split follows the guide (simple reads 10, block/tx queries 20) and lines up with btc.json on every shared method. The 500/180000 heavy tier now holds eight methods. Three methods that belong in that tier are still priced at the cheap tier — see MEDIUM-1 through MEDIUM-3 below. These are the only Phase 4 defects found.

Phase 5 — Parse directives

Two directives on the DCR collection, both required ones present, and both byte-for-byte the pattern btc.json already uses for a UTXO JSON-RPC chain:

  • GET_BLOCKNUM → getblockcount, params:[], PARSE_BY_ARG ["0"]. handleGetBlockCount returns BestSnapshot().Height as a bare number.
  • GET_BLOCK_BY_NUM → getblockhash, params:[%d], PARSE_BY_ARG ["0"]. handleGetBlockHash returns a bare hash string.

Both api_names exist in the collection. No GET_EARLIEST_BLOCK is required, because the spec declares no archive extension (neither does btc.json). No SUBSCRIBE/UNSUBSCRIBE anywhere — confirmed mechanically — so no ws/wss upstream requirement, and no category.subscription question arises. check_directive_presence.sh → OK.

Phase 6 — Verifications

One verification per spec, chain-id, implemented as getblockhash(0) compared against the genesis hash. Both values are 64 lowercase hex chars.

  • DCR = 298e5cc3d985bfe7f81dc135f360abe089edd4396b86d2de66b0cef42b21d980 — live-verified this run. https://dcrdata.decred.org/api/block/0 and https://explorer.dcrdata.org/api/block/0 both return exactly this hash for height 0.
  • DCRT = a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac — source-verified this run. Both testnet3 explorers are still down (testnet.dcrdata.org timed out, testnet.decred.org HTTP 503), so no live check was possible, but the value is corroborated independently of this spec by Decred's own decred/tinydecred repository, decred/decred/dcr/nets/testnet.py: GenesisHash = "a649dce53918caf422e9c711c858837e08d626ecfcd198969b24f7b634a49bac". This closes item 4 of the probe report's "what a maintainer must do" list to source-grade confidence; a live getblockhash(0) on testnet3 remains the only stronger evidence available and is still outstanding.

check_verifications.sh passes with an empty FAIL section. No pruning verification is needed in the absence of an archive extension.

Phase 7 — Collection inheritance (DCRT)

DCRT declares one collection whose collection_data matches DCR's exactly (jsonrpc / "" / POST / ""), with apis: [], headers: [], parse_directives: [], extensions: [], and a single chain-id verification carrying only values and no parse_directive.

This is precisely the pattern the guide prescribes. Under CombineUnique merge semantics the empty arrays inherit everything from DCR rather than zeroing it, and the parse-directive-less verification adopts DCR's VERIFICATION directive while values merge by extension so the child's testnet3 expected_value wins. The probe report confirms this resolved correctly inside the router: DCRT registered with providerCount:1, a non-empty api set inherited through the import closure, its own genesis-hash verification compiled, and averageBlockTime resolving to DCRT's 2m0s override rather than DCR's 5m0s. Defining the collection is justified — it is the only way to carry the testnet3 chain-id override.

Phase 8 — Headers

headers: [] on both collections. Correct: dcrd JSON-RPC takes HTTP Basic auth at the provider's own endpoint, which is provider configuration rather than a client-forwarded credential, so there is no pass_send key to declare. Single-content-type POST collection, so no blanket pass_override hazard.

Phase 9 — Live testing

Not performed: $ARGUMENTS[2] is empty and no reachable dcrd JSON-RPC upstream exists on either network. Per the standing rule for this run, the resulting probe gaps are an endpoint limitation and are not treated as spec defects, and no method/addon/collection is disabled on account of them. The two live checks that were possible without a node — the mainnet genesis hash via the dcrdata REST explorer, and the testnet3 genesis hash via Decred's own published parameters — were both performed and both pass (Phase 6).

Pre-flight gates (re-run, confirming the orchestrator's results)

jq -e . valid · check_unused_fields.sh PASS · check_internal_paths.sh PASS · check_network_params.sh empty FAIL · check_verifications.sh empty FAIL · check_directive_presence.sh OK · check_extensions.sh PASS · check_method_schema.sh 59/59 schema ok · check_node_admin_rpcs.sh OK · check_hanging_api.sh 3/3 hanging ok · check_stateful.sh PASS · check_disabled_count.sh 0 distinct disabled methods. All exit 0, all FAIL sections empty.


Part 3 — Disable-justification audit

jq '[.proposal.specs[] | .api_collections[] | select(.enabled==false)] | length'   → 0
jq '[.proposal.specs[] | .api_collections[].apis[] | select(.enabled==false)] | length' → 0

Zero enabled: false api collections and zero enabled: false apis across both DCR and DCRT. The Disabled-API Justifications ledger is correspondingly empty, so the audit is vacuously satisfied: there is no disabled entry lacking a positive-evidence row. This also matches the PR body's <!-- disabled-count: 0 --> and check_disabled_count.sh.

No CRITICAL finding from this audit.


Part 4 — Findings

MEDIUM-1 — gettreasuryspendvotes reads up to 3456 full blocks per tspend but is still priced at 20 CU with no timeout_ms

  • Location: dcr.json:869 (gettreasuryspendvotes, compute_units: 20, no timeout_ms)
  • Evidence: handleGetTreasurySpendVotes calls chain.TSpendCountVotes(&checkBlock, tx) once per entry in the caller's tspends array. TSpendCountVotes (internal/blockchain/treasury.go:1097) delegates to tSpendCountVotes (treasury.go:1002), whose tally loop is:
    for n := prevNode; n != nil && n.height >= int64(start); n = n.parent {
        block, err = b.fetchBlockByNode(n)          // FULL block, from disk
        for _, stx := range block.MsgBlock().STransactions { ... stake.CheckSSGenVotes(stx) ... }
    }
    start comes from standalone.CalcTSpendWindow(expiry, tvi, tvim), and mainnet sets TreasuryVoteInterval: 288 with TreasuryVoteIntervalMultiplier: 12 (chaincfg/mainnetparams.go:582,586) — a 3456-block voting window. So a single in-window or mined tspend costs up to 3456 full-block reads plus a CheckSSGenVotes parse of every stake transaction in them. The tspends array has no length cap and dcrd does not de-duplicate it, so N entries cost N × that.
  • Why this is the same tier the commit just created: ticketfeeinfo and txfeeinfo were raised to 500/180000 in this very commit precisely because they read full blocks over a range. ticketfeeinfo with blocks: 1 reads one full block and is now priced at 500 CU; gettreasuryspendvotes reads up to 3456 full blocks in its default single-tspend form and is priced at 20.
  • Failure scenario: a consumer calls gettreasuryspendvotes with 50 copies of one mined, in-window tspend hash against a mainnet provider. dcrd performs ~172,800 full-block disk reads and parses the stake tree of each (on the order of gigabytes of block data). The provider is compensated 20 CU — 1/25th of what ticketfeeinfo earns for reading a single block — and, with no timeout_ms, the relay is cut off at the router default, so the caller gets a timeout rather than an answer while the provider has already paid the full I/O cost.
  • Impact: economic under-compensation and an unmetered amplification vector against every DCR/DCRT provider; legitimate treasury-governance queries over a live voting window fail on the default timeout.
  • Suggested fix (for a follow-up, not this review): compute_units: 500, timeout_ms: 180000 — the livetickets tier, consistent with the four methods this commit just moved there.

MEDIUM-2 — getnetworkhashps is a caller-controlled whole-chain scan priced at 10 CU with no timeout_ms

  • Location: dcr.json:338 (getnetworkhashps, compute_units: 10, no timeout_ms)
  • Evidence: handleGetNetworkHashPS computes startHeight := endHeight - numBlocks where numBlocks = int64(*c.Blocks) whenever the caller passes blocks >= 0. The only clamp is if startHeight < 0 { startHeight = 0 } — there is no upper bound on blocks. GetNetworkHashPSCmd.Blocks is *int (rpc/jsonrpc/types/chainsvrcmds.go:597), i.e. 64-bit, so any value is accepted. The loop then runs:
    for curHeight := startHeight; curHeight <= endHeight; curHeight++ {
        hash, err := chain.BlockHashByHeight(curHeight)
        header, err := chain.HeaderByHash(hash)
        totalWork.Add(totalWork, standalone.CalcWork(header.Bits))
    }
    Per block that is two index lookups plus a big.Int work computation — strictly more work per block than ticketvwap's single HeaderByHeight, and ticketvwap was raised to 500/180000 in this commit for exactly this shape.
  • Failure scenario: getnetworkhashps(2000000, -1) on mainnet walks all ~1.1M blocks, performing ~2.2M block-index lookups and ~1.1M big.Int work additions, for 10 CU — the same price as getblockcount. With no timeout_ms the relay is severed at the router default while the provider absorbs the full CPU cost; repeated at any concurrency this starves the provider's chainLock readers and degrades every other DCR request it is serving.
  • Impact: same two-sided failure as MEDIUM-1 — under-compensation plus an unmetered CPU amplification vector — and it is the cheapest-priced unbounded scan left in the spec.
  • Suggested fix (for a follow-up): compute_units: 500, timeout_ms: 180000.

MEDIUM-3 — getstakeversioninfo walks the whole chain for a caller-chosen count but is still priced at 20 CU with no timeout_ms

  • Location: dcr.json:691 (getstakeversioninfo, compute_units: 20, no timeout_ms)
  • Evidence: handleGetStakeVersionInfo clamps the caller's count only to totalIntervals := (snapshot.Height + interval - 1) / interval, then loops count times calling chain.GetStakeVersions(hash, numBlocks+adjust) with numBlocks = startHeight - endHeight — one full StakeVersionInterval per iteration — plus a chain.BlockHashByHeight to step back. Mainnet StakeVersionInterval is 144 * 2 * 7 = 2016 (chaincfg/mainnetparams.go:561), so count = totalIntervals ≈ 540 at today's height walks 540 × 2016 ≈ 1.09M block-index nodes and, for each, iterates v.Votes into two map[int]int tallies (~5 votes per block, so ~5.4M map updates).
  • Why this is inconsistent with the commit: this is the sibling of getstakeversions, which this very commit moved from 20 to 500/180000 for walking the same block index over a caller-chosen count. getstakeversioninfo visits the same ~1.09M nodes and does strictly more per-node work (the vote-map aggregation); only its response is smaller. The spec now prices the two at 500 and 20 respectively.
  • Failure scenario: getstakeversioninfo(540) on mainnet performs a full-chain block-index walk with ~5.4M map operations under chainLock for 20 CU, then is cut off at the router's default timeout because no timeout_ms is set — so the caller cannot obtain the full stake-version history at all, and the provider pays for the aborted walk.
  • Impact: under-compensation; the highest-count form of the method is effectively unusable through Lava; chainLock contention degrades co-resident requests.
  • Suggested fix (for a follow-up): compute_units: 500, timeout_ms: 180000.

No CRITICAL findings

No disabled api or collection lacking justification (there are none at all), no missing required parse directive, no wrong chain-id, no removed field, no broken inheritance, no phantom or misnamed method, no mis-set stateful/hanging_api, and no regression introduced by 7d1673c.

No MINOR findings

Bounded-cost methods were checked explicitly rather than assumed: getheaders is capped at wire.MaxBlockHeadersPerMsg inside BlockChain.LocateHeaders (internal/blockchain/chain.go:1973); getvoteinfo's CountVoteVersion walks back only to the start of the current rule-change interval (internal/blockchain/thresholdstate.go:657); existsaddresses, existslivetickets and existsmempooltxs are bounded by request body size with O(1) lookups each; getblock and getrawmempool are bounded by block and mempool size and match btc.json's pricing. None of these warrants a finding.


Part 5 — Advisory notes (explicitly NOT findings; excluded from the tally)

A. gettxoutsetinfo — for the future joint btc.json + dcr.json change

Out of scope for this PR by recorded human decision ("Human decision: gettxoutsetinfo stays deterministic: true. DO NOT REVERT"). Recording the technical position for whoever makes the joint change, with no severity attached and no effect on the tally:

handleGetTxOutSetInfo (internal/rpcserver/rpcserver.go:3790) opens with best := s.cfg.Chain.BestSnapshot() and returns Height: best.Height and BestBlock: best.Hash.String() alongside the UTXO statistics, so two providers one block apart return different payloads for the same request. It also returns DiskSize: stats.Size, which is node-local and can differ between two perfectly synced providers. Under the determinism rule DCR otherwise applies consistently — tip-derived output ⇒ deterministic: false — this method would be false. btc.json:gettxoutsetinfo has the same shape (cu=500, timeout=180000, DEFAULT ["latest"], deterministic: true), which is exactly why the author has ruled the two specs change together. Nothing here needs to happen in this PR.

B. confirmations in Bitcoin-family verbose replies — catalog-wide, not a dcr.json defect

getblock, getblockheader and getrawtransaction are deterministic: true while their verbose dcrd replies embed confirmations (and nextblockhash), which are derived from the tip even when a specific finalized block hash is requested. dcr.json is identical to btc.json here, and to every Bitcoin-family spec in the catalog, so this is a settled convention rather than a defect in this spec. Raised only so it is on the record; it should travel with the same joint review as note A if anyone revisits it.

C. Out of scope by instruction

Router-side caching of Decred's node-local reads is tracked as MAG-4207 and is outside this spec. No other spec file was inspected for change, and none is proposed.


Summary

Item Value
Specs reviewed 2 (DCR mainnet, DCRT testnet3)
API methods reviewed 59 (all in DCR's single jsonrpc collection; DCRT inherits all 59)
API collections reviewed 2 (1 per spec, both jsonrpc/POST/""/"")
Parse directives reviewed 2 (GET_BLOCKNUM, GET_BLOCK_BY_NUM)
Verifications reviewed 2 (chain-id on each spec)
Disabled apis / collections 0 / 0 — ledger vacuously satisfied
Items claimed by 7d1673c and independently confirmed 3 of 3
Unintended changes in 7d1673c 0
CRITICAL 0
MEDIUM 3 (all one category: heavy-scan methods left in the cheap CU tier)
MINOR 0
Advisory notes (not findings) 3

Verdict: the three fixes this commit claims are all correctly applied and independently verified against dcrd source, and the commit changed nothing else. The spec is structurally sound — valid envelope, no removed fields, complete method coverage against dcrd's handler table, correct network parameters on both networks, correct and (for mainnet) live-verified chain-id verifications, textbook imports inheritance for DCRT, and zero disabled entries to justify.

The three remaining MEDIUM findings are all the same category as the one this commit just fixed: gettreasuryspendvotes, getnetworkhashps and getstakeversioninfo are heavy scans — one of them (gettreasuryspendvotes) reading thousands of full blocks per call — still sitting in the 10/20-CU tier with no timeout_ms, while their structural siblings now sit at 500/180000. None of them blocks deployment: they are mispricings, not correctness or safety defects, and each has an obvious one-line fix in the tier this commit established. Ready for deployment; the three CU/timeout alignments should follow in the next pricing pass.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Reviewed dcr.json at 7d1673c. Verdict: ⚠️ CHANGES REQUESTED (TALLY: CRITICAL=0 MEDIUM=3 MINOR=0) — see the Phase 11 comment above. Recorded honestly, not upgraded; the gate is CRITICAL=0 MEDIUM=0. All three items the triggering comment listed are in and all three were independently confirmed against dcrd master; the three MEDIUMs are pre-existing CU mispricings on methods this commit never touched, not regressions from it.

Annotations: ✓ verified this run · ~ partially verified · ☐ manual / out of skill scope. This span ran Phase 11 only, so every item whose evidence comes from Phases 1–10 is attributed to the run that produced it rather than claimed as verified here.

#### File Validation
- ✓ JSON syntax valid                                    (this run: `jq -e . dcr.json`)
- ✓ All required fields present                          (this run: check_method_schema.sh 59/59 schema ok; check_network_params.sh, check_verifications.sh, check_directive_presence.sh all clean)
- ✓ No duplicate API names within any collection         (Phase 11 reviewer, confirmed this run)
- ✓ Proper indentation/formatting                        (jq-formatted; unchanged in the working tree)

#### Configuration Verification
- ☐ All APIs tested and working                          (no reachable dcrd JSON-RPC upstream on either network — Phase 8 ran spec-load-only; all 56 non-stateful methods NOT_TESTABLE. Endpoint gap, not a spec defect)
- ~ Block parsing validated for each API                 (source-verified only: all 59 block_parsing entries checked against their dcrd handlers this run, incl. the 8 new EMPTY parsers. Never exercised against live traffic)
- ☐ Parse directives executed by live router             (Phase 8: PARSE=NOT_TESTABLE, VERIFY=NOT_TESTABLE — no node answered. Definitions re-confirmed against `handleGetBlockCount`/`handleGetBlockHash` this run; execution still unproven)
- ✓ Network parameters calculated per formulas           (Phase 2 + re-grounded this run against chaincfg/mainnetparams.go 5m and testnetparams.go 2m; allowed_block_lag floors to 1 on both)
- ☐ Addons & extensions tested                            (ADDONS: none declared — mechanically confirmed, nothing to test)
- ~ Verifications pass on live nodes                     (DCR genesis 298e5cc3… live-confirmed via the dcrdata REST explorer; DCRT a649dce5… source-corroborated only — both testnet3 explorers still down. A live testnet3 `getblockhash 0` remains outstanding)
- ☐ Compute units benchmarked under expected load        (user to measure — and the three open MEDIUMs are exactly this: gettreasuryspendvotes, getnetworkhashps, getstakeversioninfo)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created
      ↳ worth carrying from the earlier MINOR-3: the `--txindex` provider requirement,
        the dcrd rpcuser/rpcpass-in-node_url convention, and the DCRT genesis caveat
        have nowhere else to live.

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                (Phase 11: 59 apis, zero phantom methods against dcrd's rpcHandlers table; 18 omissions all node-operator control)
- ✓ Testnet spec inherits correctly                      (Phase 11 reviewer confirmed: DCRT imports ["DCR"], empty arrays merge, verification carries `values` only — and Phase 8's router boot resolved the closure with DCRT's 2m0s overriding DCR's 5m0s)
- ~ Chain IDs verified for mainnet AND testnet           (both well-formed 64-hex and sourced; mainnet live-confirmed, testnet3 source-only — see above)
- ☐ Both tested on respective networks                   (neither network had a reachable RPC; no live probe on either)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (envelope is exactly `{"proposal":{"specs":[DCR,DCRT]}}` — no title/description/deposit, none of the 9 governance fields; check_unused_fields.sh PASS)
- ☐ Community feedback gathered (if applicable)

Working-tree state

dcr.json is untouched — START_PHASE == END_PHASE == 11, so no Phase-10 fix pass ran and there is nothing for the workflow's commit step to pick up. The only files written this run are under docs/ (gitignored by design): the restored METHOD_PROBE_REPORT.md and the new SPEC_REVIEW_GAPS_final.md.

Required action

Not blocking on the author's judgement, but the gate will not clear until these move. Each is a one-line change into the tier 7d1673c itself established:

  1. gettreasuryspendvotes (dcr.json:869) → compute_units: 500, timeout_ms: 180000
  2. getnetworkhashps (dcr.json:338) → compute_units: 500, timeout_ms: 180000
  3. getstakeversioninfo (dcr.json:691) → compute_units: 500, timeout_ms: 180000

To apply them: /rerun-fix (Phase 10 only) or /rerun-from 10 (Phase 10 → 11, re-reviewing afterwards). If the author judges the current pricing acceptable and wants the PR to proceed as-is, that is a human override to record in the PR body the way gettxoutsetinfo already is — this run will not upgrade the verdict on its own.

Still carried forward, unchanged by this run: a live testnet3 getblockhash 0 to confirm the DCRT genesis hash, and gettxoutsetinfo for the joint btc.json + dcr.json determinism change (out of scope here by recorded human decision; Phase 11 Advisory note A). Router-side caching for Decred's node-local reads is MAG-4207, outside this spec.

Run stats — this pipeline run (Phases 11–11) only

This is a resumable run covering Phase 11 alone, in a separate workflow run from the create_spec job that executed Phases 1–7 and from the four earlier /rerun-final runs. The numbers below are not a 1–11 grand total: the Phases 1–7 time and tokens live in the create_spec run and its PR body, and the true cumulative cost for this PR is that run plus all five /rerun-final runs added together.

=== create-spec run stats ===
Elapsed:         00h 15m 18s  (first→last logged activity)
Transcripts:     1 main + 1 subagent
API round-trips: 146  (main=53, subagents=93)

Fresh tokens:    input=292  output=104284  (sum=104576)
Cached tokens:   cache_read=11560635  cache_write=500241
Total billed:    12165452 tokens

Split (total billed):  main=3174622  subagents=8990830

Models used:
  claude-opus-5           146 calls   12165452 billed

…s timeout (MAG-2961)

Applies the three items from the 2026-11-08 Phase 11 review of 7d1673c,
the same rule 7d1673c applied to ticketvwap and its siblings:

- getnetworkhashps: compute_units 10 -> 500, timeout_ms 180000. dcrd takes
  the caller's block count with no upper bound, so one call can walk the
  whole chain.
- gettreasuryspendvotes: compute_units 20 -> 500, timeout_ms 180000. Each
  tspend in the caller's list costs up to 3456 full-block reads (the
  mainnet voting window), and the list has no length cap.
- getstakeversioninfo: compute_units 20 -> 500, timeout_ms 180000. The
  caller's interval count is capped only by chain height, so one call
  can walk about 1.09M block-index nodes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-final

Final review of d02718a, which applies the three items from the 2026-11-08 Phase 11 verdict on 7d1673c and nothing else:

  1. MEDIUM-1: gettreasuryspendvotes → compute_units: 500, timeout_ms: 180000.
  2. MEDIUM-2: getnetworkhashps → compute_units: 500, timeout_ms: 180000.
  3. MEDIUM-3: getstakeversioninfo → compute_units: 500, timeout_ms: 180000.

Scope: these three edits only. As in the previous run, gettxoutsetinfo is out of scope for this PR: it stays deterministic: true by human decision (PR body, "Human decision … DO NOT REVERT") and changes together with btc.json in a separate PR. Record any disagreement with it as advisory, not as a MEDIUM. The router caching follow-up for Decred's node-local reads is MAG-4207, also outside this spec.

Pass run_in_background: false explicitly on every Agent call. CLI 2.1.278 starts an Agent call in the background when the key is omitted, which truncates the run.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

🤖 Command acknowledged — running Phase 11 only. Progress and results post here as comments. View run

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED (TALLY: CRITICAL=0 MEDIUM=0 MINOR=0)

Resumable run, Phases 11–11 only. Reviewed commit d02718a on decred-spec. Final reviewer ran on opus in a clean context; full report at docs/dcr/SPEC_REVIEW_GAPS_final.md (gitignored — reproduced below).


The three items this commit claims to apply — all three CONFIRMED CORRECT

d02718a is 6 insertions / 3 deletions in one file, across exactly the three api entries named in the 2026-11-08 verdict on 7d1673c. Nothing else in the repo changed.

Item Method dcr.json Before After Source basis (verified against dcrd, not against the commit message)
MEDIUM-1 gettreasuryspendvotes :871 / :879-880 20, no timeout 500 / 180000 blockchain/treasury.go:1002-1097 walks TreasuryVoteInterval 288 × Multiplier 12 = 3456 full blocks per tspend via fetchBlockByNode (LRU holds only 12 → ~59 MB disk per tspend), and TSpends *[]string is uncapped and not de-duplicated — a 100-entry list of one repeated hash costs ~345,600 full-block reads
MEDIUM-2 getnetworkhashps :338 / :345-346 10, no timeout 500 / 180000 rpcserver.go:2704-2782 — numBlocks taken raw from c.Blocks, clamped only at startHeight < 0, so blocks >= tipHeight walks the whole chain (~1.13M iterations, each a big.Int CalcWork)
MEDIUM-3 getstakeversioninfo :692 / :699-700 20, no timeout 500 / 180000 rpcserver.go:3140-3214 — count clamped only to totalIntervals = ceil(height/2016) ≈ 561, each calling GetStakeVersions(hash, 2016) → ≈1.13M block-index nodes

The reviewer read the handlers in full rather than accepting the rationale, and confirmed each is genuinely an uncapped caller-controlled scan. It also confirmed the negative half: deterministic, block_parsing, stateful, hanging_api, enabled and parsers on all three entries are byte-identical to 7d1673c — no field these entries did not need was touched.

Heavy tier is now internally coherent and complete. All 11 methods at that price carry identical compute_units: 500 + timeout_ms: 180000, and no unbounded scan is left at the cheap tier. deterministic within the tier is consistent too: true only where the result keys to an immutable input (getstakeversions by hash; gettxoutsetinfo by the recorded human decision), false on the nine tip-readers.

timeout_ms floor holds with margin. The rule is timeout_ms >= max(1s, compute_units × 100ms); 500 CU requires 50000 ms and these carry 180000 ms (3.6×). This matters because timeout_ms replaces the CU-derived term rather than adding to it — a value under the floor would have shortened the relay budget.


Scope discipline

gettxoutsetinfo was held out of scope, as instructed. The reviewer was told the PR body's "Human decision … DO NOT REVERT" is settled and that any disagreement must be advisory. It complied: gettxoutsetinfo appears only as Advisory note 1, with no severity and not in the tally. Its technical position is recorded there for the future joint btc.json + dcr.json change. MAG-4207 (router-side caching of node-local reads) was likewise recorded as advisory only.


Full-spec audit — no in-scope defects

Area Result
API completeness PASS, zero read-query gaps. No OpenAPI doc was supplied, so completeness was checked against dcrd's authoritative handler map rpcHandlersBeforeInit (rpcserver.go:174-253, 77 HTTP methods): all 59 spec names appear verbatim as keys — zero typos, zero wallet-only leakage (rpcAskWallet), zero unimplemented. The 18 absent methods are 17 node-operator controls (stop, addnode, invalidateblock, generate, …) plus legacy getwork, all pre-justified and confirmed clean by check_node_admin_rpcs.sh. The 17 ws-only handlers are correctly absent from an HTTP-POST collection
Network params PASS. DCR average_block_time: 300000 matches TargetTimePerBlock: 5m in chaincfg/mainnetparams.go and the probe's 299.96 s lifetime mean; DCRT 120000 matches testnetparams.go 2m. blocks_in_finalization_proof: 3 correct for PoW/PoS hybrid probabilistic finality; allowed_block_lag_for_qos_sync: 1 and block_distance_for_finalized_data: 6 both derive correctly
Verifications PASS — and upgraded. Both genesis hashes were independently re-confirmed this run. Mainnet via dcrdata.decred.org/api/block/0/hash and chaincfg.MainNetParams().GenesisHash. Testnet3 a649dce5…4a49bac was confirmed from chaincfg.TestNet3Params().GenesisHash and recomputed as blake256(header[:180]) byte-reversed from dcrd's own committed genesis test vector — this relaxes the probe report's "never live-confirmed" caveat and auto-decision #8's "confidence: medium" to source-authoritative
Testnet inheritance PASS. DCRT declares the matching jsonrpc/""/POST/"" collection with empty arrays and a single name-matched chain-id verification overriding only expected_value — exactly the documented merge semantics, and corroborated by the probe's SPEC_LOAD_TESTNET: OK (router resolved the closure, picked up DCR's apis, honoured DCRT's own 120000 override)
Parse directives PASS. GET_BLOCKNUM (getblockcount) and GET_BLOCK_BY_NUM (getblockhash [%d]) are shape-identical to btc.json's proven UTXO pattern; both api_names exist in the collection
Archive triplet PASS (uniformly absent, not mixed). No extensions, no pruning verification, no GET_EARLIEST_BLOCK. Justified: dcrd has no block-pruning flag in config.go at all
Category flags PASS. Exactly three stateful: 1 apis (sendrawtransaction, submitblock, sendrawmixmessage) — the only writes on dcrd's read surface — each with hanging_api: true and explicit timeout_ms: 10000. Determinism spot-checks hold at the boundary: createrawssrtx false (bakes the tip header in via stake.CreateRevocationFromTicket), decoderawtransaction correctly not swept into the EMPTY batch (reads BestSnapshot().Hash for isTreasuryAgendaActive)
Block parsing PASS. getrawtransaction correctly uses DEFAULT ["latest"] rather than btc.json's PARSE_BY_ARG ["2"] — dcrd's signature has no third parameter, so the BTC parser would point at an argument that does not exist

Disable-justification audit: vacuously satisfied. Zero enabled: false apis and zero enabled: false collections across DCR and DCRT, matching the empty ledger and the body's <!-- disabled-count: 0 -->. Correct under rule (c): the NOWNodes gateway returns HTTP 405 for 33 of 59 methods and the probe records 56 as NOT_TESTABLE, none of which is positive evidence of absence — all 33 ship enabled and sit on the re-probe watch-list instead.

Pre-flight gates re-run against HEAD by the orchestrator (all exit 0, all FAIL sections empty): jq -e . valid · check_unused_fields.sh → RESULT: PASS (no removed fields) · check_internal_paths.sh → RESULT: PASS (every internal_path is "") · check_network_params.sh · check_verifications.sh · check_directive_presence.sh → OK · check_extensions.sh · check_method_schema.sh → 59/59 schema ok · check_node_admin_rpcs.sh → no new node-operator control · check_hanging_api.sh → 3/3 hanging ok · check_stateful.sh · check_disabled_count.sh → 0 distinct disabled, matching the body marker. Independently re-verified by jq: 11 methods in the heavy tier, 14 carrying timeout_ms, 0 timeout-floor violations, 59 api names all unique, and the three cited line refs land exactly on the edited fields. No SUBSCRIBE directive anywhere, so the ws gate does not apply and no ws-capable node was required.


Advisory notes (NOT findings — excluded from the tally, no severity)

  1. gettxoutsetinfo deterministic: true (dcr.json:459) — out of scope by recorded human decision; changes jointly with btc.json. For that future change: handleGetTxOutSetInfo returns tip-derived height/bestblock plus node-local DiskSize, and its forced maybeFlushFn makes it the only read in the spec that mutates node-side state.
  2. btc.json's getnetworkhashps is now the stale side of the pair — priced 10 / deterministic: true / no timeout, while Bitcoin Core's getnetworkhashps(nblocks, height) is uncapped in exactly the same way dcrd's is. The fix belongs in btc.json; dcr.json's 500 / false / 180000 should not be dragged back to match.
  3. Sub-tiering within the 500 CU band — the eleven heavy methods are not equally heavy (ticketfeeinfo/txfeeinfo/gettreasuryspendvotes scan full blocks from disk; getnetworkhashps/getstakeversioninfo/ticketvwap walk comparable counts in memory). Not raised as a finding: the flat tier is internally consistent and conservative in the right direction, and the repo has no in-production heavy-tier value above 500 to anchor a higher number to. Worth revisiting if CU telemetry shows Decred providers losing money.
  4. getrawtransaction deterministic: true (dcr.json:384) — verbose output carries tip-derived confirmations and the handler checks mempool first. Recorded as advisory, not a finding, because getblock and getblockheader carry the same fields and the same true, and all three match btc.json — the catalog's operative line is "a by-hash read is deterministic; incidental tip-derived metadata is accepted noise". Flipping it in dcr.json alone would create exactly the divergence the gettxoutsetinfo decision exists to prevent.
  5. Router-side caching of node-local reads — MAG-4207, outside this spec.
  6. Testnet3 chain-id — now source-authoritative (see Verifications above); still worth a live getblockhash(0) the first time a testnet3 RPC exists, since testnet3 has been reset before while keeping its name and network magic.

Limitations of this review (stated honestly)

  • No live probing. No reachable dcrd JSON-RPC upstream exists on either network (re-verified in Phase 8). GET_BLOCKNUM, GET_BLOCK_BY_NUM and both chain-id verifications were checked for shape and for expected_value correctness against source, but never exercised end-to-end against a node. PARSE: NOT_TESTABLE / VERIFY: NOT_TESTABLE stand. This is an endpoint gap, not a spec defect, and it justifies disabling nothing.
  • No API documentation supplied — completeness was verified against dcrd's handler map in source. Stronger than an OpenAPI diff for a native node RPC, but it does not catch a method documented as deprecated.
  • CU values are not benchmarked. The 500 CU assignment rests on the handlers' asymptotic cost and the btc.json anchor, not on measured per-call latency — no node was available to measure on.

Verdict: APPROVED. d02718a applies exactly the three items the previous verdict asked for, each justified by the dcrd handler source, landing in an existing anchored tier, satisfying the timeout_ms floor with margin, and touching no field it did not need to. No CRITICAL, MEDIUM or MINOR findings remain in scope.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (resumable run, Phases 11–11 only)

Chain: Decred — dcr.json (DCR mainnet + DCRT testnet3). Commit reviewed: d02718a. Verdict: ✅ APPROVED (CRITICAL=0 MEDIUM=0 MINOR=0).

This run executed Phase 11 only (START_PHASE == END_PHASE == 11), as commanded. Phases 8–10 were not re-run; their items below are annotated with the run that produced the evidence. dcr.json is unmodified in the working tree — a Phase-11-only span has no fix pass, so there is nothing for the downstream commit step to pick up.

#### File Validation
- ✓ JSON syntax valid                                    (this run: `jq -e .` exit 0)
- ✓ All required fields present                          (this run: check_network_params / check_verifications / check_method_schema, 59/59 schema ok)
- ✓ No duplicate API names within any collection         (this run: 59 names, 59 unique)
- ✓ Proper indentation/formatting                        (4-space jq indent, no trailing newline — matches catalog convention)
- ✓ No removed-model fields                              (this run: check_unused_fields.sh → PASS; no title/description/deposit, none of the 9 governance fields, no extra_compute_units / category.local / category.subscription)
- ✓ internal_path guard                                  (this run: check_internal_paths.sh → PASS; every internal_path is "")

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 4 of the original run; re-verified this run against chaincfg: DCR 300000ms = TargetTimePerBlock 5m, DCRT 120000ms = 2m; blocks_in_finalization_proof 3 for PoW/PoS probabilistic finality)
- ~ All APIs tested and working                          (Phase 8, 2026-10-06 — see docs/dcr/METHOD_PROBE_REPORT.md. 56 of 59 NOT_TESTABLE: no reachable dcrd JSON-RPC upstream exists on either network. Endpoint gap, not a spec defect)
- ~ Block parsing validated for each API                 (static/source validation only; 59/59 have block_parsing and the shapes were source-checked, incl. getrawtransaction correctly DEFAULT ["latest"] not btc.json's PARSE_BY_ARG ["2"] — dcrd has no third parameter)
- ~ Parse directives executed by live router             (Phase 8: SPEC_LOAD=OK, SPEC_LOAD_TESTNET=OK, zero class-A spec-defect signatures — but PARSE=NOT_TESTABLE / VERIFY=NOT_TESTABLE for want of an upstream. Shape verified against btc.json's proven UTXO pattern; never exercised end-to-end)
- ✓ Addons & extensions tested                           (none declared — extensions: [] on both specs, and correctly so: dcrd has no pruning flag, so the archive/pruning/GET_EARLIEST_BLOCK triplet is uniformly absent rather than mixed)
- ~ Verifications pass on live nodes                     (NOT live-executed — no upstream. Both genesis hashes are source-authoritative: mainnet via dcrdata API + chaincfg.MainNetParams().GenesisHash; testnet3 via chaincfg.TestNet3Params().GenesisHash AND recomputed as blake256(header[:180]) byte-reversed from dcrd's committed test vector)
- ✓ hanging_api / stateful discipline                    (this run: check_hanging_api.sh 3/3 ok, check_stateful.sh clean. Exactly 3 stateful:1 apis — sendrawtransaction, submitblock, sendrawmixmessage — each with hanging_api:true and explicit timeout_ms:10000)
- ✓ timeout_ms floor respected                           (this run: 14 apis declare timeout_ms, 0 violate timeout_ms >= max(1s, cu × 100ms). The eleven 500-CU methods need 50000ms and carry 180000ms)
- ☐ Compute units benchmarked under expected load        (user to measure — the 500 CU tier rests on asymptotic handler cost + the btc.json anchor, not on measured latency; no node was available)

#### Disable Justifications
- ✓ Disabled-API audit                                   (0 enabled:false apis and 0 enabled:false collections; check_disabled_count.sh → 0 distinct, matching the body's <!-- disabled-count: 0 -->. Ledger empty, so the audit is vacuously satisfied)
- ✓ Probe errors did not drive any disable                (33 of 59 methods are whitelisted out by the NOWNodes gateway with HTTP 405; all 33 ship enabled and sit on the re-probe watch-list — correct under the free-tier rule)

#### Documentation (out of skill scope — manual reminder)
- ☐ SPEC_IMPLEMENTATION.md created
- ☐ API_REFERENCE.md created
- ☐ TESTING_GUIDE.md created
- ☐ QUICK_START.md created

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                (DCR: 59 apis, all 59 verbatim keys of dcrd's rpcHandlersBeforeInit handler map; zero read-query gaps)
- ✓ Testnet spec inherits correctly                      (DCRT imports ["DCR"], declares the matching jsonrpc/""/POST/"" collection with empty arrays + a name-matched chain-id override; Phase 8 SPEC_LOAD_TESTNET=OK confirms the router resolved the closure and honoured DCRT's own 120000ms block time)
- ~ Chain IDs verified for mainnet AND testnet           (both source-authoritative, neither live-executed — no RPC exists. Mainnet additionally cross-checked against the public dcrdata API)
- ☐ Both tested on respective networks                    (Phase 8 found no reachable dcrd JSON-RPC upstream on either network; re-test when one exists)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (envelope is the canonical { "proposal": { "specs": [ … ] } } — no title/description/deposit)
- ☐ Community feedback gathered (if applicable)

Open advisory items carried forward (none block this PR)

Item Where it belongs
gettxoutsetinfo deterministic: true Joint btc.json + dcr.json PR — settled human decision here, DO NOT REVERT
btc.json's getnetworkhashps now the stale side (10 / true / no timeout) btc.json, not here
Router-side caching of Decred's node-local reads MAG-4207
getrawtransaction / getblock / getblockheader tip-derived confirmations Catalog-wide UTXO determinism convention, not a dcr.json defect
Sub-tiering inside the 500 CU band Revisit only if CU telemetry shows providers losing money
Live getblockhash(0) on testnet3 When a testnet3 RPC first exists

Run stats — this pipeline run (Phases 11–11) only

Elapsed:         00h 16m 42s  (first→last logged activity)
Transcripts:     1 main + 3 subagent
API round-trips: 244  (main=35, subagents=209)

Fresh tokens:    input=488  output=119097  (sum=119585)
Cached tokens:   cache_read=13445847  cache_write=688355
Total billed:    14253787 tokens

Split (total billed):  main=2482215  subagents=11771572

Models used:
  claude-opus-5           244 calls   14253787 billed

These numbers cover Phase 11 of this run only — not a Phases 1–11 grand total. The original Phases 1–7 time and tokens live in the create_spec run and its PR body; Phases 8–10 were spent across the earlier resumable runs on this PR (comments above). The true end-to-end total is all of those runs added together.


Run complete. END_PHASE=11 reached — stopping here, as commanded. No phase after 11 was run, and no git operation was performed by this run.

@AnnaR-prog

Copy link
Copy Markdown
Contributor

@avitenzer could you re-review? Changes since your 2026-10-07 review:

  • 7d1673c and d02718a apply the Phase 11 findings on ce03338 and 7d1673c:
    • 7 uncapped range scans → 500 CU + timeout_ms: 180000 (ticketvwap, ticketfeeinfo, txfeeinfo, getstakeversions, getnetworkhashps, gettreasuryspendvotes, getstakeversioninfo).
    • 8 stateless methods → EMPTY parsing.
    • createrawssrtx → deterministic: false (the tip header seeds its remainder PRNG).
  • gettxoutsetinfo stays deterministic: true, as you decided (btc.json parity). The body records it as a human decision.
  • Phase 11 on d02718a: ✅ APPROVED (0 critical, 0 medium, 0 minor).
  • Live on smart-router v1.6.7 (2026-11-08, keyed NOWNodes endpoint, key withheld): chain-id verified and chain tracker OK at 7d1673c. d02718a changes only CU and timeouts.
  • The branch is behind main with no conflicts, and main's spec guards pass on dcr.json. The router cache follow-up stays in MAG-4207.

@avitenzer avitenzer left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed at d02718a. Approving.

Checked:

  • The diff since ce03338 (7d1673c, d02718a) is exactly the listed changes, nothing else:
    • 7 range scans → 500 CU + timeout_ms: 180000, the same as btc.json's gettxoutsetinfo. The router uses the spec's timeout_ms instead of the time it derives from CU.
    • 8 stateless methods → EMPTY parsing.
    • createrawssrtx → deterministic: false.
    • gettxoutsetinfo unchanged.
  • The deterministic flags on the 8 EMPTY methods make sense: version and estimatefee are false, the pure functions are true.
  • The branch merges into current main with no conflicts. Main's spec guards pass on the merged dcr.json: node-admin RPCs, removed fields, internal paths, method schema, network params, verifications, directive presence, and disabled count = 0 against the body.
  • On smart-router main (v1.6.7), the spec at d02718a loads and builds. I had no keyed Decred endpoint, so I did not check live answers; that evidence is your run at 7d1673c, and d02718a changes only CU and timeouts.

Not covered: the 33 methods NOWNodes answers with 405 have still never answered live. Router caching stays in MAG-4207.

@AnnaR-prog
AnnaR-prog merged commit d641581 into main Nov 8, 2026
3 of 6 checks passed
AnnaR-prog added a commit that referenced this pull request Nov 8, 2026
dcrd's handleTxFeeInfo always embeds the live mempool fee distribution
(FeeInfoMempool), so two providers can answer the same call
differently, exactly like ticketfeeinfo, which is already
deterministic: false. Clears the Phase 11 CRITICAL on #186.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
AnnaR-prog added a commit that referenced this pull request Nov 8, 2026
…961)

getticketpoolvalue and ticketsforaddress both walk the whole live ticket
pool (about 41k entries, one utxo read each). Give them 500 CU and a
180 s timeout, matching livetickets and gettxoutsetinfo. These were the
two remaining MEDIUMs from the Phase 11 review on #186.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants