Skip to content

feat(btc): serve the Blockbook bb_* methods from a blockbook add-on (MAG-4824) - #202

Merged
Tomelia1999 merged 5 commits into
mainfrom
feat/btc-blockbook-methods
Nov 6, 2026
Merged

Tomelia1999 merged 5 commits into
mainfrom
feat/btc-blockbook-methods

Conversation

@Tomelia1999

@Tomelia1999 Tomelia1999 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Why

QuickNode serves Blockbook methods (bb_getAddress, bb_getUTXOs, …) on Bitcoin-family endpoints that have the Blockbook RPC add-on enabled. Other node vendors refuse them, and QuickNode is the only vendor found that serves Blockbook over JSON-RPC (GetBlock and NOWNodes serve it as REST only). With no spec entries, the router forwards them under its default handler and stops on the first refusal, so a request succeeds or fails depending on which node is picked.

Ticket: MAG-4824.

What

A new blockbook add-on collection on the BTC jsonrpc interface, holding 15 methods. Only node urls that declare addons: ["blockbook"] are asked for them; other nodes never see a bb_* call. A request with no such url gets No Providers For Addon.

Every spec that imports BTC inherits the add-on: BTCT, BTCT4, BTCS, BCH, BCHT, LTC, LTCT, DOGE, DOGET, ZCASH, ZCASHT, DASH, DASHT (checked by expanding each spec with the router's own loader: 15 bb_* in the blockbook collection, 0 in the base collection, verification present).

Verification (enabled): bb_getBlockHash ["0"] must answer with a blockHash (PARSE_CANONICAL ["0","blockHash"], wildcard). Height 0 exists on every chain and network, so the one check works for every inheriting spec. A url that fails it loses only the add-on and keeps serving the base collection.

Names are taken from the request examples on QuickNode's method pages, identical for Bitcoin, Bitcoin Cash, Litecoin, Dogecoin and Zcash (camelCase, case-sensitive; the overview pages abbreviate bb_getXPUB as bb_getXpub, the requests use bb_getXPUB).

method parsing deterministic CU
bb_getAddress, bb_getBalanceHistory, bb_getUTXOs, bb_getXPUB DEFAULT latest no (change within a block) 20
bb_getEstimateFee DEFAULT latest no 10
bb_getTickers, bb_getMultiTickers, bb_getTickersList DEFAULT latest no 20
bb_getRawBlock, bb_getFeeStats PARSE_BY_ARG 0 + parsers BLOCK_HASH, BLOCK_LATEST (like getblockstats) yes 20
bb_getBlock DEFAULT latest (its answer carries confirmations, so it must not be long-cached by height) yes 20
bb_getTx, bb_getTxSpecific DEFAULT latest yes 20
bb_getBlockHash PARSE_BY_ARG 0 (like getblockhash) yes 10
bb_sendTransaction DEFAULT latest, stateful, hanging, timeout_ms 10000 no 10

Router config to use it:

node-urls:
  - url: <node with Blockbook>
    addons: ["blockbook"]

Verified

Local run on BTCT4 with the released v1.6.6 router (no router change needed). The real Alchemy and QuickNode testnet4 nodes sat behind counting proxies; QuickNode's bb_* was mocked because its add-on is not enabled yet. 30 bb_getAddress per run:

config answered bb_* calls that reached Alchemy add-on check
QuickNode declares blockbook 30/30 0 QuickNode passes
Both declare blockbook 30/30 0 Alchemy refused (-32600); keeps serving base methods
Real QuickNode without the add-on declares blockbook 0/5, No Providers For Addon 0 QuickNode refused (-32601); keeps serving base methods

All 14 read methods × 10 through the same v1.6.6 setup: 140/140 answered by QuickNode, 0 bb_* calls reached Alchemy since startup, getblockcount still split across both nodes.

Block parsing, v1.6.6 with a local cache server, each request sent 3 times (testnet4 tip 159191):

request requested_block calls that reached QuickNode
bb_getRawBlock ["150000"] 150000 1 (2 served from cache)
bb_getRawBlock [<hash>] none (not cached) 3
bb_getFeeStats ["150000"] 150000 1
bb_getFeeStats [<hash>] none (not cached) 3
bb_getRawBlock ["159191"] (tip, not final) 159191 1 (short TTL)
bb_getBlock ["150000"] none (latest) 1 (short TTL, until the tip moves)
bb_getBlockHash ["150000"] 150000 1

Spec checks against main: check_collection_addition PASS (1 collection added, everything else canonical-identical); check_node_admin_rpcs no new exposure; check_hanging_api bb_sendTransaction ok (remaining findings sendrawtransaction, submitpackage, REST /tx/send are already on main); check_method_schema ok for all 15; check_verifications notes the wildcard, same as the existing blockdaemon add-on.

No write was sent to any real endpoint; bb_sendTransaction was not exercised.

No method disabled anywhere.

🤖 Generated with Claude Code

Tomelia1999 and others added 2 commits November 5, 2026 13:54
QuickNode serves Blockbook (bb_getAddress, bb_getUTXOs, ...) on Bitcoin endpoints
with the Blockbook RPC add-on enabled. Without spec entries the router forwards them
under its default handler, and stops on the first node refusal, so a pool where only
one provider has Blockbook answered at random. Listed, a refusal is retried on a peer.

Names match QuickNode's request examples exactly (camelCase). Address, xpub, utxo,
balance-history, fee and ticker reads are non-deterministic (they change within a
block); block and tx lookups are deterministic; bb_getBlockHash parses its height
like getblockhash; bb_sendTransaction is stateful and hanging, like sendrawtransaction.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
hanging_api without timeout_ms falls back to the CU-derived budget; 10000 ms
matches the value most specs use for a broadcast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@magmadevs-bot

Copy link
Copy Markdown
Contributor

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

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 8 — smart-router boot + multi-node method probe

Resumable pipeline run (Phases 8–11). Endpoint source: self_research — MAINNET_URLS/TESTNET_URLS were both empty, so public keyless nodes were discovered and validated in a Phase-7.5 pass before booting.

verdict value
PARSE: PARTIAL — GET_BLOCKNUM OK (smartrouter_latest_block{spec="BTC"}=974675); GET_BLOCK_BY_NUM NOT_EXERCISED (router binary v1.6.6-67-gc5fae89 logs block-hash polling (fork detection) resolved enabled=false reason=off-operator-choice, so the tracker never calls it — not a spec defect; the getblockhash(%d) directive was independently verified by direct probe, PASS)
VERIFY: OK — chain-id passed on both providers (rawData="main")
ADDONS: 0 tested-ok / 0 failed / 2 not-testable (blockdaemon, rest)
counts PASS=30 FAIL=16 SKIP=3 UNPROBED=0 WARN=0 TIMEOUT=0 LOG_WARN=87
TESTNET_VERIFY: OK — BTCT chain-id="test" ✓, BTCT4 "testnet4" ✓, BTCS "signet" ✓ (all three booted clean)
BLOCK_TIME: mainnet 617562ms (+2.9%), BTCT4 547027ms (−8.8%), BTCS 588501ms (−1.9%) — all OK; BTCT 25393ms (−95.8%) → BLOCK_TIME_MISMATCH (testnet3), see auto-decision below
teardown clean — sr_btc and sr_btc_testnet removed, no leftover containers

Upstreams probed (keyless, no credentials available to this run): https://bitcoin-rpc.publicnode.com, https://bitcoin-mainnet.gateway.tatum.io (mainnet); bitcoin-testnet-rpc.publicnode.com (BTCT), bitcoin-testnet4.gateway.tatum.io (BTCT4), bitcoin-signet-rpc.publicnode.com (BTCS).

The 15 new bb_* methods could not be positively exercised. 14 returned -32601 Method not found identically on both upstreams; bb_sendTransaction was SKIPped as category.stateful: 1. Blockbook is a QuickNode add-on surface and neither keyless upstream is Blockbook-enabled. Under the skill's free-tier rule this is not evidence any method should be disabled — no disable is recommended, and the methods are carried to the watch-list for re-test on a Blockbook-enabled node. The PR body records a prior A/B run against a real QuickNode slot that did exercise them end-to-end.

Auto-decisions recorded at STOP-and-ask gates (conservative default):

  1. BLOCK_TIME_MISMATCH (testnet3/BTCT) → reported, not fixed. Bitcoin testnet3's 20-minute difficulty-reset rule produces rapid-fire block bursts; the 1000-block window landed inside one. Its long-run average remains the 10-minute retarget target, and BTCT.average_block_time is a pre-existing field unrelated to this PR's scope (adding bb_* methods). Editing it here would be an undeclared change to an established entry.
  2. rest interface + blockdaemon addon → NOT_TESTABLE, not a defect. Both are key-gated (Blockdaemon Ubiquity root returns HTTP 401 No Authorization Header; bd_getbalance → -32601 on both generic bitcoind upstreams). Carried forward with evidence rather than probed or flagged.

Two base-collection FAILs (getmemoryinfo, gettxoutsetinfo) are pre-existing and unrelated to this PR — both are node-policy blocks on the public upstreams (501 not allowed / Allnodes policy on publicnode, -32601 on Tatum).

Full probe report (docs/btc/METHOD_PROBE_REPORT.md)

Method Probe Report — btc

Generated: 2026-11-05T13:38:37Z
Router image: ghcr.io/magma-devs/smart-router:main (sha256:4652fc11f5834708b694f36d424bb584e6df90d9d3ddfa9908a69b775cc5a769)
Router config: /tmp/sr_btc.yml (mainnet), /tmp/sr_btc_testnet.yml (reused per-testnet, see Testnet section)
Spec variant: BTC (jsonrpc) — PR MAG-4824 adds 15 Blockbook bb_* methods to the base jsonrpc collection, inherited by BTCT/BTCT4/BTCS
Upstreams probed: https://bitcoin-rpc.publicnode.com (btc-upstream-1), https://bitcoin-mainnet.gateway.tatum.io (btc-upstream-2)

Parse-directive & verification runtime check (Step 3.5)

Check Verdict Evidence
GET_BLOCKNUM (router latest_block) OK smartrouter_latest_block{spec="BTC"}=974675; both rpc_endpoint_latest_block gauges (btc-upstream-1, btc-upstream-2) = 974675
GET_BLOCK_BY_NUM (log hash-reads ∥ fetch_block counters) NOT_EXERCISED hash_read_lines=0; fetch_block_* metric absent (as expected per contract — dead in this router build). Root cause confirmed in boot log: "block-hash polling (fork detection) resolved" enabled=false reason=off-operator-choice — this smart-router binary (v1.6.6-67-gc5fae89) disables fork-detection hash polling by default with no exposed config key to enable it. This is a router-deployment characteristic, not a spec defect — the getblockhash(%d) directive itself was independently exercised and confirmed correct by the direct Step-4 probe of getblockhash (PASS, returned a valid hash for height 974675).
Parse-signature log lines none —
Verification Verdict Providers OK/failed Notes
chain-id (jsonrpc, base) OK 2/2 rawData = "main" on both btc-upstream-1 and btc-upstream-2, matches expected_value: "main"
enabled (jsonrpc, blockdaemon add-on) NOT_EXERCISED 0/0 No upstream carries the blockdaemon addon (see Addon coverage below — NOT_TESTABLE); expected per Step 1c
chain-id (rest, base) NOT_EXERCISED 0/0 rest interface not configured — carried forward NOT_TESTABLE (see Addon coverage)
network (rest, base) NOT_EXERCISED 0/0 same as above

Addon & extension coverage (Step 1c + probes)

Name Type Upstreams supporting Standalone Boot verification Router probe Classification
blockdaemon (jsonrpc, 8 bd_* methods) addon none — n/a — NOT_TESTABLE — bd_getbalance probed directly against both configured upstreams: publicnode → {"error":{"code":-32601,"message":"Method not found"}}; Tatum → {"error":{"code":-32601,"message":"Method not found: bd_getbalance"}}. Neither upstream is Blockdaemon-backed. Per Step 1c-iii left out of router config (would exclude the provider at boot).
rest (all 4 networks' rest collection) interface none — n/a — NOT_TESTABLE — Blockdaemon Ubiquity-style API (chain-id GET / expects handle==bitcoin). Confirmed: curl https://svc.blockdaemon.com/universal/v1/bitcoin/mainnet/ → HTTP 401 {"title":"Unauthorized","detail":"No Authorization Header"}. No keyless tier exists and no API key is available to this run. No rest listener/direct-rpc block was added to the router config.

Method probe (base jsonrpc collection, 49 methods incl. 15 new bb_*)

Live inputs used: height=974675, hash=00000000000000000000f214ab0773b2577b965a21b53ada0345dadbd63c7cb2, a coinbase txid from that block, a live mempool txid from getrawmempool, a real raw-tx hex from getrawtransaction(...,true).hex, a real merkle proof from gettxoutproof, well-known address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa.

Method Classification Upstream notes Notes
getblockhash PASS —
getblock PASS —
createrawtransaction PASS —
decoderawtransaction PASS — first probe used placeholder hex and got -22 TX decode failed (probe-setup artifact); re-probed with real raw hex → PASS
decodescript PASS —
estimatesmartfee PASS —
getbestblockhash PASS —
getblockchaininfo PASS —
getblockcount PASS —
getblockheader PASS —
getblockstats PASS —
getchaintips PASS —
getchaintxstats PASS —
getconnectioncount PASS —
getdifficulty PASS —
getindexinfo PASS — txindex + basic block filter index both synced
getmemoryinfo FAIL btc-upstream-1 -32701: "Method getmemoryinfo is not allowed. To remove restrictions, order a dedicated full node..." (publicnode's backend is Allnodes — bitcoin-fn-ash.allnodes.me, confirmed via log). Re-probed (input-independent): btc-upstream-2 (Tatum) returned -32601 Method not found: getmemoryinfo. Fails on both configured upstreams — a provider-policy restriction on an administrative RPC, pre-existing (not introduced by this PR, not Blockbook-related).
getmempoolancestors PASS — first probe used a non-mempool (confirmed) txid → -5 Transaction not in mempool (probe-setup artifact); re-probed with a live mempool txid → PASS (empty ancestor set)
getmempooldescendants PASS — same re-probe as above → PASS
getmempoolentry PASS — same re-probe as above → PASS (full fee/size detail returned)
getmempoolinfo PASS —
getrawmempool PASS —
getrawtransaction PASS —
gettxoutproof PASS —
gettxoutsetinfo FAIL btc-upstream-1, btc-upstream-2 btc-upstream-1: HTTP 500 "Internal node error" after ~30s (consecutive 5xx, connection retired); re-probed with 35s timeout: btc-upstream-2 (Tatum) returned -32601 Method not found: gettxoutsetinfo. Fails on both upstreams — same provider-policy class as getmemoryinfo (heavy UTXO-set-scan RPC disabled on public tiers); pre-existing, not Blockbook-related.
gettxout PASS —
sendrawtransaction SKIP — category.stateful: 1 — would broadcast
submitpackage SKIP — category.stateful: 1 — would broadcast
testmempoolaccept PASS — stateful: 0; first probe used placeholder hex → -22 (probe-setup artifact); re-probed with real raw hex → PASS (allowed:false, reject-reason:"coinbase", correct functional behavior)
validateaddress PASS —
verifymessage PASS — returned result:false (correct — signature was not real), no error
verifytxoutproof PASS — first probe used placeholder proof → -1 DataStream::read(): end of data (probe-setup artifact); re-probed with real proof from gettxoutproof → PASS
getblockfilter PASS —
getnetworkhashps PASS —
bb_getAddress FAIL both -32601 Method not found on both upstreams
bb_getBalanceHistory FAIL both -32601 Method not found
bb_getBlock FAIL both -32601 Method not found
bb_getBlockHash FAIL both probed with live height 974675 (per PARSE_BY_ARG [0] rule) → -32601 Method not found
bb_getEstimateFee FAIL both -32601 Method not found
bb_getFeeStats FAIL both -32601 Method not found
bb_getMultiTickers FAIL both -32601 Method not found
bb_getRawBlock FAIL both -32601 Method not found
bb_getTickers FAIL both -32601 Method not found
bb_getTickersList FAIL both -32601 Method not found
bb_getTx FAIL both -32601 Method not found
bb_getTxSpecific FAIL both -32601 Method not found
bb_getUTXOs FAIL both -32601 Method not found
bb_getXPUB FAIL both -32601 Method not found
bb_sendTransaction SKIP — category.stateful: 1 — would broadcast

Notes on the 14 bb_* FAILs: this is the expected outcome stated in the task brief, not an unexpected finding — Blockbook is a QuickNode add-on surface and neither bitcoin-rpc.publicnode.com nor bitcoin-mainnet.gateway.tatum.io is Blockbook-enabled. All 14 probed bb_* methods returned -32601 identically on both configured upstreams (method-not-found is input-independent, no re-probe needed per the skill's re-probe-once gate). Per the skill's free-tier rule, a -32601 from a non-Blockbook public upstream is NOT evidence the methods should be disabled — this reflects upstream availability, not a spec defect. A reviewer who wants bb_* coverage verified would need a QuickNode Blockbook-enabled endpoint.

Log-scan findings (probe window)

87 non-benign warn/error/fatal/panic lines in the probe window (P0=1247). Breakdown:

Level Associated method error excerpt Count
ERR/WARN — (pacing) HTTP 429 Too Many Requests from btc-upstream-2 (Tatum) — "could not send relay to provider" / "Circuit breaker: all providers exhausted..." / "rate-limit hold-off: every candidate held off..." 73
ERR getmemoryinfo HTTP 501 Not Implemented: Method not implemented on this node (btc-upstream-1/Allnodes) + Tatum 429 attempt ~5
ERR gettxoutsetinfo HTTP 500 Internal Server Error: Internal node error (btc-upstream-1, 30s latency) + "upstream answered only 5xx; retiring its connection" + Tatum 429 attempt ~6
ERR verifytxoutproof DataStream::read(): end of data: iostream error — tied to the original placeholder-proof probe, already resolved by re-probe (PASS) ~3

Pacing observation: Tatum's free gateway (bitcoin-mainnet.gateway.tatum.io) enforces a hard 5 requests/minute limit and entered its rate-limit hold-off almost immediately at boot (first 429 logged before the first client probe was even sent, during startup chain-tracker traffic). Per the skill's pacing rule, 429 lines are evidence of upstream billing-tier capacity, not method findings — every client-visible probe response in this run (except the two genuine getmemoryinfo/gettxoutsetinfo FAILs) was served successfully by btc-upstream-1 (publicnode) despite btc-upstream-2's near-constant hold-off, so method coverage was not truncated (no UNPROBED methods). No client-visible 429 was returned to the probe loop itself, so the adaptive spaced-mode switch was never triggered for the main loop; it was engaged manually (13s spacing) for the Step 8 testnet4 block-time measurement after that gateway returned 429 directly.

Testnet verification pass (Step 7)

TESTNET_VERIFY: OK (aggregate across all 3 testnet entries)

Three separate containers were booted sequentially on ports 3460/7879 (sr_btc_testnet), one per testnet index, each with a single direct-rpc block for its given node URL, jsonrpc interface only (rest NOT_TESTABLE, carried forward — no rest listener booted for any testnet either).

BTCT (Bitcoin Testnet3) — https://bitcoin-testnet-rpc.publicnode.com

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 rawData="test", matches expected_value: "test"
GET_BLOCKNUM OK — smartrouter_latest_block{spec="BTCT"}=5300349

BTCT4 (Bitcoin Testnet4) — https://bitcoin-testnet4.gateway.tatum.io

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 rawData="testnet4", matches expected_value: "testnet4"
GET_BLOCKNUM OK — smartrouter_latest_block{spec="BTCT4"}=159175

BTCS (Bitcoin Signet) — https://bitcoin-signet-rpc.publicnode.com

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 rawData="signet", matches expected_value: "signet"
GET_BLOCKNUM OK — smartrouter_latest_block{spec="BTCS"}=329549

All three testnet entries booted cleanly, their chain-id expected_value (set by convention rather than live-verified elsewhere in the pipeline) is confirmed correct against the live upstream, and the GET_BLOCKNUM directive tracked successfully. No method probe was run per Step 7 (boot + verification only).

Empirical block time (Step 8)

Recipe: bitcoind getblockcount → getblockhash(H)/getblockhash(H-1000) → getblock(hash).time, sampled over 1000 blocks (not 100) per the task's guidance, since Bitcoin's 10-minute target is retarget-enforced and noisy over short windows. Measured direct-to-upstream (not through the router).

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet (BTC) bitcoin-rpc.publicnode.com 617,562 600,000 +2.9% OK
testnet3 (BTCT) bitcoin-testnet-rpc.publicnode.com 25,393 600,000 -95.8% BLOCK_TIME_MISMATCH (testnet3)
testnet4 (BTCT4) bitcoin-testnet4.gateway.tatum.io 547,027 600,000 -8.8% OK
signet (BTCS) bitcoin-signet-rpc.publicnode.com 588,501 600,000 -1.9% OK

Testnet3 note (not automatically a spec defect — flagging for orchestrator judgment): the empirical 1000-block sample landed inside one of testnet3's well-known rapid-fire bursts produced by its 20-minute difficulty-reset rule (if no block is found within 20 minutes, difficulty drops to the network minimum, and miners briefly produce blocks every few seconds until difficulty re-adjusts). This is intentional, irregular chain behavior on Bitcoin's oldest and most degraded testnet — not a parse-directive or average_block_time defect in the spec. A different 1000-block window on testnet3 could show a very different empirical figure. Reporting as observed per the task's instruction; recommend the orchestrator treat this as an upstream/chain-behavior note rather than a required spec edit, though an explicit (looser or disabled) average_block_time tolerance override for BTCT specifically could be considered if this drift recurs across samples.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 9 — parallel reviewers (3 independent /review-spec passes)

Three fresh-context reviewers ran against the candidate btc.json with the Phase 8 probe report as input. Reports are distinct (md5-checked, no shared-path collision); no reviewer cited a line beyond the file's 1561 lines, so none reviewed stale state.

reviewer 1  TALLY: CRITICAL=4 MEDIUM=1 MINOR=2
reviewer 2  TALLY: CRITICAL=1 MEDIUM=2 MINOR=3
reviewer 3  TALLY: CRITICAL=2 MEDIUM=2 MINOR=0

Merged gaps (convergence across the three passes)

# gap severity raised by disposition
1 The 15 bb_* methods were added to the base jsonrpc collection rather than a dedicated add_on collection CRITICAL 3/3 REPORT-ONLY — auto-decided, see below
2 bb_getBlock / bb_getRawBlock use block_parsing: DEFAULT ["latest"] although they take the target block as positional arg 0 CRITICAL (r1, r3) / MEDIUM (r2) 3/3 FIX
3 bb_getFeeStats has the same block-parsing bug, plus deterministic: false on what is immutable per-block data CRITICAL (r1) / MEDIUM (r2, r3) 3/3 FIX
4 bb_getXPUB (and possibly bb_getBalanceHistory) compute-units look under-priced; no timeout_ms on the heavier new reads MEDIUM (r3) / MINOR (r1, r2) 3/3 fix only with concrete cost evidence, else report
5 Pre-existing: estimatesmartfee vs bb_getEstimateFee determinism inconsistency MEDIUM (r1) 1/3 pre-existing, report-only
6 Pre-existing: testnet3 empirical block-time drift MINOR (r2) 1/3 report-only (already auto-decided in Phase 8)

Gap 2/3 is corroborated by the file's own established convention: the native analogues getblock, getblockheader, getblockstats and getblockfilter all use PARSE_BY_ARG [0] — including getblock, whose arg 0 is a block hash. So the added Blockbook equivalents are inconsistent with their own neighbours, not merely with an external doc.

Auto-decision recorded at the gap-1 STOP-and-ask gate (conservative default)

Gap 1 is reported, not applied. All three reviewers are right that an add-on collection is the usual home for a vendor-gated surface — but moving the 15 methods there would invert this PR's stated purpose. Per the PR body (MAG-4824), they were listed as ordinary base methods deliberately, so that a provider's UnlistedMethodRefused becomes a retryable refusal that the router can re-try on a peer (paired with Magma-Devs/smart-router#632); behind an add_on, only providers declaring that add-on would serve them at all. The change would also alter the resolved surface of the 13 specs that import BTC (BTCT, BTCT4, BTCS, BCH, BCHT, LTC, LTCT, DOGE, DOGET, ZCASH, ZCASHT, DASH, DASHT). Restructuring a deliberate, documented design decision is beyond what an unattended fix pass should decide, so it is escalated for a human call rather than auto-applied.

Reviewer 1 — full report

btc.json Spec Review — Gap Report (Reviewer 1)

Scope: PR #202 (feat/btc-blockbook-methods, MAG-4824). Per git diff origin/main...HEAD -- btc.json, the only change vs main is the addition of 15 Blockbook bb_* methods to the BTC base jsonrpc collection (add_on: ""), plus an explicit timeout_ms: 10000 on bb_sendTransaction (already landed in a follow-up commit). Review is weighted toward these 15 added entries and anything they break; pre-existing issues are labelled as such and excluded from this PR's required fix scope.

Phase 0 removed-field guard: check_unused_fields.sh btc.json → RESULT: PASS. check_internal_paths.sh btc.json → RESULT: PASS. No cleanup findings.

docs/btc/METHOD_PROBE_REPORT.md was read and incorporated (see Pre-existing / Probe-context section below).


CRITICAL

1. The 15 bb_* methods were merged into the mandatory base collection instead of a dedicated add_on collection

btc.json's BTC spec already has a precedent for exactly this situation: the 8 Blockdaemon-specific bd_* methods live in their own collection with "collection_data": {"api_interface": "jsonrpc", "add_on": "blockdaemon", ...} (btc.json ~853-1012), kept separate from the base add_on: "" jsonrpc collection specifically because not every BTC provider runs a Blockdaemon-backed node. SPEC_GUIDE.md Step 3.1a states the same rule generically: "You want a chain-specific add-on → DEFINE a NEW collection with unique add_on" (e.g. Arbitrum's arbtrace).

Blockbook is exactly this kind of vendor-specific surface — the probe report confirms it is a QuickNode add-on, and empirically 0/2 configured upstreams (publicnode, Tatum — both plain bitcoind) support any of the 14 non-stateful bb_* methods; all returned -32601 Method not found. Despite this, the PR added all 15 bb_* APIs to the base add_on: "" collection (diff hunk at former btc.json:565+), which every BTC provider is expected to serve as part of the mandatory jsonrpc surface — the same tier as getblockhash/getblock/etc.

This is not a "disable because the probe failed" finding (free-tier limitation is explicitly out of scope per review instructions) — it is that the collection placement itself doesn't match this repo's own established pattern for vendor-gated method sets. The fix is structural, not a disable: move the 15 bb_* API entries into a new api_collections entry with "collection_data": {"api_interface": "jsonrpc", "internal_path": "", "type": "POST", "add_on": "blockbook"}, mirroring the existing blockdaemon block. This lets Blockbook-capable providers (QuickNode) opt in and stake for the add-on without making it part of every generic-bitcoind provider's required surface.

Impact if unfixed: every BTC provider that stakes for the base jsonrpc collection is nominally expected to support 15 APIs that the overwhelming majority of real-world BTC nodes (plain bitcoind) cannot serve, since Blockbook is a non-standard add-on index, not a bitcoind capability.


2. bb_getBlock — wrong block_parsing: DEFAULT/"latest" instead of PARSE_BY_ARG

bb_getBlock's required first parameter is the block hash or height (confirmed via QuickNode docs: https://www.quicknode.com/docs/bitcoin/bb_getBlock — "block (string, position 0, REQUIRED) - The block hash or block height"). The PR models it as:

"block_parsing": { "parser_arg": ["latest"], "parser_func": "DEFAULT" }

i.e. "no block parameter, implicitly latest" — but the method is explicitly parameterized by an arbitrary historical block. This is the exact same shape as the pre-existing native getblock (btc.json line 44, not touched by this PR), which correctly uses:

"block_parsing": { "parser_arg": ["0"], "parser_func": "PARSE_BY_ARG" },
"parsers": [{ "parse_path": ".params.[0]", "parse_type": "BLOCK_HASH" }]

Since bb_getBlock's param accepts height-or-hash (not hash-only), the closer analog is getblockstats (btc.json ~190-214), which accepts the same height-or-hash ambiguity and carries both BLOCK_HASH and BLOCK_LATEST parsers:

"parsers": [
  { "parse_path": ".params.[0]", "parse_type": "BLOCK_HASH" },
  { "parse_path": ".params.[0]", "parse_type": "BLOCK_LATEST" }
]

Recommended fix: change bb_getBlock.block_parsing to PARSE_BY_ARG / ["0"] and add the parsers array above.

Impact if unfixed: the router treats every bb_getBlock call as a request for the latest block regardless of which historical block/hash was actually requested — this corrupts per-block caching keys, finalized/archival-distance accounting, and historical-block routing (a request for block 500000 could be served/cached as if it were the current tip).


3. bb_getRawBlock — same bug as #2

Same required param shape as bb_getBlock (block hash or height; confirmed via https://www.quicknode.com/docs/bitcoin/bb_getrawblock — "block_id (string, REQUIRED): The block height or block hash to query"), and the PR gives it the identical DEFAULT/"latest" block_parsing. Same fix: PARSE_BY_ARG / ["0"] with parsers: [BLOCK_HASH, BLOCK_LATEST], mirroring getblockstats. Same impact as #2 (raw block data cached/served against the wrong block identity).


4. bb_getFeeStats — same block_parsing bug, plus wrong deterministic flag

bb_getFeeStats's required parameter is also a block height or hash (confirmed via https://www.quicknode.com/docs/bitcoin/bb_getfeestats — "block_id (string, REQUIRED): The block height or block hash to query"), returning txCount/totalFeesSat/averageFeePerKb/decilesFeePerKb for that specific, already-mined block. The PR gives it DEFAULT/"latest" block_parsing — same defect and same fix as #2/#3 (PARSE_BY_ARG / ["0"], parsers: [BLOCK_HASH, BLOCK_LATEST]).

Compounding this, category.deterministic is set to false. Fee statistics for a block that has already been mined are fixed forever (same input block → same output, exactly like bb_getBlock/bb_getRawBlock, which this PR correctly marks deterministic: true). It should be true, not false.

Impact if unfixed: beyond the caching/routing corruption shared with #2/#3, marking genuinely immutable per-block data as non-deterministic removes it from cross-provider data-reliability verification, letting a misbehaving provider return incorrect fee-stats for a historical block without being caught by consensus checks.


MEDIUM

5. Pre-existing inconsistency surfaced by this PR: estimatesmartfee vs. bb_getEstimateFee determinism

Not introduced by this PR and out of its required fix scope, but worth recording since the new method makes the inconsistency visible: the pre-existing native estimatesmartfee (btc.json, untouched) is marked category.deterministic: true, even though it is a live mempool/fee-market estimate that varies run-to-run and node-to-node. The newly added bb_getEstimateFee — semantically the same kind of operation — correctly marks deterministic: false. Recommend a follow-up (separate ticket) to correct estimatesmartfee's flag for consistency; not blocking for this PR.


MINOR

6. Compute-unit pricing on two new methods looks low relative to their actual cost

  • bb_getXPUB (compute_units: 20) performs gap-limited address derivation and UTXO/balance aggregation across potentially many derived addresses for an xpub — closer to the guide's "Complex queries" bucket (60-100) than a single simple lookup.
  • bb_getBalanceHistory (compute_units: 20) aggregates transaction history across a timestamp range for an address/xpub — also closer to the "Complex queries" bucket than a flat 20.

Not blocking; flagging for consideration since both are priced identically to a single-block/single-tx lookup like bb_getBlockHash/bb_getTx.

7. No timeout_ms on the heavier new read methods

bb_sendTransaction got an explicit timeout_ms: 10000 in the latest commit. bb_getBlock (full block + all transactions, paginated) and bb_getBalanceHistory (full historical aggregation) can return large/slow payloads and have no explicit timeout_ms, relying on router defaults. The spec guide calls out explicit timeouts for "long-running ops." Suggestion only, not blocking.


Confirmed correct / no action needed

  • bb_getBlockHash: PARSE_BY_ARG ["0"] + parsers: [BLOCK_LATEST] correctly mirrors native getblockhash — QuickNode docs confirm the param is a height-only string (no hash form), so BLOCK_HASH is correctly omitted. No bug.
  • bb_getTx / bb_getTxSpecific: take only txid (confirmed via QuickNode docs) with no block-identifying parameter, so DEFAULT/"latest" block_parsing is correct and consistent with how this spec already treats decoderawtransaction/validateaddress/etc.
  • bb_getBalanceHistory: from/to are Unix timestamps, not block heights (confirmed via QuickNode docs) — DEFAULT block_parsing is correct.
  • bb_sendTransaction: category.stateful: 1 + hanging_api: true + compute_units: 10 exactly mirrors the pre-existing sendrawtransaction/submitpackage pattern in this same collection — not a bug. The explicit timeout_ms: 10000 added in the follow-up commit is a reasonable value, consistent with other stateful-broadcast timeouts across the repo (e.g. lit.json, eos.json, casper.json all use 10000ms for the same category).
  • Testnet inheritance (BTCT/BTCT4/BTCS): each defines an empty apis: [] jsonrpc collection while importing BTC. Per the model's merge semantics (APIs differentiated by Name; an empty child array removes nothing), all 15 new bb_* methods — and the base collection generally — are automatically inherited by all three testnets with no further action required.
  • Governance/envelope shape: canonical { "proposal": { "specs": [...] } }, no title/description/deposit, no removed governance fields — correct per the current model; not flagged.

Pre-existing / probe-context notes (not required for this PR)

These come from docs/btc/METHOD_PROBE_REPORT.md and are not caused by this PR's diff; recorded for completeness per the review brief, labelled pre-existing so the fix pass does not widen scope:

  • 14/14 non-stateful bb_* methods returned -32601 on both configured upstreams (publicnode, Tatum) because neither is Blockbook-enabled. Per the review's free-tier rule this is not evidence to disable any method — it only reinforces Finding Disable data reliability feature #1 (these methods belong behind an opt-in add_on, not that they should be removed).
  • bb_sendTransaction was correctly SKIPped as stateful (would broadcast).
  • rest interface and blockdaemon add-on remain NOT_TESTABLE (key-gated: Blockdaemon Ubiquity HTTP 401, bd_getbalance → -32601 on generic bitcoind) — unrelated to this PR, no action.
  • getmemoryinfo and gettxoutsetinfo (native, untouched) FAIL on both configured upstreams due to provider-tier RPC policy restrictions (-32701/-32601/HTTP 500), not Blockbook-related — pre-existing, non-blocking.
  • BLOCK_TIME_MISMATCH on BTCT (testnet3, empirical drift -95.8%): the 1000-block sample window landed inside one of testnet3's known 20-minute-difficulty-reset rapid-fire bursts — a chain-behavior artifact of Bitcoin's oldest, most degraded testnet, not a parse-directive or average_block_time defect. Recorded for awareness; not required for this PR, and average_block_time was not touched by this diff.

Summary

  • Endpoints reviewed: all 15 newly-added bb_* APIs in detail (cross-referenced against QuickNode's Blockbook JSON-RPC documentation per method), plus the existing 49-method base collection and the blockdaemon/rest collections for inheritance/placement context.
  • Gaps found: 4 CRITICAL, 1 MEDIUM, 2 MINOR.
  • Readiness: Not ready to merge as-is. The three block_parsing defects (bb_getBlock, bb_getRawBlock, bb_getFeeStats) are silent data-correctness bugs that will misclassify historical-block requests as "latest" once a Blockbook-enabled provider actually serves these methods. The collection-placement finding (Disable data reliability feature #1) is an architectural decision this PR should revisit before merge, following this repo's own blockdaemon precedent. None of the findings require touching pre-existing, untouched parts of the spec beyond the single estimatesmartfee consistency note, which is optional and out of scope.
Reviewer 2 — full report

BTC Spec Review — Gap Report (Reviewer 2)

Scope. This review targets btc.json on branch feat/btc-blockbook-methods (PR #202,
ticket MAG-4824). git diff origin/main...HEAD -- btc.json shows the ONLY change is the
addition of 15 Blockbook bb_* methods to the base (add_on: "") jsonrpc collection of
the BTC spec, plus an explicit timeout_ms: 10000 on bb_sendTransaction. The review is
weighted toward those 15 methods and what they break; findings against untouched,
long-established entries are labelled pre-existing and are not blocking for this PR.

Inputs used.

  • mode= (API docs) — not provided this run. API completeness (Phase 3) and parameter-shape
    verification for the new bb_* methods could not be cross-checked against an authoritative
    Blockbook/QuickNode OpenAPI reference; findings about per-parameter semantics below are
    flagged with the confidence level they warrant.
  • OPEN= (credentials) — not provided this run; no live calls were made directly by this
    review. docs/btc/METHOD_PROBE_REPORT.md (dated 2026-11-05T13:38:37Z) was read and its
    results are folded in below.
  • Phase 0 removed-field guard: check_unused_fields.sh btc.json → PASS (no removed
    fields). check_internal_paths.sh btc.json → PASS (0 warnings, no errors). No cleanup
    findings from Phase 0.

Probe findings incorporated

Per METHOD_PROBE_REPORT.md: all 14 non-stateful bb_* methods returned -32601 Method not found identically on both configured keyless public upstreams (publicnode, Tatum), because
neither is Blockbook-enabled — Blockbook is a QuickNode add-on surface. bb_sendTransaction
was SKIPped as stateful. Per the skill's free-tier rule, this -32601 result is not
treated as evidence to disable the methods (no positive evidence of removal/unsupported
status was found). It is, however, directly relevant to Finding 1 below: it empirically
confirms that the two standard non-Blockbook upstreams this project tests against cannot
serve any of these 15 new base-collection methods.


Findings

1. [CRITICAL] 15 new bb_* methods were added to the base collection instead of a dedicated add-on collection

Evidence: btc.json lines 570–801 place all 15 bb_* APIs inside the BTC spec's main
jsonrpc collection (collection_data.add_on: "", lines 15–19), alongside native bitcoind
methods like getblock/getrawtransaction. Contrast this with the existing blockdaemon
methods in the very same file (lines 853–1008): those 8 bd_* methods are deliberately
isolated in their own collection_data.add_on: "blockdaemon" collection, with their own
enabled verification (lines 986–1005) that providers must pass to advertise the add-on.

Impact: Collections with add_on: "" are the base surface every provider staking for
BTC is expected to serve; add_on is exactly the mechanism this spec already uses to carve
out vendor-specific extension surfaces (see blockdaemon) that most providers cannot serve.
Blockbook is, per this PR's own ticket context and the probe report, "a QuickNode add-on
surface" — not something plain bitcoind/Allnodes/Tatum-style nodes expose. By merging it into
the base collection, every current and future BTC provider (the overwhelming majority of
which run plain full nodes, not QuickNode's Blockbook-enabled service) is now nominally
expected to serve 15 methods they cannot. The probe empirically confirms this: 14/14
non-stateful bb_* methods returned -32601 on both of the project's two standard public
upstreams. This is not a free-tier artifact (per the skill's rule) — it is architecture: these
upstreams are not Blockbook-backed at all, mirroring the overwhelming majority of the live BTC
provider population. Left as-is, this risks QoS/relay-success degradation for the entire BTC
provider set once this spec version is adopted, for a capability that, by this repo's own
established convention, belongs behind an add-on gate.

This also propagates to BTCT, BTCT4, and BTCS: their jsonrpc collections define
"apis": [] (lines 1391, 1452, 1513), which — per the merge-by-Name inheritance rule —
inherits 100% of BTC's base-collection APis, including all 15 new bb_* methods. The
blast radius is all four specs in this file, not just mainnet.

Fix: Move the 15 bb_* APIs (with their existing block_parsing/category/
compute_units) into a new collection with collection_data.add_on: "blockbook" (jsonrpc,
type: "POST"), mirroring the blockdaemon collection's structure, and add an analogous
enabled-style verification using a cheap bb_* call so providers can positively advertise
support.


2. [MEDIUM] bb_getBlock / bb_getRawBlock block_parsing likely wrong — treated as "latest" when they take an explicit block reference

Evidence: bb_getBlock (lines 600–613) and bb_getRawBlock (lines 681–694) both use
"parser_func": "DEFAULT" / "parser_arg": ["latest"]. Blockbook's getBlock/raw-block
calls take a block hash-or-height as their first parameter (this is the whole point of the
method — "get this block"), exactly analogous to this same spec's native getblock (lines
44–63) and getblockstats (lines 190–214), both of which correctly use
"parser_func": "PARSE_BY_ARG" at position 0, with parsers entries disambiguating
BLOCK_HASH vs BLOCK_LATEST (see getblockstats's two-entry parsers array, lines
204–213, which is the established in-spec pattern for a hash-or-height-or-latest first
argument).

Impact: Tagging a historical/specific-block Blockbook lookup as pertaining to "latest"
breaks block attribution for Lava's data-reliability cross-provider consistency checks on
these two methods — a request for block 500000 gets associated with whatever the "latest"
block happens to be at request time, not the block actually being asked about. deterministic: true is set correctly on both APIs (right in isolation — the underlying data for a specific
block never changes), but it's undermined by the wrong block-parsing linkage. This should
mirror getblock/getblockstats's PARSE_BY_ARG + BLOCK_HASH/BLOCK_LATEST parser
pattern. No API docs were supplied this run (mode= empty) to pin down Blockbook's exact
parameter position with full certainty, but the method semantics (and the sibling native
methods in this same file) strongly support this read.


3. [MEDIUM] bb_getFeeStats may be block-keyed and immutable, not "latest"/non-deterministic

Evidence: bb_getFeeStats (lines 651–664) is configured block_parsing: DEFAULT /
category.deterministic: false. Blockbook's fee-stats endpoint is conventionally keyed by a
specific mined block (fee statistics for that block), which — like getblockstats — would
never change once the block is mined, making it a candidate for PARSE_BY_ARG +
deterministic: true rather than DEFAULT + false.

Impact: If confirmed, the same data-reliability block-attribution problem as Finding 2
applies, plus an avoidably-conservative deterministic: false that forfeits cross-provider
verification for an otherwise-verifiable, immutable result. Flagging at MEDIUM rather than
higher confidence because no API documentation (mode=) was provided this run to confirm the
exact parameter contract — recommend verifying against QuickNode's Blockbook JSON-RPC
reference before changing.


4. [MINOR] bb_getXPUB (and possibly bb_getBalanceHistory) may be underpriced / missing a timeout

Evidence: bb_getXPUB (lines 770–784) and bb_getBalanceHistory (lines 584–598) are both
priced at compute_units: 20 with no timeout_ms, the same tier as simple block/tx lookups.
Contrast with gettxoutsetinfo in this same collection (lines 410–425), a known-heavy full-scan
op, which is priced at compute_units: 500 with an explicit timeout_ms: 180000.

Impact: Blockbook's xpub endpoint is documented to walk the full BIP32 gap-limit address
derivation for the xpub and aggregate balance/UTXO/tx data across all of them — a
qualitatively heavier operation than a single-address or single-tx lookup, closer to this
spec's guide's "Complex queries" (60-100 CU) or "Heavy ops" tier than "Block/transaction
queries" (20 CU). bb_getBalanceHistory has a similar (if milder) multi-period aggregation
shape. Neither probe nor live testing could benchmark actual response times here (both
upstreams lack Blockbook, per the probe), so this is a recommendation rather than a confirmed
defect: benchmark CU/timeout once a Blockbook-enabled upstream is available, per Step 4.4 of
the spec guide.


5. [MINOR] CU inconsistency between bb_getTx/bb_getTxSpecific and the functionally similar native getrawtransaction

Evidence: bb_getTx (line 733) and bb_getTxSpecific (line 748) are both priced at
compute_units: 20, while the native getrawtransaction (line 388), which returns
substantially the same data (and which bb_getTxSpecific in particular is documented to
mirror — "transaction as returned by the backend"), is priced at compute_units: 10.

Impact: Likely intentional (Blockbook's indexed enrichment — address balances, spent/
unspent status per output, etc. — costs more to compute/serve than a raw bitcoind RPC passthrough),
but it's worth a one-line rationale in the PR description so a future reviewer doesn't have to
re-derive it. Not blocking.


6. [MINOR, pre-existing — informational only] Testnet3 empirical block time drift

Evidence: Probe Step 8 measured testnet3's (BTCT) empirical block time at ~25.4s over a
1000-block sample vs. the spec's average_block_time: 600000ms (-95.8% drift), flagged
BLOCK_TIME_MISMATCH. The probe report itself attributes this to testnet3's well-known
20-minute difficulty-reset rule producing rapid-fire block bursts, and explicitly recommends
treating it as upstream/chain-behavior noise rather than a required spec edit — a different
1000-block window could read very differently.

Impact: None attributable to this PR — average_block_time for BTCT/BTC was not
touched by this diff, and this parameter is shared with the untouched mainnet/testnet4/signet
entries that measured within normal drift (+2.9%, -8.8%, -1.9%). Noted here only so it isn't
silently dropped, per the pre-existing-labelling instruction; no action requested in this PR's
scope.


Summary

  • Endpoints reviewed: all 49 jsonrpc-collection APIs in BTC (34 pre-existing + 15 new
    bb_*), plus the 8 blockdaemon add-on APIs and the rest collections, cross-referenced
    against METHOD_PROBE_REPORT.md. Deepest scrutiny applied to the 15 new bb_* methods and
    the bb_sendTransaction timeout change, per this PR's actual diff.
  • Gaps found: 1 CRITICAL, 2 MEDIUM, 3 MINOR (one of the MINORs is a pre-existing,
    non-blocking informational note unrelated to this diff).
  • Readiness: Not ready to merge as-is. The CRITICAL finding (bb_* methods belong in a
    blockbook add-on collection, not the base collection) is a structural placement issue that
    the probe data directly corroborates (14/14 -32601 on both standard upstreams) and should
    be fixed before this PR ships, since it changes what every BTC/BTCT/BTCT4/BTCS
    provider is nominally required to serve. The two MEDIUM block-parsing/determinism findings
    (bb_getBlock/bb_getRawBlock, bb_getFeeStats) should be verified against Blockbook/
    QuickNode's JSON-RPC reference and fixed before merge; the MINOR CU/timeout notes are
    recommendations for follow-up benchmarking once a Blockbook-enabled upstream is available.
Reviewer 3 — full report

BTC Spec Review — Gap Report (Reviewer 3)

Scope: PR #202 (feat/btc-blockbook-methods, MAG-4824), reviewed against main. The PR's only
change is the addition of 15 Blockbook bb_* methods to the BTC base jsonrpc collection
(add_on: ""), plus an explicit timeout_ms on bb_sendTransaction. These are inherited
automatically by BTCT, BTCT4, and BTCS (all three import BTC and define the matching
jsonrpc/add_on:"" collection with an empty apis: [], which merges rather than overrides).

Phase 0 guard: check_unused_fields.sh btc.json → RESULT: PASS (no removed fields). No
cleanup findings.

Probe context incorporated: per docs/btc/METHOD_PROBE_REPORT.md, all 14 non-stateful bb_*
methods returned -32601 on both configured free-tier upstreams (publicnode, Tatum) because
neither is Blockbook-enabled; bb_sendTransaction was SKIPped as stateful. Per the task's
free-tier rule this alone is not evidence to disable the methods — but it is corroborating
evidence for Finding 1 below, which rests on a structural/placement argument, not the probe
result itself. getmemoryinfo/gettxoutsetinfo FAILs and the testnet3 block-time sampling note
in the probe report are pre-existing and unrelated to this PR's diff; not re-reported here.


Findings

1. CRITICAL — the 15 bb_* methods belong in a dedicated add_on collection, not the base collection

File: btc.json, BTC spec, api_collections[0] (collection_data.add_on: ""), all 15 new
bb_* entries (lines added by the diff, ~568-800 in the current file).

Blockbook is a QuickNode marketplace add-on surface, not a capability of a standard bitcoind
node — confirmed by the probe (-32601 on two independent plain-bitcoind-backed upstreams) and,
more importantly, by this same spec file's own established precedent: the blockdaemon bd_*
methods (8 methods) are already segregated into their own
{"api_interface":"jsonrpc","add_on":"blockdaemon"} collection, complete with an enabled-style
verification (bd_estimatefee probe) so that only providers who actually support Blockdaemon
advertise the add-on. The PR adds the structurally identical "third-party-indexer surface on top
of node RPC" capability (Blockbook) but puts it in the base collection instead of mirroring
that pattern.

The base jsonrpc (add_on: "") collection is mandatory for every provider staking BTC,
BTCT, BTCT4, or BTCS — there is no opt-out the way there is for an add_on. Since no generic
bitcoind backend implements bb_* (it requires a dedicated Blockbook indexer instance, a
QuickNode-marketplace-only product), every provider that is not specifically running
Blockbook-enabled infrastructure is now contractually on the hook for 15 methods they cannot
serve, which will depress their QoS/reliability scoring on the entire mandatory base collection —
for mainnet and, via inheritance, for all three testnets.

Fix: move the 15 bb_* APIs (bb_getAddress, bb_getBalanceHistory, bb_getBlock,
bb_getBlockHash, bb_getEstimateFee, bb_getFeeStats, bb_getMultiTickers, bb_getRawBlock,
bb_getTickers, bb_getTickersList, bb_getTx, bb_getTxSpecific, bb_getUTXOs, bb_getXPUB,
bb_sendTransaction) out of api_collections[0] into a new
{"api_interface":"jsonrpc","internal_path":"","type":"POST","add_on":"blockbook"} collection,
and add a Blockbook-presence enabled verification analogous to the blockdaemon collection's
(e.g. probe bb_getBlockHash or bb_getTickersList with expected_value: "*").


2. CRITICAL — bb_getBlock / bb_getRawBlock use DEFAULT block parsing despite taking the target block as a positional argument

File: btc.json, new bb_getBlock and bb_getRawBlock entries.

Both are configured as:

"block_parsing": { "parser_arg": ["latest"], "parser_func": "DEFAULT" }

and both are marked "deterministic": true.

Per QuickNode's Blockbook JSON-RPC docs, bb_getBlock takes (block_hash_or_height, [options]) —
the block identifier is positional argument 0 (REST equivalent GET /api/v2/block/{blockHash}).
bb_getRawBlock is the raw-hex sibling of the same call, wrapping
GET /api/v2/rawblock/{block_id} — again, the block identifier is argument 0.

This is exactly the shape of this file's own existing native siblings getblock and
getblockfilter, both of which correctly use:

"block_parsing": { "parser_arg": ["0"], "parser_func": "PARSE_BY_ARG" },
"parsers": [{ "parse_path": ".params.[0]", "parse_type": "BLOCK_HASH" }]

The new bb_getBlock/bb_getRawBlock entries copy neither convention. Tagging a
by-specific-block query as DEFAULT/"latest" means the router attributes a request for an
arbitrary historical block to "latest" for finality/data-reliability bookkeeping — the exact
"Incorrect Block Parsing" pitfall called out in the spec guide's Common Pitfalls #2. Combined with
deterministic: true, this is also a correctness risk for reliability cross-checks: two providers
answering the same historical-block request would be compared/finalized as if both answered a
"latest" request.

Fix: for both APIs, set

"block_parsing": { "parser_arg": ["0"], "parser_func": "PARSE_BY_ARG" },
"parsers": [{ "parse_path": ".params.[0]", "parse_type": "BLOCK_HASH" }]

matching getblock's existing configuration in this same file.


3. MEDIUM — bb_getFeeStats likely has the same block-parsing bug as Finding 2, plus a possibly-wrong determinism flag

File: btc.json, new bb_getFeeStats entry.

QuickNode's Blockbook REST mapping is GET /api/v2/feestats/{block_id} → bb_getFeeStats, i.e.
the block height/hash is also a positional argument, the same shape as bb_getBlock. The PR
configures it as block_parsing: DEFAULT / "deterministic": false. If (as the REST mapping
suggests) the argument is a specific sealed block, fee stats for that block are stable and the API
should use PARSE_BY_ARG position 0 with deterministic: true, mirroring Finding 2. Confidence
is lower than Finding 2 only because QuickNode's per-chain docs for the exact JSON-RPC parameter
contract weren't directly reachable during this review (only the REST mapping was confirmed) —
worth a quick live-param check before merge, but the REST-mapping evidence points the same
direction as the bb_getBlock/bb_getRawBlock bug.

Fix (pending confirmation): "block_parsing": {"parser_arg": ["0"], "parser_func": "PARSE_BY_ARG"},
re-evaluate deterministic: true.


4. MEDIUM — bb_getXPUB compute_units likely under-priced relative to its actual cost

File: btc.json, new bb_getXPUB entry (compute_units: 20).

Blockbook's xpub endpoint derives and scans a configurable gap-limit worth of child addresses per
xpub (far more than the single address Blockbook has to look up for bb_getAddress/bb_getUTXOs,
which share the same 20 CU price). The spec guide's own CU table treats "full scan"-style
operations as heavy ops (500-5000 CU) distinct from simple address/tx reads (20 CU per Step 3.2 /
4.4). Pricing bb_getXPUB identically to a single-address lookup likely under-recovers the actual
provider cost. Recommend benchmarking against a live Blockbook-enabled endpoint before merge; if
unavailable, a conservative bump (e.g. 60-100 CU, in line with the guide's "complex query" tier)
is more defensible than reusing the flat single-address price.


Not flagged (settled / out of scope per task brief)

  • Absence of title/description/top-level deposit, and of the nine removed governance
    fields — correct per the current model; not findings.
  • blocks_in_finalization_proof: 3 on BTC/BTCT/BTCT4/BTCS — correct for PoW probabilistic
    finality; pre-existing and untouched by this PR.
  • No bb_* method was flagged for disabling on the basis of the probe's -32601 results — per
    the free-tier rule, that alone is not evidence of non-support. Finding 1 above is a placement
    argument (base vs. add-on collection), not a "disable this" argument.
  • getmemoryinfo / gettxoutsetinfo provider-policy FAILs and the testnet3 block-time sampling
    anomaly from the probe report are pre-existing, unrelated to this PR's diff, and not re-reported.
  • No extra_compute_units, category.local, or category.subscription additions proposed or
    flagged; bb_* carries no FUNCTION_TAG_SUBSCRIBE directive, so none are subscriptions.
  • JSON is valid (jq empty btc.json passes); no duplicate API names in the modified collection
    (49 unique names); Phase 0 removed-field guard passes clean.

Summary

  • Endpoints reviewed: all 49 APIs in BTC's base jsonrpc collection (34 pre-existing +
    15 new bb_*), weighted toward the 15 added by this PR; testnet inheritance (BTCT, BTCT4,
    BTCS) checked for propagation of the same issues.
  • Gaps found: 2 CRITICAL, 2 MEDIUM, 0 MINOR.
  • Readiness: not ready to merge as-is. Finding 1 (collection placement) is a structural issue
    that affects every provider staking BTC/BTCT/BTCT4/BTCS, not just an edge case — it should be
    fixed before merge. Finding 2 (block parsing on bb_getBlock/bb_getRawBlock) is a correctness
    bug that undermines finality/data-reliability tracking for those two methods. Findings 3-4 are
    lower-confidence/lower-impact and can be addressed in the same pass or as fast-follow fixes.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 10 — synthesize gaps + fix pass (+ Phase 10b smoke re-probe)

Consolidation: 5 critical, 2 medium; 16 disable-suggestions stripped. All 16 stripped rows are free-tier/gateway artifacts (14 bb_* -32601 on non-Blockbook upstreams, plus the pre-existing getmemoryinfo/gettxoutsetinfo node-policy blocks) — none of the three reviewers had actually proposed a disable on that basis, so nothing was struck from their findings. Nothing is disabled in the spec; <!-- disabled-count: 0 --> in the PR body is still accurate (re-verified by check_disabled_count.sh), so no Disabled-API Justifications ledger is required.

Fixes applied (4 rows, all inside the bb_* lines this PR added)

# Severity Change Evidence
1 CRITICAL bb_getBlock.block_parsing: DEFAULT ["latest"] → PARSE_BY_ARG ["0"], plus a parsers array (BLOCK_HASH, BLOCK_LATEST on .params.[0]) QuickNode: arg 0 = block (string, REQUIRED) "block hash or block height"
2 CRITICAL bb_getRawBlock — identical change QuickNode: arg 0 = block_id, "block height or block hash to query"
3 CRITICAL bb_getFeeStats — identical change QuickNode: arg 0 = block_id, "block height or block hash to query"
4 CRITICAL bb_getFeeStats.category.deterministic: false → true per-block fee stats are immutable once the block is final — same reasoning as bb_getBlock/bb_getRawBlock and the in-file getblockstats

All three methods now mirror the file's own established idiom for a method whose positional arg 0 may be a hash or a height: getblockstats carries exactly this block_parsing + two-entry parsers shape. (The orchestrator verified that precedent directly in btc.json rather than taking it from the reviewers, and confirmed parsers is a real, widely-used key across the catalog.) bb_getBlockHash needed no change — it already matched its native analogue getblockhash exactly.

Diff is surgical: 1 file changed, 40 insertions(+), 10 deletions(-), no re-indentation of untouched regions, trailing-byte convention (no trailing newline) preserved.

Phase 10a — post-fix static gates

gate result
check_method_schema PASS — 75/75 rows ok, no FAIL
check_unused_fields PASS (no removed fields — none of the 15 banned fields introduced)
check_hanging_api --base origin/main PASS — bb_sendTransaction ok (cu=10, timeout_ms=10000 ≥ 1000ms implied)
check_stateful --base origin/main PASS — no FAIL, no advisory rows
jq valid

Three hanging_api-without-timeout_ms INFO rows (sendrawtransaction, submitpackage, REST /tx/send) are pre-existing — the base on main fails them identically, so they are advisory and out of this PR's scope.

Phase 10b — smoke re-probe against the fixed spec

SMOKE: OK — no regressions.

  • PARSE: OK on GET_BLOCKNUM (smartrouter_latest_block{spec="BTC"}=974676, both endpoint gauges agree, no parse-signature lines). GET_BLOCK_BY_NUM remains NOT_EXERCISED — unchanged from the Phase 8 baseline and router-side, not spec-side (block-hash polling (fork detection) … reason=off-operator-choice).
  • VERIFY: OK — chain-id verified on both providers (chain="main").
  • ADDONS: 0 tested-ok / 0 failed / 2 not-testable (blockdaemon, rest carried forward unchanged).
  • The router booted cleanly against the edited spec and bb_getBlock reached craft/dispatch with no CraftChainMessage or parser error before the upstream's clean -32601 — which is the meaningful signal here: the new PARSE_BY_ARG + parsers config is syntactically valid and accepted by the router's spec resolution. The -32601 itself is the unchanged non-Blockbook-upstream baseline.
  • No non-benign warn/error/fatal/panic lines in the probe window; no 429s; bb_sendTransaction correctly skipped as stateful.

Escalated for a human call — NOT auto-applied

All three reviewers independently flagged as CRITICAL that the 15 bb_* methods belong in a dedicated add_on collection rather than the base one, citing the file's own blockdaemon collection as precedent. This was deliberately not applied: per MAG-4824 the base placement is the point of the change — it turns a provider's UnlistedMethodRefused into a retryable refusal the router can retry on a peer (paired with smart-router#632), whereas behind an add_on only providers declaring it would serve the methods at all, and the resolved surface of the 13 specs importing BTC would change. Reversing a deliberate, documented design decision is not something an unattended fix pass should decide. A reviewer should confirm the base-collection placement is intended.

Also report-only: the pre-existing estimatesmartfee vs bb_getEstimateFee determinism inconsistency (untouched by this PR); bb_getXPUB compute-units (no concrete evidence it is outside its semantic band — flagged for benchmarking on a Blockbook-enabled node); the testnet3 block-time drift and the two NOT_TESTABLE surfaces (both auto-decided in Phase 8).

The fix is left uncommitted in the working tree on feat/btc-blockbook-methods for the workflow's commit step; no git state was changed by this run.

Full fix list (docs/btc/FIX_LIST.md)

btc.json Fix List — PR #202 (feat/btc-blockbook-methods, MAG-4824)

Consolidated from SPEC_REVIEW_GAPS_parallel_1.md, _parallel_2.md, _parallel_3.md, and
METHOD_PROBE_REPORT.md. Deduplicated by (gap_title, evidence_line_number); MINOR-only gaps
dropped. Severity shown is the max severity any reviewer assigned to the gap.

Scope reminder: the PR's only diff vs main is the 15 bb_* entries added to
.proposal.specs[0].api_collections[0] (jsonrpc, add_on: "") — line range ~568-801 in the
current btc.json — plus bb_sendTransaction.timeout_ms. All fixes below stay inside those
added lines; no pre-existing/untouched entry is modified.

Disable-suggestion filter applied: 16 probe FAILs stripped (14/14 non-stateful bb_*
-32601 FAILs on publicnode/Tatum — neither upstream is Blockbook-enabled — plus the 2
pre-existing base-collection FAILs getmemoryinfo/gettxoutsetinfo, which fail on both
upstreams due to provider-tier RPC-policy restrictions, not Blockbook). None of the three
reviewers actually proposed disabling/removing any method on this basis (each explicitly
called it out as insufficient evidence), so there was nothing to strike from their findings
text — the 16 are recorded here as artifacts correctly excluded from the fix list.


FIXES (apply)

All four rows below sit inside the PR-added bb_* block in
.proposal.specs[0].api_collections[0].apis[] (jsonrpc, add_on: ""). Converged across all
3 reviewers (block-parsing bug) and reviewer 1 (determinism flag); confirmed against QuickNode's
Blockbook JSON-RPC docs (fetched live during consolidation — all three methods take the target
block as a REQUIRED positional arg 0, string, height-or-hash). Target shape mirrors this file's
own existing getblockstats entry (btc.json lines 191-214), which is the established in-file
convention for a method whose arg 0 may be either a hash or a height (as opposed to plain
getblock, whose arg 0 is hash-only and which therefore carries only a single BLOCK_HASH
parser). Apply the exact string formatting shown — parser_arg entries are strings, not
numbers.

# Severity JSON path Current value Target value Evidence
1 CRITICAL apis[name="bb_getBlock"].block_parsing and .parsers (btc.json lines 600-613; block_parsing at 601-606, no parsers key present) "block_parsing": {"parser_arg": ["latest"], "parser_func": "DEFAULT"}, no parsers "block_parsing": {"parser_arg": ["0"], "parser_func": "PARSE_BY_ARG"}, add "parsers": [{"parse_path": ".params.[0]", "parse_type": "BLOCK_HASH"}, {"parse_path": ".params.[0]", "parse_type": "BLOCK_LATEST"}] QuickNode docs (fetched): bb_getBlock arg 0 = "block" (string, REQUIRED): The block hash or block height" — https://www.quicknode.com/docs/bitcoin/bb_getblock. In-file precedent: getblockstats (lines 191-214).
2 CRITICAL apis[name="bb_getRawBlock"].block_parsing and .parsers (btc.json lines 681-694; block_parsing at 682-687, no parsers key present) "block_parsing": {"parser_arg": ["latest"], "parser_func": "DEFAULT"}, no parsers "block_parsing": {"parser_arg": ["0"], "parser_func": "PARSE_BY_ARG"}, add "parsers": [{"parse_path": ".params.[0]", "parse_type": "BLOCK_HASH"}, {"parse_path": ".params.[0]", "parse_type": "BLOCK_LATEST"}] QuickNode docs (fetched): bb_getRawBlock arg 0 = "block_id" (string, REQUIRED): The block height or block hash to query" — https://www.quicknode.com/docs/bitcoin/bb_getrawblock. Same in-file precedent as row 1.
3 CRITICAL apis[name="bb_getFeeStats"].block_parsing and .parsers (btc.json lines 651-664; block_parsing at 652-657, no parsers key present) "block_parsing": {"parser_arg": ["latest"], "parser_func": "DEFAULT"}, no parsers "block_parsing": {"parser_arg": ["0"], "parser_func": "PARSE_BY_ARG"}, add "parsers": [{"parse_path": ".params.[0]", "parse_type": "BLOCK_HASH"}, {"parse_path": ".params.[0]", "parse_type": "BLOCK_LATEST"}] QuickNode docs (fetched): bb_getFeeStats arg 0 = "block_id" (string, REQUIRED): The block height or block hash to query" — https://www.quicknode.com/docs/bitcoin/bb_getfeestats. Same in-file precedent as row 1.
4 CRITICAL apis[name="bb_getFeeStats"].category.deterministic (btc.json line 661) "deterministic": false "deterministic": true Fee stats (txCount/totalFeesSat/averageFeePerKb/decilesFeePerKb) are keyed to a single already-mined block (same doc as row 3) and are fixed forever once that block is final — identical reasoning to why bb_getBlock/bb_getRawBlock and the in-file getblockstats (line 199) are all deterministic: true. Currently false wrongly excludes it from cross-provider data-reliability verification.

REPORT-ONLY (do not apply)

# Severity Topic Why it is not a fix item here
1 CRITICAL All 15 bb_* methods (btc.json lines ~568-801) should live in a dedicated add_on: "blockbook" jsonrpc collection, not the base add_on: "" collection — raised independently by all 3 reviewers, citing the existing blockdaemon collection (lines 853-1012) as in-file precedent. Orchestrator auto-decision, already made. Base placement is deliberate per MAG-4824: it makes a provider's UnlistedMethodRefused a retryable refusal the router can retry on a peer (paired with smart-router#632). Behind an add_on, only providers declaring it would serve these methods, changing the resolved surface of the 13 specs importing BTC. Escalated for a human call — do not apply.
2 MEDIUM Pre-existing estimatesmartfee (category.deterministic: true) is inconsistent with the new bb_getEstimateFee (deterministic: false) for the same kind of live mempool/fee-market estimate. Raised by reviewer 1 as MEDIUM. estimatesmartfee is untouched by this PR's diff (not one of the 15 added lines) — fixing it would widen scope beyond what PR #202 added. Worth a follow-up ticket, not this fix pass.
3 MEDIUM bb_getXPUB (compute_units: 20, btc.json line ~771-784) may be under-priced relative to a single-address lookup, since it derives/scans a gap-limit (default 20) set of child addresses per xpub. Raised by reviewer 3 as MEDIUM (reviewers 1/2 as MINOR). QuickNode docs (fetched) confirm the gap-limit derivation behavior but do not describe it as a heavy/expensive operation, and no comparable already-priced method in this file was found with solid, on-point justification (the only candidate raised, gettxoutsetinfo at 500 CU/180000ms timeout, is a full UTXO-set scan — not a close analog to a bounded 20-address derivation). Per the CU-pricing filter, this does not meet the "concrete evidence" bar required to land in FIXES; flagging for benchmarking once a Blockbook-enabled upstream is available, per reviewers' own recommendation.
4 — (MINOR per reviewers; carried forward per explicit instruction) Testnet3 (BTCT) empirical block-time drift: probe measured ~25.4s/block over a 1000-block sample vs. spec's average_block_time: 600000ms (-95.8%), flagged BLOCK_TIME_MISMATCH. Orchestrator auto-decision, already made. average_block_time is a pre-existing field untouched by this PR. Testnet3's 20-minute difficulty-reset rule produces rapid-fire block bursts that make any short sampling window unrepresentative — chain-behavior noise, not a parse-directive or spec defect. Report only.
5 — (transparent gaps, not defects) rest interface (all 4 networks) and blockdaemon addon: NOT_TESTABLE per the probe report (key-gated, no credentials available). Not caused by this PR, not actionable without credentials. Not fix items.

Disable-suggestions stripped (count)

16 total, all correctly excluded by every reviewer already (nothing required stripping from
their written findings — recorded here per the consolidation brief):

  • 14/14 non-stateful bb_* methods: -32601 Method not found on both configured upstreams
    (publicnode, Tatum) — neither is Blockbook-enabled. Free-tier/gateway artifact, not evidence
    of absence.
  • getmemoryinfo: FAILs on both upstreams (-32701/-32601) — provider-tier RPC-policy
    restriction, pre-existing, unrelated to this PR.
  • gettxoutsetinfo: FAILs on both upstreams (HTTP 500 / -32601) — same provider-policy
    class, pre-existing, unrelated to this PR.

Move the 15 Blockbook methods out of the base jsonrpc collection into a
"blockbook" add-on collection, so only node urls that declare
addons: ["blockbook"] are asked for them. One verification checks the add-on
at startup: bb_getBlockHash ["0"] must answer with a blockHash; height 0
exists on every chain and network, so every spec that imports BTC inherits a
check that works for it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Tomelia1999 Tomelia1999 changed the title feat(btc): add the Blockbook bb_* methods to the base jsonrpc collection (MAG-4824) feat(btc): serve the Blockbook bb_* methods from a blockbook add-on (MAG-4824) Nov 5, 2026
@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 11 — final reviewer verdict: ✅ APPROVED

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0

A fresh-context reviewer re-reviewed btc.json as it stands on disk (including the uncommitted Phase-10 fixes) and verified all four corrections independently — re-deriving each from the file with jq/python rather than trusting the stated diff, and cross-checking them against the in-file getblockstats, getblockhash, getblock and getblockheader precedents.

# fix verdict
1 bb_getBlock → PARSE_BY_ARG ["0"] + parsers correct, complete
2 bb_getRawBlock → same correct, complete
3 bb_getFeeStats → same correct, complete
4 bb_getFeeStats.category.deterministic → true correct

Supporting checks it ran against the current file, all clean:

  • bb_getBlockHash correctly keeps only a BLOCK_LATEST parser (no BLOCK_HASH) — it mirrors getblockhash, whose arg 0 is a height only. No regression from the fix pass.
  • bb_getEstimateFee correctly stays DEFAULT ["latest"] — its arg 0 is a confirmation-target block count, not a block identifier, so it is rightly not a candidate for this fix pattern.
  • compute_units (20) on all three fixed methods matches getblockstats; stateful is integer-typed on all 15 bb_*; no duplicate API names; jq -e . clean.
  • bb_sendTransaction.timeout_ms: 10000 present and well-typed, with category consistent with sendrawtransaction/submitpackage.
  • All 15 bb_* live only in BTC's base jsonrpc collection (49 APIs = 34 pre-existing + 15 new); BTCT/BTCT4/BTCS redefine none of them, so they inherit correctly via imports: ["BTC"] — no inheritance bug introduced.

Disabled-API audit: 0 disabled methods across all four spec entries, consistent with the ledger (empty) and the PR body's <!-- disabled-count: 0 --> marker. The reviewer additionally found two disabled collections — BTCS rest GET and rest POST (enabled: false, empty apis: []) — and verified against origin/main:btc.json that they predate this PR byte-for-byte. Pre-existing and untouched, so reported informationally rather than as a gap against #202; worth a separate ticket only if a Signet rest surface is ever wanted.

Open item for a human (not blocking, not auto-applied)

Base-collection vs add_on placement of the 15 bb_* methods — raised as CRITICAL by all three Phase-9 reviewers, deliberately not applied, rationale recorded in the Phase 10 comment. A reviewer should confirm the base placement is intended before merge.

Honest caveat on coverage

This verdict is a static + boot-level approval. The 15 bb_* methods were never positively answered by any upstream in this run: Blockbook is a QuickNode add-on surface and no keyless Blockbook-enabled node was available, so all 14 non-stateful ones returned -32601 and bb_sendTransaction was skipped as stateful. What was proven live is that the router boots on this spec, resolves the graph, tracks the chain (GET_BLOCKNUM OK), passes chain-id on all four networks, and dispatches bb_getBlock through the new PARSE_BY_ARG/parsers config without a craft or parse error. End-to-end bb_* behaviour rests on the A/B run against a real QuickNode slot recorded in the PR body, not on this pipeline run.

Full final review (docs/btc/SPEC_REVIEW_GAPS_final.md)

btc.json — Final Review Pass (PR #202, feat/btc-blockbook-methods, MAG-4824)

Reviewed btc.json as it stands on disk, including the Phase-10 fix pass that is currently
uncommitted in the working tree (git diff btc.json shows it; git diff origin/main...HEAD
does not, since it predates this review and sits only in the working tree). No state-changing
git command was run and btc.json was not modified by this review.

Phase 0 — Removed-field guard

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

No cleanup findings. Canonical envelope confirmed ({ "proposal": { "specs": [...] } }, no
title/description/deposit, no governance fields, no extra_compute_units /
category.local / category.subscription) — all per the settled model and not re-flagged.

Verification of the 4 Phase-10 fixes

All four corrections were re-derived independently from the spec on disk (via jq/python,
not by trusting the stated diff) and cross-checked against the in-file getblockstats precedent
(lines ~191-214) and against getblockhash/getblock/getblockheader for parser-shape
consistency.

# API Before → After Verdict
1 bb_getBlock block_parsing DEFAULT ["latest"] → PARSE_BY_ARG ["0"]; added parsers: [{".params.[0]", BLOCK_HASH}, {".params.[0]", BLOCK_LATEST}] Correct, complete. Matches getblockstats exactly (arg 0 accepts height-or-hash, same as Blockbook's bb_getBlock). category.deterministic: true was already correct and untouched.
2 bb_getRawBlock Same shape change as #1 Correct, complete. Identical reasoning; bb_getRawBlock's arg 0 is also height-or-hash.
3 bb_getFeeStats Same block_parsing/parsers change as #1 Correct, complete.
4 bb_getFeeStats.category.deterministic false → true Correct. Fee stats for an already-mined block (txCount, totalFeesSat, decilesFeePerKb, etc.) are fixed once that block is final — same reasoning as bb_getBlock/bb_getRawBlock/getblockstats, all deterministic: true. This correctly makes bb_getFeeStats eligible for cross-provider data-reliability verification.

Supporting checks run against the current file:

  • bb_getBlockHash (not part of this fix pass) correctly keeps PARSE_BY_ARG ["0"] with only a
    BLOCK_LATEST parser (no BLOCK_HASH) — it mirrors getblockhash, whose arg 0 is a height
    only, not a hash. No regression.
  • bb_getEstimateFee correctly remains DEFAULT ["latest"] — its arg 0 is a confirmation-target
    block count, not a block identifier, so it is not a candidate for this fix pattern.
  • compute_units for all three fixed methods (20) matches getblockstats (20); stateful is
    typed as an integer (1/0), not a boolean, on all 15 bb_* methods.
  • No duplicate API names were introduced; jq -e . parses the file cleanly.
  • bb_sendTransaction.timeout_ms: 10000 (committed separately in e466747, ahead of this
    working-tree pass) is present and well-typed; category: {deterministic: false, stateful: 1, hanging_api: true} is consistent with sendrawtransaction/submitpackage.
  • All 15 bb_* methods live only in BTC's base jsonrpc / add_on: "" collection (49 APIs
    total: 34 pre-existing + 15 new); BTCT/BTCT4/BTCS do not redefine any bb_* entry, so
    they inherit them automatically via imports: ["BTC"] — no inheritance bug introduced.

No further defects found in the 4 fixes or their immediate surroundings. The Phase-10 pass is
complete and correct.

Disabled-API Justification audit

jq '[.. api/collection enabled:false ..]' btc.json
  • Disabled APIs (method level): [] — zero, across all 4 specs. Matches
    check_disabled_count.sh (0 distinct disabled methods) and the PR body's
    <!-- disabled-count: 0 --> marker. The provided ledger (none — no disabled APIs) is
    consistent with this result; no justification rows are needed.
  • Disabled collections: found 2 — BTCS (Signet) rest GET and rest POST
    (enabled: false, empty apis: []). Verified against origin/main:btc.json — this
    predates PR feat(btc): serve the Blockbook bb_* methods from a blockbook add-on (MAG-4824) #202 byte-for-byte
    (present, identically disabled, before the bb_* change).
    It is not touched by this PR's diff and not touched by the Phase-10 fix pass. Per the
    orchestrator's scope rule for pre-existing/untouched items, this is reported as
    informational, not a CRITICAL finding against this PR — it is a structural
    collection-level disable (not a "distinct disabled method", which is what the ledger and
    check_disabled_count.sh scope covers), and it is unchanged by MAG-4824. Flagging for a
    separate ticket if a rest/Blockbook-explorer-style surface for Signet is ever desired, but
    out of scope here.

Other observations (informational / pre-existing — not gaps against this PR)

These were already adjudicated by the orchestrator or are explicitly out of scope per this
review's brief; recorded for completeness, not counted in the tally below.

  1. add_on placement of the 15 bb_* methods — raised by 3/3 prior reviewers (dedicated
    blockbook add-on vs. base collection). Deliberately not applied: base placement is the
    point of MAG-4824 (makes UnlistedMethodRefused retryable on another peer, paired with
    smart-router#632). Recorded as an open decision for a human call, not re-raised as blocking.
  2. estimatesmartfee (deterministic: true, pre-existing, untouched) vs. new
    bb_getEstimateFee (deterministic: false)
    — both are live fee-market estimates;
    the flags disagree. estimatesmartfee's value is pre-existing and untouched by this PR, so
    per scope this is not raised as a new gap. Worth a follow-up ticket to reconcile, since one
    of the two sides (bb_getEstimateFee) is new.
  3. bb_getXPUB CU (compute_units: 20) — derives/scans a gap-limit set of child addresses
    per xpub; may be under-priced relative to a single-address lookup. No confirmed-heavy
    analog exists in-file to anchor a concrete target value, and no Blockbook-enabled upstream
    was available to benchmark. Flagged for future benchmarking, not a confirmed defect.
  4. Pre-existing, unrelated to this PR, carried forward from the probe report: three
    hanging_api-without-timeout_ms rows (sendrawtransaction, submitpackage, /tx/send)
    that fail identically on main; testnet3 (BTCT) empirical block-time drift
    (-95.8% over a 1000-block sample, attributable to testnet3's 20-minute difficulty-reset
    burst behavior, not a spec defect); rest interface (all 4 networks) and blockdaemon
    add-on both NOT_TESTABLE (key-gated, no credentials available to this run).
  5. Phase 10b router re-boot against the fixed spec: SMOKE: OK, PARSE: OK on
    GET_BLOCKNUM/GET_BLOCK_BY_NUM, VERIFY: OK on chain-id (all 4 networks), no
    regressions observed.

Summary

  • Endpoints reviewed: 49 APIs in BTC's base jsonrpc collection (34 pre-existing + 15 new
    bb_*), plus inheritance correctness across BTCT/BTCT4/BTCS.
  • All 4 Phase-10 fixes verified correct and complete; no regressions found in their
    vicinity.
  • Disabled-API ledger: 0 disabled methods, consistent with the provided ledger and the PR's
    disabled-count: 0 marker. One pre-existing, PR-unrelated disabled-collection pair
    (BTCS rest GET/POST) noted informationally, not counted as a gap against this PR.
  • No new CRITICAL, MEDIUM, or MINOR findings against PR feat(btc): serve the Blockbook bb_* methods from a blockbook add-on (MAG-4824) #202 as it now stands (working tree,
    fixes included). The spec is ready for deployment from this reviewer's standpoint; the one
    open item requiring a human call (base vs. add_on placement) is already escalated and not
    blocking.

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 12 — closing summary checklist (tail of the Phase 8–11 span; ✓ verified this run, ~ partial, ☐ manual/out of scope)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a `jq` + Phase 11 reviewer re-parse)
- ✓ All required fields present                          (Phase 10a check_method_schema: 75/75 rows ok)
- ✓ No duplicate API names within any collection         (Phase 11 reviewer, verified with jq)
- ✓ Proper indentation/formatting                        (surgical 40+/10- diff; 4-space indent and
                                                          the file's no-trailing-newline convention preserved)

#### Configuration Verification
- ☐ Network parameters calculated per formulas           (Phase 4 did not run — resumable span started at Phase 8;
                                                          params are pre-existing and untouched by this PR)
- ~ All APIs tested and working                          (Phase 8: PASS=30 FAIL=16 SKIP=3 UNPROBED=0 WARN=0 TIMEOUT=0.
                                                          The 14 non-stateful bb_* FAILs are -32601 from non-Blockbook
                                                          keyless upstreams, NOT spec defects; bb_sendTransaction and 2
                                                          others SKIPped as stateful. See docs/btc/METHOD_PROBE_REPORT.md)
- ~ Block parsing validated for each API                 (the 3 fixed bb_* methods: dispatch verified through the live
                                                          router with no craft/parse error; full per-API parse validation
                                                          needs a Blockbook-enabled upstream)
- ✓ Parse directives executed by live router             (Phase 8 Step 3.5: PARSE=PARTIAL, VERIFY=OK;
                                                          Phase 10b re-check: PARSE=OK on GET_BLOCKNUM, VERIFY=OK.
                                                          GET_BLOCK_BY_NUM NOT_EXERCISED both times — router-side
                                                          fork-detection polling is off by operator choice, not a spec issue)
- ~ Addons & extensions tested                            (Phase 8 Step 1c: 0 tested-ok / 0 failed / 2 not-testable —
                                                          `blockdaemon` and `rest` are both key-gated; need credentialed nodes)
- ✓ Verifications pass on live nodes                     (chain-id OK on all four networks: BTC "main", BTCT "test",
                                                          BTCT4 "testnet4", BTCS "signet"; re-confirmed in Phase 10b)
- ☐ Compute units benchmarked under expected load        (user to measure; bb_getXPUB flagged for benchmarking
                                                          once a Blockbook-enabled node is available)

#### 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                                (BTC entry; 15 bb_* added, 4 corrected)
- ✓ Testnet spec inherits correctly                      (BTCT/BTCT4/BTCS redefine no bb_* entry, so all 15 inherit
                                                          via imports:["BTC"] — verified by the Phase 11 reviewer)
- ✓ Chain IDs verified for mainnet AND testnet           (Phase 8 Step 7: three separate router boots, one per testnet)
- ~ Both tested on respective networks                   (all four networks booted + verified; method probing ran on
                                                          mainnet only — Step 7 is boot+verification by design)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (canonical { "proposal": { "specs": [ … ] } } envelope;
                                                          check_unused_fields.sh PASS — none of the 15 removed fields present)
- ☐ Community feedback gathered (if applicable)

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

Elapsed:         00h 44m 37s  (first→last logged activity)
Transcripts:     1 main + 9 subagent
API round-trips: 587  (main=95, subagents=492)
Fresh tokens:    input=1174  output=297821  (sum=298995)
Cached tokens:   cache_read=40107082  cache_write=1530404
Total billed:    41936481 tokens
Split:           main=10411423  subagents=31525058
Models used:     claude-sonnet-5  492 calls  31525058 billed
                 claude-opus-5     97 calls  10721563 billed

These figures cover only Phases 8–11 in this resumable run. Phases 1–7 never ran in this workflow run — the spec was reconstructed from the committed btc.json on the branch. There is no 1–11 grand total to quote here; the true total would be this run plus the original create_spec run that produced the spec.

State left behind

The Phase-10 fix is uncommitted in the working tree on feat/btc-blockbook-methods (git status: M btc.json; HEAD still e466747). No git state was changed by this run — the workflow's commit step picks the edit up. Guards re-run green on the final file: check_unused_fields.sh PASS, check_method_schema PASS, check_hanging_api/check_stateful PASS against origin/main as base, jq valid, check_disabled_count.sh 0 (matching the body marker).

What a human still needs to decide

  1. Base vs add_on placement of the 15 bb_* methods — flagged CRITICAL by 3/3 Phase-9 reviewers, deliberately not auto-applied because MAG-4824 makes base placement the point of the change. Confirm it is intended before merge.
  2. bb_* end-to-end behaviour was not re-proven by this pipeline — no keyless Blockbook upstream exists. Re-run with a Blockbook-enabled node (/rerun-probe mainnet=<your-blockbook-node>) if live bb_* coverage is wanted in-pipeline; otherwise the PR body's A/B run against a real QuickNode slot is the evidence of record.

Pipeline span 8→11 complete. Verdict: APPROVED with the one open placement decision above.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Spec pipeline failed (started at Phase 8). See the run log.

Retry by commenting:
/rerun-probe (optionally /rerun-probe mainnet=https://your-node/rpc`, or mainnet=use=PAID_RPC_1 for a stored secret node)`

To also re-run every later phase on top of the fix, use /rerun-from 8 instead.

@Tomelia1999

Copy link
Copy Markdown
Contributor Author

Review: bb_* block parsing, checked against QuickNode docs and the router source

The add-on design is sound: the blockbook collection is opt-in, every spec that imports BTC gets it unchanged, and the enabled check (PARSE_CANONICAL ["0","blockHash"]) has the shape used across the repo. The findings below are about block parsing only. Router behaviour is from smart-router main (2f8099e0). This PR was tested on v1.6.6; the parser code looks stable, but I didn't diff the two versions.

Argument 0 of the block-lookup methods (QuickNode docs)

method arg 0 time-dependent fields in the response
bb_getBlock block: "The block hash or block height (as a string)" confirmations at block level and in each txs[] entry (-1 if not on the main chain)
bb_getRawBlock block_id: "The block height or block hash to query." Example ["800000"] none, only hex
bb_getFeeStats block_id: same wording, example ["800000"] none (txCount, totalFeesSat, averageFeePerKb, decilesFeePerKb)

All three currently use DEFAULT ["latest"].

What the router does with PARSE_BY_ARG ["0"] + parsers: [BLOCK_HASH, BLOCK_LATEST] (the getblockstats shape)

  • The parsers run in order and the first one that works wins (ParseWithGenericParsers).
  • A height such as "800000" is shorter than MinimumHashLength (32), so BLOCK_HASH is skipped. BLOCK_LATEST reads it, and ParseInt(s, 0, 64) makes it block 800000.
  • A 64-character hash matches BLOCK_HASH, so the requested block is "not applicable". This is how getblock and getblockstats behave today.
  • Node selection does not change. ChooseUpstreamWithStats only writes the requested block to a trace log, so the parse doesn't decide which node is picked.
  • Caching is the only effect.
    • With latest, an answer is cached under the current tip with the short non-finalized TTL, and that entry stops matching once the tip moves.
    • With PARSE_BY_ARG, a height at least block_distance_for_finalized_data (6) deep is treated as final and goes into the long-TTL store.
    • A hash request is never cached (NOT_APPLICABLE skips the cache write).
  • category.deterministic is read only for cross-validation mismatch alerting. It doesn't control caching.

Suggestions

item suggestion
bb_getRawBlock, bb_getFeeStats Switch to PARSE_BY_ARG ["0"] + parsers [{".params.[0]","BLOCK_HASH"},{".params.[0]","BLOCK_LATEST"}]. The answer for a final block never changes, so long caching is correct.
bb_getBlock Keep DEFAULT ["latest"]. With PARSE_BY_ARG, a request by height would long-cache confirmations (block and per-tx) at the value from the first call. getblock avoids this only because it takes a hash, which is never cached.
bb_getFeeStats deterministic true is correct (the data is fixed per block). It only affects mismatch alerting, so it's optional to include with the change above.
Compute units for bb_getXPUB / bb_getBalanceHistory No change. QuickNode bills the Blockbook add-on at a flat rate per call (BTC Blockbook: 10 credits; Blockbook RPC: 20; the listings disagree), and the docs say nothing else about cost beyond the default gap of 20.

Note on the pipeline comments above

The bot run started at 13:24 against 8535453, when the methods were still in the base collection. a4c9e1a (the move to the add-on) landed at 14:08, during the run. The "Phase 11 APPROVED" verdict and the open "base vs add-on" item describe the old layout, and the Phase 10 parsing fixes were never pushed (the run ended in "Spec pipeline failed"). A /rerun-from 8 after any change would give a review of the current head.

Nothing here was exercised against a live Blockbook node.

…4824)

Both take a block height or hash as argument 0, and their answer for a given
block never changes. Parse it like getblockstats: PARSE_BY_ARG 0 with a
BLOCK_HASH then BLOCK_LATEST parser. A height that is final is cached for the
long TTL; a hash is not cached. bb_getFeeStats becomes deterministic.

bb_getBlock keeps DEFAULT latest: its answer carries confirmations, which a
long cache entry keyed on the height would freeze.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Tomelia1999

Copy link
Copy Markdown
Contributor Author

/rerun-from 8

@magmadevs-bot

Copy link
Copy Markdown
Contributor

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

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 8 — smart-router boot + multi-node method probe (re-run via /rerun-from 8)

Resumable pipeline run (Phases 8–11). Endpoint source: self_research — MAINNET_URLS/TESTNET_URLS were both empty, so the keyless public nodes validated by the earlier run on this PR were re-used and re-validated before booting.

This probe is against the current HEAD (6290693), not the stale layout. The earlier Phase 8 comment on this PR probed 8535453, when the 15 bb_* methods still lived in the base jsonrpc collection; a4c9e1a (move to the blockbook add-on) and 6290693 (block-parsing fix on bb_getRawBlock/bb_getFeeStats) both landed afterwards. Treat the earlier Phase 8/9/10/11 comments as describing the old layout.

verdict value
PARSE: PARTIAL — GET_BLOCKNUM OK (smartrouter_latest_block advanced 974680→974681 live); GET_BLOCK_BY_NUM NOT_EXERCISED
VERIFY: OK — base chain-id 2/2 upstreams; both add-on enabled verifications NOT_EXERCISED (not FAIL)
ADDONS: 0 tested-ok / 0 failed / 2 not-testable (blockbook, blockdaemon) + rest interface not-testable
counts PASS=30 FAIL=0 SKIP=3 UNPROBED=0 WARN=2 TIMEOUT=0 LOG_WARN=2 (base collection; the 22 add-on methods are reported separately as NOT_TESTABLE, not folded in)
TESTNET_VERIFY: OK — all three testnets booted and verified: BTCT, BTCT4, BTCS
BLOCK_TIME: mainnet 623,084ms · BTCT 28,991ms · BTCT4 541,049ms · BTCS 591,541ms (spec 600,000ms)

The key new question this run answers: the blockbook add-on collection carries its own enabled verification, and a verification value with no severity defaults to Fail — so the risk of the a4c9e1a refactor was that an add-on no upstream supports would exclude the provider at boot and take the whole base collection down with it. It does not. Per Step 1c-iii the add-on was correctly left out of the router config (zero supporting upstreams), its enabled verification came back NOT_EXERCISED rather than FAIL, and the base collection's chain-id verification and GET_BLOCKNUM tracking were unaffected. The opt-in add-on layout boots cleanly.

PARSE: PARTIAL is a router-deployment artifact, not a spec defect. GET_BLOCK_BY_NUM was never executed because this image logs "block-hash polling (fork detection) resolved","enabled":"false","reason":"off-operator-choice" at boot — the by-number hash walk is gated behind a process-wide --enable-fork-detection CLI flag that is off by default and sits outside the config shape this phase is allowed to use. No parse-failure signatures were logged anywhere. Per the skill's rule, PARTIAL is an upstream/router-capability finding and is not treated as a spec defect; recorded so a reviewer knows the directive is unexercised rather than proven.

The 15 bb_* methods still could not be positively exercised, and that remains expected rather than a finding: Blockbook is a QuickNode add-on surface and neither keyless upstream is Blockbook-backed. All 14 non-stateful bb_* returned -32601 identically on both upstreams when probed directly, and the router answered "No Providers For Addon" through the add-on route (correct behaviour for an add-on with no configured provider); bb_sendTransaction was SKIPped as category.stateful: 1. A bounded search for a keyless Blockbook-capable endpoint found none. Per the free-tier rule this is not evidence any method should be disabled — no disable is recommended; the 15 methods go to the watch-list for re-test on a Blockbook-enabled node.

blockdaemon (8 bd_*) and the rest interface are likewise NOT_TESTABLE and key-gated — svc.blockdaemon.com/universal/v1/bitcoin/mainnet/ returned HTTP 401 No Authorization Header on re-check, with no keyless tier. Carried forward with evidence, not probed and not flagged.

The two base-collection WARNs (getmemoryinfo, gettxoutsetinfo, both -32701) are pre-existing node-policy blocks on the public upstreams and unrelated to this PR — administrative/heavy RPCs that Allnodes' public tier refuses.

BLOCK_TIME_MISMATCH (testnet3/BTCT) at −95.2% is testnet3's well-known 20-minute difficulty-reset behaviour (difficulty drops to the network minimum and miners briefly produce blocks seconds apart), not a parse-directive or average_block_time defect — see the Phase 10 comment for the decision taken on it.


Method Probe Report — btc

Generated: 2026-11-05T15:49:15Z
Router image: ghcr.io/magma-devs/smart-router:main (sha256:db69b93d3f8dc4a6c36656388d5b9125247f35a36ed86b3a229a029db3f794a6)
Router config: /tmp/sr_btc.yml
Spec variant: BTC (jsonrpc)
Upstreams probed: https://bitcoin-rpc.publicnode.com, https://bitcoin-mainnet.gateway.tatum.io

This is a re-probe of the current committed spec (commit 6290693 on this PR branch). A prior Phase 8 run probed commit 8535453, when the 15 bb_* methods still lived in the base jsonrpc collection — that report is stale. Since then: a4c9e1a moved bb_* into a dedicated blockbook add-on collection carrying its own enabled verification, and 6290693 switched bb_getRawBlock/bb_getFeeStats block_parsing from DEFAULT ["latest"] to PARSE_BY_ARG ["0"] with [BLOCK_HASH, BLOCK_LATEST] parsers.

Headline result: the router boots cleanly and serves the base BTC collection with the blockbook add-on correctly left OUT of the config (no configured upstream supports it), and its enabled verification came back NOT_EXERCISED — not FAIL — confirming the opt-in add-on does not arm its (severity-Fail-by-default) verification or otherwise disturb the base collection when unsupported. See the verification table below.

Parse-directive & verification runtime check (Step 3.5)

Check Verdict Evidence
GET_BLOCKNUM (router latest_block) OK smartrouter_latest_block progressed 974680 → 974681 during the run (a real new block was mined); rpc_endpoint_tracker_requests_total{kind="latest_block"} incrementing on both upstreams
GET_BLOCK_BY_NUM (log hash-reads ∥ fetch_block counters) NOT_EXERCISED — router-level feature flag, not a spec/config defect This image logs at boot: "message":"block-hash polling (fork detection) resolved","enabled":"false","reason":"off-operator-choice". docker run ... --help confirms a process-wide --enable-fork-detection CLI flag, OFF by default, that gates all per-endpoint GET_BLOCK_BY_NUM/block-hash tracker activity (rpc_endpoint_tracker_requests_total{kind="block_hash"} never appears without it). This flag is not part of the documented Step 1b/Step 2 YAML config shape or the verbatim docker run command this phase is instructed to use, so it was left off, per "do not improvise." No Chain Tracker Updated block hashes/read a block Hash log lines and no fetch_block_success/fails metric appeared — consistent with the directive simply never being asked for, not with it failing. No PARSE_SIG lines (ParseBlockHashFromReplyAndDecode, expected parsed hashes length, etc.) appeared anywhere in the boot or probe window.
Parse-signature log lines none no matches for the PARSE_SIG grep in the boot or probe window
Verification Verdict Providers OK/failed Notes
chain-id (base jsonrpc) OK 2/2 both upstreams verified "expected_value":"main"; 4 total success lines logged (re-verified on later epoch ticks)
enabled (blockbook add-on) NOT_EXERCISED 0/0 (addon not in router config) both upstreams confirmed -32601 Method not found on bb_getBlockHash(["0"]) direct-to-node (Step 1c); correctly left out of /tmp/sr_btc.yml so the verification never arms — no [+]/[-] verify line for enabled anywhere in the logs
enabled (blockdaemon add-on) NOT_EXERCISED 0/0 (addon not in router config) both upstreams confirmed -32601 Method not found on bd_estimatefee([]) direct-to-node (Step 1c); same treatment as blockbook

Addon & extension coverage (Step 1c + probes)

Name Type Upstreams supporting Standalone Boot verification Router probe Classification
blockbook addon none (0/2) — n/a (left out of config) 14/14 non-stateful methods → router replies "No Providers For Addon...No pairings available" (addon correctly absent from config); 1 skipped (stateful) NOT_TESTABLE — both keyless upstreams are plain bitcoind, not QuickNode/Blockbook-backed; bb_getBlockHash(["0"]) → -32601 on both direct. A 5-minute search for a keyless public Blockbook-style JSON-RPC gateway found none; per the free-tier rule this does not imply any bb_* method should be disabled.
blockdaemon addon none (0/2) — n/a (left out of config) 8/8 methods → "No Providers For Addon...No pairings available" NOT_TESTABLE — key-gated Blockdaemon Ubiquity surface; bd_estimatefee([]) → -32601 on both direct upstreams. No API key available to this run.
rest (GET, chain-id+network verifications) interface none (0 of the 2 jsonrpc upstreams given are REST-capable; no separate rest upstream provided) — n/a (no rest listener booted) not probed — no listener NOT_TESTABLE — curl https://svc.blockdaemon.com/universal/v1/bitcoin/mainnet/ → bounded re-check this run: HTTP 401 {"title":"Unauthorized","detail":"No Authorization Header"}. No keyless tier exists and no API key is available. Per the instructions this interface only gets a listener if a keyless upstream validates in Step 1c; it didn't, so /tmp/sr_btc.yml has no :3361 endpoint/direct-rpc block at all.
rest (POST) interface none — n/a not probed NOT_TESTABLE — same Blockdaemon-gated surface as rest GET, no separate verification declared for POST.

Method probe (Step 4) — through the router, localhost:3360

Live inputs resolved before probing (no hardcoded placeholders): latest height 974681, latest hash 00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b415b87, a confirmed non-coinbase txid af53a1b84f210a54cb410b1e8f3920219ba4931f722fa2d73871aaf30e8232c3 (+ its full raw hex and a spendable-looking vout), a live mempool txid, a live address 1HWqygxLA3gVrCNTWai7GwfiUJD2NfFDFy, and a gettxoutproof-derived merkle proof for verifytxoutproof.

Two methods initially WARNed on -22 TX decode failed (decoderawtransaction, testmempoolaccept) because the raw-tx hex pasted into the first probe run was truncated to 200 of its 450 hex characters — a probe-setup artifact, not a chain/spec defect. Both were re-probed once with the correct full-length hex per the re-probe-once gate and now PASS.

Method Classification Code Notes
getblockhash PASS — result: 00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b41
getblock PASS — {"hash":"00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b415b87","conf
createrawtransaction PASS — "0200000001c332820ef3aa7138d7a22f721f93a49b2120398f1e0b41cb540a214fb8a153af00000
decoderawtransaction PASS — (re-probed w/ correct full-length raw tx hex; initial WARN -22 was a probe-setup artifact - truncated hex)
decodescript PASS — {"asm":"OP_DUP OP_HASH160 b526f5af08ca86caeeffc468a1d362151a13d15c OP_EQUALVERIF
estimatesmartfee PASS — result keys: feerate, estimator, blocks, ...
getbestblockhash PASS — result: 00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b41
getblockchaininfo PASS — {"bestblockhash":"00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b415b
getblockcount PASS — result: 974681
getblockheader PASS — {"hash":"00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b415b87","conf
getblockstats PASS — {"avgfee":1437,"avgfeerate":4,"avgtxsize":478,"blockhash":"000000000000000000014
getchaintips PASS — [{"height":974681,"hash":"00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93
getchaintxstats PASS — {"time":1793892869,"txcount":1474909733,"window_final_block_hash":"0000000000000
getconnectioncount PASS — result: 132
getdifficulty PASS — result: 148364561003867.4
getindexinfo PASS — result keys: txindex, basic block filter index, ...
getmemoryinfo WARN -32701 [pre-existing, not introduced by this PR] {"code":-32701,"message":"Method getmemoryinfo is not allowed. order a dedicated full node..."}
getmempoolancestors PASS — result: []
getmempooldescendants PASS — result: []
getmempoolentry PASS — {"vsize":142,"weight":565,"time":1793892980,"height":974681,"descendantcount":1,
getmempoolinfo PASS — {"loaded":true,"size":47590,"bytes":27702066,"usage":145461408,"total_fee":0.182
getrawmempool PASS — ["70419bdb3dcaf1762c07a092886980a48d5ebc43d391c994c51d6b28327d25fd","f3bb2c07d68
getrawtransaction PASS — {"txid":"af53a1b84f210a54cb410b1e8f3920219ba4931f722fa2d73871aaf30e8232c3","hash
gettxoutproof PASS — "00c0bb28f2ebe33108acd81954d238535c86e673a61ab71ceb4c010000000000000000007f819fa
gettxoutsetinfo WARN -32701 [pre-existing, not introduced by this PR] router retries ~30s then returns {"code":-32701,"message":"broker: node error on ...allnodes.me"} (publicnode/Allno...
gettxout PASS — {"bestblock":"00000000000000000001450cba3d9ee008b0ce7c9133b20bfefc93360b415b87",
testmempoolaccept PASS — (re-probed w/ correct full-length raw tx hex; result allowed=false reject-reason=txn-already-known, which is a valid functional response - initial WARN -22 w...
validateaddress PASS — {"isvalid":true,"address":"1HWqygxLA3gVrCNTWai7GwfiUJD2NfFDFy","scriptPubKey":"7
verifymessage PASS — result: False
verifytxoutproof PASS — result: array[1]
getblockfilter PASS — {"filter":"fd4732e4daa00ab4766afad31286bd5e4d6138ec8b90e0b32e81cb197d4d8b5b98760
getnetworkhashps PASS — result: 9.936029014011083e+20
sendrawtransaction SKIP — stateful - would broadcast transaction
submitpackage SKIP — stateful - would broadcast transaction
bb_getAddress NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getBalanceHistory NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getBlock NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getBlockHash NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getEstimateFee NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getFeeStats NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getMultiTickers NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getRawBlock NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getTickers NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getTickersList NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getTx NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getTxSpecific NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getUTXOs NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_getXPUB NOT_TESTABLE -32000 no upstream supports blockbook (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bb_sendTransaction SKIP — stateful - would broadcast transaction
bd_getbalances NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_getbalance NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_estimatefee NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_listtransactions NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_getspendingtx NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_listunspent NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_marketquote NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'
bd_getblockheaderbydate NOT_TESTABLE -32000 no upstream supports blockdaemon (confirmed -32601 direct); router correctly has no provider for this addon -> 'No Providers For Addon...No pairings available'

Log-scan findings (probe window)

Non-benign warn/error/fatal/panic lines logged during probing (Step 4.5), 47 raw lines after the benign-noise filter, collapsing to the findings below (no fatal/panic level lines anywhere):

Level Associated method error excerpt
ERR getmemoryinfo HTTP 501 Not Implemented (btc-upstream-1) → final client reply -32701 "...order a dedicated full node...". [pre-existing, not introduced by this PR] — already folded into the method table row above, not double-counted.
ERR gettxoutsetinfo HTTP 500 Internal Server Error from btc-upstream-1's backend (bitcoin-fn-ash.allnodes.me) after a 30s router retry window → final client reply -32701 "broker: node error...". [pre-existing, not introduced by this PR], same public-tier admin-RPC policy block as getmemoryinfo. Already folded into the method table row above.
ERR testmempoolaccept (first attempt only) -22 "TX decode failed" — my own truncated-hex probe-setup bug (see above), fully resolved by the re-probe; the PASS row above reflects the corrected result.
ERR/WARN btc-upstream-2 (Tatum), multiple methods repeated HTTP 429 Too Many Requests / "rate-limit hold-off" / "Circuit breaker: all providers exhausted" lines. Pacing evidence, not method findings — Tatum's free tier enforces ~5 req/min as expected; the router's own retry/circuit-breaker logic absorbed every one of these transparently, and every probed method still received a final classification (no client-facing 429, no UNPROBED methods).
WARN bb_/bd_ addon methods "reason":"addon-filtered"... "message":"provider pool empty" — expected consequence of correctly leaving the unsupported blockbook/blockdaemon addons out of the router config; already reflected as NOT_TESTABLE above, not a defect.

LOG_WARN count used in the return summary = 2 (getmemoryinfo, gettxoutsetinfo — both pre-existing and already counted as the two WARN rows in the method table; nothing in this section introduces a new, previously-uncounted finding).

Transport probe (http + ws)

jq -e '[.proposal.specs[].api_collections[]?.parse_directives[]? | select(.function_tag=="SUBSCRIBE")] | any' btc.json → false: this spec declares no SUBSCRIBE directives anywhere in its import closure, so the hard "STOP if no URL answers ws" gate does not apply. The probes below are purely informational; no ws URL was added to any direct-rpc block regardless of outcome (not needed, and a ws-only upstream that can't answer request/response GET_BLOCKNUM only adds boot noise).

URL http ws
https://bitcoin-rpc.publicnode.com (BTC mainnet) OK (getblockcount answered) OK — wss://bitcoin-rpc.publicnode.com handshake returned HTTP 101 Switching Protocols
https://bitcoin-mainnet.gateway.tatum.io (BTC mainnet) OK (getblockcount answered, subject to the 5 req/min free-tier limit) refused — wss:// handshake returned HTTP 405 Method Not Allowed (this gateway endpoint is REST/HTTP-only)
https://bitcoin-testnet-rpc.publicnode.com (BTCT) OK OK — HTTP 101
https://bitcoin-testnet4.gateway.tatum.io (BTCT4) OK (subject to the same 429 limiter) refused — HTTP 405
https://bitcoin-signet-rpc.publicnode.com (BTCS) OK OK — HTTP 101

No ws failure here is treated as a spec defect or boot blocker, per the no-subscriptions rule above.

Testnet verification pass (Step 7)

TESTNET_VERIFY: OK (all three testnet indices booted cleanly, chain-id verification passed, PARSE_BLOCKNUM OK; this is a boot+verification pass only, no Step 4 method probe per the instructions)

BTCT (Bitcoin Testnet3) — https://bitcoin-testnet-rpc.publicnode.com, ports 3460/7879

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 testnet expected_value verified against the live upstream

PARSE_BLOCKNUM: OK — smartrouter_latest_block{spec="BTCT"} = 5300558. No fatal/panic lines. Container sr_btc_testnet torn down cleanly after the pass.

BTCT4 (Bitcoin Testnet4) — https://bitcoin-testnet4.gateway.tatum.io, ports 3460/7879

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 testnet expected_value verified against the live upstream

PARSE_BLOCKNUM: OK — smartrouter_latest_block{spec="BTCT4"} = 159200. No fatal/panic lines. Container torn down cleanly after the pass.

BTCS (Bitcoin Signet) — https://bitcoin-signet-rpc.publicnode.com, ports 3460/7879

Verification Verdict Providers OK/failed Notes
chain-id OK 1/1 testnet expected_value verified against the live upstream

PARSE_BLOCKNUM: OK — smartrouter_latest_block{spec="BTCS"} = 329561. No fatal/panic lines. Container torn down cleanly after the pass.

Empirical block time (Step 8)

Measured direct-to-upstream (not through the router) using the bitcoind recipe: getblockcount → getblockhash(H) and getblockhash(H-1000) → getblock(hash).time, timestamp delta ÷ 1000 blocks — not the EVM measure_abt recipe in the agent file, which doesn't apply to this chain family. Sampled over 1000 blocks per network (not 100) per the instructions, since Bitcoin's 10-minute retarget-enforced target is noisy over short windows.

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
BTC mainnet bitcoin-rpc.publicnode.com 623084 600000 +3.8% OK
BTCT (testnet3) bitcoin-testnet-rpc.publicnode.com 28991 600000 −95.2% BLOCK_TIME_MISMATCH (testnet3) — see note below
BTCT4 (testnet4) bitcoin-testnet4.gateway.tatum.io 541049 600000 −9.8% OK
BTCS (signet) bitcoin-signet-rpc.publicnode.com 591541 600000 −1.4% OK

BTCT (testnet3) note — chain-behavior, not automatically a spec defect (orchestrator decides): Bitcoin Testnet3's difficulty resets to minimum after any 20-minute gap between blocks, which produces rapid-fire bursts of trivially-mined blocks. The empirical 1000-block sample landed inside one of those bursts (28991ms/block ≈ 29s, vs. the 600000ms spec default inherited from mainnet with no testnet3 override). This is the exact behavior flagged as expected in the task brief, not a newly-discovered defect. BTCT4 and BTCS — which don't have testnet3's reset rule — both landed within 10% of the inherited 600000ms default, so an override looks warranted for BTCT specifically if the orchestrator wants the testnet entry to reflect testnet3's real-world cadence; the other two testnet variants are fine as-is.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 9 — parallel reviewers (3 independent /review-spec passes)

Three fresh-context reviewers ran against btc.json as it stands at HEAD (6290693) — the add-on layout, not the superseded base-collection one the earlier pipeline comments describe — with the new Phase 8 probe report as input.

reviewer 1  TALLY: CRITICAL=0 MEDIUM=1 MINOR=2
reviewer 2  TALLY: CRITICAL=0 MEDIUM=2 MINOR=2
reviewer 3  TALLY: CRITICAL=0 MEDIUM=1 MINOR=5

No reviewer raised a CRITICAL finding. Reports are distinct (md5-checked — no shared-path collision), and the highest line number cited by any reviewer is 1437 against a 1618-line file, so none reviewed stale state.

Merged gap list, deduplicated by topic (full bodies below; docs/ is gitignored, so this comment is the durable record):

# severity topic raised by
1 MEDIUM bb_getBlock block parsing / deterministic — two reviewers reach opposite conclusions about the same deliberate decision from the human review (R1: should match its siblings' PARSE_BY_ARG; R3: deterministic: true contradicts the stated reason for keeping DEFAULT) R1, R3
2 MEDIUM bb_getAddress / bb_getXPUB ignore the fromHeight/toHeight range filter, so historical queries parse as "latest" R2
3 MEDIUM base-collection sendrawtransaction / submitpackage lack the explicit timeout_ms this PR gave bb_sendTransaction R2, R3
4 MINOR bb_getXPUB / bb_getBalanceHistory priced and timed like simple reads despite being full-scan aggregations R1, R2
5 MINOR BTCT (testnet3) inherits mainnet's 600,000ms average_block_time against a −95% empirical reading R1, R3
6 MINOR bb_getTickers' optional block field ignored by block parsing R2
7 MINOR bb_* names / response-field paths not independently verifiable — no API docs supplied to this run R3
8 MINOR blockbook's enabled verification proves the add-on answers, not that it is on the right network R3
9 MINOR blockbook has no collection-scoped GET_BLOCKNUM / GET_BLOCK_BY_NUM (same as blockdaemon) R3

Item 1 is the one that needs a judgment call rather than a mechanical fix, and item 3 is pre-existing on main rather than introduced here — both are resolved in the Phase 10 comment.


Reviewer 1 — findings

Findings

1. [MEDIUM] bb_getBlock keeps DEFAULT ["latest"] even though its parameter is a hash-or-height identifier, inconsistently with the fix just applied to its two siblings

File: btc.json, bb_getBlock entry (blockbook add-on collection, ~line 816-829).

{
    "name": "bb_getBlock",
    "block_parsing": {
        "parser_arg": ["latest"],
        "parser_func": "DEFAULT"
    },
    "compute_units": 20,
    "category": { "deterministic": true, "stateful": 0 }
}

Background acknowledged: the PR's accepted reasoning (per the human review applied
in 6290693) is that bb_getBlock keeps DEFAULT deliberately, because resolving it
by height/hash would let the router long-cache a response whose confirmations field
is time-dependent. bb_getRawBlock and bb_getFeeStats got the opposite fix
(PARSE_BY_ARG ["0"] + parsers: [BLOCK_HASH, BLOCK_LATEST]) because their payloads
don't carry that field.

Why I disagree with keeping bb_getBlock on DEFAULT: QuickNode's own docs
describe bb_getBlock's block parameter identically to bb_getRawBlock's
block_id — "the block hash or block height (as a string)" — so the two methods have
the same request shape that was just fixed for one and not the other. The stated
reason not to apply the same fix (a time-dependent confirmations field in the
response) already exists, unaddressed, on every other hash/height-keyed, high-level
Bitcoin read in this exact file: the base collection's getblock, getblockheader,
and getblockstats all return confirmations and are all PARSE_BY_ARG/BLOCK_HASH

  • deterministic: true; so are this very add-on's own bb_getTx/bb_getTxSpecific
    (Blockbook tx objects also carry confirmations). If the confirmations-caching
    concern were disqualifying, it would have to disqualify those six methods too — it
    doesn't, so the spec's own precedent treats it as an acceptable tradeoff, and
    bb_getBlock is the one outlier.

Leaving bb_getBlock on DEFAULT doesn't make the provider's answer wrong, but it
makes Lava's own block-tracking wrong for it: every bb_getBlock call — including a
request for a genuinely historical height/hash — gets stamped as pertaining to
"latest" for QoS-sync-lag and data-reliability purposes. A request for block 500000
and a request for block 900000 both get attributed to the chain tip; cross-provider
DR comparison and freshness/lag scoring for this method are consequently measuring
the wrong thing whenever the requested block isn't actually the tip. That's the
opposite failure mode from the one the DEFAULT choice was meant to avoid.

Recommendation: switch bb_getBlock to the same shape already used for
bb_getRawBlock/bb_getFeeStats:

"block_parsing": { "parser_arg": ["0"], "parser_func": "PARSE_BY_ARG" },
"parsers": [
    { "parse_path": ".params.[0]", "parse_type": "BLOCK_HASH" },
    { "parse_path": ".params.[0]", "parse_type": "BLOCK_LATEST" }
]

If the team still wants to protect against stale-confirmations caching specifically
for this method, that's a caching-TTL/response-field concern to raise with the
smart-router side, not a reason to misreport the tracked block on the spec side.

Confidence: PLAUSIBLE — I could not live-probe bb_getBlock (no Blockbook-backed
keyless upstream exists per the probe report), so this is based on QuickNode's
documented request/response shape plus the spec's own internal precedent, not a live
divergence observed on the wire.


2. [MINOR] bb_getXPUB and bb_getBalanceHistory look like "full scan" operations priced and timed like simple reads

File: btc.json, blockbook add-on collection (~line 801-814, ~line 1006-1020).

bb_getXPUB derives and checks balances/UTXOs across an entire HD-wallet address
space (gap-limit address derivation + scan), and bb_getBalanceHistory aggregates an
address's balance across a date range. Both are priced at the same 20 CU as a plain
bb_getTx/bb_getBlock lookup, and neither carries a timeout_ms override. The base
collection already treats its one comparable full-scan operation differently:
gettxoutsetinfo is 500 CU with timeout_ms: 180000. If bb_getXPUB/
bb_getBalanceHistory turn out to be similarly heavy on a real Blockbook backend
(untestable here — see probe report, blockbook is NOT_TESTABLE on both available
upstreams), the default request timeout could kill large-wallet/long-range queries
before the provider finishes, and 20 CU would under-price the work relative to the
guide's "heavy ops / full scan" tier (500-5000 CU).

Recommendation: not a blocker, but worth a benchmarking pass against a real
Blockbook-enabled node before/soon after this add-on gets its first live provider, per
the guide's "benchmark when uncertain" rule — specifically response time for an XPUB
with a long derivation history and a wide bb_getBalanceHistory date range.

Confidence: PLAUSIBLE — reasoning from the methods' documented behavior and the
spec's own precedent for its one analogous heavy op; no live measurement available.


3. [MINOR] BTCT (testnet3) inherits mainnet's average_block_time (600000ms) despite testnet3's well-known difficulty-reset bursts

File: btc.json, BTCT spec entry (~line 1437) — no average_block_time
override; inherits 600000 from BTC.

Not part of this PR's diff (pre-existing), but visible while reviewing the whole file
and directly evidenced by the probe: a live 1000-block empirical measurement against
bitcoin-testnet-rpc.publicnode.com landed at ~28,991ms/block (−95.2% vs. the inherited
600000ms), consistent with testnet3's documented behavior of resetting difficulty to
minimum after any 20-minute gap and then mining bursts of near-instant blocks. BTCT4
and BTCS (no such reset rule) both landed within 10% of the inherited default and are
fine as-is. A single 1000-block sample is inherently noisy for a chain with this
bursty behavior, so this is a judgment call rather than a hard defect: either leave
BTCT on the mainnet-inherited value (defensible, since testnet3's "true" average over
a long window is closer to 600000ms outside of reset bursts) or give BTCT its own
lower average_block_time/allowed_block_lag_for_qos_sync reflecting its real-world
burst-prone cadence. Flagging for a conscious decision, not requesting a specific
number.

Confidence: PLAUSIBLE — single empirical sample, chain-behavior-driven, not a
parsing or config bug.


Summary

  • Endpoints reviewed: all 30 base-collection jsonrpc APIs, all 8 blockdaemon add-on
    APIs, all 15 new blockbook add-on APIs (the PR's actual scope), all 13 REST GET
    APIs and 3 REST POST APIs, across BTC, BTCT, BTCT4, and BTCS.
  • Gaps by severity: CRITICAL = 0, MEDIUM = 1, MINOR = 2.
  • Removed-field / envelope hygiene: clean (Phase 0 guard passed; canonical
    {proposal:{specs:[...]}} envelope; no removed fields anywhere in the file).
  • Readiness: the blockbook add-on's opt-in layout, inheritance into the three
    testnets, and its enabled verification are all sound and boot-verified clean per
    the probe. The one correctness item worth resolving before/soon after this ships is
    bb_getBlock's block-parsing choice (Disable data reliability feature #1) — it doesn't block boot or break the base
    collection, but it does mean the add-on's own historical-block requests get
    misattributed to "latest" for tracking purposes once a real Blockbook provider is
    online. Nothing here blocks merging on its own.

Reviewer 2 — findings

Findings

MEDIUM — bb_getAddress and bb_getXPUB ignore the fromHeight/toHeight block-range filter, mis-tagging historical queries as "latest"

  • File/lines: btc.json:785-799 (bb_getAddress), btc.json:1006-1020 (bb_getXPUB)
  • Evidence: Both APIs are configured "block_parsing": {"parser_arg": ["latest"], "parser_func": "DEFAULT"}. Per QuickNode's Blockbook docs (fetched live): bb_getAddress (https://www.quicknode.com/docs/bitcoin/bb_getaddress) and bb_getXPUB (https://www.quicknode.com/docs/bitcoin/bb_getxpub) both take an optional second parameter object with fromHeight/toHeight integer fields that explicitly bound the returned transaction history to a historical block range — the same shape as eth_getLogs's toBlock field, which the spec guide explicitly calls out as a PARSE_CANONICAL case (["0", "toBlock"]).
  • Impact: When a consumer calls either method with a historical toHeight (e.g. toHeight: 500000 while the chain is at block 974681), the router still attributes/caches the response against the current latest block rather than the actual historical upper bound the response reflects. This degrades the data-reliability/caching bookkeeping Lava performs for the request (the response is deterministic for a given historical range but is tracked as if it were a volatile "latest" read), and is the same class of oversight the PR already fixed for bb_getRawBlock/bb_getFeeStats in 6290693 — just not caught for the two xpub/address-range methods.
  • Suggested fix: Add a parsers entry (or a PARSE_CANONICAL block_parsing) targeting ["1", "toHeight"] so a historical-range call is correctly attributed to its requested upper block, mirroring how eth_getLogs handles toBlock.

MEDIUM — sendrawtransaction/submitpackage (base collection) still lack the timeout_ms fix this PR applied to bb_sendTransaction

  • File/lines: btc.json:441-456 (sendrawtransaction), btc.json:457-472 (submitpackage)
  • Evidence: Both are "stateful": 1, "hanging_api": true with no timeout_ms field at all. Commit e466747 in this same PR series ("fix(btc): give bb_sendTransaction an explicit timeout_ms") added "timeout_ms": 10000 to bb_sendTransaction (btc.json:1030) specifically because an unbounded hanging+stateful API risks hanging indefinitely against a slow/broken provider.
  • Impact: The identical risk the PR fixed for bb_sendTransaction is still present, unaddressed, in the two native broadcast methods that sit right next to the add-on this PR touched. Since the PR was already in this exact area of the spec fixing this exact bug class, this is a reasonable in-scope catch rather than unrelated pre-existing debt.
  • Suggested fix: Add an explicit timeout_ms (e.g. matching the 10000 used for bb_sendTransaction) to sendrawtransaction and submitpackage.

MINOR — bb_getTickers' optional block field is ignored by block parsing

  • File/lines: btc.json:931-945
  • Evidence: Configured DEFAULT ["latest"], deterministic: false. Per QuickNode docs (https://www.quicknode.com/docs/bitcoin/bb_gettickers, fetched live), the single object parameter accepts an optional block integer field: "Return fiat rates as of the specified block height." bb_getMultiTickers/bb_getTickersList were checked too and only take timestamp (no block field), so this is specific to bb_getTickers.
  • Impact: Same gap class as the bb_getAddress/bb_getXPUB finding above but on a lower-traffic, secondary-feature endpoint (fiat-rate-as-of-block lookups) — a historical block-pinned ticker query is deterministic but gets tracked as a volatile "latest" read.
  • Suggested fix: PARSE_CANONICAL on ["0", "block"] when present, same pattern as above.

MINOR — bb_getBalanceHistory compute_units may be underpriced for its aggregation cost

  • File/lines: btc.json:800-814
  • Evidence: compute_units: 20 (the guide's "Block/transaction queries" tier). Per QuickNode docs (https://www.quicknode.com/docs/bitcoin/bb_getbalancehistory, fetched live), the call supports a from/to Unix-timestamp range plus a groupBy interval, i.e. a time-bucketed aggregation scan over the address's full history — structurally closer to the guide's "Complex queries (getLogs, estimateGas): 60-100 CU" tier than a simple single-record lookup.
  • Impact: Low — a pricing/economics nit, not a correctness bug. Flagged for consideration since the guide explicitly calls out range/aggregation queries as warranting a higher tier than flat reads.
  • Suggested fix: Consider 60 CU to align with the getLogs-style aggregation tier, or leave as-is if benchmarking shows the underlying Blockbook index makes this cheap in practice.

Items considered and explicitly NOT flagged

  • bb_getBlock keeping DEFAULT ["latest"] instead of PARSE_BY_ARG — per the PR's stated rationale (avoiding long-caching the time-dependent confirmations field) and QuickNode docs confirming the first positional param does accept either height or hash. Agreed with the reasoning; not re-flagged.
  • bb_getRawBlock/bb_getFeeStats PARSE_BY_ARG ["0"] + [BLOCK_HASH, BLOCK_LATEST] — verified this exactly mirrors the pre-existing, already-proven native getblockstats pattern in the base collection (same parser pair, same order), confirming BLOCK_LATEST resolves to a real height/hash before the call reaches the provider rather than forwarding the literal string. No issue.
  • blockbook/blockdaemon add-ons having empty parse_directives: [] — correct; GET_BLOCKNUM/GET_BLOCK_BY_NUM are spec-level (tracked once via the base add_on: "" collection), add-on collections don't need their own, matching the established ETH1 debug/trace pattern.
  • Testnet inheritance of blockbook/blockdaemon via automatic (undefined-collection) inheritance into BTCT/BTCT4/BTCS — correct and intentional; the enabled verification's wildcard expected_value: "*" and genesis-height ("0") probe work identically across mainnet/testnet/signet with no per-network override needed.
  • All -32601/HTTP 401 probe results on bb_*/bd_*/rest — free-tier/gateway limitation per the task's settled rule, not disabling evidence.
  • CU, category, and parser consistency for the other 13 bb_* methods (bb_getBlockHash, bb_getEstimateFee, bb_getMultiTickers, bb_getTickersList, bb_getTx, bb_getTxSpecific, bb_getUTXOs, bb_sendTransaction) — checked against QuickNode docs and the base-collection CU reference points; no parameter shape implies an unhandled block reference, and CU/category/timeout values are internally consistent with analogous native methods.

Summary

  • Endpoints reviewed: 15 new bb_* Blockbook methods (full detail) + the pre-existing base jsonrpc (31 methods), blockdaemon add-on (8 methods), and REST collections (spot-checked for consistency, no new findings).
  • Gaps found: 0 CRITICAL, 2 MEDIUM, 2 MINOR.
  • Readiness: No blocking/critical defects. The two MEDIUM items are correctness nits in the data-reliability/QoS bookkeeping layer (not functional breakage — the opt-in add-on boots cleanly and the probe report shows no live failures attributable to this PR), so the spec is deployable as-is; fixing the block-range parsing gap on bb_getAddress/bb_getXPUB before/shortly after merge is recommended but not a merge-blocker.

Reviewer 3 — findings

Findings

1. [MEDIUM] bb_getBlock's deterministic: true contradicts the PR's own stated reason for keeping DEFAULT block parsing

Evidence: btc.json, blockbook add-on collection, bb_getBlock:

{
  "name": "bb_getBlock",
  "block_parsing": {"parser_arg": ["latest"], "parser_func": "DEFAULT"},
  "compute_units": 20,
  "category": {"deterministic": true, "stateful": 0}
}

The accepted rationale for keeping bb_getBlock on DEFAULT (rather than switching it to
PARSE_BY_ARG + BLOCK_HASH/BLOCK_LATEST the way bb_getRawBlock/bb_getFeeStats were
fixed in 6290693) is that a height-keyed parse would long-cache a response whose
confirmations field is time-dependent — i.e., the same request made at two different times
returns two different payloads. That is, by definition, the opposite of
deterministic: true ("API returns same result for same block ... every time", per the spec
guide's Phase 4b). The same reasoning and the same risk apply to bb_getTx and
bb_getTxSpecific, which also use DEFAULT + deterministic: true and (per Blockbook's
standard tx-response shape) also carry a confirmations field.

Impact: if Lava's data-reliability engine performs full-response equality checks across
providers for deterministic: true APIs, two otherwise-correct Blockbook providers queried a
few seconds apart will almost always disagree on confirmations and fail cross-provider
consensus — a false-positive reliability failure baked into the spec itself, worst for recently
mined blocks/transactions where confirmations churn fastest. This is not a new pattern in this
file (native getblock/getblockheader/getrawtransaction carry the same inconsistency), but
bb_getBlock is the one place in this PR's diff where the author explicitly reasoned about the
time-dependent field and still left deterministic: true standing, so it's worth a second look
here specifically: either flip bb_getBlock/bb_getTx/bb_getTxSpecific to
deterministic: false, or confirm (and ideally note in-repo) that the DR engine already
excludes known-volatile fields like confirmations from its comparison, in which case the flag
is fine as-is and this can be closed as a documentation gap rather than a behavior bug.

2. [MINOR] bb_sendTransaction got an explicit timeout_ms; the two analogous base-collection hanging stateful APIs did not

Evidence: e466747 added "timeout_ms": 10000 to bb_sendTransaction specifically because
it is stateful: 1 + hanging_api: true. The base jsonrpc collection's sendrawtransaction
and submitpackage carry the identical category shape (stateful: 1, hanging_api: true)
but neither has a timeout_ms override — they still rely on the router default.

Impact: low risk (the default timeout may well be adequate for a bitcoind p2p broadcast),
but it's an inconsistency this PR introduced the fix pattern for and didn't backport: if the
router default timeout was judged too short/long for bb_sendTransaction's broadcast-and-wait
semantics, the same judgment likely applies to sendrawtransaction/submitpackage, which share
the same hanging_api behavior against the same underlying network.

3. [MINOR] bb_* method names/response-field paths could not be independently verified — no API docs available

Evidence: $1 (API docs path) was empty for this run, and per the probe report, both
keyless upstreams are plain bitcoind (not Blockbook-backed), so none of the 15 bb_* methods
could be positively exercised against a live Blockbook backend either.

Impact: this review cross-checked the bb_* surface against general knowledge of
Blockbook's JSON/HTTP API shape (e.g., bb_getBlockHash → {"blockHash": "..."}, matching the
enabled verification's PARSE_CANONICAL ["0","blockHash"]) and against the file's own git
history (8535453/a4c9e1a/6290693), but could not confirm exact method-name casing or
parameter/response shapes for several methods (bb_getXPUB, bb_getMultiTickers,
bb_getTickers, bb_getTickersList, bb_getBalanceHistory) against an authoritative
QuickNode/Blockbook reference. Flagged as a completeness limitation per Phase 3 of the spec
guide, not as a defect — per the free-tier/no-positive-evidence rule, this is not a basis to
disable any of these methods.

4. [MINOR] blockbook's enabled verification confirms the add-on responds, not that it's on the right chain/network

Evidence: the blockbook collection's only verification is:

{
  "name": "enabled",
  "parse_directive": {... "api_name": "bb_getBlockHash" ...},
  "values": [{"expected_value": "*"}]
}

a wildcard match that only proves bb_getBlockHash(["0"]) returns some blockHash. There is
no chain-identity check scoped to the blockbook collection itself (e.g., verifying the genesis
hash at height 0 equals the real BTC mainnet genesis hash, rather than accepting any non-empty
string).

Impact: a misconfigured Blockbook backend pointed at the wrong network (say, a Bitcoin
testnet Blockbook instance mistakenly registered against the BTC mainnet spec) would pass the
enabled check since it legitimately returns a blockHash for height 0 — just the wrong
chain's. This mirrors the pre-existing blockdaemon add-on's identical enabled-only pattern
(not introduced by this PR), so it's a missed opportunity rather than a regression, but this PR
restructured the add-on specifically to give it "its own enabled verification" and could have
tightened it (e.g., pin expected_value to BTC mainnet's actual genesis hash) while doing so.

5. [MINOR / informational] BTCT (testnet3) average_block_time is empirically far off the inherited mainnet default

Evidence: probe report Step 8 — BTCT empirical block time 28991ms vs. the spec's
600000ms (inherited from BTC, re-declared verbatim in BTCT), a −95.2% drift, attributed to
testnet3's well-known difficulty-reset-driven burst-mining behavior rather than a parse/config
defect. BTCT4 (−9.8%) and BTCS (−1.4%) both track the 600000ms default closely.

Impact: average_block_time feeds allowed_block_lag_for_qos_sync (QoS freshness
threshold) and indirectly the perceived finality window; a value this far from testnet3's
observed real-world cadence makes QoS lag scoring on BTCT specifically unreliable (either too
lax during 20-minute-gap resets or too strict during normal cadence). Not a hard defect — the
probe report itself frames this as a judgment call for the spec maintainer rather than a bug —
but flagged here as a candidate follow-up specific to BTCT, not the other two testnets.

6. [MINOR] blockbook (like blockdaemon) has no collection-scoped GET_BLOCKNUM/GET_BLOCK_BY_NUM

Evidence: the blockbook collection's parse_directives array is []; these function tags
only exist in the base (add_on: "") jsonrpc collection, and per the spec's merge semantics,
ParseDirectives only merge within a matching CollectionData (same add_on), so the
blockbook collection does not inherit the base collection's GET_BLOCKNUM/GET_BLOCK_BY_NUM.

Impact: there is no independent freshness tracking for the Blockbook surface itself; if a
Blockbook indexer backend lags behind the underlying node it's indexing (a realistic scenario —
Blockbook indexing is asynchronous relative to the node), Lava has no collection-local signal to
detect that lag via this add-on's own GET_BLOCKNUM. This exactly mirrors the pre-existing
blockdaemon add-on (not a regression introduced here), so it's carried as a minor
observation rather than a blocking finding — but worth noting since this PR was an opportunity
to close the gap for the new add-on rather than repeat it.

Summary

  • API methods reviewed: 15 bb_* methods (primary PR scope) + the pre-existing 32 base
    jsonrpc methods, 8 bd_* methods, and 16 REST endpoints (reviewed for consistency/regressions
    but out of this PR's direct diff).
  • Gaps found: 0 CRITICAL, 1 MEDIUM, 5 MINOR.
  • Readiness: the bb_* add-on addition is structurally sound — correctly isolated as an
    opt-in add-on collection with its own enabled verification, boots cleanly with no supporting
    upstream (confirmed NOT_EXERCISED, not FAIL), and the 6290693 block-parsing fix for
    bb_getRawBlock/bb_getFeeStats is correct and consistent with the file's existing
    BLOCK_HASH/BLOCK_LATEST dual-parser convention (e.g. getblockstats). The one MEDIUM
    finding (determinism flag vs. the PR's own stated time-dependent-field reasoning) is worth a
    decision before merge but isn't a boot-blocker or a correctness regression visible to
    consumers today, since the addon is unexercised on any currently configured upstream. Ready
    to ship from a structural standpoint; the MEDIUM finding and the timeout_ms /
    enabled-verification consistency MINORs are good candidates for a fast-follow.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 10 — synthesize gaps + fix pass (+ Phase 10b smoke re-probe)

Consolidation: 0 critical, 2 medium; 0 disable-suggestions stripped. Nothing needed stripping — no reviewer proposed a disable, so the free-tier filter had no work to do this run. Both surviving gaps were applied; the fix touches 3 fields across 7 insertions / 5 deletions, all inside the BTC entry's blockbook add-on collection.

Applied

# severity change why
1 MEDIUM bb_getAddress + bb_getXPUB .block_parsing: DEFAULT ["latest"] → PARSE_CANONICAL ["1","toHeight"] Both take [address, {…, fromHeight, toHeight, …}], so a historical range query was being parsed as "latest". I verified the in-repo precedent before allowing it: eth_getLogs uses PARSE_CANONICAL ["0","toBlock"] for the identical shape — an optional nested upper-bound block field on an options object — in ethereum.json and several other specs. Index 1 rather than 0 because the options object is the second param.
2 MEDIUM bb_getBlock .category.deterministic: true → false bb_getBlock's response carries confirmations at block level and in every txs[] entry, which legitimately differs between two correct upstreams queried moments apart. deterministic feeds cross-validation mismatch alerting, so true here invites false alerts. This is a different axis from the block-parsing decision below — per the human review, deterministic does not control caching.

Dropped, with reasons

  • bb_getBlock → PARSE_BY_ARG (reviewer 1, MEDIUM) — dropped as contradicted by better analysis. Reviewers 1 and 3 reached opposite conclusions about the same deliberate decision, so it was resolved against the human review on this PR: with PARSE_BY_ARG, a height-keyed request ≥block_distance_for_finalized_data (6) deep enters the long-TTL cache, which would pin bb_getBlock's time-dependent confirmations at its first-call value forever; a hash-keyed request is never cached (NOT_APPLICABLE skips the write). That is precisely why bb_getRawBlock (returns only hex) and bb_getFeeStats (fixed per-block aggregates) correctly moved to PARSE_BY_ARG in 6290693 while bb_getBlock kept DEFAULT ["latest"]. The decision stands; reviewer 3's deterministic point was the live half of it and was applied as fix feat: Strknt spec v9 #2.
  • Base-collection sendrawtransaction / submitpackage missing timeout_ms (reviewers 2 + 3) — reported, not fixed. Auto-decision at a gate, conservative default: these fail identically on main (verified via git show origin/main:btc.json), and check_hanging_api.sh --base classifies them === INFO === [pre-existing: the base fails this row identically], exit 0 — explicitly non-blocking. Fixing them would widen a Blockbook add-on PR into an unrelated base-collection change. Follow-up below. Worth noting the guard caught a third instance all three reviewers missed: the rest POST /tx/send.
  • BTCT (testnet3) average_block_time override — not applied. Auto-decision at a gate, conservative default. Phase 8 measured −95.2% drift, but that is testnet3's documented 20-minute difficulty-reset behaviour (difficulty drops to the network minimum and blocks arrive seconds apart until it readjusts), so a different 1000-block window would read very differently and pinning 28991ms would be wrong most of the time. Both reviewers who raised it rated it MINOR/informational, not MEDIUM. Editing an unrelated pre-existing testnet parameter off one unrepresentative sample is not something this PR should do; recorded as a follow-up instead.

Phase 10a — offline static gates re-run after the fixer

All green, no FAIL rows:

check_method_schema   PASS (75/75 rows schema ok)
check_unused_fields   RESULT: PASS (no removed fields)
check_hanging_api     PASS + 3 INFO rows (all [pre-existing], exit 0)
check_stateful        PASS (no INFO, no FAIL)
check_disabled_count  0 distinct methods disabled — matches the PR body's <!-- disabled-count: 0 --> marker
jq                    exit 0

Disabled-API Justifications: none — no API, addon or collection is disabled in this spec, and this pass disabled nothing. The 15 bb_* / 8 bd_* methods that could not be exercised remain enabled: true, which is the correct outcome under the free-tier rule.

No removed-model field was introduced: the spec remains the canonical { "proposal": { "specs": [ … ] } } envelope with compute_units as the only compute-unit input and no category.subscription anywhere.

Phase 10b — smoke re-probe: ✅ SMOKE: OK

Re-booted the dockerized smart-router (:latest, digest sha256:476faaac…) against the fixed spec and re-probed the deterministic 7-item set. No regressions.

# probe Phase 8 Phase 10b
1 GET_BLOCKNUM (getblockcount) PASS PASS (974682)
2 chain-id (getblockchaininfo) PASS PASS (chain: "main")
3 createrawtransaction PASS PASS
4 decoderawtransaction PASS PASS
5 decodescript PASS PASS
6 estimatesmartfee PASS PASS
7 getbestblockhash PASS PASS

Post-fix verdicts: PARSE: PARTIAL (unchanged — same "reason":"off-operator-choice" fork-detection gate, not a spec defect) · VERIFY: OK (chain-id 2/2 upstreams) · ADDONS: 0 tested-ok / 0 failed / 2 not-testable (unchanged).

The regression surface that mattered was spec resolution, not probe results — all three edited methods live in the blockbook add-on, which no available upstream supports, so they cannot be exercised through the router. What the re-boot proves is that the router still loads and resolves the spec graph with the new PARSE_CANONICAL block parsing: no PARSE_SIG lines, no spec-resolution error, clean boot, and the blockbook add-on's enabled verification still correctly comes back NOT_EXERCISED rather than FAIL.

Follow-ups (not in this PR)

  1. Give the base collection's sendrawtransaction, submitpackage and rest POST /tx/send an explicit timeout_ms — pre-existing on main, all three.
  2. Re-probe the 15 bb_* and 8 bd_* methods against a Blockbook-enabled / Blockdaemon-keyed node; this run could only reach keyless bitcoind upstreams.
  3. Consider whether BTCT warrants a looser average_block_time, if the drift recurs across multiple sampling windows.
  4. The bb_getBlock deterministic reasoning applies to its siblings too (bb_getTx, bb_getTxSpecific, and the base getblock) — worth a consistency pass.

btc.json — Consolidated Fix List (Phase 10 consolidation)

Sources: docs/btc/SPEC_REVIEW_GAPS_parallel_{1,2,3}.md (reviewer tallies: R1
CRITICAL=0/MEDIUM=1/MINOR=2, R2 CRITICAL=0/MEDIUM=2/MINOR=2, R3
CRITICAL=0/MEDIUM=1/MINOR=5 — no CRITICALs raised by anyone) and
docs/btc/METHOD_PROBE_REPORT.md (Phase 8 re-probe of commit 6290693).
Deduplicated by (gap_title, evidence_line_number). Target file for the actual
edits: btc.json (NOT modified by this document — consolidation only).

Disable-suggestion filter: 0 stripped. None of the three reports suggested
setting enabled: false on, or removing, any method/addon/collection on the
basis of probe results. All three reports explicitly treat the -32601/401
probe outcomes on bb_*/bd_*/rest as free-tier/gateway artifacts and
state outright that this is not evidence to disable anything — consistent
with the hard rule, so there was nothing to strip.


Fix list (CRITICAL + MEDIUM)

# Severity Gap title File / JSON path Change Evidence
1 MEDIUM bb_getAddress / bb_getXPUB ignore the fromHeight/toHeight historical range filter btc.json, blockbook add-on collection — bb_getAddress (lines 786-799) and bb_getXPUB (lines 1007-1020), field .block_parsing Switch both from {"parser_arg": ["latest"], "parser_func": "DEFAULT"} to {"parser_arg": ["1", "toHeight"], "parser_func": "PARSE_CANONICAL"}, mirroring the repo's own eth_getLogs ["0","toBlock"] pattern (SPEC_GUIDE.md lines ~716-724, 2052-2055) — same shape (optional nested field on a filter/options object, absent on most calls, upper-bound block reference), just at params index 1 instead of 0 since bb_getAddress/bb_getXPUB take [address, {options}] rather than [{filter}]. R2 SPEC_REVIEW_GAPS_parallel_2.md:27-32. Verified independently via QuickNode docs during consolidation: bb_getAddress (quicknode.com/docs/bitcoin/bb_getaddress) and bb_getXPUB (.../bb_getxpub) both confirm fromHeight/toHeight as integer fields nested in the optional second params-array object (params: [address, {page, size, fromHeight, toHeight, details, ...}]) — matches R2's claim exactly (field names, not from/to). PARSE_CANONICAL with an arbitrary non-zero index is an established, working pattern in this repo (getrawtransaction's parser_arg: ["2"], eth_getBalance's ["1"]), and the field being optional/usually-absent mirrors eth_getLogs's toBlock, which already works this way in-repo. Introduced-by-PR: yes, both methods are new in this PR.
2 MEDIUM bb_getBlock's category.deterministic: true risks false cross-provider mismatch alerts btc.json, blockbook add-on collection, bb_getBlock (lines 816-829), field .category.deterministic true → false. R3 SPEC_REVIEW_GAPS_parallel_3.md:37-69. Verified against the human reviewer's analysis (gh pr view 202 comment by Tomelia1999): "category.deterministic is read only for cross-validation mismatch alerting. It doesn't control caching" — so this is a distinct axis from the DEFAULT ["latest"] block-parsing decision (see Dropped #1 below), and QuickNode's own bb_getBlock docs confirm confirmations is present at block level and in every txs[] entry, a value that legitimately differs between two otherwise-correct upstreams queried moments apart. Per SPEC_GUIDE.md:53, deterministic means "returns the same result when called twice ... (enables data reliability checks)" — a time-varying confirmations field breaks that for cross-provider comparison. Introduced-by-PR: yes, bb_getBlock is new in this PR.

No CRITICALs were raised by any reviewer and none survived the merits review as CRITICAL; the fix list is MEDIUM-only.


Dropped

# Gap Source Reason
1 bb_getBlock should switch to PARSE_BY_ARG ["0"] to match bb_getRawBlock/bb_getFeeStats R1 SPEC_REVIEW_GAPS_parallel_1.md:24-86 Contradicted by better analysis. Per the human reviewer (Tomelia1999 PR comment, fetched via gh pr view 202), this was already the explicit, deliberate decision: "Keep DEFAULT ["latest"]. With PARSE_BY_ARG, a request by height would long-cache confirmations (block and per-tx) at the value from the first call. getblock avoids this only because it takes a hash, which is never cached." bb_getRawBlock (only hex) and bb_getFeeStats (fixed per-block aggregates) carry no time-dependent fields, so long-caching them is safe; bb_getBlock does carry confirmations, so it isn't. R1's own file-wide precedent argument (that getblock/getblockheader/getblockstats already accept this "tradeoff") doesn't apply the same way: those are hash-keyed PARSE_BY_ARG, which per the router source never caches a hash-keyed request (BLOCK_HASH → NOT_APPLICABLE skips the cache write) — so there's no stale-cache exposure there, whereas a height-keyed bb_getBlock would be cached long-TTL once block_distance_for_finalized_data deep. Standing decision kept as-is.
2 sendrawtransaction/submitpackage (base collection) lack timeout_ms, unlike bb_sendTransaction R2 SPEC_REVIEW_GAPS_parallel_2.md:34-39 (MEDIUM) and R3 SPEC_REVIEW_GAPS_parallel_3.md:71-82 (MINOR) — same underlying gap, two severities, consolidated Pre-existing on main, not to be fixed in this PR (orchestrator-resolved, not re-litigated). Verified via git show origin/main:btc.json: sendrawtransaction (main line 442), submitpackage (main line 458) carry stateful: 1, hanging_api: true with no timeout_ms on main already, identical to this branch. The rest POST /tx/send (main line 1108, this branch btc.json:1398-1412) shares the exact same shape and was missed by all three reviewers. check_hanging_api.sh --base classifies all three as === INFO === [pre-existing: the base fails this row identically], exit 0 — non-blocking. Conservative default: report, don't widen this PR's diff. Moved to Watch-list.
3 bb_getAddress/bb_getXPUB/bb_getBalanceHistory full-history scans priced/timed like simple reads — (would've been inferred from R1 #2 + R2's underpricing note) Not dropped for being wrong — see Watch-list; kept as MINOR, not promoted, since it's explicitly benchmarking-contingent ("not a blocker... worth a benchmarking pass") rather than a concrete, provable defect, and both source reports themselves frame it as non-blocking.

No gap asked for any of the 15 removed model fields (min_stake_provider, providers_types, contributor, contributor_percentage, shares, identity, block_last_updated, reliability_threshold, data_reliability_enabled, proposal.title, proposal.description, top-level deposit, extra_compute_units, category.local, category.subscription) or proposed marking anything a subscription other than via FUNCTION_TAG_SUBSCRIBE; nothing needed dropping on that basis.


Watch-list

MINOR gaps (kept as MINOR, not applied)

# Gap Source Evidence
1 bb_getXPUB/bb_getBalanceHistory priced/timed like simple reads despite being full-scan/aggregation ops R1 :90-113, R2 :48-53 (dup topic, consolidated) 20 CU, no timeout_ms override, vs. the base collection's one comparable full-scan op gettxoutsetinfo (500 CU, timeout_ms: 180000). bb_getBalanceHistory's from/to + groupBy time-bucketed aggregation is structurally closer to the guide's 60-100 CU "complex query" tier. Non-blocking per both reports; needs a benchmarking pass against a real Blockbook backend — untestable in this probe round (blockbook = NOT_TESTABLE both upstreams). Tomelia1999's PR comment notes QuickNode bills the whole Blockbook add-on at a flat per-call rate regardless of method weight, which cuts against re-pricing on CU grounds alone.
2 bb_getTickers's optional block field ignored by block parsing R2 :41-46 DEFAULT ["latest"], deterministic: false; QuickNode docs confirm an optional block integer field ("fiat rates as of the specified block height"). Same gap class as fix-list #1 but lower-traffic/secondary; not promoted to the fix list to keep this round's diff minimal, flagged for a fast-follow alongside #1 above if the team wants full consistency.
3 sendrawtransaction/submitpackage//tx/send missing timeout_ms R2 :34-39 (MEDIUM), R3 :71-82 (MINOR) See Dropped #2 — pre-existing on main (verified via git show origin/main:btc.json), follow-up only, not this PR's diff.
4 bb_* method names/response shapes could not be independently verified (no API docs path given this run) R3 :84-98 Completeness/confidence caveat, not a concrete defect; per the free-tier/no-positive-evidence rule this is not a basis to disable anything.
5 blockbook's enabled verification only checks that bb_getBlockHash(["0"]) returns some blockHash (wildcard "*"), not that it's BTC mainnet's actual genesis hash R3 :100-121 Mirrors the pre-existing blockdaemon add-on's identical pattern (not a regression introduced here); a missed opportunity when this PR gave the add-on "its own" verification, but not a regression. Candidate fast-follow: pin expected_value to BTC mainnet's real genesis blockHash.
6 blockbook add-on has no collection-scoped GET_BLOCKNUM/GET_BLOCK_BY_NUM parse_directives R3 :137-150 blockbook.parse_directives == []; per spec merge semantics, directives don't cross add_on boundaries, so there's no independent freshness signal for a Blockbook indexer lagging its underlying node. Mirrors the pre-existing blockdaemon add-on identically (not a regression), carried as a non-blocking observation.
7 BTCT (testnet3) inherits mainnet's average_block_time (600000ms) despite empirically measuring ~28,991ms/block (−95.2%) during the Phase 8 probe R1 :116-136, R3 :123-135 (dup topic/same underlying evidence, consolidated) METHOD_PROBE_REPORT.md Step 8: BTCT measured 28991ms vs. spec 600000ms, attributed to testnet3's documented difficulty-reset burst-mining behavior (20-min-gap resets → rapid-fire low-difficulty blocks), landing the 1000-block sample inside a burst — not a parse/config bug. BTCT4 (−9.8%) and BTCS (−1.4%) both track the default closely and need no change. Both source reports and the probe report itself frame this as a judgment call for the spec maintainer, not a defect; feeds allowed_block_lag_for_qos_sync/QoS freshness scoring on BTCT specifically. Flagged as a conscious-decision follow-up, no specific number recommended.

Stripped disable-suggestions

None. 0 stripped — see filter note above.

Pre-existing follow-ups (explicitly out of this PR's scope)

# Item Evidence
1 Base-collection sendrawtransaction/submitpackage and REST POST /tx/send carry category.hanging_api: true with no timeout_ms Orchestrator-resolved (not re-litigated here). Verified identical on main via git show origin/main:btc.json (lines 442, 458, 1108 respectively) and check_hanging_api.sh --base → === INFO === [pre-existing: the base fails this row identically], exit 0, non-blocking. Conservative default: report, don't widen this PR's diff.
2 Sibling deterministic: true + time-dependent confirmations field pattern exists elsewhere, both pre-existing and newly introduced Verified directly against btc.json during consolidation: base collection's getblock (lines 44-56), getblockheader (lines 170-182), and gettxout (lines 427-440) are all pre-existing, hash/latest-keyed, deterministic: true, and their responses carry confirmations — same shape fix-list #2 addresses for bb_getBlock, but pre-existing and out of this PR's diff. This PR's own bb_getTx (lines 962-975) and bb_getTxSpecific (lines 977-990) are new, DEFAULT ["latest"], deterministic: true, and (per standard Blockbook tx-response shape) also carry confirmations — identical risk profile to bb_getBlock, not flipped in this round to keep the fix list to the single item the merits review centered on. Recommended fast-follow: either extend fix-list #2's deterministic: false treatment to bb_getTx/bb_getTxSpecific, or resolve this as a systemic DR-engine policy decision (e.g., excluding known-volatile fields like confirmations from mismatch comparison) covering all five affected methods (3 pre-existing + 2 new) at once, rather than one field at a time.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 11 — final reviewer verdict: ✅ APPROVED

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0

A fresh-context reviewer re-reviewed btc.json as it stands on disk — including Phase 10's three uncommitted fixes — and re-derived each change from the file with jq/python3 rather than trusting the stated diff. It confirmed the diff is limited to exactly those three fields (7 insertions / 5 deletions) with no drift into the base collection, the blockdaemon add-on, either rest collection, or any of the three testnet entries.

It also independently verified the three settled decisions were applied as described and not conflated: bb_getBlock keeps DEFAULT ["latest"] block parsing with only deterministic moved to false; bb_getRawBlock/bb_getFeeStats carry PARSE_BY_ARG ["0"] with BLOCK_HASH/BLOCK_LATEST; the pre-existing hanging_api-without-timeout_ms trio is identical to main and correctly outside this PR's diff; BTCT defines no average_block_time override.

Disabled-API audit: 0 methods carry enabled: false, matching the <!-- disabled-count: 0 --> marker and the empty ledger. The reviewer did surface one thing worth recording — BTCS's two rest collections are enabled: false at the collection level. I verified this against origin/main: both are already disabled there, so it is pre-existing, outside this PR's diff, and independently justified in commit 892e976 ("BTCS cannot serve REST… Blockdaemon's supported-networks table lists bitcoin mainnet, testnet and testnet4 — no signet"). Not a discrepancy against the ledger, which covers method-level disables.

One honest caveat on what this verdict does not cover: the 15 bb_* methods have never been positively exercised by this pipeline. No keyless Blockbook-enabled upstream exists, so every bb_* probe returned -32601 or "No Providers For Addon". The approval rests on static review plus the human review of the block-parsing semantics against QuickNode's docs and the smart-router source — not on live Blockbook traffic. A pre-merge probe against a Blockbook-enabled node would close that gap.


btc.json — Final-Pass Spec Review (post Phase 10 fixes)

Reviewed: working-tree btc.json (uncommitted Phase 10 fixes on top of commit 6290693,
branch feat/btc-blockbook-methods, PR #202). git show HEAD:btc.json was not used as
the review target — it is stale relative to the three uncommitted fixes verified below.

Inputs read before this pass: docs/btc/METHOD_PROBE_REPORT.md (Phase 8 re-probe of
6290693) and docs/btc/FIX_LIST.md (Phase 10 consolidation: 2 MEDIUM fixes applied, 3
items dropped/resolved, 7 items watch-listed).

Phase 0 — Removed-field guard

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

jq empty btc.json — valid JSON. Canonical envelope confirmed ({"proposal":{"specs":[...]}},
no title/description/deposit).

Working-tree diff verification (re-derived independently, not trusted from the stated diff)

git diff --stat btc.json
 btc.json | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

Confirmed via git diff btc.json — exactly three field changes, all inside
BTC → blockbook add-on collection, nothing else touched:

# API Field Before After Verified in file
1 bb_getAddress block_parsing {"parser_arg":["latest"],"parser_func":"DEFAULT"} {"parser_arg":["1","toHeight"],"parser_func":"PARSE_CANONICAL"} ✅ landed exactly as specified
2 bb_getXPUB block_parsing {"parser_arg":["latest"],"parser_func":"DEFAULT"} {"parser_arg":["1","toHeight"],"parser_func":"PARSE_CANONICAL"} ✅ landed exactly as specified
3 bb_getBlock category.deterministic true false ✅ landed exactly as specified

Re-derived directly from the on-disk JSON with python3 -c 'json.load(...)' (not from the
diff text): all three APIs in the blockbook collection show the new values; no other API
in that collection, in the base collection, in blockdaemon, in either rest collection,
or in BTCT/BTCT4/BTCS differs from what the stated diff claims. No drift beyond the
documented 7 insertions / 5 deletions.

Settled decisions — verified applied as described

  • bb_getBlock keeps DEFAULT ["latest"] block parsing (reviewer 1's PARSE_BY_ARG
    suggestion was correctly dropped, not applied). Confirmed in file: bb_getBlock.block_parsing == {"parser_arg":["latest"],"parser_func":"DEFAULT"}. Only category.deterministic moved to
    false on this API — the two axes were not conflated. bb_getRawBlock and bb_getFeeStats
    both carry PARSE_BY_ARG ["0"] with BLOCK_HASH/BLOCK_LATEST parsers[] entries and
    deterministic: true, consistent with their fixed/no-time-dependent-field response shapes.
  • Base-collection sendrawtransaction/submitpackage and REST POST /tx/send: confirmed
    category.hanging_api: true with no timeout_ms on all three in the working tree, and
    git show origin/main:btc.json shows the identical shape on main — pre-existing, correctly
    left out of this PR's diff. Treated as informational only, not raised as a finding here.
  • BTCT keeps the inherited average_block_time: 600000 — confirmed no override is defined
    on the BTCT spec entry (average_block_time absent from BTCT's own JSON, inherited from
    BTC). Consistent with the testnet3 difficulty-reset-burst rationale; not flagged.

Disabled-API / disabled-collection audit

check_disabled_count.sh-equivalent query (.apis[]? | select(.enabled==false)) across all
four spec entries: 0 distinct methods, 0 rows. Matches the ledger's claim exactly
(<!-- disabled-count: 0 -->). Phase 10 disabled nothing at the API level.

One collection-level enabled: false pair exists, found by also checking collections (not just
APIs), as instructed:

Spec Collection enabled
BTCS rest / GET / add_on: "" false
BTCS rest / POST / add_on: "" false

This is pre-existing on main (git show origin/main:btc.json shows the identical pair,
byte-for-byte) and unrelated to this PR's diff — PR #202 touches only the blockbook
add-on collection, never BTCS's rest collections. It also carries its own positive-evidence
justification already in the repo's history, outside this round's ledger: commit 892e976
("fix(btc,bch): Phase 10 — correct the REST surface against Blockdaemon's own endpoint list")
states "BTCS cannot serve REST. Blockdaemon's supported-networks table lists bitcoin mainnet,
testnet and testnet4 — no signet... It now carries disabled rest stubs."
That is a
docs/client-source-backed justification (Blockdaemon's own endpoint list), just recorded in an
earlier commit message rather than in this round's ledger (which only tracks this PR's
blockbook work). Not a discrepancy against this round's ledger, and not introduced by Phase
10 — reported here for completeness only, not as a CRITICAL/MEDIUM finding.

No other enabled: false entries (API or collection) exist anywhere in btc.json.

Method-level spot checks (blockbook add-on, 15 APIs)

All 15 bb_* methods carry block_parsing, category, and compute_units; no duplicate
names; CU values (10 for bb_getBlockHash/bb_getEstimateFee/bb_sendTransaction, 20 for the
rest) mirror the base collection's own getblockhash=10 / getblock=20 precedent exactly.
bb_sendTransaction carries stateful: 1, hanging_api: true, timeout_ms: 10000 (fixed in
e466747, unchanged by this Phase 10 pass, still correct). The blockbook collection is
absent from BTCT/BTCT4/BTCS's own api_collections[], so all three testnet entries pick
it up via automatic Scenario-A inheritance through imports: ["BTC"] — confirmed, not
redefined anywhere in the three testnet entries.

Network parameters on BTC (and inherited unchanged on all three testnets): average_block_time: 600000, block_distance_for_finalized_data: 6, blocks_in_finalization_proof: 3,
allowed_block_lag_for_qos_sync: 1 — all consistent with Bitcoin's PoW/probabilistic-finality
model and the 10000/600000→1 floor formula.

Watch-list items (carried forward, not re-litigated, not re-raised as new findings)

Per the brief, these remain open follow-ups from FIX_LIST.md and are not elevated in this
pass: bb_getXPUB/bb_getBalanceHistory pricing vs. full-scan cost; bb_getTickers's ignored
block field; pre-existing sendrawtransaction/submitpackage//tx/send missing
timeout_ms; no independent doc verification of bb_* response shapes; blockbook's wildcard
enabled verification; no collection-scoped GET_BLOCKNUM/GET_BLOCK_BY_NUM on the
blockbook add-on; BTCT's inherited block time vs. its burst-mining empirical reading. Also
carried forward un-promoted: bb_getTx/bb_getTxSpecific share bb_getBlock's old
deterministic: true + confirmations-field risk profile but were deliberately left
unflipped this round (per FIX_LIST.md Pre-existing follow-ups #2) — noted again here for
visibility, not re-raised as a new finding since it was explicitly scoped out of this PR's
diff by the prior consolidation pass.

Findings

None survived verification. All three Phase 10 fixes landed exactly as specified, the diff is
byte-for-byte limited to those three changes (7 insertions / 5 deletions, nothing else), the
disabled-API ledger (0 methods) is accurate, the one collection-level disable predates this PR
and is independently justified in prior commit history, and every "settled decision" in the
brief (bb_getBlock's DEFAULT parsing, the hanging-API timeout gap, BTCT's block time) is
applied in the file exactly as described. No CRITICAL, MEDIUM, or MINOR gaps are being raised
in this final pass.

Summary

  • Endpoints reviewed: 15 bb_* methods in the blockbook add-on (direct focus of this
    PR) + spot-checks across the 34-method base collection, blockdaemon add-on, both rest
    collections, and all three testnet entries (BTCT, BTCT4, BTCS) for inheritance/drift.
  • Gaps by severity: CRITICAL = 0, MEDIUM = 0, MINOR = 0.
  • Verdict: Ready for deployment as-is. The three Phase 10 fixes are correctly applied, no
    new drift was introduced, and no disabled API/collection lacks justification.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

Phase 12 — closing summary checklist (tail of the Phase 8–11 span; ✓ verified this run, ~ partial, ☐ manual / out of scope)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a `jq` exit 0 + Phase 11 reviewer re-parse)
- ✓ All required fields present                          (Phase 10a check_method_schema: 75/75 rows ok)
- ✓ No duplicate API names within any collection         (check_method_schema)
- ✓ Proper indentation/formatting                        (surgical 4-space edit; 7 insertions / 5 deletions, no trailing-newline change)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (unchanged by this PR; BTC entry params verified against main)
- ~ All APIs tested and working                          (Phase 8: 30 PASS / 0 FAIL / 2 WARN / 3 SKIP / 0 UNPROBED on the base
                                                          collection. The 15 bb_* and 8 bd_* add-on methods are NOT_TESTABLE —
                                                          no keyless Blockbook/Blockdaemon upstream exists. See the caveat below.)
- ~ Block parsing validated for each API                 (Phase 8 existence-tested through the router; the three edited bb_*
                                                          methods resolve cleanly at boot but could not be exercised live)
- ✓ Parse directives executed by live router             (Phase 8 Step 3.5: PARSE=PARTIAL, VERIFY=OK; Phase 10b re-check:
                                                          PARSE=PARTIAL, VERIFY=OK — PARTIAL is the router's fork-detection
                                                          feature gate, not a spec defect)
- ~ Addons & extensions tested                            (Phase 8 Step 1c: 0 tested-ok / 0 failed / 2 not-testable —
                                                          blockbook and blockdaemon both need a supporting node to verify)
- ✓ Verifications pass on live nodes                     (chain-id OK 2/2 upstreams at Phase 8 and again at Phase 10b;
                                                          all three testnets verified)
- ☐ Compute units benchmarked under expected load        (user to measure)

#### 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                                (BTC entry; Blockbook add-on added by this PR)
- ✓ Testnet spec inherits correctly                      (BTCT / BTCT4 / BTCS import BTC; Phase 11 reviewer confirmed no drift)
- ✓ Chain IDs verified for mainnet AND testnet           (Phase 8: mainnet chain-id 2/2 upstreams; TESTNET_VERIFY: OK for
                                                          all three testnet indexes)
- ~ Both tested on respective networks                   (Phase 8 booted and verified all four variants; method probing was
                                                          mainnet-only, per Step 7 which is boot + verification only)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (canonical `{ "proposal": { "specs": [ … ] } }` envelope — no
                                                          title/description/deposit, no governance fields, verified by
                                                          check_unused_fields.sh)
- ☐ Community feedback gathered (if applicable)

The one caveat that should gate the merge

The 15 bb_* methods this PR adds have never been positively exercised. No keyless Blockbook-enabled upstream exists, so every probe returned -32601 (direct) or "No Providers For Addon" (through the router). Under the skill's free-tier rule that is correctly not evidence to disable anything — but it does mean the APPROVED verdict rests on static review plus the human review of block-parsing semantics against QuickNode's docs and the smart-router source, not on live Blockbook traffic. A probe against a Blockbook-enabled node before merge would close the gap.

What this run did establish that the earlier one could not: the opt-in add-on layout from a4c9e1a boots cleanly. That was the real risk of the refactor — the blockbook collection's enabled verification defaults to Fail severity, so an add-on no upstream supports could have excluded the provider at boot and taken the base collection down with it. It does not: the add-on is correctly left out of the router config, its verification comes back NOT_EXERCISED rather than FAIL, and base-collection routing and chain tracking are unaffected.

Decisions auto-taken at gates (conservative default, recorded)

  1. Pre-existing hanging_api without timeout_ms on sendrawtransaction, submitpackage and rest POST /tx/send — reported, not fixed. Identical on main; the guard classifies them non-blocking INFO. Fixing them would widen a Blockbook PR into an unrelated base-collection change.
  2. BTCT average_block_time override — not applied, despite a −95.2% empirical reading. That reading is testnet3's documented 20-minute difficulty-reset burst behaviour, not a steady-state rate; both reviewers who raised it rated it MINOR/informational.
  3. Reviewer 1's bb_getBlock → PARSE_BY_ARG — dropped in favour of the human review's caching analysis (a height-keyed request would long-cache the time-dependent confirmations). Reviewer 3's related deterministic point was the live half and was applied.

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

Elapsed:         00h 43m 55s  (first→last logged activity)
Transcripts:     1 main + 8 subagent
API round-trips: 528  (main=82, subagents=446)

Fresh tokens:    input=1056  output=344434  (sum=345490)
Cached tokens:   cache_read=45229892  cache_write=1981748
Total billed:    47557130 tokens

Split (total billed):  main=8988436  subagents=38568694

Models used:
  claude-sonnet-5         446 calls   38568694 billed
  claude-opus-5            84 calls   9291960 billed

These figures cover only Phases 8–11 in this run. They are not a 1–11 grand total: Phases 1–7 ran in the original create_spec job (and an earlier Phase 8–11 attempt ran before a4c9e1a/6290693 landed), each with its own time and token cost. The true total for this PR is those runs added together.

Retry

If anything here needs redoing, use the exact commands: /rerun-probe (Phase 8 only), /rerun-review (Phase 9), /rerun-fix (Phase 10 + 10b), /rerun-final (Phase 11), or /rerun-from <8|9|10|11> to run that phase through to the end. Re-probing bb_* against a Blockbook-enabled node would be /rerun-probe mainnet=<your-blockbook-url>.

@magmadevs-bot

Copy link
Copy Markdown
Contributor

📦 Committed pipeline fixes to feat/btc-blockbook-methods (d6f65a8): btc.json — the branch now matches the spec that Phase 10b/11 verified.

@idanhen1 idanhen1 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Reviewed d6f65a8. The diff adds only the blockbook JSON-RPC collection; existing BTC collections and network overrides remain unchanged. The write method is stateful and has an explicit timeout.

Independent validation: collection-addition, method-schema, verification, removed-field, node-admin and stateful guards passed. Using the released v1.6.6 binary with the current chart-rendered configuration and two loopback mock providers: 30/30 bb_* reads succeeded through the Blockbook-capable provider, with zero bb_* calls to the other provider; a failed add-on verification or an omitted add-on refused all 30 bb_* reads without falling back, while ordinary Bitcoin reads still worked through each provider.

This approval covers the spec change. The routing tests used mocked upstreams, not a purchased QuickNode Blockbook endpoint. The tenant rollout still requires the chart schema companion tracked in MAG-4971, explicit opt-in on the intended QuickNode endpoint, and positive read tests through the deployed customer hostname before announcing availability.

@Tomelia1999
Tomelia1999 merged commit 3d9c518 into main Nov 6, 2026
3 checks passed
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