Repository navigation
feat(btc): serve the Blockbook bb_* methods from a blockbook add-on (MAG-4824) - #202
Conversation
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>
|
🤖 Spec pipeline started on PR open — running Phase 8 → 11. Results post here as comments. View run |
|
Phase 8 — smart-router boot + multi-node method probe Resumable pipeline run (Phases 8–11). Endpoint source:
Upstreams probed (keyless, no credentials available to this run): The 15 new Auto-decisions recorded at STOP-and-ask gates (conservative default):
Two base-collection FAILs ( Full probe report (
|
| 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.
|
Phase 9 — parallel reviewers (3 independent Three fresh-context reviewers ran against the candidate Merged gaps (convergence across the three passes)
Gap 2/3 is corroborated by the file's own established convention: the native analogues 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 Reviewer 1 — full reportbtc.json Spec Review — Gap Report (Reviewer 1)Scope: PR #202 ( Phase 0 removed-field guard:
CRITICAL1. The 15
|
|
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 Fixes applied (4 rows, all inside the
|
| # | 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 onGET_BLOCKNUM(smartrouter_latest_block{spec="BTC"}=974676, both endpoint gauges agree, no parse-signature lines).GET_BLOCK_BY_NUMremainsNOT_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-idverified on both providers (chain="main").ADDONS:0 tested-ok / 0 failed / 2 not-testable (blockdaemon,restcarried forward unchanged).- The router booted cleanly against the edited spec and
bb_getBlockreached craft/dispatch with noCraftChainMessageor parser error before the upstream's clean-32601— which is the meaningful signal here: the newPARSE_BY_ARG+parsersconfig is syntactically valid and accepted by the router's spec resolution. The-32601itself is the unchanged non-Blockbook-upstream baseline. - No non-benign warn/error/fatal/panic lines in the probe window; no 429s;
bb_sendTransactioncorrectly 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 foundon 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>
|
Phase 11 — final reviewer verdict: ✅ APPROVED A fresh-context reviewer re-reviewed
Supporting checks it ran against the current file, all clean:
Disabled-API audit: 0 disabled methods across all four spec entries, consistent with the ledger (empty) and the PR body's Open item for a human (not blocking, not auto-applied)Base-collection vs Honest caveat on coverageThis verdict is a static + boot-level approval. The 15 Full final review (
|
| # | 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 keepsPARSE_BY_ARG ["0"]with only a
BLOCK_LATESTparser (noBLOCK_HASH) — it mirrorsgetblockhash, whose arg 0 is a height
only, not a hash. No regression.bb_getEstimateFeecorrectly remainsDEFAULT ["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_unitsfor all three fixed methods (20) matchesgetblockstats(20);statefulis
typed as an integer (1/0), not a boolean, on all 15bb_*methods.- No duplicate API names were introduced;
jq -e .parses the file cleanly. bb_sendTransaction.timeout_ms: 10000(committed separately ine466747, ahead of this
working-tree pass) is present and well-typed;category: {deterministic: false, stateful: 1, hanging_api: true}is consistent withsendrawtransaction/submitpackage.- All 15
bb_*methods live only inBTC's basejsonrpc/add_on: ""collection (49 APIs
total: 34 pre-existing + 15 new);BTCT/BTCT4/BTCSdo not redefine anybb_*entry, so
they inherit them automatically viaimports: ["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)restGETandrestPOST
(enabled: false, emptyapis: []). Verified againstorigin/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 thebb_*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.shscope covers), and it is unchanged by MAG-4824. Flagging for a
separate ticket if arest/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.
add_onplacement of the 15bb_*methods — raised by 3/3 prior reviewers (dedicated
blockbookadd-on vs. base collection). Deliberately not applied: base placement is the
point of MAG-4824 (makesUnlistedMethodRefusedretryable on another peer, paired with
smart-router#632). Recorded as an open decision for a human call, not re-raised as blocking.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.bb_getXPUBCU (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.- Pre-existing, unrelated to this PR, carried forward from the probe report: three
hanging_api-without-timeout_msrows (sendrawtransaction,submitpackage,/tx/send)
that fail identically onmain; 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);restinterface (all 4 networks) andblockdaemon
add-on bothNOT_TESTABLE(key-gated, no credentials available to this run). - Phase 10b router re-boot against the fixed spec:
SMOKE: OK,PARSE: OKon
GET_BLOCKNUM/GET_BLOCK_BY_NUM,VERIFY: OKonchain-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 acrossBTCT/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: 0marker. One pre-existing, PR-unrelated disabled-collection pair
(BTCSrest 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_onplacement) is already escalated and not
blocking.
TALLY: CRITICAL=0 MEDIUM=0 MINOR=0
|
Phase 12 — closing summary checklist (tail of the Phase 8–11 span; Run stats — this pipeline run only (Phases 8–11)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 State left behindThe Phase-10 fix is uncommitted in the working tree on What a human still needs to decide
Pipeline span 8→11 complete. Verdict: APPROVED with the one open placement decision above. |
|
Spec pipeline failed (started at Phase 8). See the run log. Retry by commenting: To also re-run every later phase on top of the fix, use |
Review:
|
| 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 thanMinimumHashLength(32), soBLOCK_HASHis skipped.BLOCK_LATESTreads it, andParseInt(s, 0, 64)makes it block 800000. - A 64-character hash matches
BLOCK_HASH, so the requested block is "not applicable". This is howgetblockandgetblockstatsbehave today. - Node selection does not change.
ChooseUpstreamWithStatsonly 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 leastblock_distance_for_finalized_data(6) deep is treated as final and goes into the long-TTL store. - A hash request is never cached (
NOT_APPLICABLEskips the cache write).
- With
category.deterministicis 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>
|
/rerun-from 8 |
|
🤖 Command acknowledged — running Phase 8 → 11. Progress and results post here as comments. View run |
|
Phase 8 — smart-router boot + multi-node method probe (re-run via Resumable pipeline run (Phases 8–11). Endpoint source: This probe is against the current HEAD (
The key new question this run answers: the
The 15
The two base-collection WARNs (
Method Probe Report — btcGenerated: 2026-11-05T15:49:15Z 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 Headline result: the router boots cleanly and serves the base BTC collection with the Parse-directive & verification runtime check (Step 3.5)
Addon & extension coverage (Step 1c + probes)
Method probe (Step 4) — through the router, localhost:3360Live inputs resolved before probing (no hardcoded placeholders): latest height 974681, latest hash Two methods initially WARNed on
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
Transport probe (http + ws)
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
PARSE_BLOCKNUM: OK — BTCT4 (Bitcoin Testnet4) — https://bitcoin-testnet4.gateway.tatum.io, ports 3460/7879
PARSE_BLOCKNUM: OK — BTCS (Bitcoin Signet) — https://bitcoin-signet-rpc.publicnode.com, ports 3460/7879
PARSE_BLOCKNUM: OK — Empirical block time (Step 8)Measured direct-to-upstream (not through the router) using the bitcoind recipe:
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. |
|
Phase 9 — parallel reviewers (3 independent Three fresh-context reviewers ran against 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;
Item 1 is the one that needs a judgment call rather than a mechanical fix, and item 3 is pre-existing on Reviewer 1 — findingsFindings1. [MEDIUM]
|
|
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 Applied
Dropped, with reasons
Phase 10a — offline static gates re-run after the fixerAll green, no Disabled-API Justifications: none — no API, addon or collection is disabled in this spec, and this pass disabled nothing. The 15 No removed-model field was introduced: the spec remains the canonical Phase 10b — smoke re-probe: ✅
|
| # | 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)
- Give the base collection's
sendrawtransaction,submitpackageandrestPOST/tx/sendan explicittimeout_ms— pre-existing onmain, all three. - Re-probe the 15
bb_*and 8bd_*methods against a Blockbook-enabled / Blockdaemon-keyed node; this run could only reach keyless bitcoind upstreams. - Consider whether
BTCTwarrants a looseraverage_block_time, if the drift recurs across multiple sampling windows. - The
bb_getBlockdeterministicreasoning applies to its siblings too (bb_getTx,bb_getTxSpecific, and the basegetblock) — 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. |
|
Phase 11 — final reviewer verdict: ✅ APPROVED A fresh-context reviewer re-reviewed It also independently verified the three settled decisions were applied as described and not conflated: Disabled-API audit: 0 methods carry One honest caveat on what this verdict does not cover: the 15 btc.json — Final-Pass Spec Review (post Phase 10 fixes)Reviewed: working-tree Inputs read before this pass: Phase 0 — Removed-field guard
Working-tree diff verification (re-derived independently, not trusted from the stated diff)Confirmed via
Re-derived directly from the on-disk JSON with Settled decisions — verified applied as described
Disabled-API / disabled-collection audit
One collection-level
This is pre-existing on No other Method-level spot checks (blockbook add-on, 15 APIs)All 15 Network parameters on Watch-list items (carried forward, not re-litigated, not re-raised as new findings)Per the brief, these remain open follow-ups from FindingsNone survived verification. All three Phase 10 fixes landed exactly as specified, the diff is Summary
|
|
Phase 12 — closing summary checklist (tail of the Phase 8–11 span; The one caveat that should gate the mergeThe 15 What this run did establish that the earlier one could not: the opt-in add-on layout from Decisions auto-taken at gates (conservative default, recorded)
Run stats — this pipeline run only (Phases 8–11)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 RetryIf anything here needs redoing, use the exact commands: |
Auto-committed by spec_pipeline.yml after the Phase-10 fix pass. Run: https://github.com/Magma-Devs/lava-specs/actions/runs/42055735442
|
📦 Committed pipeline fixes to |
idanhen1
left a comment
There was a problem hiding this comment.
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.
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
blockbookadd-on collection on the BTCjsonrpcinterface, holding 15 methods. Only node urls that declareaddons: ["blockbook"]are asked for them; other nodes never see abb_*call. A request with no such url getsNo 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 theblockbookcollection, 0 in the base collection, verification present).Verification (
enabled):bb_getBlockHash ["0"]must answer with ablockHash(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_getXPUBasbb_getXpub, the requests usebb_getXPUB).bb_getAddress,bb_getBalanceHistory,bb_getUTXOs,bb_getXPUBbb_getEstimateFeebb_getTickers,bb_getMultiTickers,bb_getTickersListbb_getRawBlock,bb_getFeeStatsBLOCK_HASH,BLOCK_LATEST(likegetblockstats)bb_getBlockconfirmations, so it must not be long-cached by height)bb_getTx,bb_getTxSpecificbb_getBlockHashgetblockhash)bb_sendTransactiontimeout_ms10000Router config to use it:
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. 30bb_getAddressper run:bb_*calls that reached Alchemyblockbookblockbook-32600); keeps serving base methodsblockbookNo Providers For Addon-32601); keeps serving base methodsAll 14 read methods × 10 through the same v1.6.6 setup: 140/140 answered by QuickNode, 0
bb_*calls reached Alchemy since startup,getblockcountstill split across both nodes.Block parsing, v1.6.6 with a local cache server, each request sent 3 times (testnet4 tip 159191):
requested_blockbb_getRawBlock ["150000"]bb_getRawBlock [<hash>]bb_getFeeStats ["150000"]bb_getFeeStats [<hash>]bb_getRawBlock ["159191"](tip, not final)bb_getBlock ["150000"]bb_getBlockHash ["150000"]Spec checks against main:
check_collection_additionPASS (1 collection added, everything else canonical-identical);check_node_admin_rpcsno new exposure;check_hanging_apibb_sendTransactionok (remaining findingssendrawtransaction,submitpackage, REST/tx/sendare already on main);check_method_schemaok for all 15;check_verificationsnotes the wildcard, same as the existingblockdaemonadd-on.No write was sent to any real endpoint;
bb_sendTransactionwas not exercised.No method disabled anywhere.
🤖 Generated with Claude Code