Skip to content

feat(spec): add Siacoin chain spec - #197

Merged
AnnaR-prog merged 7 commits into
mainfrom
siacoin-spec-20-10-2026
Nov 3, 2026
Merged

AnnaR-prog merged 7 commits into
mainfrom
siacoin-spec-20-10-2026

Conversation

@magmadevs-bot

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

Copy link
Copy Markdown
Contributor

New chain spec: Siacoin

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

Field Value
Chain name Siacoin
Mainnet index SC
Testnet index SCT
Spec file sc.json

Update 2026-11-03: nodes started from a checkpoint are admitted (commit d1ba22b)

  • chain-id now checks the network name, not the genesis block id. It reads GET /api/consensus/network → .name: "mainnet" on SC, "zen" on SCT (SCT still inherits the directive and overrides only the value). omer's MAG-2968 comment 31063: The customer runs the router on its own premises, so the router has to handle nodes synced either way, and nothing is asked of the customer. The genesis pin (/api/consensus/index/0) refused every node started from a -checkpoint, because such a node answers 404 there. This replaces the 2026-11-02 decision to keep the pin. Do NOT re-add the genesis pin.
  • For the routes the customer calls, a checkpoint node gives an error, never a wrong answer. It has no blocks before its checkpoint: old heights, blocks and events answer 404, and the router tries another node. The customer's other reads answer the same as on a block-0 node. Broadcast was not tested on a checkpoint node.
  • Known effect, documented and accepted for now: the address routes (/api/addresses/{addr}/*, /api/batch/addresses/*, /api/check/addresses) answer 200 with zero or missing data for coins received before a node's checkpoint (balance tested on zen on 2026-10-20). The router can't tell that from a real zero. The customer calls none of them, so this is acceptable for the customer for now (owner decision 2026-11-03). Do NOT remove or disable these routes, and do NOT re-add the genesis pin to avoid it.
  • Tested with smart-router v1.6.2 and v1.6.4 (no cache) against walletd v2.15.2:
    • SC on our mainnet node: chain-id passes (mainnet). SC on a zen node: refused (zen, wanted mainnet).
    • SCT on a block-0 zen node plus a zen node started from a checkpoint (height 63821): both admitted.
    • v1.6.4: 20 index lookups below the checkpoint all answered 200. 9 went to the checkpoint node first, got its 404 (NODE_DATA_NOT_HELD) and were retried on the other node. Old block and event lookups: 20 of 20 answered 200, 8 of them after a retry.
    • v1.6.2: the same 20 index lookups all answered 200, 9 of them after a retry.
    • The customer's reads on the checkpoint node vs the block-0 node: consensus/tipstate, consensus/network and txpool/transactions give the same body; state differs only in startTime, and syncer/peers in the live peer list.
    • SCT on the checkpoint node alone: an old height answers 404 "height not found", a new one 200.

Update 2026-11-02: review fixes (commit f254bce)

  • 5 routes are now deterministic: false (avitenzer's review). Their answer changes as the chain moves, so cross-validation would treat two honest nodes a block apart as disagreeing. Do NOT set them back to true.
    • GET /api/events/{id}: the reply carries Confirmations = 1 + scanHeight - height (persist/sqlite/events.go:121), which grows every block.
    • GET /api/outputs/siacoin/{id}, GET /api/outputs/siafund/{id}: only unspent outputs are returned (persist/sqlite/utxo.go: spent_index_id IS NULL), so the answer changes once the output is spent. On full nodes the reply also carries a Merkle proof that walletd refreshes as the chain grows.
    • GET /api/consensus/blocks/{id}, GET /api/consensus/checkpoint/{id}: a numeric id is read as a height through cm.BestIndex (api/server.go), so a reorg near the tip changes the answer. checkpoint/{id} was not in the review but takes the same code path.
    • GET /api/consensus/index/{height} stays deterministic: true on purpose: the router parses its height from the path (PARSE_DICTIONARY_OR_ORDERED), so it treats it like block-by-number methods on other chains. With DEFAULT parsing on blocks/{id} and checkpoint/{id}, the router can't know the height.
  • Tested with smart-router v1.6.4 against our walletd v2.15.2 nodes, at this commit:
    • mainnet (SC): The customer's call list answers through the router with the same status and body as directly (syncer/peers differs only in live peer stats); a broadcast with an invalid body gets walletd's own 400; PUT gets the router's own 501; chain-id passes; the password never appears in the router log
    • zen (SCT): the same, including the POST broadcast route SCT inherits from SC
  • Superseded on 2026-11-03: the decision to keep the genesis pin and require the customer to sync every node from block 0 was replaced by omer's MAG-2968 comment 31063 (see the update above).
  • Router side, not this spec: when the router runs with a cache, walletd mempool and peer reads can be served up to 1/8 of the block time (75 s) old, because nodeBoundMethods lists no walletd paths. Tracked as MAG-4793.
  • The customer runs the router on its own premises (MAG-2968 comment 31000), so walletd's API port can stay on the customer's private network.

Update 2026-11-01: added GET /api/syncer/peers (commit 3b75f23)

  • Added GET /api/syncer/peers because the customer calls it in production (MAG-2968 comment 30943). Do NOT remove it.
    • walletd serves it as a public route (wrapPublicAuthHandler), so it needs no password.
    • It returns the peer list of whichever node the router picks: deterministic: false, stateful: 0, DEFAULT/["latest"], CU 10 like /api/txpool/fee.
  • No wallet routes. The customer builds and signs its own transactions and only broadcasts through walletd; none of its calls use /api/wallets/* (MAG-2968 comment 30943). Do NOT add any /api/wallets/* route in a fix pass.
  • Auth: option 1, decided by omer (MAG-2968 comment 30985: the walletd password is never stored). The customer runs walletd with the public API option on every node, and the router holds no password. The spec declares no authorization header, so a caller's password is dropped before walletd (tested: a password-only call with the right password gets 401 through the router). Do NOT add an authorization header directive or any router auth config.
  • Tested with smart-router v1.6.2 against walletd v2.15.2 on mainnet, with the customer's call list and the customer's headers (Authorization: Basic, User-Agent: Sia-Agent):
    • all 8 GETs (tipstate, network, index, blocks, events, txpool transactions, state, syncer/peers) answer 200 through the router; 7 return the same body as calling walletd directly, and syncer/peers differs only in live peer stats
    • POST /api/txpool/broadcast with an invalid body gets walletd's own 400 through the router (nothing was broadcast)
    • PUT /api/wallets/1/addresses gets the router's own 501: the spec has no PUT collection, on purpose (wallet setup runs directly on each node)
    • the chain-id check passed, the password never appears in the router log, and SCT on zen serves syncer/peers too (inherited)

Update 2026-10-29: personal index mode accepted (commit a299510)

  • Removed the index-mode verification (GET /api/state → .indexMode == "full"). omer asked to support both index modes (MAG-2968 comment 30546). personal and none nodes are now admitted on SC and SCT. Do NOT re-add the check.
  • Kept the chain-id genesis pin at the time. It was replaced by a network-name check on 2026-11-03 (see that update).
  • The risk moves to the customer's setup: a personal-mode node answers 200 with a zero balance for any address it does not track, so every address must be added on every node. The customer's setup requirements are on MAG-2968.
  • Tested with smart-router v1.6.2 against walletd v2.15.2 on zen:
    • before: personal-mode node refused (index-mode got personal, wanted full)
    • after: personal-mode node accepted, and an untracked funded address reads 0
    • after: full-mode node still accepted, and the same address reads 1,356,000,020 SC
  • Wallet routes (/api/wallets/*) stay out: The customer uses none of them (see the 2026-11-01 update above).

Inputs provided

Siacoin (Sia), asset SC, Jira MAG-2968. Pass run_in_background: false explicitly on every Agent call.

API: walletd (the customer's node runs walletd, confirmed by the customer 2026-10-19). REST only, base path /api. Source of truth for routes: github.com/SiaFoundation/walletd api/server.go at tag v2.15.2.
Include the chain-wide public routes: GET /state, /consensus/network, /consensus/tip, /consensus/tipstate, /consensus/index/{height}, /consensus/blocks/{id}, /consensus/checkpoint/{id}, /consensus/updates/{index} (index = "height::blockid"), /txpool/transactions, /txpool/fee, /txpool/events, /addresses/{addr}/balance, /addresses/{addr}/events, /addresses/{addr}/events/unconfirmed, /addresses/{addr}/outputs/siacoin, /addresses/{addr}/outputs/siafund, /outputs/siacoin/{id}, /outputs/siacoin/{id}/spent, /outputs/siafund/{id}, /outputs/siafund/{id}/spent, /events/{id}, /syncer/peers (added 2026-11-01 because the customer calls it; it returns one node's peer list); POST /txpool/broadcast (transaction submission: stateful, send to all providers), /txpool/parents, /txpool/transactions/v2/basis, /batch/addresses/balance, /batch/addresses/events, /batch/addresses/outputs/siacoin, /batch/addresses/outputs/siafund, /check/addresses.
Leave out: /wallets/* (the customer uses none of them, MAG-2968 comment 30943; wallet IDs and their address sets exist only on the node that created them); /rescan, /syncer/connect, /debug/* (node admin, password-only); /health (node-local); /syncer/broadcast/block (miners only).
Latest block: GET /consensus/tip -> {"height","id"}. Block by number: GET /consensus/index/{height} -> {"height","id"}.

Chain identity (updated 2026-11-03): check the network name, GET /consensus/network -> .name: mainnet "mainnet", testnet "zen". Do NOT pin the genesis block id (GET /consensus/index/0): omer's MAG-2968 comment 31063 requires nodes started from a checkpoint to be admitted, and such a node answers /consensus/index/0 with 404.
Checkpoint effect (tested on zen 2026-10-20 and 2026-11-03): a walletd instant-synced with -checkpoint answers 404 for heights, blocks and events before its checkpoint (the router retries those on another node), and answers the address routes with 200 and a zero balance for coins received before its checkpoint (the customer calls none of them, so this is documented and accepted for now, owner decision 2026-11-03).

Index mode (updated 2026-10-29): accept both full and personal. omer asked for both (MAG-2968 comment 30546), so the /state indexMode check was removed on purpose in commit a299510; do NOT re-add it. Index mode "none" is accepted too. Known risk, now a customer setup requirement: a walletd in "personal" mode answers /addresses/{addr}/balance with HTTP 200 and zero balances, /events with [], /outputs/siacoin with "outputs": null for any address it does not track (tested on zen 2026-10-20 and 2026-10-29), so every address must be added on every node.

Defaults (updated 2026-11-03): (1) chain-id checks the network name (/consensus/network .name), so nodes started from a checkpoint are admitted (omer, MAG-2968 comment 31063); do NOT re-add the genesis block id pin. (2) the indexMode "full" check was removed on 2026-10-29 per omer's comment 30546; do NOT re-add it. (3) no /wallets/* routes: The customer builds and signs its own transactions and uses none of them (MAG-2968 comment 30943); do NOT add them in a fix pass. (4) /syncer/peers is included on purpose since 2026-11-01 because the customer calls it; do NOT remove it. (5) /events/{id}, /outputs/siacoin/{id}, /outputs/siafund/{id}, /consensus/blocks/{id} and /consensus/checkpoint/{id} are deterministic false since 2026-11-02 because their answers change as the chain moves; do NOT set them back to true. (6) POST /txpool/transactions/v2/basis stays at CU 20 (owner decision 2026-11-02); do NOT raise it in a fix pass. (7) the address routes stay enabled although a node started from a checkpoint answers them with a zero balance for coins received before its checkpoint; the customer calls none of them, so this is documented and accepted for now (owner decision 2026-11-03); do NOT remove or disable them.

Network params: proof of work. blockInterval 600 s on both nets (/consensus/network). Measured over the last 1000 blocks on 2026-10-20: mainnet 595.4 s, zen 606.7 s -> average_block_time 600000 on both.
Finality (adjudicated): The customer waits 6 confirmations (ticket + the customer's deposit page) -> block_distance_for_finalized_data 6 (= 3600 s).
Mainnet v2 hardfork: allowHeight 526000, requireHeight 530000 (v1 transactions are invalid after it). maturityDelay 144.

Testnet: zen (walletd -network zen), same API, imports mainnet, overrides only chain-id.

Endpoints: no public walletd exists. Our walletd nodes run on a private machine CI cannot reach, so leave the ENDPOINTS block blank; a manual smart-router run on those nodes will be posted on the PR. api.siascan.com is explored, not walletd: it shares only /consensus/tip and /consensus/network, so do not use it as a provider.

PR body notes: (a) deployment: run walletd with -http.public and give the router no API password, so wallet and admin routes answer 401 even if the router relays paths that are not in the spec; the router must never store the walletd password (decided 2026-10-29); (b) index lag cannot be verified: /consensus/tip is the consensus tip, not the index tip (walletd's /health reports index lag but is node-local).

⚠️ Defaults — do NOT revert

  1. chain-id checks the network name, not the genesis block id (commit d1ba22b, omer's MAG-2968 comment 31063). Nodes started from a -checkpoint must be admitted. They answer 404 for anything before their checkpoint, and the router retries that on another node. Do NOT re-add the /api/consensus/index/0 genesis pin.
  2. No indexMode check: removed on purpose on 2026-10-29 (commit a299510). omer asked to support both index modes (MAG-2968 comment 30546). Do NOT re-add the index-mode verification. A personal-mode node answers zero for any address it does not track, so the customer's setup requirements (MAG-2968) say every address must be added on every node.
  3. No /api/wallets/* routes. The customer builds and signs its own transactions and uses none of them (MAG-2968 comment 30943). Do not add them in a fix pass.
  4. /api/syncer/peers stays (added 2026-11-01, commit 3b75f23). The customer calls it. Do not remove it as node-local.
  5. No authorization header directive and no stored walletd password (omer, MAG-2968 comment 30985). The customer runs walletd with the public API option. Do not add a pass-through header or router auth config.
  6. 5 routes are deterministic: false (commit f254bce): /api/events/{id}, /api/outputs/siacoin/{id}, /api/outputs/siafund/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}. Their answers change as the chain moves. Do not set them back to true.
  7. POST /api/txpool/transactions/v2/basis stays at CU 20 (owner decision 2026-11-02). A Phase 9 reviewer suggested 60 for its worst case (a walk of up to 144 blocks that recomputes proofs). The usual call is cheap, nothing has been measured, and the customer doesn't call this route. Do not raise it in a fix pass.
  8. The address routes stay enabled (owner decision 2026-11-03). On a node started from a checkpoint they answer 200 with a zero balance for coins received before its checkpoint. The customer calls none of them, so this is documented and accepted for now. Do not remove or disable them in a fix pass.

A checkpoint-synced node is admitted by (1). On the address routes it answers 200 with a zero balance for coins received before its checkpoint. The customer calls none of them, so this is documented and accepted for now (owner decision 2026-11-03).

Deployment note

Nodes may be synced from block 0 or started from a -checkpoint (omer, MAG-2968 comment 31063). A checkpoint
node answers 404 for heights, blocks and events before its checkpoint, and the router retries those on another
node. It answers the address routes with a zero balance for coins received before its checkpoint
(documented and accepted for now: The customer calls none of them).

Run walletd with -http.public and give the smart-router no API password. Then the
wallet and admin routes answer 401 even if the router relays a path that is not in
this spec — defence in depth behind the spec's own route allow-list. Confirmed from
api/server.go @ v2.15.2: -http.public only un-gates the handlers wrapped in
wrapPublicAuthHandler; everything in wrapAuthHandler (/wallets/*, /rescan,
/syncer/connect, /debug/*) stays password-gated regardless.

Public walletd routes that this spec leaves out (GET /api/health, POST /api/syncer/broadcast/block) are still
relayed: the router passes any unlisted REST path to the node (defaultApiContainer). They need no password and
expose nothing private.

walletd refreshes the proofs of v2 transactions it broadcasts only on full index-mode nodes (api/server.go:477).
The customer runs full.

Index lag cannot be verified by this spec. /api/consensus/tip is the consensus
tip, not the index tip, so a node whose wallet index lags behind consensus still
reports a current height. walletd does expose index lag via /health, but that route
is node-local and excluded. No spec-level mechanism closes this gap today.

Sources used

  • Upstream parent spec: none. imports: [] on SC — Siacoin is standalone. All 156
    root specs were scanned for index SC/SCT or a name matching Sia: zero hits.
    BTC was evaluated and rejected: btc.json's base collection is jsonrpc with
    Bitcoin Core method names (getblockhash, getblock, getblockcount,
    estimatesmartfee, … 34 methods) that walletd does not serve, so importing it would
    add dozens of guaranteed-failing inherited APIs. The five chains that do import BTC
    (doge, litecoin, dash, zcash, qtum, bch) all run Bitcoin-Core-derived daemons; Sia does
    not. SCT imports SC (intra-file) and overrides only chain-id.
    Structural conventions were copied from kaspa.json (standalone, UTXO, PoW,
    REST-only, no imports, split GET/POST collections, internal_path: "") and
    aptos.json (height-placeholder block_parsing) — as templates only, not imports.

Calculations table

Parameter Source Formula Computed value
average_block_time /consensus/network .blockInterval = 600 s on BOTH nets; empirically 595818 ms mainnet / 606392 ms zen over the last 1000 blocks (2026-10-20) docs value locked — drift ≤1.1%, far under the 20% tie-breaker threshold 600000 ms (both SC and SCT)
block_distance_for_finalized_data adjudicated — the customer waits 6 confirmations for SC deposits (MAG-2968 + the customer's deposit page) not formula-derived; 6 × 600 s = 3600 s 6 (both)
blocks_in_finalization_proof finality-typed Siacoin is proof of work (Blake2b + Oak retarget) ⇒ probabilistic finality ⇒ the 3 row, not the fast-finality 1 and not the max(ceil(1000/abt), 3) fallback 3 (both)
allowed_block_lag_for_qos_sync derived max(ceil(10000 / 600000), 1) = max(ceil(0.0167), 1) = max(1, 1) 1 (both)

Empirical block-time measurement (via the siascan explorer, 2026-10-20):

  • mainnet tip 598144 @ 2026-10-20T14:55:08Z; tip-1000 597144 @ 2026-10-13T17:24:50Z → Δ 595818 s / 1000 = 595818 ms/block (0.70% faster than target)
  • zen tip 62139 @ 2026-10-20T14:56:09Z; tip-1000 61139 @ 2026-10-13T14:29:37Z → Δ 606392 s / 1000 = 606392 ms/block (1.07% slower than target)

Coverage (updated 2026-11-01, commit 3b75f23): 30 of 52 registered routes included (22 GET + 8 POST); 22 omitted, every one
with a source-grounded reason (see the omission ledger below). 0 extra, 0 invented, 0
disabled.

⚠️ Auto-decisions made (review these)

There was no human available on this run, so every STOP-and-ask gate was auto-resolved
with the conservative default. All of them:

  1. Archive extension — OMITTED on both mainnet and testnet (the archive-researcher's
    include/omit gate). Decided from source rather than escalated: walletd v2.15.2 has
    no pruning mechanism at all — an exhaustive grep for prune/retention/history/
    keep across its flags, api/server.go, wallet/manager.go and the sqlite persist
    layer returns zero hits. A node is either synced from genesis (full history, always) or
    instant-synced from a -checkpoint (history starts at an operator-chosen height and is
    never trimmed) — and since 2026-11-03 the latter is admitted (omer 31063): a lookup of history it
    lacks answers 404, and the router retries it on another node. There is no
    full-vs-archive tier to model. Per the indivisible-triplet rule the spec therefore
    carries none of: archive extension, pruning verification,
    GET_EARLIEST_BLOCK parse directive. retention_blocks, rule.block,
    pruning.latest_distance and the pruning expected_value are all n/a.
    The archive-researcher returned status: OK (not NEEDS_HUMAN_DECISION) because this
    is a definitive source finding, not an inconclusive probe.
  2. Block-time disagreement — no conflict, docs value used. Docs 600000 ms vs empirical
    595818/606392 ms is ≤1.1% drift, far below the 20% gate, so tie-breaker rule 1 applied
    automatically and no gate fired.
  3. internal_path convention — "" with the full /api wire path baked into every api
    name.
    This was a genuine judgment call the scout flagged. internal_path is used by
    the router to pick which node-url to dial, not to match the request. The catalog
    majority for REST chains (kaspa, aptos, stacks, vechain, arweave, hedera — 6 of 7)
    leaves it empty and bakes the full path into name; only ton.json uses it, and only
    because it hosts two coexisting API versions side by side. walletd has one base path
    and no competing versions, so the majority convention applies — and it keeps provider
    node-url config as the plain host root rather than requiring an /api-suffixed URL.
    check_internal_paths.sh passes with 0 warnings and 0 errors.
  4. No index-mode verification (removed 2026-10-29, commit a299510). The first version gated on
    GET /state → .indexMode == "full". omer asked to support both index modes (MAG-2968 comment
    30546), so the check was removed; personal and none nodes are now admitted. A personal-mode
    node does not 404 or error on any route — it silently returns zeros for untracked addresses — so
    this is a customer setup requirement (every address on every node), not something the spec can
    check. Do NOT re-add it.
  5. SCT overrides only chain-id. references/phase3.1-inheritance.md specifies that
    verifications merge via CombineUnique() keyed on Name. SCT overrides only chain-id
    (the network name zen since 2026-11-03), with parse_directive omitted so the parent's directive is adopted — the same
    shape kaspa.json's testnet entry uses.
  6. Phase-6 live chain-id curl — SKIPPED (unavoidable). The pre-flight normally
    confirms both chain-id values with a live curl. No public walletd endpoint exists, so
    this could not run in CI. Mitigation: both genesis ids were verified on our private
    walletd v2.15.2 nodes on 2026-10-20 and independently re-confirmed during this run
    against api.siascan.com (/consensus/tip/0 for mainnet, /zen/consensus/tip/0 for
    zen) — two independent sources agreeing exactly. Since 2026-11-03 chain-id checks the
    network name instead, tested through router v1.6.4 on both networks.
  7. Phases 8–12 not run, per the run's instructions — spec_pipeline.yml runs the
    boot/probe and review phases after this PR opens. Note the ENDPOINTS block is
    intentionally blank, so the automated probe will have nothing to dial; the real
    verification is the manual smart-router run against the private nodes, which will be
    posted as a PR comment.
  8. /api/check/addresses priced at CU 20, not in the batch band. It shares the
    1000-address cap with the four /api/batch/addresses/* routes (which are at 60) but
    returns a single {known:bool} and short-circuits on the first hit, so it does not
    fan out the same way.
  9. content-type: application/json header added to the POST collection
    (kind: pass_override). Not in the inputs; mirrors kaspa.json's POST collection. Safe
    here because all 8 POST routes decode JSON via jape/encoding/json, so there is no
    mixed-content-type trap.

Not a decision, but worth flagging to a reviewer: /api/consensus/blocks/{id} and
/api/consensus/checkpoint/{id} each run strconv.ParseUint on the {id} segment
first and resolve via BestIndex(height) on success, falling back to hex BlockID
parsing — so they double as height lookups in v2.15.2. This is undocumented-but-real
behaviour. The spec deliberately does not rely on it: GET_BLOCK_BY_NUM uses the
explicit, documented /api/consensus/index/{height} route.

Gate results (Phases 6–7, at creation, before /api/syncer/peers was added)

All 9 Phase-6 static gates PASS; no fixer pass was needed.

Gate Result Note
methods-coverage PASS 29 present, 23 justified omissions, 0 extra
parse-directives PASS presence OK, %d placeholder OK, echoed-slot OK; matrix skipped (family rest/other not in matrix)
chain-metadata PASS all 4 network params on both entries
verifications PASS 0 FAIL, 0 INFO
extensions PASS extensions: [] everywhere
cu-semantic PASS Layer 0 vacuous (no subscriptions), Layer 1 0 advisories
pruning PASS INFO: retention unknown — not verifiable, correctly not blocking
enabled PASS watch-list empty; 0 disabled apis, 0 disabled collections
method-schema PASS schema + hanging_api + stateful all exit 0, no ADVISORY rows

Phase 7: jq exit 0 · check_unused_fields.sh PASS (no removed fields) ·
check_internal_paths.sh PASS (0 warnings, no errors) ·
check_disabled_count.sh reports 0 distinct disabled methods, matching the
disabled-count: 0 marker above.

Disabled-API Justifications ledger: EMPTY — no api, collection or addon ships
enabled: false. Every one of the 30 included routes is a live, public, documented
walletd route (wrapPublicAuthHandler). The 22 omitted routes were left out outright
rather than included-and-disabled, which is why the ledger is empty rather than
unjustified.

Supporting evidence (INLINE — do NOT reference file paths)

Parse directives

Both live on the SC mainnet rest/GET collection (add_on: "", internal_path: "").
GET_EARLIEST_BLOCK is deliberately absent (no archive triplet), and there are no
SUBSCRIBE/UNSUBSCRIBE directives — walletd exposes no websocket surface at all, and
no api name on this chain contains ubscribe.

[
  {
    "function_tag": "GET_BLOCKNUM",
    "function_template": "/api/consensus/tip",
    "result_parsing": {
      "parser_arg": [
        "0",
        "height"
      ],
      "parser_func": "PARSE_CANONICAL"
    },
    "api_name": "/api/consensus/tip"
  },
  {
    "function_tag": "GET_BLOCK_BY_NUM",
    "function_template": "/api/consensus/index/%d",
    "result_parsing": {
      "parser_arg": [
        "0",
        "id"
      ],
      "parser_func": "PARSE_CANONICAL"
    },
    "api_name": "/api/consensus/index/{height}"
  }
]

GET /api/consensus/tip returns {"height":N,"id":"<hex>"}, so GET_BLOCKNUM plucks
.height — the height is the legitimate block-number analog there.
GET /api/consensus/index/{height} returns the same {"height","id"} shape, so
GET_BLOCK_BY_NUM must pluck .id, not .height: plucking the height would echo
the %d input back, making every provider "agree" trivially and defeating
data-reliability cross-checks. The echoed-slot gate confirms parser_arg is
["0","id"].

ChainIndex serialization gotcha (from go.sia.tech/core/types): as a path parameter
(/api/consensus/updates/{index}) a ChainIndex is the text form
"<height>::<64-hex-char-blockid>" — the full id, not the truncated String() form. As
a response body field (/consensus/tip, the .basis field) MarshalJSON
deliberately hides MarshalText and emits the plain object {"height":N,"id":"<hex>"}.
So response-body parsing targets .height / .id and never a colon-string.

Verifications — SC mainnet (network name, since 2026-11-03)
[
  {
    "name": "chain-id",
    "parse_directive": {
      "function_template": "/api/consensus/network",
      "function_tag": "VERIFICATION",
      "result_parsing": {
        "parser_arg": [
          "0",
          "name"
        ],
        "parser_func": "PARSE_CANONICAL"
      },
      "api_name": "/api/consensus/network"
    },
    "values": [
      {
        "expected_value": "mainnet"
      }
    ]
  }
]

Why chain-id checks the network name, not the genesis block id (changed 2026-11-03).
The first version pinned the genesis block id (/api/consensus/index/0 → .id) to refuse
nodes started from a -checkpoint. Such a node seeds its consensus DB at the checkpoint
(cmd/walletd/node.go: syncer.RetrieveCheckpoint + chain.NewDBStoreAtCheckpoint), so it
answers /api/consensus/index/0 with HTTP 404 "height not found", and the pin refused it.
omer's MAG-2968 comment 31063 requires the router to work with nodes synced either way, so the
check now reads the network name ("mainnet", "zen"), which every walletd on that network
reports. What a checkpoint node does differently:

  • heights, blocks and events before its checkpoint answer 404 (NODE_DATA_NOT_HELD in the
    router), and the router retries them on another node (tested 2026-11-03 on router v1.6.2 and v1.6.4);
  • the address routes answer 200 with a zero balance for coins received before its
    checkpoint (an address a block-0 node shows at 16.97M SC, tested 2026-10-20 on zen). The customer
    calls none of them, so this is documented and accepted for now (owner decision 2026-11-03).

Do NOT re-add the genesis pin.

Why there is no index-mode check (removed 2026-10-29). walletd's default index mode is
personal, not full (wallet.NewManager sets indexMode: IndexModePersonal, and
cmd/walletd/main.go defaults Index.Mode to the same). A personal-mode node returns
HTTP 200 with empty data for any address it does not track — never an error:
persist/sqlite/addresses.go swallows sql.ErrNoRows and returns a zero Currency,
while the events/outputs queries return nil slices with err == nil. Observed on zen on
2026-10-20, and again on 2026-10-29 through the router (an untracked funded address reads 0).
The first version refused such nodes. The check was removed because omer asked to support
both index modes (MAG-2968 comment 30546), so the risk moves to the customer's setup: every address
must be added on every node. Do NOT re-add the check.

Verifications — SCT (zen testnet override)

The testnet entry is the standard lean shape: imports: ["SC"], one rest/GET
collection matching the mainnet's primary collection key with apis: [], and a
verifications array overriding only chain-id. The parse_directive is omitted so
the parent's is adopted.

[
  {
    "name": "chain-id",
    "values": [
      {
        "expected_value": "zen"
      }
    ]
  }
]
POST collection headers
[
  {
    "name": "content-type",
    "kind": "pass_override",
    "value": "application/json"
  }
]

All 8 POST routes decode JSON via jape/encoding/json, so there is no mixed-content-type
trap. Mirrors kaspa.json's POST collection.

Collection layout and CU distribution
SC  | rest GET  add_on="" internal_path="" | apis=22 parse_directives=2 verifications=1 extensions=0
SC  | rest POST add_on="" internal_path="" | apis=8  parse_directives=0 verifications=0 extensions=0
SCT | rest GET  add_on="" internal_path="" | apis=0  parse_directives=0 verifications=1 extensions=0

GET and POST are two separate collections — unanimous convention across every REST spec
in the catalog (kaspa, ton, aptos, stacks, vechain, arweave, hedera, and the six
btc-family REST addenda). Both carry add_on: "": there are no add-on collections,
because the only chain-specific capability tiers (indexMode, checkpoint sync) change
the correctness of base routes rather than unlocking new endpoint families.

CU distribution (updated 2026-11-02) — 7 apis @ 10, 18 @ 20, 5 @ 60:

  • @10 — /api/state and /api/consensus/network (EMPTY/[""]: static node and
    network constants, no chain state); /api/consensus/tip, /api/consensus/tipstate,
    /api/txpool/fee (simple current-state reads); /api/syncer/peers (one node's peer list, added 2026-11-01); and /api/txpool/broadcast, the single
    stateful: 1 route (tx-submit band 10–40).
  • @20 — the 18 state-by-id reads: block / checkpoint / index-by-height,
    outputs and events by id, the per-address reads, the two mempool list reads, and
    /api/check/addresses.
  • @60 — /api/consensus/updates/{index} (a window of block updates up to the tip; raised from 20 in the Phase 10
    fix pass) and the four /api/batch/addresses/* routes. api/api.go caps each batch body at
    1000 addresses and each address costs its own sqlite index lookup, so one request can
    fan out to ~1000 single-address reads that individually bill 20. 60 is the floor of the
    heavy/complex-queries band and brackets kaspa.json's comparable batch routes
    (/addresses/balances=20, /transactions/search=60, /addresses/utxos=100). The
    cu-semantic gate judged these heavy and raised no advisory.

block_parsing distribution — 27 DEFAULT/["latest"], 2 EMPTY/[""]
(/api/state, /api/consensus/network), 1 PARSE_DICTIONARY_OR_ORDERED/["height","=","0"]
(/api/consensus/index/{height}, the aptos /blocks/by_height/{block_height} shape).
DEFAULT is retained on the by-id REST reads because a hex block/output/event id cannot
be parsed as a block number — those routes are nonetheless priced at 20 as state-by-id
queries, not 10.

stateful — exactly one route sets category.stateful: 1: /api/txpool/broadcast,
the transaction-submission route, which must be sent to all providers. The other seven
POSTs are reads that merely carry a request body (batch address lists, or a transaction
to inspect/rebase), so they are stateful: 0 — the same rule that makes eth_call and
eth_estimateGas non-stateful. No api sets hanging_api, and consequently none sets
timeout_ms: walletd has no long-poll or streaming route.

Omission ledger — the 22 routes left out, with reasons (updated 2026-11-01)

Every row is grounded in the auth wrappers and route gating in
https://github.com/SiaFoundation/walletd/blob/v2.15.2/api/server.go. walletd wraps each
handler in either wrapPublicAuthHandler (password-exempt under -http.public) or
wrapAuthHandler (password required always, regardless of -http.public).

route reason
/api/wallets admin-only — wrapAuthHandler always; wallet IDs are node-local, cannot be load-balanced
/api/wallets/{id} admin-only — same
/api/wallets/{id}/addresses admin-only — same
/api/wallets/{id}/addresses/{addr} admin-only — same
/api/wallets/{id}/batch/addresses admin-only — same
/api/wallets/{id}/balance admin-only — same
/api/wallets/{id}/events admin-only — same
/api/wallets/{id}/events/unconfirmed admin-only — same
/api/wallets/{id}/outputs/siacoin admin-only — same
/api/wallets/{id}/outputs/siafund admin-only — same
/api/wallets/{id}/construct/transaction admin-only — same
/api/wallets/{id}/construct/v2/transaction admin-only — same
/api/wallets/{id}/reserve admin-only — same
/api/wallets/{id}/release admin-only — same
/api/wallets/{id}/fund admin-only — same
/api/wallets/{id}/fundsf admin-only — same
/api/rescan admin-only — wrapAuthHandler; Manager.Scan() errors "scans are disabled in index mode %s" unless the node runs personal mode
/api/syncer/connect admin-only — wrapAuthHandler, peer management
/api/debug/mine admin-only — registered only under -debug, plus wrapAuthHandler
/api/debug/pprof/{handler} admin-only — registered only under -debug, plus wrapAuthHandler
/api/health admin-only / node-local — liveness endpoint
/api/syncer/broadcast/block platform-specific — block broadcast is a miner-only operation, not a consumer RPC

/api/health and /api/syncer/broadcast/block are the two routes
that are technically public under -http.public but are excluded by deliberate policy
as node-local or miner-only. The methods-coverage gate sees them as omissions and accepts
the justifications; they must not be "fixed" by adding them. /api/syncer/peers was excluded
the same way until 2026-11-01; it is now included because the customer calls it.

Arithmetic: 30 included + 22 omitted = 52 registered unique paths. Verified mechanically
against the route list with comm: 0 extra, 0 invented.

Route-table audit (walletd api/server.go @ v2.15.2)
  • Total routes registered: 54 unconditional verb+path entries plus 2 conditional
    (/debug/*, registered only when -debug is set) = 56 max; 52 unique paths.
  • Routes in the intended include list that do not exist in source: none — all 30
    were verified present verbatim at that tag (converting jape's :param to {param}).
  • Public chain-wide routes in source missing from the include list: none beyond
    /health, excluded by deliberate policy above.
  • Routes requiring the API password always (wrapAuthHandler, independent of
    -http.public): POST /syncer/connect, GET+POST /rescan, all 16 /wallets*
    routes, POST /debug/mine, GET /debug/pprof/{handler}. Everything else uses
    wrapPublicAuthHandler.
  • Interface surface: REST only. No JSON-RPC, no gRPC, no tendermintrpc, and no
    WebSocket/subscription routes
    of any kind.
  • GET /api/state → .indexMode confirmed to take exactly "personal" / "full" /
    "none" (wallet/manager.go, serialized via MarshalText).
  • GET /api/consensus/network confirmed fields include .name, .blockInterval,
    .maturityDelay, and .hardforkV2.{allowHeight,requireHeight,finalCutHeight,ephemeralOutputHeight}
    — note two more hardforkV2 fields than the inputs mention.
  • Batch bodies confirmed as flat address arrays ({addresses:[...]}) for all four
    /batch/addresses/* routes and /check/addresses (→ {known:bool}), each capped at
    1000 addresses (HTTP 400 above that).
  • One easy-to-miss route: DELETE /wallets/{id} is written in source with a tab
    between verb and path, so a naive grep '"DELETE ' misses it. It is excluded anyway.
Sibling Sia daemons — explicitly out of scope

renterd (renter/storage client), hostd (storage host), siad (deprecated legacy v1
all-in-one daemon), and explored / its hosted instance siascan / api.siascan.com
are all separate Sia Foundation daemons with separate, non-overlapping REST APIs.
None of their routes appear in this spec.

api.siascan.com deserves a specific warning: it coincidentally exposes
/consensus/tip and /consensus/network paths that look like walletd's, but it is a
pure explorer/indexer with no wallet, no /addresses/{addr}/balance watch-set semantics,
and a different route tree overall (it has no /consensus/index/{height} at all — the
genesis lookup there is /consensus/tip/0). It was used in this run only to
corroborate chain facts, and must not be configured as a provider for this spec.

Also note: hostd has an experimental consensus.pruneTarget reorg-window pruning
setting. That is a different daemon and is not evidence about walletd's retention — it
did not influence the archive decision.

🤖 Generated with Claude Code


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

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

Verdicts: SPEC_LOAD: OK (SC and SCT) · PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · ADDONS: none declared · TESTNET_VERIFY: NOT_TESTABLE · spec defects in boot logs: none
Counts: PASS=0 FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=28 WARN=0 TIMEOUT=0 LOG_WARN=0

Auto-decision (no human on this run): the <!-- ENDPOINTS --> block is empty and endpoint discovery re-confirmed independently that no public walletd instance exists (mainnet or zen). Rather than silently skipping Phase 8, the conservative default was taken: run the strongest subset that is possible without an upstream — the router spec-graph load boot for both variants — and mark every live verdict NOT_TESTABLE with evidence. Live method/parse/verification coverage for this spec requires a reachable walletd node (retry with /rerun-probe mainnet=<url>).


Method Probe Report — sc (Siacoin)

Generated: 2026-10-20T15:44:57Z
Router image: ghcr.io/magma-devs/smart-router:main (sha256:e288f09b6c7b053ebbad64f07f3e18452e5e10ba3076d7a736f902172b268a76)
Router configs: /tmp/sr_sc.yml (mainnet, SC), /tmp/sr_sc_testnet.yml (testnet, SCT)
Spec variants: SC (rest), SCT (rest, imports SC)
Upstreams probed: none (no usable upstream exists — see below). Placeholder used only to exercise spec-load/boot: https://api.siascan.com.

⚠️ No usable upstream — live probing NOT_TESTABLE

The Siacoin node software is walletd (github.com/SiaFoundation/walletd, api/server.go @ v2.15.2); every api in sc.json is a /api/... REST GET/POST route served by walletd. No public walletd instance exists for mainnet or Zen testnet. Sources checked, all negative:

  • docs.sia.tech, github.com/SiaFoundation/walletd, sia.tech — no public walletd endpoint documented.
  • siascan.com / zen.siascan.com — explorer frontends, not a walletd RPC.
  • siastats.info/nodes — connection refused.
  • comparenodes.com — no Sia page.
  • docs.sia.tech Zen-testnet node list — P2P gateway nodes on :9884 only (HTTP/0.9 gateway handshake, no REST server); ports 9980/9981/9882/9883/9885 all refused or timed out.

https://api.siascan.com is the siascan explorer backend, not walletd, and cannot act as a provider: its routes are mounted with no /api prefix (GET /api/consensus/tip → 404; the explorer's own GET /consensus/tip → 200), GET /state is missing indexMode, and /consensus/tipstate / /consensus/index/{height} → 404. It serves at most 2 of the spec's 29 routes. The PR body for this chain states the same conclusion independently: walletd nodes run on a private machine CI cannot reach, and api.siascan.com must not be used as a provider.

Given this, Phase 8's method-probe loop (Step 4), its log-scan (Step 4.5), and the empirical block-time measurement (Step 8) are NOT_TESTABLE for both mainnet (SC) and testnet (SCT). What remains testable without any upstream — and the one most likely to catch a real spec defect — is the router's spec-graph load and boot sequence, which happens before and independently of upstream verification. That check was run below, using https://api.siascan.com strictly as a degraded placeholder to get the router past spec-load into its verification stage. It is explicitly NOT a provider and NOT evidence of method coverage.

Spec-graph load check (what WAS tested)

variant spec graph loaded imports resolved verification definitions well-formed boot outcome evidence (log excerpt)
SC YES n/a (imports: []) YES (no Bad verification definition) Router booted, listened on 0.0.0.0:3360, entered "ready for requests"; placeholder upstream then failed the chain-id verification (404 from siascan's unprefixed routes) and was excluded → provider pool empty / No pairings available on a live request. This is the expected degraded outcome, not a spec defect. {"level":"info","endpoints":"SC:rest Network Address:0.0.0.0:3360","message":"RPCSmartRouter Listening"} / {"level":"info","message":"RPCSmartRouter done setting up all endpoints, ready for requests"} / {"level":"warn","error":"...404 page not found...","verification":"chain-id","message":"failed verification on provider startup"}
SCT YES YES — imports: ["SC"] resolved cleanly, no spec not found for chainId YES (overridden chain-id verification for SCT ran, referencing chainID:SCT, not Bad verification definition) Identical shape to SC: router booted and listened on 0.0.0.0:3360 (mapped 3460), placeholder upstream failed the SCT chain-id check and was excluded → no live request attempted (not needed to prove spec-load). {"level":"info","endpoints":"SCT:rest Network Address:0.0.0.0:3360","message":"RPCSmartRouter Listening"} / {"level":"warn","error":"...404 page not found...","chainID":"SCT",...,"verification":"chain-id","message":"failed verification on provider startup"}

No occurrence in either container's full log of: failed to load any specs, spec not found for chainId, Bad verification definition, panic, fatal, duplicate. The only invalid/error lines present are the expected per-provider invalid Verification on provider startup / provider validation failed — excluding from provider list, both caused by the placeholder's 404s, not by a malformed spec.

Parse-directive & verification runtime check (Step 3.5)

Check Verdict Evidence
GET_BLOCKNUM (router latest_block) NOT_EXERCISED No metric emitted for smartrouter_latest_block / lava_rpcsmartrouter_latest_block; log shows "no direct RPC endpoints to initialize ChainTrackers" — the chain tracker never starts because the sole static provider never passed verification. Expected with a dead placeholder upstream, not a spec defect.
GET_BLOCK_BY_NUM (log hash-reads ∥ fetch_block counters) NOT_EXERCISED Same cause — no healthy provider, so the tracker never ran.
Parse-signature log lines none PARSE_SIG grep (failed to parse response / formatResponseForParsing / ParseBlockHashFromReplyAndDecode / CraftChainMessage / Failed parsing default value / blockParsing / expected parsed hashes length / tried decoding a hex response / failed to parse generic parser path / failed to unmarshal result) returned zero matches on either container.
Verification Verdict Providers OK/failed Notes
chain-id FAIL (against placeholder only) 0/1 sc-upstream-1 / sc-testnet-upstream-1 (https://api.siascan.com) returned 404 ("404 page not found") for /api/consensus/index/0 — siascan's explorer API has no /api prefix, so this is an upstream-shape mismatch with a known-dead placeholder, not a spec expected_value defect. No real walletd upstream was available to validate the chain-id verification's function_template/expected_value against.
index-mode NOT_EXERCISED 0/0 Never attempted — the sole provider was already excluded by the failing chain-id check before index-mode could run.

Addon & extension coverage (Step 1c)

ADDONS: none declared. Both inventories are empty:

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

No addon/extension coverage table is applicable.

Method probe (Step 4) — NOT_TESTABLE, no upstream

All 29 apis declared under SC (and inherited by SCT) are reported NOT_TESTABLE except the one stateful api, which is SKIP (stateful) regardless of upstream availability. (Note: the dispatch brief estimated 8 stateful apis; a direct jq check of .category.stateful over every api in sc.json found exactly 1 — /api/txpool/broadcast — the rest are a mix of deterministic and non-deterministic but all stateful:0. The table below reflects the verified count.)

Method Classification Upstream notes Notes
/api/txpool/broadcast SKIP (stateful) — would broadcast a transaction
/api/state, /api/consensus/network, /api/consensus/tip, /api/consensus/tipstate, /api/consensus/index/{height}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}, /api/consensus/updates/{index}, /api/txpool/transactions, /api/txpool/fee, /api/txpool/events, /api/addresses/{addr}/balance, /api/addresses/{addr}/events, /api/addresses/{addr}/events/unconfirmed, /api/addresses/{addr}/outputs/siacoin, /api/addresses/{addr}/outputs/siafund, /api/outputs/siacoin/{id}, /api/outputs/siacoin/{id}/spent, /api/outputs/siafund/{id}, /api/outputs/siafund/{id}/spent, /api/events/{id}, /api/txpool/parents, /api/txpool/transactions/v2/basis, /api/batch/addresses/balance, /api/batch/addresses/events, /api/batch/addresses/outputs/siacoin, /api/batch/addresses/outputs/siafund, /api/check/addresses (28 apis) NOT_TESTABLE No usable walletd upstream exists (see top section); no provider ever passed verification, so these were never probed through the router. Not a FAIL, not a SKIP, not an UNPROBED-under-rate-limit — there was nothing to probe against.

Log-scan findings (probe window)

Not run — Step 4 (the probe loop) never executed, so there is no probe window to scan. The only non-benign warn/error lines observed anywhere in either container's lifetime are the expected per-provider verification failures against the placeholder ("[-] verify failed sending chainMessage", "invalid Verification on provider startup", "provider validation failed — excluding from provider list"), all attributable to https://api.siascan.com not being walletd — not router/spec-level findings.

Testnet verification pass (Step 7)

TESTNET_VERIFY: NOT_TESTABLE (no testnet upstream)

The spec-load boot for SCT (above) proves imports: ["SC"] resolves and the SCT-overridden chain-id verification definition is well-formed and loadable. The live verification outcome cannot be assessed because no testnet walletd upstream exists — the same placeholder-driven 404/exclusion seen on mainnet occurred here too.

Verification Verdict Providers OK/failed Notes
chain-id (SCT expected_value) NOT_TESTABLE (live) / well-formed (load-time) 0/1 Ran against placeholder, got 404 (shape mismatch, not a value mismatch) — no real upstream to confirm the expected_value itself.
index-mode NOT_EXERCISED 0/0 Never reached — same reason as mainnet.

Empirical block time (Step 8)

Not measured in this phase — no upstream to query. The PR body already records an explorer-derived measurement from a prior run, cited here as prior-run evidence only, NOT a Phase-8 measurement:

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet (explorer-derived, prior run) 595818 600000 ~0.7% OK (prior-run evidence, not re-measured here)
testnet (Zen) (explorer-derived, prior run) 606392 600000 ~1.1% OK (prior-run evidence, not re-measured here)

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

Reviewer TALLY
1 CRITICAL=0 MEDIUM=1 MINOR=0
2 CRITICAL=0 MEDIUM=1 MINOR=1
3 CRITICAL=0 MEDIUM=1 MINOR=2

Three distinct reports confirmed on disk (distinct md5s, shared SPEC_REVIEW_GAPS.md never written). All CRITICAL evidence-line references are within sc.json's 596 lines — no stale-state review.

All three ran with the Phase-8 constraint in hand (no public walletd endpoint ⇒ every api NOT_TESTABLE), and all three treated that as absence of evidence rather than a defect.


Merged gaps

MEDIUM (unanimous — all 3 reviewers, independently) — deterministic flag inconsistency on address-indexed event queries

sc.json:216 — /api/addresses/{addr}/events is "deterministic": true, while every structurally identical sibling is false:

api deterministic
/api/addresses/{addr}/events true ← the outlier
/api/addresses/{addr}/events/unconfirmed false
/api/addresses/{addr}/balance false
/api/addresses/{addr}/outputs/siacoin false
/api/addresses/{addr}/outputs/siafund false
/api/batch/addresses/events (sc.json:493, its own batch form) false

Verified against walletd v2.15.2 source by reviewer 1: addressesAddrEventsHandlerGET (api/server.go:1350) → wm.AddressEvents(addr, offset, limit) and batchAddressesEventsHandlerPOST (api/server.go:1509) → wm.BatchAddressEvents(...) return the same class of data with the same pagination semantics, so no technical property distinguishes them.

Impact: QoS/data-reliability only — not correctness, not boot, not block tracking. A tip-dependent query marked deterministic: true can produce spurious reliability mismatches between two honest providers synced to slightly different tip heights.

Reviewers disagreed on direction: reviewer 1 suggested raising the batch form to true; reviewers 2 and 3 framed the singular as the outlier to lower. Resolved in Phase 10 — see that comment.

MINOR (dropped from the fix list per Phase-10 consolidation rules, recorded here for the reviewer)

  • /api/check/addresses parsing may not match its semantics (reviewer 2, sc.json:528) — currently block_parsing: DEFAULT/latest, deterministic: false. If the route is pure address-format validation with no chain-state dependency, the guide's rule would call for block_parsing: EMPTY + deterministic: true (the bucket /api/consensus/network already uses). Could not be confirmed either way with no live walletd and no API docs — flagged for confirmation, not asserted as a defect.
  • No timeout_ms on the four /api/batch/addresses/* POST routes (reviewer 3, sc.json:467-526) — each accepts up to 1000 addresses with a per-address sqlite lookup. Not a convention violation at their 60-CU tier (kaspa.json's same-tier /transactions/search carries none either), so a soft suggestion only.
  • Cross-chain determinism convention note (reviewer 3) — kaspa.json marks its balance-equivalent true where sc.json uses false; the catalog is not uniform on this axis. Informational, no action.

Confirmed correct by all three (no findings)

API coverage complete and HTTP-method-accurate against the walletd v2.15.2 binary source (21 GET + 8 POST); both parse directives (GET_BLOCKNUM → /api/consensus/tip, GET_BLOCK_BY_NUM → /api/consensus/index/{height} with PARSE_DICTIONARY_OR_ORDERED) verified correct at source level; network params; the genesis-block-id chain-id verification (a sound substitute for a node with no native chain-id RPC) plus the index-mode check; SC → SCT inheritance correctly minimal; CU tiering consistent; removed-field guard clean; no routing collisions; archive/pruning/GET_EARLIEST_BLOCK triplet consistently all-absent.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 10 — gap synthesis + fix pass, and Phase 10b — smoke re-probe

Consolidation

0 critical, 1 medium; 0 disable-suggestions stripped → docs/sc/FIX_LIST.md. The three MINOR findings were dropped per the consolidation rule (MINOR gaps do not enter the fix list; they are recorded in the Phase 9 comment above for the human reviewer).

Nothing was stripped by the disable-suggestion filter because no reviewer proposed a disable — all three correctly read the Phase-8 NOT_TESTABLE rows as absence of evidence rather than grounds to disable. The spec still disables nothing: <!-- disabled-count: 0 --> in the PR body remains accurate (check_disabled_count.sh → 0 distinct method(s), 0 row(s)), and the Disabled-API Justifications ledger stays EMPTY, unchanged from the original run.

⚠️ Auto-decision (no human on this run) — reviewer disagreement on fix direction

All three reviewers flagged the same deterministic inconsistency but split on which side to align. Resolved conservatively:

Set /api/addresses/{addr}/events → "deterministic": false (lower the outlier). Not the alternative of raising /api/batch/addresses/events to true.

false is what its own batch form and all four address-indexed siblings already carry. The route returns a tip-dependent, paginated view of an address's confirmed events — new events appear as blocks arrive — so two honest providers at slightly different tip heights legitimately disagree, which is precisely the case where deterministic: true manufactures spurious data-reliability mismatches (reviewer 1's own impact analysis makes this argument). In this spec deterministic: true is correctly reserved for records pinned by an immutable id (/api/events/{id}, /api/outputs/siacoin/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}, /api/consensus/index/{height}, /api/consensus/updates/{index}). It is the one-field, minimum-risk direction, and the one 2 of 3 reviewers favoured.

Fix log

  • sc.json:216 — category.deterministic true → false on /api/addresses/{addr}/events (SC, GET collection) (gap: MEDIUM, "deterministic flag inconsistency on address-indexed event queries")

Diff is exactly one line (1 insertion(+), 1 deletion(-)); no reformatting, no trailing newline added. jq exit: 0.

DISABLED-API JUSTIFICATIONS: none — nothing was disabled in this pass.

Phase 10a — post-fix static gates

Gate Result
jq validity exit 0
check_method_schema.sh PASS — 29/29 apis schema ok, FAIL section empty
check_unused_fields.sh PASS (no removed fields) — none of the 15 fields removed in smart-router #218 are present; envelope is still { "proposal": { "specs": [ … ] } }
check_hanging_api.sh PASS — no FAIL rows (new chain, so no --base)
check_stateful.sh PASS — no FAIL rows
check_disabled_count.sh PASS (report only) — 0 distinct disabled methods, matching the body marker

compute_units remains the only compute-unit input, and no category.subscription exists anywhere (this spec has no subscription methods at all — zero FUNCTION_TAG_SUBSCRIBE directives).

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

Still no usable upstream, so this was the same degraded shape as Phase 8: re-boot both variants against the fixed spec and check the one thing a one-field edit could plausibly break — the router's spec-graph load.

Variant SPEC_LOAD Evidence
SC OK "chain_id":"SC","total_specs_loaded":"304","message":"Successfully loaded and expanded spec from aggregated sources"
SCT OK "chain_id":"SCT","total_specs_loaded":"304" with both SC and SCT in the loaded spec_ids — imports: ["SC"] resolves, and the overridden chainID:"SCT" verification is still well-formed and loadable

No panic / fatal / failed to load any specs / spec not found for chainId / Bad verification definition / duplicate in either log. No new log signature versus Phase 8 — both boots reproduced the identical expected placeholder-upstream 404 on chain-id verification and nothing else.

PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · ADDONS: none declared · all 7 smoke items NOT_TESTABLE (no upstream). A NOT_TESTABLE item cannot regress, so none of these counts against the fix.

jq re-confirms only the intended field moved: /api/addresses/{addr}/events det=false, every other address-indexed row false, no other deterministic value touched. Both containers torn down.

The fixed sc.json is left uncommitted in the working tree, as this run's contract requires — a later workflow step commits and pushes it to the PR branch.

@magmadevs-bot

magmadevs-bot commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0

A fresh-context reviewer re-ran /review-spec on the fixed sc.json and reported zero remaining CRITICAL and zero MEDIUM gaps. Report: docs/sc/SPEC_REVIEW_GAPS_final.md (96 lines). All evidence line references fall inside sc.json's 596 lines — no stale-state review.

What the final pass verified

  • The Phase 10 fix landed exactly as specified and nothing else moved. git diff is one line at sc.json:216 ("deterministic": true → false inside the /api/addresses/{addr}/events api object, SC GET collection). Every other deterministic value is untouched; the immutable-id-pinned routes (/api/events/{id}, /api/outputs/siacoin/{id}, /api/outputs/siafund/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}, /api/consensus/index/{height}, /api/consensus/updates/{index}, /api/consensus/network) correctly remain true. SCT declares no GET-collection apis, so it inherits the corrected value — no SCT-side edit was needed and none was made.
  • The chosen direction was independently judged correct — lowering the singular route rather than raising the batch form, for the tip-dependence reason recorded in the Phase 10 comment.
  • Guards re-run clean on the fixed file: check_unused_fields.sh → RESULT: PASS (no removed fields); check_internal_paths.sh → RESULT: PASS (0 warnings, no errors). The envelope is the canonical { "proposal": { "specs": [ … ] } }; none of the 15 fields removed in smart-router #218 are present.
  • Disabled-API ledger audit: jq confirms zero enabled: false entries anywhere — no api, no collection, no spec entry. That matches the empty ledger, so there is nothing requiring a positive-evidence row and no CRITICAL on that axis. <!-- disabled-count: 0 --> in the PR body is accurate.
  • Carried-forward and re-checked: 29 apis (21 GET + 8 POST) match the walletd v2.15.2 route table 1:1 with no gaps or extras (correctly excluding the password-gated /wallets/**, /rescan, /syncer/*, /debug/* and the node-local /health); network params (average_block_time: 600000, block_distance_for_finalized_data: 6, blocks_in_finalization_proof: 3 for probabilistic PoW finality, allowed_block_lag_for_qos_sync: 1); both verifications (chain-id via /api/consensus/index/0 → .id, index-mode via /api/state → .indexMode == "full") and their SCT inheritance; both parse directives; no duplicate names, no hanging_api, archive/pruning/GET_EARLIEST_BLOCK triplet consistently all-absent.

⚠️ Scope of this approval — read before merging

APPROVED here means the spec passed static/structural review plus a router spec-graph load check. It does NOT mean the spec was exercised against a real node. No public walletd instance exists for Siacoin mainnet or the Zen testnet, so across this entire pipeline run:

  • 0 of 29 apis were probed live. 28 are NOT_TESTABLE; /api/txpool/broadcast is SKIP (stateful).
  • PARSE: NOT_TESTABLE — the chain tracker never started (no healthy provider), so neither GET_BLOCKNUM nor GET_BLOCK_BY_NUM was ever executed against a real upstream.
  • VERIFY: NOT_TESTABLE and TESTNET_VERIFY: NOT_TESTABLE — neither the mainnet nor the Zen chain-id expected_value has ever been live-confirmed, nor has the index-mode check.
  • Block time was not measured this run; the PR body's figures (mainnet 595818 ms, zen 606392 ms vs spec 600000 ms, drift ≤1.1%) are prior-run explorer-derived evidence, not Phase-8 measurements.

What was proven live: the smart-router loads and resolves the spec graph for both SC and SCT (304 specs loaded, imports: ["SC"] resolves, both verification definitions well-formed and loadable), with no panic / fatal / failed to load any specs / spec not found for chainId / Bad verification definition / duplicate in either boot — before and after the fix.

The PR body's three customer-pending defaults (the genesis-block-id pin, the indexMode: "full" check, and the omission of /api/wallets/*) are therefore still unvalidated against a real node, and MAG-2968 remains the gating question. To close the gap, re-run with a reachable walletd node: /rerun-probe mainnet=<url> testnet=<url> (that re-runs Phase 8 only), or /rerun-from 8 to redo probe → review → fix → verdict on top of it.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (tail of Phase 11; this pipeline run covered Phases 8–11)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a `jq` exit 0 on the fixed file)
- ✓ All required fields present                          (Phase 11 final review; removed-field guard PASS)
- ✓ No duplicate API names within any collection         (Phase 11 re-check; check_method_schema 29/29 ok)
- ✓ Proper indentation/formatting                        (surgical one-line edit; no reformat, no trailing newline added)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (PR body calculations table; re-verified Phase 9 + Phase 11)
- ☐ All APIs tested and working                          (Phase 8/10b: NO public walletd endpoint exists — 0 of 29 apis probed live; 28 NOT_TESTABLE, /api/txpool/broadcast SKIP (stateful). See docs/sc/METHOD_PROBE_REPORT.md)
- ☐ Block parsing validated for each API                 (not exercised — no upstream; validated statically only, against walletd v2.15.2 handler source)
- ☐ Parse directives executed by live router             (Phase 8 Step 3.5: PARSE=NOT_TESTABLE, VERIFY=NOT_TESTABLE — chain tracker never started, no healthy provider. Phase 10b re-check: NOT_TESTABLE, unchanged)
- ✓ Addons & extensions tested                            (Phase 8 Step 1c: none declared — 0 addons, 0 extensions; nothing to test)
- ☐ Verifications pass on live nodes                     (NEVER live-confirmed: chain-id and index-mode both NOT_TESTABLE on mainnet AND Zen testnet. Only their definitions were proven well-formed and loadable by the router)
- ☐ Compute units benchmarked under expected load        (user to measure)

#### What WAS proven live
- ✓ Smart-router loads + resolves the spec graph          (Phase 8 and Phase 10b, both variants: SPEC_LOAD OK, 304 specs loaded, SCT's imports:["SC"] resolves, no panic/fatal/failed-to-load/spec-not-found/Bad-verification-definition/duplicate)

#### 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                                (SC: 29 apis across GET + POST collections, 2 verifications, 2 parse directives)
- ✓ Testnet spec inherits correctly                      (SCT imports SC, overrides only chain-id; confirmed by Phase 11 and by the router resolving the import closure at boot)
- ☐ Chain IDs verified for mainnet AND testnet           (NOT live-verified this run — no walletd endpoint. Both expected_values remain as researched in Phases 1–7)
- ☐ Both tested on respective networks                   (no endpoint for either network)

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

Auto-decisions taken on this unattended run

  1. Phase 8 zero-endpoint gate — the <!-- ENDPOINTS --> block is empty and discovery independently re-confirmed no public walletd exists. Conservative default: do not silently skip Phase 8; run the strongest possible subset (router spec-graph load boot, both variants) and mark every live verdict NOT_TESTABLE with named-source evidence. api.siascan.com was used strictly as a labelled degraded placeholder to reach the spec-load stage, never counted as a provider or as coverage.
  2. Phase 10 reviewer disagreement — all three reviewers raised the same MEDIUM but split on direction. Conservative default: lower the outlier (/api/addresses/{addr}/events → deterministic: false) rather than raise the batch form, since true on a tip-dependent route is the direction that creates spurious data-reliability mismatches. 2 of 3 reviewers favoured this direction.

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

Elapsed:         00h 33m 11s  (first→last logged activity)
Transcripts:     1 main + 9 subagent
API round-trips: 417  (main=78, subagents=339)

Fresh tokens:    input=834  output=247358  (sum=248192)
Cached tokens:   cache_read=26353532  cache_write=1402031
Total billed:    28003755 tokens

Split (total billed):  main=7828592  subagents=20175163

Models used:
  claude-sonnet-5         339 calls   20175163 billed
  claude-opus-5            79 calls   7975826 billed

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

State left behind

sc.json is modified and uncommitted in the working tree (one line, sc.json:216), exactly as this run's contract requires — the following workflow step commits and pushes it to siacoin-spec-20-10-2026. No git operation was performed by this run. Run span complete: Phases 8 → 11 inclusive, stopping here.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

📦 Committed pipeline fixes to siacoin-spec-20-10-2026 (31b596e): sc.json — the branch now matches the spec that Phase 10b/11 verified.

Remove the index-mode verification (GET /api/state, indexMode == "full").
omer asked to support both index modes (MAG-2968 comment 30546), and the
decision to accept personal-mode nodes was made on 2026-10-29. SCT
inherited the check from SC, so it goes away on both networks. Index mode
"none" is now accepted as well.

The chain-id verification (genesis block at height 0) stays. It still
refuses nodes started from a checkpoint.

Personal-mode risk: a personal node answers 200 with a zero balance for
any address it does not track, so Kraken must add every address on every
node.

Tested with smart-router v1.6.2 against walletd v2.15.2 on zen:
- before: personal-mode node refused (index-mode got "personal", want "full")
- after: personal-mode node accepted; an untracked funded address reads 0
- after: full-mode node still accepted; the same address reads 1,356,000,020 SC

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

Copy link
Copy Markdown
Contributor

/rerun-from 8
Re-validate head a299510. The index-mode verification was removed on purpose (see the PR body section "Update 2026-10-29"): do NOT re-add it, and do NOT add /api/wallets/* routes in a fix pass.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 8 — smart-router boot + method probe (resumable run, Phases 8–11 · re-validating head a299510)

Verdicts: SPEC_LOAD: OK (SC and SCT) · PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · ADDONS: none declared · TESTNET_VERIFY: NOT_TESTABLE · spec defects in boot logs: none
Counts: PASS=0 FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=28 WARN=0 TIMEOUT=0 LOG_WARN=0
BLOCK_TIME: mainnet=skipped testnet=skipped (no upstream, and walletd's index response carries no timestamp — no recipe exists regardless)

Net finding for this re-validation: head a299510's removal of the index-mode verification left no artifact. The sole remaining verification (chain-id, the genesis-block pin) loads and executes well-formed on both SC and SCT; /api/state remains a clean ordinary route with no dangling reference. No spec defect at the boot/spec-graph level. The removed check was not re-added and no /api/wallets/* routes were introduced, per the triggering comment and the PR body's "Update 2026-10-29".

Auto-decision (no human on this run): the <!-- ENDPOINTS --> block is empty, and this run's own endpoint research independently re-confirmed that no public walletd instance exists for mainnet or zen. Rather than silently skipping Phase 8, the conservative default was taken — run the strongest subset possible without an upstream (the router spec-graph load + boot for both variants) and mark every live verdict NOT_TESTABLE with evidence. Live method/parse/verification coverage for this spec requires a reachable walletd node: retry with /rerun-probe mainnet=<url>.

No subscription methods exist in the resolved closure (function_tags are only GET_BLOCKNUM, GET_BLOCK_BY_NUM, VERIFICATION), so the ws-capable-node gate did not apply.


Method Probe Report — sc

Generated: 2026-10-29T10:46:50Z
Router image: ghcr.io/magma-devs/smart-router:main @ sha256:0addb690fd25f06b6c9adfe34cbdc12bfa97da7cd8db180a724a23b587c1abb5
Router config (mainnet): /tmp/sr_sc.yml
Router config (testnet): /tmp/sr_sc_testnet.yml
Spec variants: SC (rest), SCT (rest, imports SC)
Branch taken: (B) — no usable upstream exists.
Head under test: a299510 (removed the index-mode verification, MAG-2968; only chain-id remains).

Why Branch B

Per the orchestrator brief and this run's own endpoint research (below), no publicly reachable
walletd instance exists for Siacoin mainnet or the Zen testnet. The pipeline therefore cannot
exercise live upstream behavior (parse-directive execution, chain-id verification against a real
node, method probing, block-time measurement). The strongest test still available — and the one
most likely to catch a spec-level defect — is the router's own spec-graph load + boot sequence,
which runs before and independently of upstream verification. That is what this report validates.

Endpoint research (this run, 2026-10-29)

Bounded search (~15 min) for a reachable public walletd instance, mainnet and/or Zen testnet.
Minimum bar: answers /api/consensus/tip and /api/consensus/index/0 (the /api-prefixed routes
walletd actually serves; GET /api/consensus/index/{height} is also the chain-id verification's
own route).

Candidate Method Result
api.siascan.com (siascan explorer backend) curl /api/consensus/tip HTTP 404 — no /api prefix on this backend
api.siascan.com (siascan explorer backend) curl /consensus/tip (no /api prefix) HTTP 200, but shape is the explored indexer's own schema ({"height","id"}) — confirmed not walletd: walletd's own /api/consensus/tip route 404s here
api.siascan.com (siascan explorer backend) curl /api/consensus/index/0 HTTP 404
api.siascan.com/zen/consensus/tip (zen testnet via same explorer backend) curl HTTP 200, same explored-shape (not walletd), confirms symmetry with mainnet finding
zen.siascan.com/api/consensus/tip curl HTTP 200 but returns an HTML document (website frontend), not a JSON API
walletd.sia.tech curl connection failed (HTTP:000, no DNS/route)
docs.sia.tech (incl. v2/exchanges page), github.com/SiaFoundation/walletd, github.com/SiaFoundation/docs WebSearch "No public walletd instance exists for mainnet or Zen testnet"; walletd is designed to be privately operated (-http.public only exposes safe routes, exchanges are told to run their own node)
siastats.info, comparenodes.com WebSearch no walletd-shaped public RPC listing found for Siacoin
GitHub issues/discussions (SiaFoundation org) WebSearch no community-run public walletd endpoint surfaced

Conclusion: re-confirms the prior 2026-10-20 pipeline run's known-negative finding.
api.siascan.com is independently verified here to be the siascan explorer backend
(explored), not walletd: its routes have no /api prefix and it serves at most the 2 routes with
exact name collisions (consensus/tip, consensus/network) out of the spec's 29 /api/... routes.
Per the PR body and this run's own evidence, it must NOT be configured as a real provider — it is
used below ONLY as a clearly-labelled degraded placeholder to get the router through spec-load into
its verification stage (Step 1, branch B instructions).

No ws/wss upstream was sought or required: the spec's only function_tags are GET_BLOCKNUM,
GET_BLOCK_BY_NUM, VERIFICATION (confirmed via jq over the resolved import closure) — no
SUBSCRIBE directive anywhere, so the missing-ws boot-failure mode does not apply to this chain.

Spec-graph load + boot sequence (both variants)

Config shape: one direct-rpc block per variant, node-urls: [{url: "https://api.siascan.com"}],
clearly labelled in the config as *-upstream-1-degraded-placeholder. Booted as two separate
containers (sr_sc on ports 3360/7779, sr_sc_testnet on ports 3460/7879), per Step 7 shape.

Check SC (mainnet) SCT (testnet)
Spec directory loaded (Loaded specs from local directory) OK — spec_count: 304 OK — spec_count: 304
imports resolved (Successfully loaded and expanded spec from aggregated sources) OK (SC has no imports) OK — chain_id":"SCT","total_specs_loaded":"304" confirms imports: ["SC"] resolved cleanly
Endpoint registered / listener up (RPCSmartRouter Listening) OK — SC:rest Network Address:0.0.0.0:3360 OK — SCT:rest Network Address:0.0.0.0:3360
RPCSmartRouter done setting up all endpoints, ready for requests present present
Fatal defect signatures (failed to load any specs, spec not found for chainId, Bad verification definition, duplicate, panic, fatal) NONE FOUND NONE FOUND
chain-id verification definition loadable/well-formed (executes, as opposed to rejected as malformed) OK — ran 3x per retry cycle, failed only on the placeholder's HTTP-shape mismatch (404 page not found, not JSON) — never a Bad verification definition or expected_value-type parse defect OK — same: the SCT-overridden expected_value loaded and the verification executed; failure is the identical upstream-shape 404, not a malformed-definition error
/api/state orphan check /api/state remains present in api_collections[].apis[] as an ordinary, enabled, non-stateful REST GET route (block_parsing: EMPTY). No verification references it (the removed index-mode verification was the only consumer). No dangling reference, no orphan artifact in the boot log. same (inherited)

Explicit answer to the orchestrator's question: the one remaining verification (chain-id)
still loads and runs well-formed on BOTH SC and SCT at head a299510. Removing index-mode left
no artifact in the boot logs — no dangling reference, no Bad verification definition, and
/api/state is untouched as a legitimate, independently probe-able api (it simply lost its one
verification consumer).

Parse-directive & verification runtime check (Step 3.5)

Check Verdict Evidence
GET_BLOCKNUM (router latest_block) NOT_TESTABLE no smartrouter_latest_block / lava_rpcsmartrouter_latest_block metric emitted (curl :7779/metrics matched nothing) — chain tracker never started because the sole provider never passed startup verification (no healthy providers for endpoint — serving unavailable until one recovers)
GET_BLOCK_BY_NUM (log hash-reads) NOT_TESTABLE grep -c 'Chain Tracker Updated block hashes|Chain Tracker read a block Hash' = 0 on both containers
Parse-signature log lines none (tracker never ran, so parser code paths for these two directives were never reached) —
Verification Verdict Providers OK/failed Notes
chain-id (SC) NOT_TESTABLE 0/1 Failed on the placeholder with Rest reply is neither a JSON object nor a JSON array of objects {reply.Data:404 page not found} — an upstream-shape mismatch (siascan's explored backend has no /api prefix, so GET /api/consensus/index/0 404s), NOT an expected_value defect. Retried on a 2s/4s backoff loop, failed identically every time — confirms it is systematic (wrong upstream), not transient.
chain-id (SCT) NOT_TESTABLE 0/1 Same failure mode, same root cause, against the SCT-overridden expected_value.

PARSE: NOT_TESTABLE (no upstream). VERIFY: NOT_TESTABLE (no upstream) — both for the reason
above, not a spec defect. See "Spec-graph load" table above for the positive signal this run DID
obtain: both verification definitions are well-formed and execute correctly against whatever
upstream they are given; they simply have no real walletd upstream to succeed against.

Addon & extension coverage (Step 1c)

ADDONS: none declared — jq over sc.json confirms add_on is "" everywhere and
extensions is [] everywhere (both SC and SCT). No Step 1c matrix needed.

Method probe (Step 4)

Not run as a true probe loop (no upstream to probe against). For evidence, 2 representative
GET calls were sent through the router at localhost:3360 (/api/consensus/network,
/api/txpool/transactions) and both returned {"error":"...No pairings available...}" —
consistent with No pairings available / AllProvidersExhausted relay outcome, confirming the
router correctly refuses to serve when its sole provider fails verification (expected and correct
behavior, not a spec defect).

All 28 non-stateful apis are marked NOT_TESTABLE (no upstream; see evidence above), and
/api/txpool/broadcast is SKIP (stateful — would broadcast a transaction). jq confirms this
is the ONLY api with category.stateful: 1 in the spec (the orchestrator brief's prior estimate
of 8 was wrong; trust jq, which was used here).

Method Classification Notes
/api/state NOT_TESTABLE no upstream
/api/consensus/network NOT_TESTABLE probed through router — No pairings available (expected, no healthy provider)
/api/consensus/tip NOT_TESTABLE probed through router — No pairings available
/api/consensus/tipstate NOT_TESTABLE no upstream
/api/consensus/index/{height} NOT_TESTABLE this is also the chain-id verification's route; see Step 3.5
/api/consensus/blocks/{id} NOT_TESTABLE no upstream
/api/consensus/checkpoint/{id} NOT_TESTABLE no upstream
/api/consensus/updates/{index} NOT_TESTABLE no upstream
/api/txpool/transactions NOT_TESTABLE probed through router — No pairings available
/api/txpool/fee NOT_TESTABLE no upstream
/api/txpool/events NOT_TESTABLE no upstream
/api/addresses/{addr}/balance NOT_TESTABLE no upstream
/api/addresses/{addr}/events NOT_TESTABLE no upstream
/api/addresses/{addr}/events/unconfirmed NOT_TESTABLE no upstream
/api/addresses/{addr}/outputs/siacoin NOT_TESTABLE no upstream
/api/addresses/{addr}/outputs/siafund NOT_TESTABLE no upstream
/api/outputs/siacoin/{id} NOT_TESTABLE no upstream
/api/outputs/siacoin/{id}/spent NOT_TESTABLE no upstream
/api/outputs/siafund/{id} NOT_TESTABLE no upstream
/api/outputs/siafund/{id}/spent NOT_TESTABLE no upstream
/api/events/{id} NOT_TESTABLE no upstream
/api/txpool/broadcast SKIP stateful — would broadcast transaction
/api/txpool/parents NOT_TESTABLE no upstream
/api/txpool/transactions/v2/basis NOT_TESTABLE no upstream
/api/batch/addresses/balance NOT_TESTABLE no upstream
/api/batch/addresses/events NOT_TESTABLE no upstream
/api/batch/addresses/outputs/siacoin NOT_TESTABLE no upstream
/api/batch/addresses/outputs/siafund NOT_TESTABLE no upstream
/api/check/addresses NOT_TESTABLE no upstream

Log-scan findings (probe window)

No panic/fatal lines on either container, before or during probing. The only warn/error lines
on both containers are the expected [-] verify failed sending chainMessage / Rest reply is neither a JSON object nor a JSON array of objects / provider validation failed — excluding from provider list chain, all attributable to the degraded placeholder's HTTP-shape mismatch, and the
routine provider pool empty / No pairings available relay-rejection lines once the probe calls
were sent. None are spec-level defects.

Testnet verification pass (Step 7)

TESTNET_VERIFY: NOT_TESTABLE — same no-upstream reason as mainnet. Positive evidence obtained:
booting sr_sc_testnet resolved imports: ["SC"] (304 specs loaded, chain_id":"SCT" registered),
the listener came up, and the SCT-overridden chain-id verification (expected_value
172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3) executed and failed only on the
same placeholder 404 shape mismatch — not a malformed-definition or inheritance defect.

Verification Verdict Providers OK/failed Notes
chain-id (SCT override) NOT_TESTABLE 0/1 well-formed, loadable, executes; fails only because the placeholder upstream doesn't serve walletd's /api routes

Empirical block time (Step 8)

Not measured — no upstream. walletd's GET /api/consensus/index/{height} response carries no
timestamp field (confirmed from the spec's own chain-id verification parse: parser_arg: ["0","id"] extracts only id, not a timestamp), so even with a reachable upstream the only
available recipe (tip height + index/{height} at an older height) cannot yield two timestamps.
Per the brief's instruction, no number is invented.

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet (SC) — skipped: no upstream 600000 - skipped
testnet (SCT) — skipped: no upstream 600000 - skipped

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 9 — parallel reviewers (3 independent /review-spec passes) · re-validating head a299510

Reviewer TALLY Report Lines
1 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_1.md 209
2 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_2.md 200
3 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_3.md 152

Merged gaps: none. All three fresh-context reviewers returned zero CRITICAL, zero MEDIUM
and zero MINOR findings on sc.json at head a299510.

Anti-collision check passed: the three reports have distinct md5sums and distinct lengths, so
each reviewer wrote its own path (no shared-file overwrite, no duplicated review). No reviewer
cited an evidence_line_number outside sc.json's 576 lines, so none reviewed stale state.

What each pass independently confirmed

  • Reviewer 1 — exact 21 GET + 8 POST match against walletd v2.15.2's authoritative route
    table (api/server.go), with the full delta to walletd's 38 registered routes accounted for
    (wallet-management, debug-gated, health/P2P-admin, rescan surfaces). Block parsing, category
    flags, compute units, parse directives, the chain-id verification and the SCT override all
    check out. All automated gate scripts pass clean.
  • Reviewer 2 — re-derived the route table from source rather than from any prior
    transcription
    , reaching the same 21+8 match. Went one layer deeper, into the SQL store behind
    the output/event endpoints, and confirmed the deterministic split between address-keyed
    (false) and ID-keyed (true) endpoints is a principled reflection of walletd's
    error-vs-silent-zero behaviour under personal index mode — not an inconsistency.
  • Reviewer 3 — verified the SCT inheritance override against the guide's documented
    verification merge-semantics special case (empty arrays merge rather than zero out; a same-named
    verification with no parse_directive inherits the parent's while adopting the child's
    expected_value), the POST collection's single content-type: application/json
    pass_override against all 8 JSON-decoding POST handlers, and the un-prefixed hex
    expected_value shape against btc.json/aptos.json/stellar.json precedent. It also
    recorded three investigated-and-dismissed leads so later reviewers do not re-walk them:
    missing /syncer/* routes, the absence of hanging_api on /txpool/broadcast, and
    address-endpoint determinism versus Cardano/Stellar/Aptos precedent.

Context carried into the reviews

Each reviewer read docs/sc/METHOD_PROBE_REPORT.md first. Phase 8's NOT_TESTABLE rows (28 apis,
no public walletd upstream) were treated as "nothing existed to probe against" — not as method
failures and not as evidence of a spec defect — per the free-tier disable rule. The three
deliberate decisions on this PR (no index-mode verification, no /api/wallets/* routes, no
archive/pruning/GET_EARLIEST_BLOCK triplet) were passed to all three as settled and are
correctly reflected as absent; none was re-litigated or proposed for reversal.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 10 — gap synthesis + fix pass, and Phase 10b — smoke re-probe · head a299510

Consolidation

0 critical, 0 medium; 0 disable-suggestions stripped → docs/sc/FIX_LIST.md

All three Phase 9 reviewers returned CRITICAL=0 MEDIUM=0 MINOR=0, so the deduplicated gap
list is empty. A cross-check grep over all three reports for severity-tagged rows the tallies
might have under-counted also came back empty. There were no MINOR gaps to drop, and the
free-tier disable filter stripped nothing — no reviewer proposed enabled: false on any method,
addon, or collection, and Phase 8 produced no probe errors that could be misread as evidence of
absence (all 28 non-stateful apis were NOT_TESTABLE, i.e. nothing existed to probe against,
which is weaker evidence than a probe error and never justifies disabling).

Fix pass — no edit applied

sc.json is byte-identical to committed head a299510. git diff HEAD -- sc.json is empty
both before and after this phase. The fixer's contract is "do not touch any field not mentioned
in the gap list", and the gap list is empty, so no fixer edit was warranted. Nothing is left
uncommitted in the working tree for the pipeline's commit step to pick up — this re-validation
confirms the existing head rather than changing it.

Phase 10a — post-fix static gates (run regardless)

Gate Result
jq parse exit 0
check_method_schema.sh PASS — all 29 apis schema ok, empty FAIL section
check_unused_fields.sh RESULT: PASS (no removed fields)
check_hanging_api.sh PASS — empty FAIL and empty INFO
check_stateful.sh PASS — empty FAIL and empty INFO (no consensus advisories)
check_internal_paths.sh RESULT: PASS (0 warnings, no errors)
check_disabled_count.sh RESULT: PASS — 0 distinct disabled methods, matching the body's <!-- disabled-count: 0 --> marker (no marker update needed)

Governance-field guard: an explicit scan for all 15 fields removed in smart-router #218 —
the nine spec-level governance fields, the proposal.title/proposal.description/top-level
deposit envelope fields, and extra_compute_units/category.local/category.subscription —
returns 0 hits. The envelope remains the canonical { "proposal": { "specs": [ … ] } }:
top-level keys are exactly ["proposal"] and proposal's are exactly ["specs"].
compute_units is the only compute-unit input, and the spec declares no subscription (no
FUNCTION_TAG_SUBSCRIBE directive anywhere), so no category.subscription is implied.

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

No regressions. Both variants were re-booted on ghcr.io/magma-devs/smart-router:latest
(Phase 8 used :main; no behavioural difference between the tags was observed).

Boot check SC (3360/7779) SCT (3460/7879)
RPCSmartRouter Listening + ready for requests present present
Fatal signatures (failed to load any specs, spec not found for chainId, Bad verification definition, duplicate, panic, fatal) none none
Spec load total_specs_loaded: 304 total_specs_loaded: 304, spec_ids includes SCT
imports: ["SC"] resolution — OK — SCT's chain-id override carries only expected_value (172fb3d5…) and correctly inherits SC's parse_directive (/api/consensus/index/0)
chain-id definition well-formed/loadable OK OK

Post-fix verdicts: PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · TESTNET_VERIFY: NOT_TESTABLE
· ADDONS: none declared. All seven probe items came back NOT_TESTABLE (no provider), matching
Phase 8 row-for-row.

Why no regression was structurally possible at the probe level, stated plainly: nothing was
PASS or TESTED_OK in Phase 8, because no public walletd upstream exists. So the comparison
rules had no classification that could regress. What this pass did establish is the part that
is still meaningful without an upstream — the spec continues to load and boot cleanly in the
router on both variants, with no fatal or Bad verification definition signature in either
container's full log, and SCT's inheritance intact. The placeholder upstream's chain-id failure
(404 page not found from the siascan explorer's un-prefixed routes) is an upstream URL-shape
mismatch, identical to Phase 8, and is not a defect in the spec's expected_value.

Log scan of the probe window: no panic/fatal and no non-benign errors. Five lines matched the
literal string 429 but all were false positives (GUIDs/timestamps containing that digit run);
no actual HTTP 429 occurred on either container. Both containers torn down; no sr_sc*
containers remain.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED · head a299510

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0

A fresh-context reviewer re-ran /review-spec on sc.json and reported zero remaining CRITICAL
and zero MEDIUM gaps (and zero MINOR). Report: docs/sc/SPEC_REVIEW_GAPS_final.md (272 lines).
Prior-run reports were archived to docs/sc/_archive/ before dispatch so they could not anchor
the review.

Stale-state sanity check passed: the highest line number the report cites is 561, inside
sc.json's 576 lines. The reviewer saw the live file, which — because the fix phase applied zero
edits — is byte-identical to committed head a299510.

What the final pass covered

Audit section Result
Removed-field / internal-path guards PASS (0 hits; 0 warnings, 0 errors)
Disabled-API / disabled-collection audit (verified independently) 0 disabled apis, 0 disabled collections — consistent with the empty Disabled-API Justifications ledger
Provider identification walletd v2.15.2 confirmed as the node software
Network parameters no defects (average_block_time 600000 on both nets, block_distance_for_finalized_data 6, blocks_in_finalization_proof 3 per PoW/probabilistic finality, allowed_block_lag_for_qos_sync 1)
API completeness 29 apis (21 GET + 8 POST) across 2 specs and 3 collections, checked against walletd's authoritative route table
Method-by-method: block parsing, category flags, compute units no defects
Parse directives no defects
Verifications no defects (chain-id genesis pin well-formed)
Collection inheritance (SCT) correct — inherits SC with only the intentional chain-id override
Headers no defects
Collection layout / duplicate names clean

Scope of the verdict — read this alongside the approval

This APPROVED verdict is a static and boot-level judgement. Live method coverage was never
obtained, because no public walletd upstream exists for Siacoin mainnet or zen testnet: PARSE,
VERIFY and TESTNET_VERIFY are all NOT_TESTABLE, and 28 of the 29 apis were never probed
against a real node (the 29th, /api/txpool/broadcast, is deliberately skipped as stateful).
What is verified: the spec loads and boots cleanly in the smart-router on both SC and SCT,
with no Bad verification definition, no spec not found for chainId, and no fatal signature in
either container's log; SCT's imports: ["SC"] resolves and its chain-id override correctly
inherits SC's parse_directive; and every offline gate passes.

The two genesis block ids pinned by the chain-id verification remain verified only out-of-band
(on the project's private walletd v2.15.2 nodes on 2026-10-20, independently re-confirmed against
api.siascan.com) — not through the router. Live confirmation needs a reachable walletd node:
/rerun-probe mainnet=<url>.

Re-validation outcome for the a299510 change

The commit's removal of the index-mode verification left no artifact. /api/state remains a
clean, ordinary probe-able route with no dangling reference, and the sole remaining verification
(chain-id) loads and executes well-formed on both variants. Per the triggering comment and the
PR body's "Update 2026-10-29", the index-mode check was not re-added and no /api/wallets/*
routes were introduced — in Phase 8, in the (empty) Phase 10 fix pass, or anywhere else in this
run. No reviewer proposed either change.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (tail of Phase 11; this pipeline run covered Phases 8–11 at head a299510)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a `jq` exit 0)
- ✓ All required fields present                          (Phase 11 final review; removed-field guard PASS, 0 hits)
- ✓ No duplicate API names within any collection         (Phase 11 collection-layout/duplicate-name check)
- ✓ Proper indentation/formatting                        (file unchanged from commit a299510; no reformat)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (Phase 11 network-parameters audit: abt 600000 both nets,
                                                          bdfd 6, bifp 3 per PoW/probabilistic finality, lag 1)
- ☐ All APIs tested and working                          (NO public walletd upstream exists — 28 of 29 apis
                                                          NOT_TESTABLE, 1 SKIP stateful; see
                                                          docs/sc/METHOD_PROBE_REPORT.md. Needs a reachable
                                                          walletd node: /rerun-probe mainnet=<url>)
- ☐ Block parsing validated for each API                 (not exercised — the chain tracker never started, since
                                                          no provider could pass startup verification)
- ☐ Parse directives executed by live router             (Phase 8 Step 3.5: PARSE=NOT_TESTABLE,
                                                          VERIFY=NOT_TESTABLE; Phase 10b re-check: identical.
                                                          Definitions confirmed WELL-FORMED and loadable on both
                                                          variants — no Bad verification definition — but never
                                                          executed against a real node)
- ~ Addons & extensions tested                            (ADDONS: none declared — 0 addons, 0 extensions in the
                                                          spec, so there is nothing to test; vacuously complete)
- ☐ Verifications pass on live nodes                     (the sole `chain-id` verification failed only against a
                                                          clearly-labelled degraded placeholder on a 404 URL-shape
                                                          mismatch, not a value mismatch. The two genesis ids are
                                                          verified out-of-band only — private walletd v2.15.2 nodes
                                                          2026-10-20, re-confirmed vs api.siascan.com — NOT through
                                                          the router. Phase 6's live chain-id curl was also
                                                          unavailable for the same reason)
- ☐ 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                                (SC: 29 apis across GET + POST collections)
- ✓ Testnet spec inherits correctly                      (SCT imports ["SC"]; Phase 10b boot confirmed the import
                                                          resolves and the chain-id override inherits SC's
                                                          parse_directive; Phase 11 reviewer confirmed the merge
                                                          semantics)
- ☐ Chain IDs verified for mainnet AND testnet           (NOT live-verified through the router on either network —
                                                          TESTNET_VERIFY: NOT_TESTABLE. Out-of-band evidence only,
                                                          as above)
- ☐ Both tested on respective networks                   (no upstream existed for either network)

#### Governance Prep (out of skill scope — manual reminder)
- ☐ Proposal JSON formatted correctly                    (envelope IS canonical: top-level keys exactly
                                                          ["proposal"], proposal's exactly ["specs"]; no
                                                          title/description/deposit; 0 of the 15 removed fields)
- ☐ Community feedback gathered (if applicable)

Honest status of this run

  • Verdict: APPROVED — 0 CRITICAL, 0 MEDIUM, 0 MINOR from the final reviewer, and 0/0/0 from all
    three Phase 9 reviewers independently. Not upgraded from anything: no phase in this span produced
    a CHANGES-REQUESTED condition.
  • No spec change was made. The Phase 10 fix list was empty, so sc.json in the working tree is
    byte-identical to committed head a299510. There is nothing uncommitted for the pipeline's commit
    step to pick up. This run confirms the existing head rather than amending it.
  • The a299510 change re-validated clean. Removing the index-mode verification left no
    artifact: /api/state is still a clean ordinary route, and the sole remaining chain-id
    verification loads and runs well-formed on both SC and SCT. Per the triggering comment, the check
    was not re-added and no /api/wallets/* routes were introduced at any point in this run.
  • Governance-field constraint honoured. None of the 15 fields removed in smart-router #218 are
    present (explicit scan: 0 hits), compute_units is the only compute-unit input, and the spec
    declares no subscription — it has no FUNCTION_TAG_SUBSCRIBE directive, so no
    category.subscription was implied anywhere.
  • The one standing gap is infrastructure, not the spec: no public walletd instance exists for
    Siacoin mainnet or zen. This run did its own endpoint research and re-confirmed that
    independently. Every live verdict is therefore NOT_TESTABLE, and the real verification remains
    the manual smart-router run against the private walletd nodes (the PR body commits to posting it).
    To close the gap in CI: /rerun-probe mainnet=<url>.

Auto-decisions taken (no human on this unattended run)

  1. Phase 8 with zero endpoints → degraded boot rather than skip. The <!-- ENDPOINTS --> block
    is intentionally blank and research re-confirmed no public walletd exists. The conservative
    default was taken: run the strongest subset possible without an upstream (the router spec-graph
    load + boot, for both variants) and mark every live verdict NOT_TESTABLE with evidence, rather
    than silently skipping the phase or inventing an endpoint. api.siascan.com was used strictly as
    a labelled degraded placeholder to reach the verification stage — it is the siascan explorer
    backend, not walletd, and must never be configured as a provider.
  2. ws-capable-node gate did not fire. The spec declares no subscription methods (function_tags
    are only GET_BLOCKNUM, GET_BLOCK_BY_NUM, VERIFICATION), so the absence of a ws upstream is
    not a blocker and no STOP-and-ask comment was warranted.
  3. Phase 10b run despite an empty fix list. The skill permits skipping 10b only when Phase 8 was
    skipped; Phase 8 ran, so the smoke pass was executed rather than reasoned away.
  4. <!-- disabled-count: 0 --> left unchanged. Recomputed from the file on disk: 0 distinct
    enabled: false methods, so the marker is still true and the Disabled-API Justifications ledger
    is correctly empty.

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

Elapsed:         00h 32m 14s  (first→last logged activity)
Transcripts:     1 main + 6 subagent
API round-trips: 384  (main=71, subagents=313)

Fresh tokens:    input=768  output=213353  (sum=214121)
Cached tokens:   cache_read=28369299  cache_write=1427696
Total billed:    30011116 tokens

Split (total billed):  main=7766969  subagents=22244147

Models used:
  claude-sonnet-5         313 calls   22244147 billed
  claude-opus-5            71 calls   7766969 billed

These figures cover only this resumable run (Phases 8–11). They are not a Phases 1–11 grand
total: the Phases 1–7 research and drafting ran in a separate create_spec workflow run (and its
time/tokens live in that run and the PR body), and the earlier 2026-10-20 pipeline run covering
Phases 8–11 at the previous head is a third, separate tally. The true total is those runs added
together.

Kraken calls it in production (MAG-2968 comment 30943). walletd serves it
as a public route (wrapPublicAuthHandler in api/server.go, v2.15.2), so it
needs no walletd password, like every other route in this spec. It returns
the peer list of whichever node the router picks: deterministic false,
stateful 0, DEFAULT latest, and CU 10 like /api/txpool/fee. SCT inherits
it from SC.

Tested with smart-router v1.6.2 against our walletd v2.15.2 nodes: on
mainnet and zen it answers 200 through the router, the same as calling
walletd directly.

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

AnnaR-prog commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

/rerun-from 8
Re-validate head 3b75f23. It adds GET /api/syncer/peers on purpose: The customer calls it in production (see the PR body section "Update 2026-11-01"). Keep it: it is a public walletd route, DEFAULT latest, deterministic false, stateful 0, CU 10. Do NOT add any /api/wallets/* route (the customer uses none of them), do NOT add an authorization header directive or router auth config (omer chose option 1: the walletd password is never stored or passed through), and do NOT re-add the index-mode check.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

@magmadevs-bot

magmadevs-bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 8 — smart-router boot + method probe (resumable run, Phases 8–11 · re-validating head 3b75f23)

Verdicts: SPEC_LOAD: OK (SC and SCT) · PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · ADDONS: none declared · TESTNET_VERIFY: NOT_TESTABLE · spec defects in boot logs: none
Counts: PASS=0 FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=29 WARN=0 TIMEOUT=0 LOG_WARN=0
BLOCK_TIME: mainnet=skipped testnet=skipped (no upstream, and walletd's /api/consensus/index/{height} response carries no timestamp — no recipe exists regardless)

Auto-decision (no human on this run): the <!-- ENDPOINTS --> block is empty, so the Phase 3/8 endpoint-research fallback ran and independently re-confirmed that no public walletd instance exists (mainnet or Zen) — the third consecutive run to reach that conclusion. Rather than silently skipping Phase 8, the conservative default was taken: run the strongest subset possible without an upstream — the router spec-graph load boot for both variants — and mark every live verdict NOT_TESTABLE with per-source evidence. NOT_TESTABLE is not coverage. Live method/parse/verification coverage for this spec requires a reachable walletd node (retry with /rerun-probe mainnet=<url>).

What changed vs. head a299510: NOT_TESTABLE went 28 → 29 — the one added route, GET /api/syncer/peers (30 routes total = 22 GET + 8 POST; 1 SKIP for the stateful broadcast). The router accepted it into the spec graph with no complaint. Its presence, the absence of /api/wallets/*, the absence of an authorization header directive, and the absence of the index-mode verification were all treated as settled decisions, not findings.


Method Probe Report — sc

Generated: 2026-11-01T14:44:08Z
Router image: ghcr.io/magma-devs/smart-router:main (sha256:6583f57b097d221d7704096ce5eb1319eb6e2942556d051bbcd0626f2a2797ef)
Router config: /tmp/sr_sc.yml (mainnet load boot), /tmp/sr_sc_testnet.yml (testnet load boot)
Spec variant: SC (rest, GET + POST collections), SCT (rest, thin-import of SC)
Upstreams probed: none — no reachable public walletd upstream exists. See "Endpoint research" below.

Endpoint research (crux of this run)

Two prior pipeline runs on this PR (2026-10-20, 2026-10-29) concluded no public walletd instance exists for Siacoin mainnet or Zen testnet. This run independently re-confirmed that conclusion with a fresh, time-boxed search (~10 minutes):

  • WebSearch — "public walletd API endpoint Sia Foundation reachable https", "walletd Sia api/consensus/tip public node", "siascan explored api public endpoint". All three confirm: no public walletd instance is documented anywhere (docs.sia.tech, SiaFoundation GitHub, pkg.go.dev); walletd is designed to be run privately (optionally with --http.public to drop auth on safe routes, but no operator publishes one); the customer is known to run walletd but not publicly; api.siascan.com is the explored (explorer) daemon, not walletd, and shares only a small subset of routes (/consensus/tip, /consensus/network), confirming the "do not use as provider" instruction.
  • Direct curl probes (candidate validation per the instructions — GET <base>/api/consensus/tip + GET <base>/api/consensus/index/0, checking for walletd's {"height":…,"id":…} shape with the /api prefix):
    • https://walletd.sia.tech, https://walletd.siacentral.com, https://api.siacentral.com — no DNS/connection (curl exit 000).
    • https://wallet.sia.tech — HTTP 523 (Cloudflare origin unreachable).
    • https://api.sia.tech/api/consensus/tip — HTTP 200 but returns the Sia API documentation single-page app HTML, not a live walletd — not a real API, ruled out.
    • https://api.siascan.com/api/consensus/tip and .../api/consensus/index/0 — HTTP 404 ("page not found"), confirming siascan's route tree has no /api prefix and no /api/consensus/index/{height} — exactly the mismatch the task description flagged. Not used as a provider.
  • Corroboration-not-probe (chain facts only, labeled as such, matching prior-run methodology): https://api.siascan.com/consensus/tip/0 → {"height":0,"id":"25f6e3b9295a61f69fcb956aca9f0076234ecf2e02d399db5448b6e22f26e81c"} and https://api.siascan.com/zen/consensus/tip/0 → {"height":0,"id":"172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3"}. Both genesis ids exactly match the spec's chain-id verification expected_value for SC and SCT respectively — strong independent corroboration that the spec's verification values are correct, even though this explorer cannot serve as a router upstream.
  • The team's own walletd nodes are on a private machine CI cannot reach (per the triggering comment); not independently verifiable from this environment, taken as given.

Conclusion: re-confirmed — no reachable walletd upstream exists. Proceeding with the conservative fallback: router spec-graph load boots only, no method probing, no verification-pass (beyond observing it execute and fail solely on connection-refused), no block-time measurement.

Spec-graph load boot (SC)

Docker: image was genuinely missing locally and was pulled fresh (docker pull ghcr.io/magma-devs/smart-router:main) — succeeded, digest sha256:6583f57b097d221d7704096ce5eb1319eb6e2942556d051bbcd0626f2a2797ef.

Config /tmp/sr_sc.yml: chain-id: SC, api-interface: rest, one direct-rpc block pointed at an intentionally-unreachable http://127.0.0.1:9999 (no real upstream exists; the goal of this boot is purely to exercise the router's startup spec resolution, not to serve real traffic).

Boot log evidence (docker logs sr_sc):

  • "spec_count":"304" ... "message":"Loaded specs from local directory" — all specs in the staging dir parsed, including sc.json.
  • "chain_id":"SC","total_sources":"1","total_specs_loaded":"304" ... "message":"Successfully loaded and expanded spec from aggregated sources" — SC's two rest collections (22 GET + 8 POST = 30 apis) and its chain-id verification parsed into the router's spec graph without error.
  • "message":"RPCSmartRouter Listening" and "message":"RPCSmartRouter done setting up all endpoints, ready for requests" — listener bound successfully.
  • GET http://localhost:3360/api/consensus/tip → HTTP 500 — expected: no healthy provider (the only configured upstream is unreachable by design), not a spec defect. The router does NOT crash or exit; it logs "ATTENTION: no healthy providers for endpoint — serving unavailable until one recovers" and keeps retrying in the background.
  • Verification chain-id did execute against the configured (unreachable) upstream and failed solely with PROTOCOL_CONNECTION_REFUSED / dial tcp 127.0.0.1:9999: connect: connection refused — an endpoint artifact, not a spec defect (confirms the verification's function_template/result_parsing are wired up and reachable by the router's verification engine; it just has nothing to talk to).
  • Grep for spec-level defect signatures (panic, failed to load any specs, spec not found for chainId, Bad verification definition, duplicate-api-name, invalid-parser) → none found, clean.

SPEC_LOAD (SC): OK

Spec-graph load boot (SCT)

Config /tmp/sr_sc_testnet.yml: chain-id: SCT, api-interface: rest, same unreachable placeholder upstream.

Boot log evidence (docker logs sr_sc_testnet):

  • "spec_count":"304" ... "message":"Loaded specs from local directory", "chain_id":"SCT","total_specs_loaded":"304" ... "message":"Successfully loaded and expanded spec from aggregated sources" — SCT's imports: ["SC"] closure resolved cleanly (SC's 30 apis + SCT's own override of the chain-id verification value).
  • Verification chain-id executed with the SCT-specific expected_value (172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3) against the same unreachable upstream — failed only with connection-refused, same as SC. Confirms SCT's override is live and distinct from SC's, not silently inherited unchanged.
  • GET http://localhost:3360/api/consensus/tip → HTTP 500 (same expected no-healthy-provider artifact).
  • Grep for spec-level defect signatures → none found, clean.

SPEC_LOAD (SCT): OK

Both containers (sr_sc, sr_sc_testnet) were run sequentially (not concurrently — same host ports) and torn down (docker rm -f) after their boot logs were captured. No leftover containers (docker ps -a --filter name=sr_sc is empty).

Parse-directive & verification runtime check (Step 3.5)

No chain tracker cycles ran (no healthy provider → "no direct RPC endpoints to initialize ChainTrackers"), so PARSE directives are NOT_TESTABLE, not OK/FAIL — do not read this as coverage.

Check Verdict Evidence
GET_BLOCKNUM (/api/consensus/tip) NOT_TESTABLE no reachable walletd upstream; searched WebSearch (3 queries) + direct curl against api.sia.tech, api.siascan.com, walletd.sia.tech, walletd.siacentral.com, api.siacentral.com, wallet.sia.tech → none serve a live walletd API. Router log: "no direct RPC endpoints to initialize ChainTrackers".
GET_BLOCK_BY_NUM (/api/consensus/index/%d) NOT_TESTABLE same — tracker never ran.
Parse-signature log lines none no failed to parse response / ParseBlockHashFromReplyAndDecode / etc. signatures in either boot log — consistent with the tracker never running, not with a parse defect being masked.
Verification Verdict Providers OK/failed Notes
chain-id (SC) NOT_TESTABLE (executed, failed only on connection-refused) 0/1 function_template/result_parsing confirmed wired (verification engine sent the request); failure is PROTOCOL_CONNECTION_REFUSED against the deliberately-unreachable placeholder, not a spec/result-parsing defect. Independently corroborated via api.siascan.com: mainnet genesis id matches expected_value exactly.
chain-id (SCT) NOT_TESTABLE (executed, failed only on connection-refused) 0/1 Same shape, SCT-specific expected_value confirmed live and distinct from SC's. Independently corroborated via api.siascan.com/zen: Zen genesis id matches expected_value exactly.

Addon & extension coverage (Step 1c + probes)

ADDONS: none declared. jq over sc.json for .add_on and .extension fields returns empty lists. No archive/debug/trace addon, no pruning verification, no GET_EARLIEST_BLOCK — all deliberately absent per walletd having no pruning mechanism. No addon table is applicable; nothing to classify TESTED_OK/TESTED_FAIL/NOT_TESTABLE.

Per-method table (all 30 methods — NOT_TESTABLE, no reachable upstream)

Method Classification Upstream notes Notes
GET /api/state NOT_TESTABLE — no reachable walletd upstream; searched WebSearch + candidate curls → none
GET /api/consensus/network NOT_TESTABLE — same
GET /api/consensus/tip NOT_TESTABLE — same (GET_BLOCKNUM template)
GET /api/consensus/tipstate NOT_TESTABLE — same
GET /api/consensus/index/{height} NOT_TESTABLE — same (GET_BLOCK_BY_NUM / chain-id verification template)
GET /api/consensus/blocks/{id} NOT_TESTABLE — same
GET /api/consensus/checkpoint/{id} NOT_TESTABLE — same
GET /api/consensus/updates/{index} NOT_TESTABLE — same
GET /api/syncer/peers NOT_TESTABLE — present on purpose (the customer's production usage, head 3b75f23); deterministic:false, body legitimately differs per node — not probed here, not a defect
GET /api/txpool/transactions NOT_TESTABLE — same
GET /api/txpool/fee NOT_TESTABLE — same
GET /api/txpool/events NOT_TESTABLE — same
GET /api/addresses/{addr}/balance NOT_TESTABLE — same
GET /api/addresses/{addr}/events NOT_TESTABLE — same
GET /api/addresses/{addr}/events/unconfirmed NOT_TESTABLE — same
GET /api/addresses/{addr}/outputs/siacoin NOT_TESTABLE — same
GET /api/addresses/{addr}/outputs/siafund NOT_TESTABLE — same
GET /api/outputs/siacoin/{id} NOT_TESTABLE — same
GET /api/outputs/siacoin/{id}/spent NOT_TESTABLE — same
GET /api/outputs/siafund/{id} NOT_TESTABLE — same
GET /api/outputs/siafund/{id}/spent NOT_TESTABLE — same
GET /api/events/{id} NOT_TESTABLE — same
POST /api/txpool/broadcast SKIP — stateful: 1 — would broadcast a transaction; never probed regardless of upstream availability
POST /api/txpool/parents NOT_TESTABLE — same
POST /api/txpool/transactions/v2/basis NOT_TESTABLE — same
POST /api/batch/addresses/balance NOT_TESTABLE — same
POST /api/batch/addresses/events NOT_TESTABLE — same
POST /api/batch/addresses/outputs/siacoin NOT_TESTABLE — same
POST /api/batch/addresses/outputs/siafund NOT_TESTABLE — same
POST /api/check/addresses NOT_TESTABLE — same

Deliberately absent from the spec (not findings, not missing coverage — confirmed on-purpose per the triggering comment): /api/wallets/* routes, authorization header directive / router auth config, index-mode verification.

Log-scan findings (probe window)

No method probe loop ran (no reachable upstream to probe through), so there is no probe-window log scan. The only warn/error lines in either boot's log are the expected per-retry [-] verify failed sending chainMessage / provider node error / refusing node url / retry: provider verification still failing lines against the intentionally-unreachable placeholder (PROTOCOL_CONNECTION_REFUSED), which are the load-boot's deliberate endpoint artifact, not router-wide or spec-level errors. No fatal/panic lines in either log.

Level Associated method error excerpt
(none — clean) — —

Testnet verification pass (Step 7)

TESTNET_VERIFY: NOT_TESTABLE (no reachable walletd upstream for either network; see Endpoint research above). The SCT load boot (above) did execute the chain-id verification with the SCT-specific expected_value and confirmed it is distinct from SC's and independently corroborated against api.siascan.com/zen's genesis id — this is as far as verification could be exercised without a reachable upstream.

Verification Verdict Providers OK/failed Notes
chain-id (SCT) NOT_TESTABLE (executed, failed only on connection-refused) 0/1 see SCT load boot section above

Empirical block time (Step 8)

BLOCK_TIME: mainnet=skipped testnet=skipped

No recipe applies regardless of upstream availability: walletd's /api/consensus/index/{height} response is {"height":…,"id":…} and carries no timestamp, so there is no way to compute an empirical block interval from this API family even with a reachable node. This is independent of the "no upstream" finding above.

Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet — - n/a - skipped (no timestamp field in walletd's consensus/index response)
testnet — - n/a - skipped (same reason; also no reachable upstream)

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 9 — parallel reviewers (3 independent /review-spec passes) · re-validating head 3b75f23

Reviewer TALLY Report Size
1 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_1.md 11160 B
2 CRITICAL=0 MEDIUM=3 MINOR=1 docs/sc/SPEC_REVIEW_GAPS_parallel_2.md 11210 B
3 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_3.md 9020 B

Integrity checks: all three reports landed at their own numbered paths (no shared-path write), all three md5 digests differ (no reviewer wrote another's path), and every evidence line reference falls inside sc.json's 591 lines — no stale-state review. Each reviewer was briefed with the settled decisions for this PR (/api/syncer/peers stays; no /api/wallets/*; no auth header; no index-mode check; the deliberately-absent archive/pruning/GET_EARLIEST_BLOCK triplet; internal_path: "" convention) so none of them re-litigated those.

No CRITICAL findings from any reviewer. Reviewers 1 and 3 found the spec clean. Reviewer 2's merged gaps:

MEDIUM 1 — POST /api/syncer/broadcast/block missing from the spec

Reviewer 2 notes walletd registers it under wrapPublicAuthHandler (public, no password) and argues it is an unintentional coverage gap, proposing it be added with stateful: 1.

Auto-decision: NOT applied — the reviewer's premise is wrong. This route is a documented deliberate omission: the PR body's include/exclude list says "Leave out: … /syncer/broadcast/block (miners only)", and the omission ledger records a source-grounded reason for it, alongside the standing instruction that the ledger entries "must not be 'fixed' by adding them." Reviewer 2 only checked the four exclusions named in its brief (/api/wallets/*, auth header, index-mode, the archive triplet) and did not see the full ledger. The conservative default at this gate is to preserve the documented decision rather than widen a spec scoped for an exchange integration with a stateful block-relay write path that no consumer of this spec uses. Carried to the watch-list below for the human reviewer instead.

MEDIUM 2 — /api/consensus/updates/{index} underpriced at CU 20 → fix applied in Phase 10

consensusUpdatesIndexHandler takes a limit form param (default 10, max 100) and returns up to 100 RevertUpdate/ApplyUpdate entries, each embedding a full Block and full State. That is a bulk fetch, not the flat-20 "single record by id" tier it currently shares with /api/consensus/blocks/{id} et al.

MEDIUM 3 — /api/consensus/updates/{index} marked deterministic: true but is tip-bounded → fix applied in Phase 10

UpdatesSince(index, limit) returns updates since index capped at limit, so for any index near the tip the result set grows between two identical calls. The same spec already marks every other tip-bounded query (/api/consensus/tip, /api/txpool/*, /api/addresses/*) deterministic: false. Leaving it true risks cross-provider data-reliability checks flagging honest providers near the chain head.

MINOR (dropped from the fix list per the consolidation rule, recorded here)

  • CU spread between /api/check/addresses (20) and the sibling /api/batch/addresses/* endpoints (60) despite both capping input at 1000 addresses. Reviewer 2 rates the impact "low" and notes the lighter response body ({Known: bool}) plausibly justifies a lower CU — just maybe not a full 3×.

Watch-list for the human reviewer (no spec change made)

  • POST /api/syncer/broadcast/block — deliberately omitted as miners-only. If a Lava consumer ever needs to relay self-constructed blocks, this is the route to revisit; adding it is a scope decision, not a defect fix.
  • Every live verdict remains NOT_TESTABLE (Phase 8): no reachable walletd upstream exists anywhere public. The spec's method/parse/verification behaviour is still unexercised against a real node. Re-run with /rerun-probe mainnet=<url> once a reachable walletd is available.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 10 — gap synthesis + fix pass, and Phase 10b — smoke re-probe · head 3b75f23

Consolidation

0 critical, 2 medium; 0 disable-suggestions stripped; 1 settled-decision strip; 1 MINOR dropped → docs/sc/FIX_LIST.md

Reviewers 1 and 3 returned no findings, so the merged CRITICAL+MEDIUM set is reviewer 2's, deduplicated. Both applied items target the same api entry.

Fixes applied (uncommitted in the working tree — a later workflow step commits them)

  • sc.json:138 — raised compute_units 20 → 60 on GET /api/consensus/updates/{index} (gap: MEDIUM, "/api/consensus/updates/{index} compute_units likely underpriced at 20"). walletd's consensusUpdatesIndexHandler takes a limit form param (default 10, max 100) and returns up to 100 RevertUpdate/ApplyUpdate entries, each embedding a full Block and full State — a bulk fetch, not the flat-20 "single record by id" tier it shared with /api/consensus/blocks/{id}. 60 is the bulk tier this spec already uses for its four /api/batch/addresses/* endpoints, so the CU table stays internally consistent instead of gaining a new band.
  • sc.json:141 — set category.deterministic true → false on the same api (gap: MEDIUM, "/api/consensus/updates/{index} is marked deterministic: true but is time-bounded by the chain tip"). UpdatesSince(index, limit) returns updates after index capped at limit, so near the chain head the result set grows between two identical calls. Every other tip-bounded query in this spec (/api/consensus/tip, /api/consensus/tipstate, /api/txpool/*, all /api/addresses/*) is already deterministic: false. Left true, cross-provider data-reliability checks would flag honest providers near the tip.

git diff sc.json is exactly two changed value lines (1 file changed, 2 insertions, 2 deletions). Nothing else was touched — not SCT, not the POST collection, not the parse directives, not the verifications, not a spec-level field.

Auto-decisions at this phase (no human on this run)

  1. Did NOT add POST /api/syncer/broadcast/block (reviewer 2, MEDIUM). The reviewer asserted it "is not covered by any of the deliberate-omission decisions recorded for this PR" — that premise is wrong. The PR body's include/exclude list says "Leave out: … /syncer/broadcast/block (miners only)" and the omission ledger carries a source-grounded reason plus the standing instruction that ledger entries must not be "fixed" by adding them. The reviewer saw only four of the exclusions in its brief. Conservative default: preserve the documented decision rather than widen an exchange-integration spec with a stateful block-relay write path no consumer of it uses. Carried to the PR watch-list.
  2. Declined reviewer 2's floated timeout_ms on the same api. timeout_ms replaces the CU-derived relay window rather than extending it, so adding one to an api whose CU was just tripled would shorten its window — the precise mistake the Phase 10a hanging-api gate exists to catch. The api does not set hanging_api, so no timeout_ms is required.
  3. Nothing disabled. No reviewer cited positive docs/client-source evidence for disabling anything, and the disable-suggestion filter had nothing to strip. The disabled set stays 0, matching the PR body's <!-- disabled-count: 0 --> marker — re-verified against the fixed file with check_disabled_count.sh.

Phase 10a — post-fix static gates (all PASS, empty FAIL sections)

Gate Result
jq . exit 0
check_method_schema.sh PASS — all 30 apis "schema ok", no FAIL rows
check_unused_fields.sh RESULT: PASS (no removed fields) — none of the 15 fields removed in smart-router#218 present
check_hanging_api.sh PASS — no FAIL, no INFO rows
check_stateful.sh PASS — no FAIL, no INFO/consensus rows
check_disabled_count.sh 0 distinct method(s) — matches the body marker

The envelope remains the canonical { "proposal": { "specs": [ … ] } }; compute_units remains the only compute-unit input; no category.subscription was introduced (and none could be — the spec has no FUNCTION_TAG_SUBSCRIBE directive and walletd serves no WebSocket routes).

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

Re-booted the router against the fixed spec for both variants, per the standing rule not to skip the re-boot just because the change looks small.

  • SPEC_LOAD (SC): OK · SPEC_LOAD (SCT): OK — 304 specs loaded, SC's 30 apis across GET+POST re-parsed, SCT's imports: ["SC"] closure re-resolved with its own distinct chain-id expected_value, listeners bound. No panic / fatal / failed to load any specs / spec not found for chainId / Bad verification definition / duplicate-api-name / invalid-parser signature in either log. The router accepted compute_units: 60 and deterministic: false on the fixed api without complaint.
  • Log diff vs Phase 8: no new warn/error signatures. Both boots show the identical expected chain of PROTOCOL_CONNECTION_REFUSED lines against the deliberately-unreachable placeholder upstream — the same endpoint artifact Phase 8 recorded, not a regression.
  • PARSE: NOT_TESTABLE · VERIFY: NOT_TESTABLE · TESTNET_VERIFY: NOT_TESTABLE · ADDONS: none declared — unchanged from Phase 8. Every method was NOT_TESTABLE (or SKIP for the stateful broadcast) before the fix, so there is no PASS to regress from; per the smoke-tester's own rule, no-data is not a regression. Phase 8's classifications are carried forward unchanged and remain unverified, not covered.
  • Structural re-confirmation on the fixed file: 22 GET + 8 POST = 30 apis, parse directives ["GET_BLOCKNUM","GET_BLOCK_BY_NUM"], chain-id on both SC and SCT (distinct values), 0 disabled apis.
  • Image tag: this pass ran :latest (digest sha256:476faaac…) as its instruction file specifies, where Phase 8 ran :main (digest sha256:6583f57b…). Recorded for an honest comparison — the two boots are on different digests, which is the documented tag split between the two phases, not a discrepancy introduced here.
  • Teardown: sr_sc and sr_sc_testnet both removed; no containers remain.

@magmadevs-bot

magmadevs-bot commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED · head 3b75f23 + the Phase 10 working-tree fix

TALLY: CRITICAL=0 MEDIUM=0 MINOR=1

A fresh-context reviewer re-ran /review-spec on the fixed sc.json and reported zero CRITICAL and zero MEDIUM gaps. The one MINOR is carried forward from Phase 9 (not newly introduced) and does not block. Report: docs/sc/SPEC_REVIEW_GAPS_final.md (128 lines). Prior reviews were archived to docs/sc/_archive/ before dispatch so the final pass was not anchored on them.

What the final pass verified

  • Both Phase 10 fixes are correct and internally consistent. With /api/consensus/updates/{index} at CU 60, the full 30-api CU table now reads as a clean three-tier structure: 10 static/tip reads, 20 single-record lookups, 60 bulk/batch responses (the four /api/batch/addresses/* plus this one), and 10 for the single stateful broadcast. The deterministic: false flip correctly moves a tip-bounded window out of the immutable-by-id grouping it had been lumped into.
  • Disabled-API Justifications ledger — vacuously satisfied. jq confirms zero enabled: false entries anywhere in the file, matching check_disabled_count.sh (0 distinct method(s), 0 row(s)) and the PR body's <!-- disabled-count: 0 --> marker. The marker is true against the file as shipped; no body revision was needed.
  • Guards clean: check_unused_fields.sh PASS (none of the 15 fields removed in smart-router#218), check_internal_paths.sh PASS (0 warnings, 0 errors — no NAME_CARRIES_PATH, LABEL_AS_PATH, AMBIGUOUS_REST_NAME or AMBIGUOUS_REST_SHAPE), plus clean sweeps on network params, verifications, stateful, hanging-api, extensions, method schema and directive presence. All 30 api names are distinct REST path templates with no placeholder-only collisions.
  • Network params (600000 / 6 / 3 / 1 on both SC and SCT) match the established PoW baseline; the GET_BLOCKNUM / GET_BLOCK_BY_NUM templates match walletd's ChainIndex{height,id} shape; SCT's inheritance shape and its distinct chain-id override are correct.
  • Every settled decision was re-confirmed rather than re-flagged: /api/syncer/peers stays; no /api/wallets/*; no auth header or router auth config; no index-mode verification; the archive/pruning/GET_EARLIEST_BLOCK triplet deliberately all-absent; the internal_path: "" convention; and POST /api/syncer/broadcast/block left out as documented.

MINOR carried forward (non-blocking, no change made)

  • CU spread between /api/check/addresses (20) and the sibling /api/batch/addresses/* endpoints (60), despite both capping input at 1000 addresses. Dropped from the fix list per the MINOR consolidation rule. check/addresses returns a single aggregate boolean ({Known: bool}) rather than a full per-address result set, which plausibly justifies a discount — just perhaps not a full 3×. Optional nudge to ~30–40 if a maintainer wants the table tighter.

⚠️ The honest limit on this approval

APPROVED means the spec is structurally and semantically sound and loads cleanly into the smart-router's spec graph. It does not mean the spec has been exercised against a real node. For the third consecutive run, no reachable public walletd upstream exists, so PARSE, VERIFY, TESTNET_VERIFY and all 29 non-stateful methods remain NOT_TESTABLE — unverified, not covered. The genesis-id expected_values for both SC and SCT are corroborated by two independent sources but have never been live-executed through the router in CI. The PR body notes a manual smart-router run against the team's private walletd nodes (v2.15.2, mainnet and zen, with the customer's call list and headers) covering exactly this gap; that manual evidence, not this pipeline run, is what establishes live behaviour. To close it in CI: /rerun-probe mainnet=<walletd-url>.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (tail of Phase 11; this pipeline run covered Phases 8–11 at head 3b75f23)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a `jq` exit 0 on the fixed file; re-confirmed Phase 11)
- ✓ All required fields present                          (Phase 11 final review; check_unused_fields.sh PASS, 0 hits)
- ✓ No duplicate API names within any collection         (Phase 11: all 30 names distinct REST templates; no AMBIGUOUS_REST_SHAPE)
- ✓ Proper indentation/formatting                        (4-space, no trailing newline preserved; diff is 2 value lines only)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (600000/6/3/1 on SC and SCT; Phase 11 re-verified vs the PoW baseline)
- ☐ All APIs tested and working                          (Phase 8: 29 of 30 NOT_TESTABLE, 1 SKIP — NO reachable public walletd
                                                          upstream exists; see docs/sc/METHOD_PROBE_REPORT.md. NOT coverage.)
- ☐ Block parsing validated for each API                 (not exercised — no upstream; block_parsing shapes reviewed statically only)
- ☐ Parse directives executed by live router             (Phase 8 PARSE=NOT_TESTABLE, VERIFY=NOT_TESTABLE; Phase 10b re-check:
                                                          NOT_TESTABLE. The chain tracker never ran: "no direct RPC endpoints
                                                          to initialize ChainTrackers". Templates verified structurally only.)
- ~ Addons & extensions tested                           (Phase 8 Step 1c: ADDONS none declared — nothing to test. The absent
                                                          archive/pruning/GET_EARLIEST_BLOCK triplet is a source-grounded decision.)
- ☐ Verifications pass on live nodes                     (NOT run through the router. The chain-id verification executed and failed
                                                          only on PROTOCOL_CONNECTION_REFUSED against a placeholder upstream, which
                                                          proves its wiring, not its value. Both genesis ids corroborated from two
                                                          independent sources; never live-executed in CI.)
- ☐ Compute units benchmarked under expected load        (user to measure; Phase 10 raised consensus/updates 20→60 on source
                                                          evidence — reasoned, not benchmarked)

#### Spec graph / router load
- ✓ Spec loads into the smart-router spec graph          (Phase 8 SPEC_LOAD: OK for SC and SCT; Phase 10b re-confirmed on the
                                                          FIXED file — 304 specs, 30 apis, SCT imports closure resolved, no panic/
                                                          fatal/Bad verification definition/dup-api/invalid-parser signatures)
- ✓ Router accepts the Phase 10 fixed values             (Phase 10b: compute_units 60 + deterministic false accepted, no complaint)
- ✓ No regression from the fix pass                      (Phase 10b SMOKE: OK; no new log signatures vs Phase 8)

#### Governance-field guard (smart-router #218)
- ✓ None of the 15 removed fields present               (check_unused_fields.sh PASS at context-reconstruction AND post-fix)
- ✓ Canonical envelope { "proposal": { "specs": [...] } } (no title/description/deposit, no governance fields)
- ✓ compute_units is the only compute-unit input         (no extra_compute_units; no category.local/category.subscription)
- ✓ No category.subscription, and none possible          (spec has no FUNCTION_TAG_SUBSCRIBE; walletd serves no WebSocket routes)

#### Testnet vs Mainnet
- ✓ Mainnet spec complete                                (SC: 30 apis across GET+POST rest collections)
- ✓ Testnet spec inherits correctly                      (SCT imports ["SC"], overrides only chain-id; Phase 11 confirmed the
                                                          CombineUnique merge shape is textbook-correct)
- ~ Chain IDs verified for mainnet AND testnet           (both genesis ids corroborated by two independent sources and confirmed
                                                          distinct + live in the router's verification engine — but the live
                                                          Phase-6 curl could not run and TESTNET_VERIFY is NOT_TESTABLE)
- ☐ Both tested on respective networks                   (neither network probed — no reachable upstream for either)

#### Disabled APIs
- ✓ Disabled set is empty and the body marker is true     (0 enabled:false entries; <!-- disabled-count: 0 --> matches the file;
                                                          Disabled-API Justifications ledger vacuously satisfied)

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

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

Auto-decisions made in this run (no human available — all recorded)

  1. Phase 8, zero node URLs — the skill's STOP-and-ask gate. Auto-resolved with the conservative default: ran the endpoint-research fallback (which independently re-confirmed no public walletd exists), then ran the strongest subset possible without an upstream — the router spec-graph load boot for both variants — and marked every live verdict NOT_TESTABLE with per-source evidence rather than silently skipping the phase.
  2. Phase 10, POST /api/syncer/broadcast/block — declined. A Phase 9 reviewer proposed adding it on the premise that it was not a documented exclusion; that premise was wrong (the PR body's exclude list names it, "miners only"). Conservative default: preserve the documented omission.
  3. Phase 10, timeout_ms on /api/consensus/updates/{index} — declined. timeout_ms replaces the CU-derived relay window rather than extending it, so adding one to an api whose CU had just tripled would shorten its window.
  4. No ws-capable-node gate fired — the spec has no SUBSCRIBE parse directive in its resolved import closure and walletd serves no WebSocket routes, so the "STOP and ask for a ws node" rule did not apply. Verified mechanically, not assumed.

Working tree

sc.json carries the Phase 10 fix uncommitted (1 file changed, 2 insertions, 2 deletions), as required — no git operation was run by this skill. A later workflow step commits and pushes it to siacoin-spec-20-10-2026.

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

Elapsed:         00h 27m 15s  (first→last logged activity)
Transcripts:     1 main + 7 subagent
API round-trips: 365  (main=78, subagents=287)

Fresh tokens:    input=730  output=237192  (sum=237922)
Cached tokens:   cache_read=25053409  cache_write=1519047
Total billed:    26810378 tokens

Split (total billed):  main=8796987  subagents=18013391

Models used:
  claude-sonnet-5         287 calls   18013391 billed
  claude-opus-5            80 calls   9121875 billed

These figures cover only Phases 8–11 of this resumable run. The Phases 1–7 research and drafting ran in a separate create_spec.yml workflow run (and the two earlier re-validation runs at heads 31b596e and a299510 are separate again); their time and tokens live in their own runs. The true end-to-end total is the sum of all of them — not the number above, which looks complete but covers one part.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

📦 Committed pipeline fixes to siacoin-spec-20-10-2026 (1792a3a): sc.json — the branch now matches the spec that Phase 10b/11 verified.

@avitenzer

avitenzer commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Live parse + chain-id check on head 1792a3a: PASS (mainnet data via a siascan shim)

The pipeline's Phase 8 marks PARSE and VERIFY as NOT_TESTABLE because CI has no walletd upstream. This run fills that gap for the spec's block-height and chain-id directives.

Setup

  • Router: smart-router v1.6.4-9 (commit bb43ae96).
  • Spec: fetched from this PR, byte-identical to 1792a3a, including the Phase 10 compute-units fix.
  • Upstream: no public walletd exists, so a local test-only shim served the spec's two walletd routes from api.siascan.com's equivalents. Both return the same {height, id} shape:
    • /api/consensus/tip → /consensus/tip
    • /api/consensus/index/{h} → /consensus/tip/{h}
    • Every other path returned 404, so nothing else was faked.
Check Result
Spec loads; SCT → SC import resolves PASS for both
GET_BLOCKNUM (/api/consensus/tip → .height) reads a live mainnet tip PASS: latestBlock=600063, same as siascan
Requests through the router: /api/consensus/tip, /api/consensus/index/0 200, bodies identical to siascan
chain-id on SC (smartrouter health): /api/consensus/index/0 → .id == 25f6e3b9…26e81c PASS
Negative control: chain-id on SCT against mainnet data FAIL, as it should: expected 172fb3d5…, got 25f6e3b9…. The check really compares values, and SCT inherits SC's directive and overrides only the expected value.
The router never calls /api/state Confirmed: the index-mode check is gone, as intended in a299510

Not covered by this run

  • walletd's own routes: the other 28 methods, including the customer's 8 GETs and POST /api/txpool/broadcast. They're covered by the manual walletd v2.15.2 run recorded in the PR body ("Update 2026-11-01"). That run was on an earlier head, and the only change since is the compute-units bump on GET /api/consensus/updates/{index}, which doesn't change routing.
  • SCT against a real Zen node.

🤖 Generated with Claude Code

@avitenzer

avitenzer commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Merge-readiness review at head 1792a3a: not ready yet, 2 blockers

@AnnaR-prog: a review against walletd v2.15.2 source and the router at origin/main. Every finding below was checked in code; the file and line references are the ones I opened.

Blocking

1. Four routes are deterministic: true but return a different answer as the chain moves. This is the same issue Phase 10 fixed on /api/consensus/updates/{index}, which the pipeline rated MEDIUM.

Route sc.json Why its answer changes (walletd v2.15.2)
GET /api/events/{id} 341 scanEvent sets Confirmations = 1 + scanHeight - ev.Index.Height (persist/sqlite/events.go:120). The body changes every block, and between nodes indexed to different heights. The customer calls this route (MAG-2968 comment 30943).
GET /api/outputs/siacoin/{id} 281 Returns unspent outputs only, so the answer changes once the output is spent.
GET /api/outputs/siafund/{id} 311 Same as above.
GET /api/consensus/blocks/{id} 101 A numeric id is resolved as a height through cm.BestIndex(height) (api/server.go:256), so near the tip a reorg changes the answer. A block-ID id is stable. If you'd rather keep true here, say so in the body.

Why it matters: with deterministic: true, cross-validation treats honest nodes a block apart as disagreeing.

Fix: set these to false, or say in the body why each one stays true.

2. Open question: The customer's sync mode against the genesis pin. The chain-id check on /api/consensus/index/0 (sc.json:384-404) refuses a checkpoint-synced walletd, which answers 404 there. The PR body (lines 73-81) calls that the intended failure mode. The customer was asked (MAG-2968 comment 30967), and Omer's answer on 11-01 (comment 31001) was "It might be checkpoint and might be first block". That answer came after the body's last update.

If the customer's nodes were started from a checkpoint, the router refuses all of them and every customer call fails. Unlike index mode, auth and wallet routes, the pin has no owner decision recorded.

Clears when: The customer confirms its nodes synced from the first block, or Omer signs off on the pin as it is.

Not yet tested at this head

  • Real walletd at 1792a3a. The run against a real walletd (router v1.6.2) was at 3b75f23, before Phase 10 changed the CU and the deterministic flag. My run on 1792a3a used a siascan shim and covered only GET_BLOCKNUM, chain-id and two routes. To settle it: rerun the customer's call list from the body against the team's walletd node at 1792a3a.
  • SCT against a real Zen node, including the POST collection it inherits from SC (broadcast).

Non-blocking: for the reviewer, and before the customer goes live

  • Mempool and peer reads can be served 75 s stale when the router runs with a cache.
    • The router doesn't use deterministic to decide caching (see the comment at protocol/rpcsmartrouter/node_bound_methods.go:21-26). It skips only stateful requests and the names in nodeBoundMethods, which covers txpool_content, getmempoolinfo, status and others but no walletd path.
    • So /api/txpool/transactions, /api/txpool/events, /api/txpool/fee, /api/syncer/peers and /api/addresses/{addr}/events/unconfirmed are cached for 1/8 of the block time: 75 s at 600 s blocks (ecosystem/cache/core/policy.go:55).
    • The customer polls /api/txpool/transactions after broadcasting.
    • The fix is on the router side, not in this spec: the walletd paths need adding to nodeBoundMethods. /api/state and /api/consensus/network are not affected; their EMPTY parser makes them NOT_APPLICABLE, and those are never cached.
  • Paths the spec doesn't list are still relayed. The router's defaultApiContainer (protocol/chainlib/base_chain_parser.go:518, reached from rest.go:179) relays an unlisted REST path with deterministic: true, CU 20 and latest. So public walletd routes the omission table treats as excluded, such as GET /api/health and POST /api/syncer/broadcast/block, still go through. This is how the router handles every REST spec, but the deployment note only covers the password-gated routes.
  • Broadcast behaves differently on personal-mode nodes. walletd refreshes v2 broadcast proofs only on full index nodes (api/server.go:477). The customer runs full, so the impact is low, but the body doesn't say so.
  • The body is stale after Phase 10. The CU table says "7 @ 10, 19 @ 20, 4 @ 60" and lists updates at 20. The file now has 7 / 18 / 5.

Checked and fine

  • PARSE_DICTIONARY_OR_ORDERED ["height","=","0"] does read the height out of the REST path: the router logged requested_block=5 for /api/consensus/index/5.
  • SCT inherits SC's chain-id directive and overrides only the value: a mainnet node fails SCT's check, as it should.
  • Ticket coverage: an independent read of MAG-2968 (all 13 comments) found 12 obligations implemented, 1 deliberately deviated (wallet routes, documented) and 0 missing.

🤖 Generated with Claude Code

@avitenzer

avitenzer commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to the review above: the router-side caching gap (walletd mempool and peer reads cached for 75 s, because nodeBoundMethods has no walletd paths) is now tracked as MAG-4793, assigned to @AnnaR-prog and linked to MAG-2968. It's a router fix, so it doesn't block this spec PR, but it should land before the customer goes live.

…(MAG-2968)

avitenzer's review on PR #197: these answers change as the chain moves, so
cross-validation would treat two honest nodes a block apart as disagreeing.

- GET /api/events/{id}: the reply carries Confirmations = 1 + scanHeight -
  height (persist/sqlite/events.go:121, walletd v2.15.2). It grows every
  block and differs between nodes indexed to different heights.
- GET /api/outputs/siacoin/{id}, GET /api/outputs/siafund/{id}: only
  unspent outputs are returned (persist/sqlite/utxo.go: spent_index_id IS
  NULL), so the answer changes once the output is spent.
- GET /api/consensus/blocks/{id}, GET /api/consensus/checkpoint/{id}: a
  numeric id is read as a height through cm.BestIndex (api/server.go), so a
  reorg near the tip changes the answer. checkpoint/{id} was not in the
  review but takes the same code path.

Tested with smart-router v1.6.4 against our walletd v2.15.2 nodes: Kraken's
call list answers the same through the router as directly, on mainnet (SC)
and on zen (SCT, including the POST broadcast route it inherits).

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

AnnaR-prog commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

@avitenzer thanks. Addressed at f254bce:

Blocking

  1. Fixed. The 4 routes are now deterministic: false, plus GET /api/consensus/checkpoint/{id}, which reads a numeric id as a height through the same cm.BestIndex path as blocks/{id}.
  2. Open. Still waiting on the customer's sync mode (MAG-2968 comment 31001). The pin stays until the customer confirms or omer decides.

Not yet tested at this head: now tested (router v1.6.4, our walletd v2.15.2 nodes, at f254bce)

  • Mainnet (SC): The customer's call list answers the same through the router as directly.
  • Zen (SCT): the same, including the POST broadcast route it inherits from SC (an invalid body gets walletd's own 400 both ways).

Non-blocking

  • Cache: tracked in MAG-4793, thanks.
  • Unlisted public routes: added to the deployment note.
  • Broadcast proofs on personal-mode nodes: added to the deployment note.
  • CU table: fixed (7 / 18 / 5).

@AnnaR-prog

Copy link
Copy Markdown
Contributor

/rerun-from 8
Re-validate head f254bce. It sets 5 routes to deterministic false on purpose, from avitenzer's review (see the PR body section "Update 2026-11-02"): /api/events/{id}, /api/outputs/siacoin/{id}, /api/outputs/siafund/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}. Their answers change as the chain moves; do NOT set them back to true. Keep /api/consensus/updates/{index} at CU 60, keep GET /api/syncer/peers, do NOT add any /api/wallets/* route or an authorization header directive, and do NOT re-add the index-mode check.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

@magmadevs-bot

magmadevs-bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 8 — smart-router boot + method probe (resumable run, Phases 8–11 · re-validating head f254bce)

Verdicts: SPEC_LOAD: OK (SC and SCT) · PARSE: OK (via test-only siascan shim — not a provider) · VERIFY: OK (same shim; positive + negative control) · ADDONS: none declared · TESTNET_VERIFY: OK (via shim) · spec defects in boot logs: none
Counts: PASS=2 FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=27 WARN=0 TIMEOUT=0 LOG_WARN=0
BLOCK_TIME: mainnet=skipped testnet=skipped — walletd's /api/consensus/index/{height} response carries no timestamp, so no measurement recipe exists regardless of upstream reachability.

Auto-decision (unattended run, no human in the loop): the <!-- ENDPOINTS --> block is empty, so the Phase 3/8 endpoint-research fallback ran and — for the fourth consecutive run — re-confirmed that no public walletd instance exists on mainnet or Zen. The conservative default was taken: run the strongest subset possible without a real upstream. That is (a) the router spec-graph load boot for both variants against a deliberately-unreachable placeholder, and (b) the test-only shim @avitenzer used on 1792a3a (local HTTP shim proxying only the spec's two directive routes to api.siascan.com's equivalents, /zen/… for SCT, everything else 404). api.siascan.com was not configured as a provider, per the PR body's instruction.

What the shim buys: PARSE and VERIFY are real verdicts at this head instead of NOT_TESTABLE for a fourth run. What it does not buy: coverage of the other 28 walletd-only routes — those stay NOT_TESTABLE, and NOT_TESTABLE is not coverage. Live coverage of the full route list still needs a reachable walletd (/rerun-probe mainnet=<url>); the nearest thing on record is @AnnaR-prog's manual run against the team's private walletd v2.15.2 nodes at this commit (PR body, "Update 2026-11-02").

What changed vs head 3b75f23: the 5 deterministic: true → false flips (/api/events/{id}, /api/outputs/siacoin/{id}, /api/outputs/siafund/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}) and compute_units: 60 on GET /api/consensus/updates/{index}. The router accepted the spec graph with those values with no complaint — no duplicate-api, no invalid-parser, no Bad verification definition. All of them, plus the retained /api/syncer/peers, the absent /api/wallets/*, the absent authorization directive and the absent index-mode check, were treated as settled decisions, not findings.

Negative control worth reading: SCT booted against mainnet shim data failed its chain-id check exactly as it should (expected 172fb3d5…, got 25f6e3b9…), proving SCT's override is live rather than silently inheriting SC's value.


Method Probe Report — sc

Generated: 2026-11-02T10:52:03Z
Router image: ghcr.io/magma-devs/smart-router:main (sha256:df1ba866df791a20467cd6a70e3b0ed975976f82f0145afbd1ac37d28930ca99)
Router config: /tmp/sr_sc.yml, /tmp/sr_sc_testnet.yml (spec-graph load boots), /tmp/sr_sc_shim.yml, /tmp/sr_sct_shim.yml, /tmp/sr_sct_shim_negctrl.yml (shim-upgrade boots)
Spec variant: SC (rest, GET + POST collections, 22+8=30 apis), SCT (rest, thin-import of SC, imports: ["SC"])
Upstreams probed (real production walletd): none — no reachable public walletd upstream exists; see "Endpoint re-confirmation" below.
Upstreams used for the shim upgrade: a local test-only HTTP shim proxying api.siascan.com's explorer routes for ONLY the 2 directive paths. Not a provider — see "Shim upgrade" section. All other 28 methods remain NOT_TESTABLE.

This is the 4th consecutive pipeline run of Phase 8 on this chain (after heads a299510, 3b75f23, and the human reviewer's live-parse run at 1792a3a). This run replicates the prior conservative spec-graph-load methodology for both variants and adds the siascan-shim upgrade the human reviewer piloted, now re-run fresh at head f254bce (after the 5-route deterministic:false fix and the CU-60 bump on /api/consensus/updates/{index}).

Endpoint re-confirmation (time-boxed, ~6 minutes)

Re-confirmed, rather than relitigated, the settled conclusion that no public walletd instance exists for Siacoin mainnet or Zen:

  • https://walletd.sia.tech, https://walletd.siacentral.com, https://api.siacentral.com → curl exit 000 (no DNS/connection).
  • https://wallet.sia.tech → HTTP 523 (Cloudflare origin unreachable).
  • https://api.sia.tech/api/consensus/tip → HTTP 200 but returns the Sia API documentation SPA HTML, not a live walletd.
  • https://api.siascan.com/api/consensus/tip → HTTP 404 — confirms siascan's route tree has no /api prefix (it is a different daemon, explored, not walletd).
  • https://api.siascan.com/consensus/tip → {"height":600083,"id":"00000000000000008efebe23f3555cb8fde7ce588ec51dd9894b3826cf1bb53e"} (the real siascan path — reachable, but not walletd-shaped and missing the walletd-only routes).
  • https://api.siascan.com/zen/consensus/tip → {"height":63983,"id":"000000001203ff55148d2a92d1084cb2562b85dee7ffbe40e270497aa9ad3b39"}.
  • The team's walletd nodes remain on a private machine CI cannot reach (per the triggering PR comment); not independently verifiable from this environment.

Conclusion: re-confirmed, 4th consecutive run. api.siascan.com is reachable and shares only the /consensus/tip (and /consensus/tip/{h}) shape with walletd's /api/consensus/tip / /api/consensus/index/{height} — this is exactly what the shim upgrade below exploits for the 2 directive routes only, and exactly why it must never be read as coverage of the other 28 walletd-only routes.

Spec-graph load boot (SC) — conservative baseline, unreachable placeholder upstream

Config /tmp/sr_sc.yml: chain-id: SC, api-interface: rest, one direct-rpc block pointed at http://127.0.0.1:9999 (deliberately unreachable — this boot exercises only the router's startup spec resolution).

Boot log evidence (docker logs sr_sc):

  • "spec_count":"304" ... "message":"Loaded specs from local directory" — all specs in the staging dir parsed, sc.json included.
  • "chain_id":"SC","total_sources":"1","total_specs_loaded":"304" ... "message":"Successfully loaded and expanded spec from aggregated sources" — SC's 2 rest collections (22 GET + 8 POST = 30 apis) and its chain-id verification parsed into the router's spec graph without error.
  • "message":"RPCSmartRouter Listening" / "message":"RPCSmartRouter done setting up all endpoints, ready for requests" — listener bound.
  • GET http://localhost:3360/api/consensus/tip → HTTP 500 ("No pairings available") — expected (the only upstream is unreachable by design), not a spec defect.
  • chain-id verification did execute against the unreachable placeholder and failed only with PROTOCOL_CONNECTION_REFUSED / dial tcp 127.0.0.1:9999: connect: connection refused — confirms the verification's function_template/result_parsing are wired, not a spec/parsing defect.
  • Grep for defect signatures (panic, failed to load any specs, spec not found for chainId, Bad verification definition, duplicate-api-name, invalid-parser) → none found, clean.

SPEC_LOAD (SC): OK

Spec-graph load boot (SCT) — conservative baseline, unreachable placeholder upstream

Config /tmp/sr_sc_testnet.yml: chain-id: SCT, api-interface: rest, same unreachable placeholder.

Boot log evidence (docker logs sr_sc, reused name, sequential boot after SC's teardown):

  • "chain_id":"SCT","total_specs_loaded":"304" ... "Successfully loaded and expanded spec from aggregated sources" — SCT's imports: ["SC"] closure resolved cleanly (SC's 30 apis + SCT's own override of the chain-id verification value).
  • chain-id verification executed with the SCT-specific expected_value (172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3) against the same unreachable placeholder, failing only on connection-refused — confirms SCT's override is live and distinct from SC's.
  • Grep for defect signatures → none found, clean.

SPEC_LOAD (SCT): OK

Both boots were sequential on the same host ports, fresh container each time, torn down after capture.

Shim upgrade — PARSE/VERIFY exercised live at head f254bce

Status: SUCCEEDED. Stood up a local test-only HTTP shim (python3 http.server-equivalent, /tmp/sia_shim.py) on 127.0.0.1:8181 (mainnet prefix) and 127.0.0.1:8182 (/zen prefix) that serves only the spec's 2 directive routes by proxying api.siascan.com's equivalents with the identical {height,id} shape, 404 on everything else:

  • /api/consensus/tip → https://api.siascan.com/consensus/tip (or /zen/consensus/tip)
  • /api/consensus/index/{h} → https://api.siascan.com/consensus/tip/{h} (or /zen/consensus/tip/{h})

The router containers ran with --network host to dial the shim at 127.0.0.1. This is not a provider and not coverage of walletd's 28 other routes — it only exercises the GET_BLOCKNUM / GET_BLOCK_BY_NUM parse directives and the chain-id verification, all three of which are shared in shape with the siascan explorer.

SC against the mainnet shim (/tmp/sr_sc_shim.yml, upstream 127.0.0.1:8181)

  • Boot succeeded; init relay: "latestBlock":"600083","endpoint":"sc-shim-upstream" ... "[+] init relay succeeded".
  • chain-id verification: "rawData":"25f6e3b9295a61f69fcb956aca9f0076234ecf2e02d399db5448b6e22f26e81c" ... "[+] verified successfully" — matches sc.json's expected_value exactly.
  • Metrics after ~6.5 minutes: smartrouter_latest_block{spec="SC"} 600083; rpc_endpoint_tracker_requests_total{kind="latest_block"} 6 (tracker polled GET_BLOCKNUM repeatedly and positively).
  • rpc_endpoint_tracker_requests_total{kind="block_hash",...} never appeared (0 occurrences) and no Chain Tracker Updated block hashes / Chain Tracker read a block Hash log lines appeared in ~6.5 minutes of uptime — the tracker's own by-number hash-read cadence (tied to average_block_time=600000ms/2 ≈ 5 min flatPollInterval, see "per-endpoint chain tracker poll cadence resolved" log line) did not fire a cycle inside the observation window.
  • To avoid leaving GET_BLOCK_BY_NUM as a pure NOT_EXERCISED, a manual router-relayed probe was sent (GET http://localhost:3360/api/consensus/index/500000) and returned {"height":500000,"id":"00000000000000007e194c8dcbade6192242fee436be5be6bbf3e9df821795af"} — correct shape, correctly templated %d substitution, correctly relayed. This confirms the directive's result_parsing/template wiring is correct, though it is a manual probe, not an autonomous tracker cycle.
  • Zero failed to parse response / ParseBlockHashFromReplyAndDecode / expected parsed hashes length / other PARSE_SIG lines anywhere in the log.

SCT against the zen shim (/tmp/sr_sct_shim.yml, upstream 127.0.0.1:8182) — positive control

  • chain-id verification: "rawData":"172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3" ... "[+] verified successfully" — matches sc.json's SCT expected_value exactly, and is distinct from SC's value above (confirms SCT's values[].expected_value override is live, not silently inherited from SC).
  • smartrouter_latest_block{spec="SCT"} 63984.

SCT against MAINNET shim data — negative control

Booted SCT (chain-id: SCT) against the mainnet shim on port 8181 (/tmp/sr_sct_shim_negctrl.yml) to confirm the testnet override is actually compared, not vacuously accepted:

  • "rawParsedBlock":"25f6e3b9295a61f69fcb956aca9f0076234ecf2e02d399db5448b6e22f26e81c","verification.Value":"172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3" ... "message":"[-] verify failed expected and received are different" → FAILED as expected: expected 172fb3d5… (SCT), got 25f6e3b9… (SC's genesis), exactly matching the task's predicted failure shape.
  • The provider was excluded ("provider validation failed — excluding from provider list"), and the endpoint served HTTP 500 ("no healthy providers") — the override is confirmed live, not a pass-through bug.

PARSE/VERIFY verdicts (via test-only siascan shim — not a provider; only the 2 directive routes were served)

PARSE: OK — GET_BLOCKNUM confirmed live and repeatedly polled with a correct value (smartrouter_latest_block=600083/63984, tracker_requests_total{kind="latest_block"} incrementing, zero parse-signature log lines). GET_BLOCK_BY_NUM's autonomous tracker cycle did not fire inside the ~6.5-minute observation window (0 block_hash-kind tracker requests, 0 hash-read log lines) — classified NOT_EXERCISED for the tracker's own cadence, but corroborated PASS via a manual router-relayed probe that returned the correctly-shaped, correctly-parsed body. No ParseBlockHashFromReplyAndDecode/expected parsed hashes length signature fired anywhere, so there is no FAIL evidence from either path — this is a timing/observation-window artifact (average_block_time=600000ms drives a multi-minute tracker poll cadence), not a spec defect.

VERIFY: OK — chain-id on SC passed against mainnet data, chain-id on SCT passed against zen data with its own distinct expected_value, and the negative control proved the comparison is live (SCT correctly rejects mainnet data with the exact expected …, got … mismatch). All three outcomes via the shim, not through real walletd.

Addon & extension coverage (Step 1c)

ADDONS: none declared. jq over sc.json for .add_on and .extension fields returns empty lists — confirmed this run. No archive/debug/trace addon, no pruning verification, no GET_EARLIEST_BLOCK (walletd has no pruning mechanism; see PR body auto-decision #1). No addon table applies.

Per-method table (all 30 methods)

Only the 2 directive routes were exercised (via the shim, labelled above); the other 28 remain NOT_TESTABLE — no reachable walletd upstream serves them, and the shim deliberately does not fake any method outside the 2 directive paths (every other path returns its own 404, confirmed in the shim's design).

Method Classification Upstream notes Notes
GET /api/state NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/network NOT_TESTABLE — same
GET /api/consensus/tip PASS (via test-only siascan shim — not a provider) shim 127.0.0.1:8181/8182 GET_BLOCKNUM directive; also NOT_TESTABLE against real walletd
GET /api/consensus/tipstate NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/index/{height} PASS (via test-only siascan shim — not a provider) shim 127.0.0.1:8181/8182 GET_BLOCK_BY_NUM directive + chain-id verification template; manual probe at height 500000 confirmed correct parsing; also NOT_TESTABLE against real walletd
GET /api/consensus/blocks/{id} NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/checkpoint/{id} NOT_TESTABLE — same
GET /api/consensus/updates/{index} NOT_TESTABLE — same
GET /api/syncer/peers NOT_TESTABLE — present on purpose (the customer's production usage, head 3b75f23); not probed here, not a defect
GET /api/txpool/transactions NOT_TESTABLE — same
GET /api/txpool/fee NOT_TESTABLE — same
GET /api/txpool/events NOT_TESTABLE — same
GET /api/addresses/{addr}/balance NOT_TESTABLE — same
GET /api/addresses/{addr}/events NOT_TESTABLE — same
GET /api/addresses/{addr}/events/unconfirmed NOT_TESTABLE — same
GET /api/addresses/{addr}/outputs/siacoin NOT_TESTABLE — same
GET /api/addresses/{addr}/outputs/siafund NOT_TESTABLE — same
GET /api/outputs/siacoin/{id} NOT_TESTABLE — same
GET /api/outputs/siacoin/{id}/spent NOT_TESTABLE — same
GET /api/outputs/siafund/{id} NOT_TESTABLE — same
GET /api/outputs/siafund/{id}/spent NOT_TESTABLE — same
GET /api/events/{id} NOT_TESTABLE — same
POST /api/txpool/broadcast SKIP — stateful: 1 — would broadcast a transaction; never probed regardless of upstream availability
POST /api/txpool/parents NOT_TESTABLE — no reachable walletd upstream
POST /api/txpool/transactions/v2/basis NOT_TESTABLE — same
POST /api/batch/addresses/balance NOT_TESTABLE — same
POST /api/batch/addresses/events NOT_TESTABLE — same
POST /api/batch/addresses/outputs/siacoin NOT_TESTABLE — same
POST /api/batch/addresses/outputs/siafund NOT_TESTABLE — same
POST /api/check/addresses NOT_TESTABLE — same

Counts: PASS=2 (directive routes, shim-only, not real coverage) FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=27 WARN=0 TIMEOUT=0 LOG_WARN=0.

Deliberately absent from the spec (not findings — confirmed on-purpose settled decisions, see PR body): /api/wallets/* routes, authorization header directive / router auth config, index-mode verification.

Real walletd coverage of the other 28 methods, including the customer's 8 GETs and the broadcast POST, comes from the manual run the team posted on the PR (router v1.6.4 against walletd v2.15.2 at this commit f254bce — see PR body "Update 2026-11-02"): all answer through the router with the same status/body as calling walletd directly (syncer/peers differs only in live peer stats); a broadcast with an invalid body gets walletd's own 400; PUT gets the router's own 501; the password never appears in the router log. That run is out-of-band evidence from the team's private walletd nodes, not reproduced by this CI run.

Log-scan findings

No full probe-window log scan applies in the usual sense (no method-probe loop ran against a real upstream for the 28 non-directive methods). For the shim boots specifically: zero non-benign warn/error/fatal/panic lines beyond the expected verification-retry noise (connection-refused on the deliberately-unreachable placeholder boots; the expected mismatch message on the negative control). No fatal/panic lines in any boot.

Level Associated method error excerpt
(none — clean) — —

Testnet verification pass

TESTNET_VERIFY: OK (via test-only siascan shim — not a provider; only the 2 directive routes were served). SCT's chain-id verification passed against zen shim data with its own expected_value (172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3), and the negative control (SCT booted against mainnet shim data) correctly FAILED with expected 172fb3d5…, got 25f6e3b9… — proving the override is live, not vacuously accepted. Against a real Zen walletd node, this remains out-of-band (see PR body's "Update 2026-11-02" manual-run note, which covers SCT's full GET+POST surface against the team's real zen walletd).

Verification Verdict Providers OK/failed Notes
chain-id (SCT, positive, zen shim) OK (shim) 1/1 expected_value matches zen genesis id exactly
chain-id (SCT, negative control, mainnet shim) FAIL as expected (shim) 0/1 expected 172fb3d5…, got 25f6e3b9… — confirms the check compares real values
chain-id (SCT, unreachable placeholder) NOT_TESTABLE (executed, connection-refused only) 0/1 baseline load-boot evidence, see above

Empirical block time

BLOCK_TIME: mainnet=skipped testnet=skipped

No recipe applies regardless of upstream availability: walletd's /api/consensus/index/{height} response is {"height":…,"id":…} and carries no timestamp field, so there is no way to compute an empirical block interval from this API family even with a reachable node. The shim's upstream (api.siascan.com/consensus/tip) is likewise {height,id}-only with no timestamp exposed at that path. The PR body already documents an independent empirical corroboration of the 600000ms docs value (595818ms mainnet / 606392ms zen, measured via the siascan UI's displayed block timestamps over 1000 blocks on 2026-10-20, ≤1.1% drift) — not re-derived in this run since it requires a different siascan surface than the {height,id} shim serves.

Corroboration (not a probe) of the genesis-id chain-id values, reconfirmed this run:

Network Source Returned id Matches sc.json expected_value
mainnet https://api.siascan.com/consensus/tip/0 25f6e3b9295a61f69fcb956aca9f0076234ecf2e02d399db5448b6e22f26e81c yes, exact match
zen https://api.siascan.com/zen/consensus/tip/0 172fb3d508c86ac628f93c3362ba60312251466c77d63a8c99ea87717e4112c3 yes, exact match
Network RPC Empirical (ms) Spec effective (ms) Drift Verdict
mainnet — - 600000 - skipped (no timestamp field in walletd's consensus/index response)
testnet — - 600000 - skipped (same reason)

Diff vs head 3b75f23 (prior Phase 8 run's baseline)

Change Accepted by router? Notes
5 routes set deterministic: false (/api/events/{id}, /api/outputs/siacoin/{id}, /api/outputs/siafund/{id}, /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}) Yes, no complaint sc.json loaded cleanly in both SC and SCT boots ("Successfully loaded and expanded spec from aggregated sources", no parse/schema error); deterministic is not itself verification-gated, so this surfaces only as clean spec-graph load, consistent with prior runs
GET /api/consensus/updates/{index} compute_units raised to 60 Yes, no complaint Same — CU values are not boot-time verified by the router; clean load is the full extent of what this phase can observe for a CU change

Both changes are settled decisions per the PR body (avitenzer's review fix, addressed at f254bce) — not flagged as findings.

Settled decisions — not findings

Per the PR body's "Defaults — do NOT revert" section, the following are confirmed present/absent as intended and are NOT flagged: the genesis-block-id chain-id pin on /api/consensus/index/0 (refusing checkpoint-synced nodes is the intended failure mode); no index-mode verification; no /api/wallets/* routes; GET /api/syncer/peers present; no authorization header directive / router auth config; the 5 deterministic: false routes.

@magmadevs-bot

magmadevs-bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 9 — parallel reviewers (3 independent /review-spec passes) · re-validating head f254bce

Reviewer TALLY Report Size
1 CRITICAL=0 MEDIUM=0 MINOR=2 docs/sc/SPEC_REVIEW_GAPS_parallel_1.md 11.5 KB
2 CRITICAL=0 MEDIUM=0 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_2.md 6.6 KB
3 CRITICAL=0 MEDIUM=1 MINOR=0 docs/sc/SPEC_REVIEW_GAPS_parallel_3.md 6.2 KB

Three distinct reports (distinct md5s — no shared-path collision), every evidence line number within sc.json's 591 lines, so no reviewer read stale state.

Merged gaps

MEDIUM — 1 (reviewer 3)

  • POST /api/txpool/transactions/v2/basis is priced in the wrong CU band. The handler calls coreutils Manager.UpdateV2TransactionSet(txns, basis, target), which runs reorgPath(from, to, 144) and reverts/re-applies Merkle proofs for every transaction in the set, for every block in the window — a bounded-but-expensive proof-recomputation walk, not a single-record read. At compute_units: 20 it sits in the "block/transaction query" band while this spec already prices the 1000-address-capped batch fan-outs at 60. Reviewer 3 also raises, as the lower-severity half of the same finding, that block_parsing is DEFAULT/["latest"] even though the request body carries its own target ChainIndex.

MINOR — 2 (reviewer 1), dropped from the fix list per the Phase 10 rule (MINOR is not fixed)

  • No timeout_ms on the 4 batch POST /api/batch/addresses/* routes (CU 60 already sets a floor on the relay window; reviewer 1 rates it minor and not urgent).
  • Index mode none's behaviour on the address routes is undocumented and untested — a customer-setup/documentation gap, not a spec field.

What all three agree on

  • Route coverage is exact. Reviewers 2 and 3 each independently diffed sc.json against walletd v2.15.2's full route table fetched live from api/server.go: 30 routes, 0 missing, 0 extra, 0 invented.
  • No duplicates; category.stateful is exactly one route (POST /api/txpool/broadcast), matching the only state-mutating handler.
  • Parse directives are sound — GET_BLOCKNUM → .height, GET_BLOCK_BY_NUM → .id, both pointing at apis that exist in the collection, both matching the real route shapes.
  • SCT inherits correctly — apis: [] plus a live, distinct chain-id override, confirmed by this run's positive and negative-control shim boots.
  • Network params check out for a PoW chain: average_block_time=600000, block_distance_for_finalized_data=6, blocks_in_finalization_proof=3, allowed_block_lag_for_qos_sync=1.
  • Every settled decision held. None of the three flagged the 5 deterministic: false routes, the CU-60 on updates/{index}, /api/syncer/peers, the genesis-id pin, or the deliberate absence of /api/wallets/* / the authorization directive / the index-mode check. The MAG-4793 router caching gap was correctly treated as a router bug, not a spec defect.

The 1 MEDIUM goes to the Phase 10 fix pass. NOT_TESTABLE probe rows were correctly read as upstream unavailability, and no reviewer proposed disabling anything on probe evidence.

@magmadevs-bot

magmadevs-bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 10 — gap synthesis + fix pass, and Phase 10b — smoke re-probe · head f254bce

Consolidation

0 critical, 1 medium; 0 disable-suggestions stripped; 0 settled-decision gaps stripped → docs/sc/FIX_LIST.md

Nothing needed stripping this run: no reviewer proposed disabling anything on probe evidence (all three read the 27 NOT_TESTABLE rows as upstream unavailability), and none proposed reverting a settled owner decision. The 2 MINOR findings were dropped per the MINOR rule and carried to the watch-list below.

Fix applied (1 of 1)

  • sc.json:455 — raised compute_units from 20 → 60 on POST /api/txpool/transactions/v2/basis (gap: MEDIUM, "under-priced for its actual compute cost"). The handler runs coreutils UpdateV2TransactionSet → reorgPath(from, to, 144) and reverts/re-applies Merkle proofs per transaction per block, which is complex-query-shaped work; the spec already prices its other worst-case fan-out routes (the 4 batch address routes) at 60.

DISABLED-API JUSTIFICATIONS: none — nothing was disabled. The disabled set is still 0 distinct methods, so the body's <!-- disabled-count: 0 --> marker remains correct and needs no edit.

Auto-decisions recorded (unattended run, conservative default taken at each gate):

  1. Reviewer 3's second, lower-severity half of the MEDIUM — "consider whether block_parsing should key off the body's target field via PARSE_CANONICAL" — was deferred, not applied. The reviewer frames it as "consider", the route is already deterministic: false, and changing a parser_func is materially riskier than changing a number. Recorded in FIX_LIST.md under DEFERRED.
  2. The suggested timeout_ms on the same route was not applied for the same reason (a suggestion attached to the CU finding, not an independent defect). Note that a reflexive timeout_ms on a CU-60 api can shorten the relay window, since timeout_ms replaces the CU term rather than adding to it.
  3. The 2 MINOR items go to the watch-list, unfixed.

Phase 10a — post-fix static gates

check_method_schema PASS (30/30 schema ok) · check_unused_fields PASS (no removed fields) · check_hanging_api PASS · check_stateful PASS · jq exit 0. No === FAIL === rows, no INFO rows. No base on origin/main (new chain), so every gate ran unconditioned.

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

Re-booted ghcr.io/magma-devs/smart-router:main (same tag as Phase 8, like-for-like) against the fixed spec, both the unreachable-placeholder load boot and the test-only siascan shim.

# Probe Result Phase 8 Verdict
1 GET /api/consensus/tip (GET_BLOCKNUM, via shim) 200 · height=600084 PASS · height=600083 PASS — chain advanced 1 block, as expected
2 GET /api/consensus/index/0 (chain-id route) 200 · id=25f6e3b9… exact match PASS PASS
3 GET /api/consensus/index/500000 (manual GET_BLOCK_BY_NUM) 200 · id=0000…795af same value PASS — byte-identical to Phase 8
4 POST /api/txpool/transactions/v2/basis (the edited route) shim 501 (bare http.server implements GET only); router log shows a full relay_end with the shim upstream attempted, and zero CU-related log lines not probed NOT_TESTABLE — the router accepted and routed the edited entry; no CU-related rejection
  • SPEC_LOAD (SC): OK — spec_count=304, chain_id=SC, listener bound, no panic / failed to load any specs / spec not found for chainId / Bad verification definition / duplicate-api / invalid-parser signature.
  • PARSE: OK (via test-only siascan shim — not a provider; only the 2 directive routes were served) — smartrouter_latest_block{spec="SC"}=600084, zero parse-signature lines. GET_BLOCK_BY_NUM's autonomous tracker cycle again did not fire inside the observation window (the poll cadence at a 600 s block time), so it is corroborated by the manual router-relayed probe in row 3 rather than by the tracker — same as Phase 8.
  • VERIFY: OK (same shim) — chain-id on SC [+] verified successfully, 1/1 providers.
  • ADDONS: none declared — unchanged.
  • SCT not re-tested: the diff touches only an SC entry, so per the skill the testnet pass was not required — this is distinct from "skipped for lack of inputs". Phase 8's SCT boot (positive and negative control) stands at this head.
  • Log scan: one benign circuit-breaker warn tied to probe 4's GUID — the expected consequence of POSTing to a GET-only shim, not a regression. Nothing else non-benign in the probe window.
  • Teardown: both containers removed, shim killed, ports free.

Watch-list (unfixed, for the reviewer)

  • No timeout_ms on the 4 batch POST /api/batch/addresses/* routes — reviewer 1 rates it minor, since CU 60 already sets the relay-window floor.
  • Index mode none's behaviour on the address routes is undocumented and untested — a customer-setup/docs gap, not a spec field.
  • block_parsing on /api/txpool/transactions/v2/basis keys off latest rather than the request body's own target ChainIndex (deferred above).

⚠️ One body-prose drift this fix introduces

The PR body's CU table — corrected to "7 / 18 / 5" at f254bce — is now 7 @ 10 / 17 @ 20 / 6 @ 60 because of this one bump. The <!-- disabled-count: 0 --> marker (the part under machine test) is unaffected; the CU line is prose, so it was left for @AnnaR-prog rather than edited by this unattended run.

@magmadevs-bot

magmadevs-bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ❌ CHANGES REQUESTED · head f254bce

TALLY: CRITICAL=1 MEDIUM=0 MINOR=0 — report at docs/sc/SPEC_REVIEW_GAPS_final.md

The verdict is reported as the reviewer returned it and is not upgraded. The one CRITICAL is aimed squarely at the fix this unattended run itself applied in Phase 10, not at anything in f254bce.

The finding

CRITICAL — Phase 10's CU bump on POST /api/txpool/transactions/v2/basis (20 → 60) is unjustified and contradicts the file's own documented CU-band rationale. (sc.json:455)

Its evidence, which I verified independently against the file and the body:

  • The PR body's "CU distribution (updated 2026-11-02)" states 7 @ 10, 18 @ 20, 5 @ 60 and enumerates the @60 band as exactly /api/consensus/updates/{index} plus the four /api/batch/addresses/* routes, justified by the 1000-address batch cap in api/api.go. /api/txpool/transactions/v2/basis is not in that band and is not covered by that argument.
  • With the bump applied, jq over the file returned 7 @ 10 / 17 @ 20 / 6 @ 60 — one route moved out of the reviewed distribution that both @avitenzer and @AnnaR-prog signed off on one round earlier.
  • CU values are not boot-time verified by the router. Phase 10b's SMOKE: OK / SPEC_LOAD (SC): OK cannot and did not test the change — a clean load is the full extent of what any phase here can observe for a CU edit. So the pipeline's own green signals say nothing about whether 60 is right.

Auto-decision taken (unattended run, conservative default, recorded)

The Phase 10 CU bump has been reverted. The working tree is now byte-identical to f254bce, so the pipeline's commit step has nothing to push.

Reasoning: two model reviewers disagree about this one number and no human has ever ruled on it. Phase 9's reviewer 3 raised it as MEDIUM from walletd source (UpdateV2TransactionSet → reorgPath(from, to, 144) reverts and re-applies Merkle proofs per transaction per block, which is complex-query-shaped work). Phase 11's reviewer rebuts it from band consistency and the absence of any benchmark on record. The conservative default between "ship an unreviewed 3× pricing change on an unattended run" and "leave the value two humans already reviewed" is the latter. Reverting also restores the body's 7 / 18 / 5 table, so the drift this run's Phase 10 comment flagged no longer exists.

What this leaves for the owners — one open question, not a defect

Should POST /api/txpool/transactions/v2/basis be CU 20 or CU 60? @AnnaR-prog / @avitenzer, this needs a human call — the pipeline cannot settle it, and it is the kind of judgment the @60 band's existing written rationale was built on:

  • For 60: the handler's worst case is a 144-block walk with per-transaction proof recomputation, which is the shape of work this spec already prices at 60 for the batch routes.
  • For 20: the route has no documented fan-out cap analogous to the 1000-address batch limit, no benchmark exists, and the published band table does not include it.

If the answer is 60, the @60 bullet in the body needs to name it and give the rationale (as the batch routes' bullet does). If it is 20, nothing needs doing — the file is already there.

Everything else in the final pass came back clean

  • check_unused_fields.sh PASS (no removed fields) · check_internal_paths.sh PASS (0 warnings, 0 errors) · valid JSON · 4-space indentation and the no-trailing-newline convention preserved byte-for-byte.
  • 0 enabled: false entries, matching the empty Disabled-API Justifications ledger and the body's <!-- disabled-count: 0 --> marker. No unjustified disable.
  • All 9 settled owner decisions confirmed present/absent exactly as mandated: the 5 deterministic: false routes, /api/consensus/index/{height} still true, /api/consensus/updates/{index} still CU 60, /api/syncer/peers retained, no /api/wallets/*, no authorization directive, no index-mode check, the genesis-id pin intact, and MAG-4793 correctly treated as a router bug.
  • Network params, block_parsing distribution, both parse directives, the chain-id verifications on SC and SCT, SCT's lean inheritance, and the POST collection's content-type header all re-verified with no new findings.

Per the skill this run does not loop back into another fix pass. The one substantive question above is the only thing between this spec and a clean verdict; the second open item from @avitenzer's review — the customer's walletd sync mode against the genesis pin — remains owner-tracked on MAG-2968 and is also outside what this pipeline can resolve.

@magmadevs-bot

magmadevs-bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (tail of Phase 11; this pipeline run covered Phases 8–11 at head f254bce)

#### File Validation
- ✓ JSON syntax valid                                    (Phase 10a + Phase 11 `jq` exit 0)
- ✓ All required fields present                          (Phase 11 final review; removed-field + internal-path guards PASS)
- ✓ No duplicate API names within any collection         (Phase 9 reviewers 2 & 3, independently, against walletd v2.15.2's route table)
- ✓ Proper indentation/formatting                        (4-space, no trailing newline — byte-for-byte vs HEAD)

#### Configuration Verification
- ✓ Network parameters calculated per formulas           (abt=600000, bdffd=6, bifp=3 PoW-probabilistic, ablfqs=1 — re-derived by all 4 reviewers)
- ☐ All APIs tested and working                          (NO reachable public walletd exists anywhere — 27/30 NOT_TESTABLE, 1 SKIP stateful, 2 exercised only via the test-only siascan shim. NOT_TESTABLE IS NOT COVERAGE. The real coverage on record is @AnnaR-prog's manual run against the team's private walletd v2.15.2 nodes at this commit, in the PR body.)
- ~ Block parsing validated for each API                 (the 2 directive routes parse correctly through the live router; the other 28 are existence-untested for lack of an upstream)
- ✓ Parse directives executed by live router             (Phase 8: PARSE=OK, VERIFY=OK via the shim; Phase 10b re-check: PARSE=OK, VERIFY=OK, SPEC_LOAD(SC)=OK — all labelled shim-derived)
- ✓ Addons & extensions tested                           (none declared — `jq` over add_on/extension returns empty; nothing to test)
- ~ Verifications pass on live nodes                     (chain-id passes on SC and SCT against shim data, and the SCT-vs-mainnet negative control FAILS as it must; genesis ids independently corroborated against api.siascan.com. No walletd node was reachable.)
- ☐ Compute units benchmarked under expected load        (user to measure — and this is now the PR's one open spec question: see the Phase 11 verdict on `/api/txpool/transactions/v2/basis`)

#### 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                                (SC: 30 apis across a GET and a POST collection)
- ✓ Testnet spec inherits correctly                      (SCT: imports SC, overrides only the chain-id value — confirmed by Phase 8's positive AND negative-control boots)
- ✓ Chain IDs verified for mainnet AND testnet           (both genesis ids match api.siascan.com exactly; SCT's override proven live, not vacuously inherited)
- ~ Both tested on respective networks                   (spec-graph load boot on both variants; no live walletd on either net)

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

Verdict and branch state

  • Phase 11: ❌ CHANGES REQUESTED (CRITICAL=1 MEDIUM=0 MINOR=0) — reported as returned, not upgraded. The single CRITICAL was against this run's own Phase 10 fix, which has been reverted.
  • Nothing to commit. sc.json in the working tree is byte-identical to f254bce; the pipeline's commit step will find an empty diff. No change was pushed by this run.
  • One open spec question for a human: CU 20 vs 60 on POST /api/txpool/transactions/v2/basis (full argument on both sides in the Phase 11 comment). One open non-spec item: The customer's walletd sync mode against the genesis pin, tracked on MAG-2968.
  • Every settled decision held through all four phases — the 5 deterministic: false routes, CU 60 on /api/consensus/updates/{index}, /api/syncer/peers, no /api/wallets/*, no authorization directive, no index-mode check, the genesis pin. No reviewer proposed reverting any of them, and the Phase 10 consolidation stripped 0 settled-decision gaps because none were raised.
  • To retry after deciding the CU question: /rerun-final re-runs Phase 11 alone; /rerun-from 10 re-runs the fix pass and everything after it. To get real method coverage: /rerun-probe mainnet=<walletd-url>.

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

Elapsed:         00h 39m 44s  (first→last logged activity)
Transcripts:     1 main + 8 subagent
API round-trips: 345  (main=70, subagents=275)

Fresh tokens:    input=690  output=235848  (sum=236538)
Cached tokens:   cache_read=25584819  cache_write=1835112
Total billed:    27656469 tokens

Split (total billed):  main=8184363  subagents=19472106

Models used:
  claude-sonnet-5         275 calls   19472106 billed
  claude-opus-5            70 calls   8184363 billed

These figures cover Phases 8–11 of this resumable run only. Phases 1–7 ran in a separate create_spec job (see the PR body), and the three earlier Phase 8–11 pipeline runs on this PR each have their own tallies in their closing comments. The true cumulative total for this PR is all of those added together — this number alone is not a grand total.

@AnnaR-prog

AnnaR-prog commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

@avitenzer re blocker 2 in your merge-readiness review (the customer's sync mode vs the genesis pin). Owner decision (2026-11-02): the pin stays as it is.

  • Instead of waiting for the customer to confirm, the customer will be required to run every walletd node synced from the first block (height 0). This joins the other requirements for the customer: the public option on every node and a private API port.
  • A node started from a checkpoint stays refused. It serves zero balances for coins older than its checkpoint (tested on zen, see the body), so a visible refusal is the safer failure.
  • No spec change, so the PR doesn't need to wait for the customer's answer. The check for the customer (GET /api/consensus/index/0 on each node, and a full resync if it answers 404) is in MAG-2968 comment 31062.

@AnnaR-prog

AnnaR-prog commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

@avitenzer can you re-review? Both blockers are answered, and the head is still f254bce:

  1. The routes you flagged, plus GET /api/consensus/checkpoint/{id}, are deterministic: false (reply).
  2. The genesis pin stays, and the customer will be required to run every walletd node synced from block 0 (decision). The PR description now records it.

The last CI run's ❌ Phase 11 verdict is not about f254bce. Its one CRITICAL was against Phase 10's own CU bump on POST /api/txpool/transactions/v2/basis (20 → 60), which Phase 11 reverted, and it asked for a human call. The answer is CU 20, an owner decision recorded in the description (do-not-revert item 7).

@AnnaR-prog
AnnaR-prog requested a review from avitenzer November 2, 2026 14:33
@AnnaR-prog

AnnaR-prog commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

@avitenzer please pause the re-review. My blocker 2 reply above is superseded: omer's MAG-2968 comment 31063, posted before it, says the router must work with nodes synced either way, and nothing is asked of the customer. So the genesis pin goes: I'm replacing it with a network-name check and will update the description. I'll ping you when it's pushed.

…kpoint-synced nodes (MAG-2968)

omer's MAG-2968 comment 31063: the router must work with nodes synced either way,
and nothing is asked of Kraken. The genesis block id pin (/api/consensus/index/0)
refused every node started from a checkpoint, because such a node answers 404 there.
chain-id now reads /api/consensus/network .name: "mainnet" for SC, "zen" for SCT
(SCT still inherits the directive and overrides only the value).

Tested with smart-router v1.6.4 and walletd v2.15.2 (zen block-0 node plus a
checkpoint-synced node): both admitted; old index, block and event lookups that hit
the checkpoint node get its 404 (NODE_DATA_NOT_HELD) and are retried on the other
node; SC refuses a zen node.

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

AnnaR-prog commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

/rerun-from 8
Re-validate head d1ba22b. It changes chain-id on purpose, from omer's MAG-2968 comment 31063 (see the PR body section "Update 2026-11-03"): chain-id reads /api/consensus/network .name ("mainnet" on SC, "zen" on SCT) instead of the genesis block id, so nodes started from a checkpoint are admitted. Do NOT re-add the /api/consensus/index/0 genesis pin in a fix pass. The zero balances that address routes give on a checkpoint node are a known, documented effect, accepted for now because the customer calls none of them (owner decision 2026-11-03, do-not-revert item 8): do NOT remove or disable those routes. Keep POST /api/txpool/transactions/v2/basis at CU 20 (owner decision, do-not-revert item 7).

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

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

@magmadevs-bot

magmadevs-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 8 — smart-router boot + method probe (resumable run, Phases 8–11 · re-validating head d1ba22b)

Verdicts: SPEC_LOAD: OK (SC and SCT) · PARSE: OK (via test-only siascan shim — not a provider) · VERIFY: OK (same shim; 2 positive + 2 negative controls) · ADDONS: none declared · TESTNET_VERIFY: OK (via shim) · spec defects in boot logs: none
Counts: PASS=3 FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=26 WARN=0 TIMEOUT=0 LOG_WARN=0
BLOCK_TIME: mainnet=skipped testnet=skipped — walletd's /api/consensus/index/{height} response carries no timestamp, so no measurement recipe exists regardless of upstream reachability.

The one thing this run existed to test: the new chain-id at d1ba22b

chain-id no longer pins the genesis block id — it reads GET /api/consensus/network → .name (PARSE_CANONICAL, parser_arg ["0","name"]), "mainnet" on SC and "zen" on SCT. The verification was exercised live at this head through the shim, in four configurations, and it discriminated correctly in all four:

# Config Expected Result
1 SC vs mainnet shim verify OK (mainnet) PASS — "verification":"chain-id","rawData":"mainnet" … "[+] verified successfully"
2 SCT vs zen shim (positive control) verify OK (zen) PASS — rawData:"zen" → verified
3 SCT vs mainnet shim (negative control) verify FAIL PASS (failed as required) — rawParsedBlock:"mainnet" != verification.Value:"zen" → provider excluded
4 SC vs zen shim (negative control) verify FAIL PASS (failed as required) — rawParsedBlock:"zen" != verification.Value:"mainnet" → provider excluded

Control 4 is the live reproduction of "SC pointed at a zen node is refused", which @AnnaR-prog's manual run observed against real walletd. Controls 3+4 together prove the comparison is not vacuously accepted — which is the risk a string-valued expected_value carries that a 32-byte block-id pin did not. The parse itself was checked too: the router extracted the plain strings mainnet/zen, not the raw JSON object and not an empty string, with zero parse-failure signatures across all four boots.

What has and has not been shown

  • Shown: the spec graph loads and the import closure (SCT → SC) resolves at this head; both parse directives execute (smartrouter_latest_block{spec="SC"}=600203; a router-relayed /api/consensus/index/600000 parsed the correct block id); the new chain-id verification works in both directions on both networks.
  • Not shown: live coverage of the other 26 walletd-only routes, which stay NOT_TESTABLE, plus POST /api/txpool/broadcast (SKIP, stateful). NOT_TESTABLE is not coverage. api.siascan.com is the explored/siascan explorer daemon, not walletd — it shares only /consensus/tip, /consensus/tip/{height} and /consensus/network, which is exactly the 3 routes the shim proxies and exactly why it must never be configured as a provider. Full live coverage still needs a reachable walletd (/rerun-probe mainnet=<url>); the nearest thing on record is @AnnaR-prog's manual run against the team's private walletd v2.15.2 nodes, reported in the PR body's "Update 2026-11-03" (including the checkpoint-synced-node retry behaviour, which no CI-reachable endpoint can reproduce).
  • No /api/wallets/* route exists in this spec at all, so none appears in the coverage table (settled owner decision — the customer uses none of them).
Full probe report (docs/sc/METHOD_PROBE_REPORT.md)

Method Probe Report — sc

Generated: 2026-11-03T10:42:29Z
Router image: ghcr.io/magma-devs/smart-router:main (digest sha256:41f227a8d04cd31315cb3961e58932e775bacb634b3a82ca46ee105daeb6f71c)
Spec variants: SC (mainnet, rest), SCT (Siacoin Zen testnet, rest, imports: [SC])
Head under test: d1ba22b "fix(spec): check the walletd network name in chain-id, admitting checkpoint-synced nodes (MAG-2968)"

Scope note: there is no public walletd node for this chain (team's walletd v2.15.2 nodes are on a
private machine CI cannot reach; the PR's <!-- ENDPOINTS --> block ships empty). This run
re-validates ONLY the chain-id verification change at this head, using two complementary,
clearly-labelled methodologies. It does not attempt the full 30-method Step 4 probe loop —
27 of 30 routes have no reachable walletd-compatible upstream and are NOT_TESTABLE (see below).

(A) Conservative baseline boot — unreachable placeholder upstream (SPEC_LOAD)

Booted the router against node-urls: [http://127.0.0.1:1] (deliberately unreachable) for both
spec variants, to prove static spec-graph resolution / import closure / REST pattern compilation /
verification wiring load cleanly at this head, independent of any live upstream.

Variant SPEC_LOAD Evidence
SC OK "message":"Successfully loaded and expanded spec from aggregated sources","chain_id":"SC"; "RPCSmartRouter Listening"; "ready for requests". Only failures: PROTOCOL_CONNECTION_REFUSED / "provider validation failed — excluding from provider list" on the placeholder URL (expected — connection refused, not a spec defect).
SCT OK Same signature with chain_id:"SCT", import closure (imports:["SC"]) resolved transparently (no spec not found for chainId / no failed to load any specs). Same connection-refused-only exclusion.

No panic, fatal, failed to load any specs, or spec not found for chainId lines in either boot.

(B) Test-only siascan shim — real PARSE/VERIFY verdicts

All results in this section are via a local test-only shim at /tmp/sia_shim.py (ports 8181
mainnet, 8182 zen) — NOT a provider, and not evidence for the other 27 walletd-only routes.
The
shim serves only /api/consensus/tip, /api/consensus/index/{height}, /api/consensus/network
and 404s everything else, proxying bodies unmodified from api.siascan.com (mainnet) /
api.siascan.com/zen (zen) — confirmed those upstreams answer HTTP 200 and that
/consensus/network truly returns {"name":"mainnet",...} / /zen/consensus/network returns
{"name":"zen",...} (no hardcoded value in the shim).

# Config Expected Result Evidence (log excerpt)
1 SC vs mainnet shim chain-id verify OK ("mainnet"); tracker runs GET_BLOCKNUM/GET_BLOCK_BY_NUM PASS "verification":"chain-id","rawData":"mainnet",...,"message":"[+] verified successfully"; smartrouter_latest_block{spec="SC"} 600203; router-proxied GET /api/consensus/index/600000 → {"height":600000,"id":"00000000000000056d82a01f9fb788ddde15d0f09d0ecaabb3cb6f90ac57f654"}
2 SCT vs zen shim (positive control) chain-id verify OK ("zen") PASS "verification":"chain-id","rawData":"zen",...,"message":"[+] verified successfully"
3 SCT vs mainnet shim (negative control, REQUIRED) chain-id verify FAIL with explicit mismatch PASS (failed as required) "rawParsedBlock":"mainnet","verification.Value":"zen",...,"message":"[-] verify failed expected and received are different" → "provider validation failed — excluding from provider list" → "no healthy providers for endpoint"
4 SC vs zen shim (negative control, REQUIRED) chain-id verify FAIL with explicit mismatch PASS (failed as required) "rawParsedBlock":"zen","verification.Value":"mainnet",...,"message":"[-] verify failed expected and received are different" → "provider validation failed — excluding from provider list" → "no healthy providers for endpoint"
5 Parse-signature sanity PARSE_CANONICAL parser_arg ["0","name"] resolves the network name string, not the raw object/empty string PASS rawData/rawParsedBlock fields above show the plain strings "mainnet"/"zen" (not a JSON blob, not empty); zero hits for the parse-failure signature grep across all 4 boots

Conclusion: the new network-name comparison is live, not vacuous. Both negative controls
produced an explicit expected X, got Y mismatch and excluded the provider — the single most
important check this run — and both positive cases verified cleanly with the real string pulled
from the live (proxied) /consensus/network body.

What the shim does NOT buy: coverage of the other 27 walletd-only routes (/api/wallets/*,
/api/txpool/*, /api/addresses/*, etc.) — these remain NOT_TESTABLE for lack of any reachable
walletd instance, exactly as in the prior 4 pipeline runs. This is not a spec defect.

Parse-directive runtime check (unchanged directives, confirmed still correct)

Check Verdict Evidence
GET_BLOCKNUM (/api/consensus/tip, parser_arg ["0","height"]) OK smartrouter_latest_block{spec="SC"} 600203 (matches shim's proxied tip height); rpc_endpoint_tracker_requests_total{kind="latest_block"} 3
GET_BLOCK_BY_NUM (/api/consensus/index/%d, parser_arg ["0","id"]) OK Direct-through-router call GET /api/consensus/index/600000 returned the correct block id string for that height. Note: the chain tracker's own automatic fork-detection block-hash poll is disabled by default ("block-hash polling (fork detection) resolved","enabled":"false","reason":"off-operator-choice") — a router default, not a spec issue — so the directive was confirmed via an explicit router call instead of the periodic tracker cycle.
Parse-signature log lines none Grepped all 4 shim boots for `failed to parse response

Verification runtime check — chain-id

Verification Verdict Providers OK/failed Notes
chain-id (SC, expected "mainnet") OK 1/1 (vs mainnet shim) rawData:"mainnet" — matches
chain-id (SCT, expected "zen") OK 1/1 (vs zen shim) rawData:"zen" — matches
chain-id (SCT, expected "zen", fed mainnet data) FAIL (expected to fail — negative control) 0/1 rawParsedBlock:"mainnet" != verification.Value:"zen"
chain-id (SC, expected "mainnet", fed zen data) FAIL (expected to fail — negative control) 0/1 rawParsedBlock:"zen" != verification.Value:"mainnet"

Addon & extension coverage (Step 1c)

ADDONS: none declared — jq over sc.json (both .add_on and .extension fields across the
full object tree) returns an empty list for both. Nothing to probe, nothing NOT_TESTABLE to carry.

Per-method table (all 30 routes)

Only the 3 explorer-shared routes were exercised (via the shim, labelled above); the other 27
are either NOT_TESTABLE (26 — no reachable walletd upstream serves them, and the shim
deliberately 404s every path outside the 3 it proxies) or SKIP (1 — stateful broadcast).

Method Classification Upstream notes Notes
GET /api/state NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/network PASS (via test-only siascan shim — not a provider) shim 127.0.0.1:8181 / 8182 chain-id VERIFICATION directive at this head (d1ba22b); 2 positive + 2 negative controls; also NOT_TESTABLE against real walletd
GET /api/consensus/tip PASS (via test-only siascan shim — not a provider) shim 127.0.0.1:8181 / 8182 GET_BLOCKNUM directive; also NOT_TESTABLE against real walletd
GET /api/consensus/tipstate NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/index/{height} PASS (via test-only siascan shim — not a provider) shim 127.0.0.1:8181 / 8182 GET_BLOCK_BY_NUM directive; router-relayed probe at height 600000 parsed correctly; also NOT_TESTABLE against real walletd
GET /api/consensus/blocks/{id} NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/checkpoint/{id} NOT_TESTABLE — no reachable walletd upstream
GET /api/consensus/updates/{index} NOT_TESTABLE — no reachable walletd upstream
GET /api/syncer/peers NOT_TESTABLE — no reachable walletd upstream; present on purpose (the customer's production usage, head 3b75f23) — not a defect
GET /api/txpool/transactions NOT_TESTABLE — no reachable walletd upstream
GET /api/txpool/fee NOT_TESTABLE — no reachable walletd upstream
GET /api/txpool/events NOT_TESTABLE — no reachable walletd upstream
GET /api/addresses/{addr}/balance NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
GET /api/addresses/{addr}/events NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
GET /api/addresses/{addr}/events/unconfirmed NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
GET /api/addresses/{addr}/outputs/siacoin NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
GET /api/addresses/{addr}/outputs/siafund NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
GET /api/outputs/siacoin/{id} NOT_TESTABLE — no reachable walletd upstream
GET /api/outputs/siacoin/{id}/spent NOT_TESTABLE — no reachable walletd upstream
GET /api/outputs/siafund/{id} NOT_TESTABLE — no reachable walletd upstream
GET /api/outputs/siafund/{id}/spent NOT_TESTABLE — no reachable walletd upstream
GET /api/events/{id} NOT_TESTABLE — no reachable walletd upstream
POST /api/txpool/broadcast SKIP — stateful — would broadcast a transaction
POST /api/txpool/parents NOT_TESTABLE — no reachable walletd upstream
POST /api/txpool/transactions/v2/basis NOT_TESTABLE — no reachable walletd upstream
POST /api/batch/addresses/balance NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
POST /api/batch/addresses/events NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
POST /api/batch/addresses/outputs/siacoin NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
POST /api/batch/addresses/outputs/siafund NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)
POST /api/check/addresses NOT_TESTABLE — no reachable walletd upstream; stays enabled per owner decision 2026-11-03 (checkpoint-node zero-balance effect documented and accepted)

Counts: PASS=3 (directive/verification routes, shim-only — not real walletd coverage) FAIL=0 SKIP=1 UNPROBED=0 NOT_TESTABLE=26 WARN=0 TIMEOUT=0 LOG_WARN=0.

Coverage scope (27 routes not exercised live)

26 of the 30 routes in the SC/SCT spec closure require a real walletd instance
(/api/state, /api/consensus/tipstate, /api/consensus/blocks/{id}, /api/txpool/*,
/api/addresses/*, /api/outputs/*, /api/events/{id}, /api/batch/addresses/*,
/api/check/addresses, …), and 1 more (POST /api/txpool/broadcast) is SKIP because it is
stateful and probing it would broadcast a transaction. No public walletd node exists and the
team's private nodes are unreachable from CI. These are NOT_TESTABLE — carried forward
unchanged from the prior 4 pipeline runs, same reason ("no reachable walletd-compatible endpoint
found"). This is a coverage gap to flag to a human with real walletd access, not a spec defect,
and it is explicitly not addressed by the siascan shim (the shim only ever serves the 3
explorer-shared routes). Note the spec declares no /api/wallets/* routes at all (settled
owner decision — the customer uses none of them), so none appear in this table.

Log-scan findings

None. No non-benign warn/error/fatal/panic lines beyond the expected connection-refused (baseline)
and expected-mismatch (negative controls) lines documented above.

Testnet verification pass (Step 7)

Folded into (B) above: SCT booted against the zen shim passed chain-id verification with its own
expected_value: "zen" (test #2), and against the mainnet shim correctly failed (test #3). No
separate Step 7 testnet-vs-real-node pass was run — no real testnet walletd endpoint exists (same
constraint as mainnet).

TESTNET_VERIFY: OK (via shim tests #2 and #3 above — not a real walletd node)

Empirical block time (Step 8)

BLOCK_TIME: mainnet=skipped testnet=skipped

Reason: walletd's /api/consensus/index/{height} response carries no timestamp field, so there is
no measurement recipe (same as prior runs). Not invented from siascan explorer-only fields.

Teardown

All containers removed: sr_sc, sr_sc_testnet (Step A boots, reused names), sr_sc_t1,
sr_sct_t2, sr_sct_t3_negctrl, sr_sc_t4_negctrl (Step B boots). Both shim processes
(sia_shim.py on 8181/8182) killed. Verified clean via docker ps -a --filter name=sr_sc (empty)
and ps aux | grep sia_shim (no processes).

@magmadevs-bot

magmadevs-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 9 — parallel reviewers (3 independent /review-spec passes) · re-validating head d1ba22b

Reviewer Angle TALLY
1 Broad audit, weighted to what the chain-id change touched CRITICAL=0 MEDIUM=0 MINOR=0
2 Route-table fidelity against walletd v2.15.2 Go source CRITICAL=0 MEDIUM=0 MINOR=1
3 Router-runtime semantics, incl. risks the change introduces CRITICAL=0 MEDIUM=0 MINOR=1

Aggregate: 0 CRITICAL, 0 MEDIUM, 2 MINOR. Three independent reports, three distinct md5 digests, every cited line number inside sc.json's 591 lines — no stale-state or shared-path artifacts.

The two MINOR findings (both informational; neither is a defect, neither feeds the fix pass)

MINOR-A (reviewer 2) — two public walletd routes the spec leaves out. GET /health (server.go:190-196) and POST /syncer/broadcast/block (server.go:369-382) are both inside wrapPublicAuthHandler and both absent from the spec. The reviewer recommends no action: /health reports the local WalletManager's indexing state rather than chain data (the same "platform/liveness, not chain data" exclusion the spec guide applies elsewhere), and /syncer/broadcast/block is a miner/node-operator route for relaying a newly-mined block — the customer broadcasts transactions, not blocks. Both are already named in the PR body's "Public walletd routes that this spec leaves out" note, which is exactly the explicit sign-off the reviewer asked for. Raised for the record only.

MINOR-B (reviewer 3) — the network-name check defends against a narrower set of failure modes than the retired genesis pin. The old pin compared a value cryptographically derived from the chain's genesis block, so anything answering with a different genesis necessarily failed. The new check compares a plain string that walletd reports from its own loaded network identity. Any process answering GET /api/consensus/network with {"name":"mainnet",...} — a forked/custom-genesis build, a devnet mislabeled by its operator, or a non-walletd impersonator — now passes a gate the pin would have rejected.

The reviewer is explicit that this is not a request to revert anything: the trade was the owner's deliberate call (MAG-2968 comment 31063), mainnet and zen are the only names real walletd builds use, and Phase 8's two negative controls prove the two live networks still separate cleanly. Its only suggested action is a documentation one — note in the decision log that chain-id now trusts the node's self-reported network name rather than a chain-derived value. Worth a line in the PR body; nothing in the spec changes.

What all three reviewers verified clean

  • Every one of the 30 routes matched individually against walletd v2.15.2's handler-map registration (HTTP method, path, placeholder position); no invented, misspelled or misrouted path. The public/private split checks out in both directions: nothing from wrapAuthHandler (/wallets/*, /rescan, /syncer/connect, /debug/*) appears in the spec.
  • GET /api/consensus/network is a registered public route and its response type carries a top-level name field, so PARSE_CANONICAL + parser_arg ["0","name"] is correct — confirmed against the Go structs and network-preset constants, not only against Phase 8's shim. Both expected values ("mainnet", "zen") likewise.
  • SCT still inherits the directive and overrides only the value. No residue of the retired genesis id or of /api/consensus/index/0 anywhere in the file.
  • check_unused_fields.sh PASS · check_internal_paths.sh PASS with zero AMBIGUOUS_REST_NAME / AMBIGUOUS_REST_SHAPE / NAME_CARRIES_PATH / LABEL_AS_PATH — no REST pattern collisions among /api/consensus/blocks/{id}, /api/consensus/checkpoint/{id}, /api/consensus/index/{height} or the outputs/{id} pairs.
  • deterministic flags: the 5 settled false routes are correct and no additional route was found with the same chain-moving property. stateful is on POST /api/txpool/broadcast and nothing else. No hanging_api/timeout_ms violations. CU bands coherent.
  • Network params and the SCT inheritance consistent: average_block_time 600000 ms, block_distance_for_finalized_data 6, blocks_in_finalization_proof 3 (PoW ⇒ probabilistic), allowed_block_lag_for_qos_sync 1.

All 9 settled owner decisions were handed to each reviewer up front and none was re-raised — including item 7 (POST /api/txpool/transactions/v2/basis at CU 20), which the previous round's Phase 11 had flagged and which the owner has since ruled on.

Reports on disk: docs/sc/SPEC_REVIEW_GAPS_parallel_{1,2,3}.md.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 10 — gap synthesis + fix pass, and Phase 10b — smoke re-probe · head d1ba22b

Fix pass: nothing to fix. sc.json is byte-identical to d1ba22b — the working tree is clean, so the pipeline's commit step has nothing to push.
Phase 10b: SMOKE: OK · PARSE: OK · VERIFY: OK · ADDONS: none declared · negative control still fails as designed.

Phase 10 — consolidation

The three Phase 9 reviewers returned CRITICAL=0 MEDIUM=0 unanimously. Deduplicating by (gap_title, evidence_line_number) and dropping MINOR per the skill leaves an empty fix list (docs/sc/FIX_LIST.md), so no fixer subagent was dispatched and no field was touched. Confirmed mechanically: only two ###-level severity headings exist across all three reports, both MINOR.

Disable-suggestion filter: 0 stripped. No reviewer proposed enabled: false on any method, addon or collection — notably none proposed disabling the address routes despite the checkpoint-node zero-balance effect, which is settled owner decision #8. The spec still carries 0 enabled: false entries, matching the body's <!-- disabled-count: 0 --> marker, so the marker needs no edit and the Disabled-API Justifications ledger stays correctly empty.

The two dropped MINOR gaps go to the watch-list, not the fixer:

Reviewer Gap Why not fixed
2 GET /health and POST /syncer/broadcast/block are public walletd routes absent from the spec MINOR; the reviewer recommends no action, and both are already named in the PR body's "Public walletd routes that this spec leaves out" note.
3 The network-name chain-id check defends against a narrower set of failure modes than the retired genesis pin MINOR/informational, documentation-only suggestion. Acting on it in a fix pass would mean re-adding the genesis pin — an explicit do-not-revert item.

Phase 10a — offline static gates, re-run after the (empty) fix pass

Gate Result
jq parse exit 0
check_method_schema.sh PASS — all 30 routes schema ok, empty FAIL section
check_unused_fields.sh PASS (no removed fields) — none of the 15 fields removed in smart-router #218 is present
check_hanging_api.sh PASS — empty FAIL and empty INFO
check_stateful.sh PASS — empty FAIL and empty INFO (no consensus-disagreement rows)
check_internal_paths.sh PASS — 0 warnings, 0 errors
check_disabled_count.sh PASS (report-only) — 0 distinct disabled methods, 0 rows

No --base was passed because sc.json does not exist on main — this is a new chain, so every row is this PR's and none can be excused as pre-existing. The envelope is still the canonical { "proposal": { "specs": [ … ] } } with compute_units as the only compute-unit input and no category.subscription anywhere (the spec has no subscription methods at all).

Phase 10b — smoke re-boot

Run even though the spec is unchanged, per the skill's standing instruction not to reason a re-boot away. Since there were no edits, a regression here would have indicated environmental flakiness or a Phase 8 measurement error rather than a Phase 10 change — none appeared.

# Probe Phase 8 Phase 10b Verdict
1 GET_BLOCKNUM via metrics gauge OK (latest_block 600203) OK (latest_block 600205) no change
2 chain-id SC vs mainnet shim PASS (mainnet) PASS (verified successfully) no change
3 chain-id SCT vs zen shim PASS (zen) PASS (rawData:"zen") no change
4 GET_BLOCK_BY_NUM at height 600000 PASS PASS — identical block id 0000000000000005…57f654 no change
5 Router-relayed GET /api/consensus/network PASS PASS (real proxied body) no change
6 Negative control — SCT vs mainnet shim must FAIL FAIL as required FAIL as required (rawParsedBlock:"mainnet" != verification.Value:"zen" → provider excluded) no change
7 Remaining 26 routes + POST /api/txpool/broadcast NOT_TESTABLE (26) / SKIP (1) unchanged no change

The 10b pass ran image tag :latest (digest sha256:476faaac…) while Phase 8 ran :main (sha256:41f227a8…), as the two agent specs prescribe. That cross-tag agreement is a bonus signal: the spec loads and verifies identically on both images. The only delta attributable to the tag was cold-start warn noise on :latest (provider data not found, using default, invalid adaptive latency/sync bounds, using defaults) emitted before the probe window, carrying no method field — generic adaptive-scoring startup noise, not a Siacoin finding.

Both boots re-created the test-only siascan shim (killed after Phase 8) and tore it down again; all containers and shim processes verified clean. Reminder that the shim is not a provider and buys nothing for the 26 walletd-only routes.

@magmadevs-bot

Copy link
Copy Markdown
Contributor Author

Phase 11 — final reviewer verdict: ✅ APPROVED · head d1ba22b

TALLY: CRITICAL=0 MEDIUM=0 MINOR=0 — report at docs/sc/SPEC_REVIEW_GAPS_final.md

The verdict is reported exactly as the reviewer returned it. Nothing was upgraded: all three Phase 9 reviewers and the final pass independently returned zero CRITICAL and zero MEDIUM, and because Phase 10 applied no changes, this APPROVED verdict is against committed head d1ba22b itself, not against a working-tree patch. git status --porcelain sc.json is empty — the pipeline's commit step has nothing to push.

The change this round validated

chain-id reads GET /api/consensus/network → .name (PARSE_CANONICAL, parser_arg ["0","name"]), "mainnet" on SC / "zen" on SCT, replacing the /api/consensus/index/0 genesis-id pin so checkpoint-synced nodes are admitted (omer, MAG-2968 comment 31063). It was validated three independent ways:

  1. Live, at this head — Phase 8 exercised the verification in four router boots: SC+mainnet verified, SCT+zen verified, and both negative controls (SCT fed mainnet data, SC fed zen data) failed with explicit rawParsedBlock != verification.Value mismatches and provider exclusion. The check is live and non-vacuous, which is the specific risk a string expected_value carries that a 32-byte block-id pin did not.
  2. Against the upstream source, not just the shim — reviewer 2 confirmed /api/consensus/network is a registered public route in walletd v2.15.2's handler map and that its response type carries a top-level name field, and confirmed both expected values against the network-preset constants in the Go source.
  3. Re-confirmed on a second router image — Phase 10b repeated the positive and negative cases on tag :latest (sha256:476faaac…) after Phase 8 ran :main (sha256:41f227a8…), with identical outcomes down to the same parsed block id at height 600000.

What the final pass checked

  • jq valid · check_unused_fields.sh PASS (none of the 15 removed fields) · check_internal_paths.sh PASS · check_method_schema.sh PASS (30/30 schema ok) · check_hanging_api.sh, check_stateful.sh, check_network_params.sh, check_verifications.sh, check_directive_presence.sh, check_extensions.sh, check_node_admin_rpcs.sh all clean.
  • 0 enabled: false entries, verified independently with jq at spec, collection and API level — matching the empty Disabled-API Justifications ledger and the body's <!-- disabled-count: 0 --> marker. No unjustified disable exists because no disable exists.
  • All 30 routes cross-checked 1:1 against walletd v2.15.2's api/server.go handler list with correct HTTP methods. The only public walletd routes absent (/health, /syncer/broadcast/block) are the already-filed MINOR, deliberately excluded and already named in the PR body.
  • Method-by-method block_parsing, deterministic/stateful flags and CU values across all 30 routes; both parse directives; the SC/SCT collection inheritance and chain-id override; the POST collection's content-type header.
  • All 9 settled owner decisions re-verified present/absent as mandated and none re-raised — including item 7 (POST /api/txpool/transactions/v2/basis at CU 20), the single CRITICAL from the previous round. That finding was aimed at a CU bump the pipeline itself had applied; the bump was reverted then, the owner has since ruled on the value, and this round's reviewers were told it was settled. It did not recur.

Open items — owner-tracked, not defects, and not blockers

  1. Live coverage of 26 of 30 routes. No public walletd node exists and the team's nodes are unreachable from CI, so 26 routes stay NOT_TESTABLE and 1 is SKIP (stateful broadcast). NOT_TESTABLE is not coverage. The real coverage on record is @AnnaR-prog's manual smart-router run against the private walletd v2.15.2 nodes (PR body, "Update 2026-11-03"), including the checkpoint-node 404-and-retry behaviour that no CI-reachable endpoint can reproduce. To close it in CI: /rerun-probe mainnet=<walletd-url>.
  2. Documentation suggestion (MINOR-B, reviewer 3). chain-id now trusts the node's self-reported network name rather than a chain-derived value, so it cannot by itself distinguish a mislabeled or forked walletd build from a genuine one. The two real networks still separate cleanly. Worth one line in the PR's decision log alongside the existing checkpoint and personal-index-mode disclosures; no spec change implied, and explicitly not a request to re-add the genesis pin.
  3. MAG-4793 (router-side caching of walletd mempool/peer reads) remains a smart-router fix, correctly treated as out of scope for this spec.

@magmadevs-bot

magmadevs-bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Phase 12 — closing summary checklist (tail of Phase 11; this pipeline run covered Phases 8–11 at head d1ba22b)

File Validation

  • ✓ JSON syntax valid — (Phase 10a ran jq, exit 0; Phase 11 re-confirmed)
  • ✓ All required fields present — (Phase 11 completeness pass; check_network_params.sh + check_method_schema.sh clean)
  • ✓ No duplicate API names within any collection — (Phase 9 reviewer 2 + check_internal_paths.sh: 0 AMBIGUOUS_REST_NAME / AMBIGUOUS_REST_SHAPE)
  • ✓ Proper indentation/formatting — (4-space, no trailing newline, byte-identical to d1ba22b)

Configuration Verification

  • ✓ Network parameters calculated per formulas — (average_block_time 600000 ms from /consensus/network .blockInterval, drift ≤1.1% vs empirical; block_distance_for_finalized_data 6 = the customer's 6 confirmations; blocks_in_finalization_proof 3 = PoW probabilistic; allowed_block_lag_for_qos_sync 1 — re-verified Phase 9 + 11)
  • ☐ All APIs tested and working — 26 of 30 routes NOT_TESTABLE, 1 SKIP (no public walletd node exists; the team's nodes are unreachable from CI). Only 3 explorer-shared routes were exercisable, via a clearly-labelled test-only shim. NOT_TESTABLE is not coverage. Real coverage is out-of-band: @AnnaR-prog's manual run against the private walletd v2.15.2 nodes (PR body, "Update 2026-11-03"). Close in CI with /rerun-probe mainnet=<walletd-url>.
  • ~ Block parsing validated for each API — (reviewed statically for all 30 routes in Phases 9 and 11; executed live for only the 2 directive routes)
  • ✓ Parse directives executed by live router — (Phase 8: PARSE: OK — smartrouter_latest_block{spec="SC"}=600203, GET_BLOCK_BY_NUM parsed the correct id at height 600000; VERIFY: OK. Phase 10b re-check on a different image tag: PARSE: OK, VERIFY: OK, same block id)
  • ✓ Addons & extensions tested — (ADDONS: none declared — the spec declares zero addons and zero extensions; walletd v2.15.2 has no pruning mechanism, so the archive/pruning/GET_EARLIEST_BLOCK triplet is correctly absent in all three places)
  • ~ Verifications pass on live nodes — (chain-id verified live on both SC and SCT, plus two negative controls that correctly failed, in Phase 8 and again in Phase 10b — but through the test-only siascan shim, not a real walletd node)
  • ☐ Compute units benchmarked under expected load — (user to measure; POST /api/txpool/transactions/v2/basis at CU 20 is a standing owner decision taken without a benchmark, do-not-revert item 7)

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 — (SC, 30 routes: 22 GET + 8 POST, 0 disabled)
  • ✓ Testnet spec inherits correctly — (SCT imports: ["SC"], lean entry overriding only the chain-id value; inheritance audited in Phases 9 and 11 and resolved live by the router at boot)
  • ✓ Chain IDs verified for mainnet AND testnet — (SC→"mainnet", SCT→"zen", both verified live and both negative controls correctly rejected; values also confirmed against walletd's network-preset constants in the Go source)
  • ~ Both tested on respective networks — (both variants booted and verified; neither against a real walletd node — see the coverage item above)

Governance Prep (out of skill scope — manual reminder)

  • ☐ Proposal JSON formatted correctly — (the file is the canonical { "proposal": { "specs": [ … ] } } envelope with no title/description/deposit; check_unused_fields.sh PASS confirms none of the 15 removed fields is present)
  • ☐ Community feedback gathered (if applicable)

Auto-decisions taken this run (unattended; conservative default; recorded)

  1. No endpoints were resolved and none were invented. MAINNET_URLS/TESTNET_URLS were empty and the PR body ships an empty <!-- ENDPOINTS --> block on purpose. Rather than configure api.siascan.com as a provider — it is the explored explorer daemon, not walletd — Phase 8 kept it strictly as a test-only shim for the 3 shared routes and reported the other 26 as NOT_TESTABLE. The conservative default here is an honest coverage gap, not a green run bought with a fake provider.
  2. The ws probe gate did not apply. The spec declares no subscription methods (zero SUBSCRIBE directives in the resolved closure), so no ws-capable node was required and the run did not stop to ask for one.
  3. No fix pass was applied. With 0 CRITICAL and 0 MEDIUM across three reviewers, the fix list was empty; the two MINOR findings were dropped per the skill. Acting on MINOR-B would have meant re-adding the genesis pin — an explicit do-not-revert item.
  4. The verdict was not upgraded. It is APPROVED because the final reviewer returned CRITICAL=0 MEDIUM=0 MINOR=0, independently of the previous round's CHANGES REQUESTED (whose single CRITICAL concerned a CU bump the pipeline itself had applied and then reverted, since settled by the owner at CU 20).

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

Elapsed:         00h 29m 29s  (first→last logged activity)
Transcripts:     1 main + 6 subagent
API round-trips: 400  (main=71, subagents=329)
Fresh tokens:    input=800  output=206930  (sum=207730)
Cached tokens:   cache_read=27500991  cache_write=1487294
Total billed:    29196015 tokens
Split:           main=7901134  subagents=21294881
Models:          claude-sonnet-5 (329 calls, 21294881) · claude-opus-5 (71 calls, 7901134)

These figures cover Phases 8–11 of this run alone. Phases 1–7 ran in the original create_spec job (their time and tokens are reported in that run and the PR body), and the four earlier /rerun-from 8 rounds each have their own totals in their own comments. The true end-to-end cost of this PR is the sum of all of them — stated that way deliberately rather than printing a number that looks complete but covers one slice.

Working tree

sc.json is unmodified — no fix pass ran, so the branch already matches the spec that Phase 10b and Phase 11 verified. There is nothing for the pipeline's commit step to push.

@AnnaR-prog

AnnaR-prog commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

@avitenzer ready for re-review at d1ba22b. Blocker 2 is resolved the other way, so my earlier blocker 2 reply is replaced: following omer's MAG-2968 comment 31063, chain-id now checks the network name (/api/consensus/network → .name), nodes started from a checkpoint are admitted, and nothing is asked of the customer.

  • Tested on router v1.6.2 and v1.6.4: a checkpoint node's 404 for old heights, blocks and events is retried on another node, and the customer's other reads answer the same as on a block-0 node.
  • CI at d1ba22b: Phase 11 ✅ APPROVED (0 critical, 0 medium, 0 minor), and the fix pass changed nothing.
  • Known effect, documented and accepted for now: on such a node the address routes answer zero balances for coins received before its checkpoint. The customer calls none of them.

Details are in the description's "Update 2026-11-03".

@avitenzer avitenzer left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved at head d1ba22b: the spec is correct for what it encodes

@AnnaR-prog: approving on spec correctness. Everything below was checked against walletd v2.15.2 source, smart-router origin/main (acc4455a), and a live run: walletd v2.15.2 (-index.mode full -http.public) started from a checkpoint on mainnet (600171) and zen (64124), each behind the router with sc.json at this head and no verifications skipped.

Verified

Check Result
chain-id: SC on mainnet, SCT on zen both verified successfully; checkpoint nodes are admitted, as 31063 asks
chain-id: SC on zen, SCT on mainnet (negative controls) both refused
Latest block matches siascan on both networks
GET /api/consensus/index/{h} below the checkpoint 404 height not found; the router treats it as NODE_DATA_NOT_HELD, retries another node, never caches it
1792a3a..d1ba22b only the 5 deterministic: false flips and the chain-id swap
Content guards all 13 pass; disabled-count: 0 matches the file
Route coverage all 30 routes exist in walletd v2.15.2; SC/SCT collide with nothing on main
Mempool/peer routes as DEFAULT ["latest"], stateful: 0 correct, same shape as ETH's txpool_content; cache exclusion is the router's job (MAG-4793)

Caveats, none of them spec defects

  1. Checkpoint nodes still answer some routes without an error (31063 says "never a wrong answer silently"). Measured on the mainnet checkpoint node: GET /api/addresses/{addr}/balance for the Sia Foundation address returns {"siacoins":"0"} (siascan: about 1.87 billion SC), and GET /api/consensus/blocks/600172 returns all 34 inputs with origin.source: "unknown". The customer doesn't call the address routes; it does call blocks/{id}, though walletd marks any spend older than 144 blocks unknown on every node (wallet/manager.go:571), so that field is best-effort by design. The spec can't turn either into an error (a disabled api is still relayed as Default-<path>). The body records this as an owner decision; the ticket record is your 31168, which omer hasn't answered yet. His ack closes this.
  2. Wallet routes. The customer's 30943 lists PUT api/wallets/1/addresses, which gets a 501 through the router. Omitting the routes is consistent with Option 1 (30985: no password through the router), but the body's "the customer makes no wallet calls" isn't what 30943 says. Please fix the wording; omer's call on whether the customer sends it straight to the nodes (your 30990) belongs on the ticket.
  3. MAG-4793 before go-live. Mempool, fee and peer reads are cached for 75 s on any router with a cache. Router fix, not spec; the customer polls /api/txpool/transactions after each broadcast.
  4. Description nits. The archive section says there is "no full-vs-archive tier to model"; admitting checkpoint nodes creates that split. Name the minimum router version: the 404 rule shipped in v1.5.8 (tested on v1.6.2, v1.6.4, main).

Non-blocking, for the record

  • walletd answers "not found" on GET /api/outputs/siacoin/{id}, /outputs/siafund/{id} and /consensus/updates/{index} with a plain-text 500. The router returns its own 500 and marks the node unhealthy. The customer calls none of these; the clean fix is upstream (the /spent handlers already return 404).
  • Not proven: broadcast of an input older than the node's checkpoint through a checkpoint node (OverwriteElementProofs keeps the caller's proof for inputs the node never indexed). Only a pool made entirely of checkpoint nodes would show it.

@AnnaR-prog
AnnaR-prog merged commit 8c1474c into main Nov 3, 2026
3 of 6 checks passed
AnnaR-prog added a commit that referenced this pull request Nov 3, 2026
…(MAG-2968)

avitenzer's review on PR #197: these answers change as the chain moves, so
cross-validation would treat two honest nodes a block apart as disagreeing.

- GET /api/events/{id}: the reply carries Confirmations = 1 + scanHeight -
  height (persist/sqlite/events.go:121, walletd v2.15.2). It grows every
  block and differs between nodes indexed to different heights.
- GET /api/outputs/siacoin/{id}, GET /api/outputs/siafund/{id}: only
  unspent outputs are returned (persist/sqlite/utxo.go: spent_index_id IS
  NULL), so the answer changes once the output is spent.
- GET /api/consensus/blocks/{id}, GET /api/consensus/checkpoint/{id}: a
  numeric id is read as a height through cm.BestIndex (api/server.go), so a
  reorg near the tip changes the answer. checkpoint/{id} was not in the
  review but takes the same code path.

Tested with smart-router v1.6.4 against our walletd v2.15.2 nodes: Kraken's
call list answers the same through the router as directly, on mainnet (SC)
and on zen (SCT, including the POST broadcast route it inherits).

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants