Repository navigation
feat(spec): name Ripple's finality field for XRP and XRPT (MAG-5339) - #212
Tomelia1999 wants to merge 1 commit into
Conversation
A Ripple node that is behind the network answers a numbered ledger read with its own open copy of that ledger: HTTP 200 and "validated": false. The router decided "final" from block numbers alone, so such a reply could be cached as final. Declare the field on both specs, so a router that reads it keeps a reply as final only when the block distance says so and result.validated, if present, is true: finality_field_path "result.validated" finality_field_final_value "true" Both specs carry the settings: an import brings API collections, not spec-level values. A router that does not know the settings ignores them. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
🤖 Spec pipeline started on PR open — running Phase 8 → 11. Results post here as comments. View run |
|
Phase 8 — smart-router boot + multi-node method probe Resumable run (
The spec carries Verdicts
Addon & extension coverage
No FAIL / WARN methods
Testnet pass —
|
| Check | Verdict | Evidence |
|---|---|---|
| GET_BLOCKNUM (router latest_block) | OK | smartrouter_latest_block=108432542+ (rising across the run); rpc_endpoint_fetch_latest_success 75-102 per upstream, 0 fails |
| GET_BLOCK_BY_NUM (log hash-reads ∥ fetch_block counters) | NOT_EXERCISED | hash_read_lines=0; fetch_block_* metric absent (confirmed dead, per doc); rpc_endpoint_tracker_requests_total{kind="block_hash"} never appears — only kind="latest_block". Router-wide behavior on this image, not ripple-specific. Corroborating positive evidence: the pruning verification uses the SAME GET_BLOCK_BY_NUM function_tag/template and succeeded 12/12 times across all upstreams at boot (see below), so the directive itself is not broken — the periodic chain-tracker simply never exercises it for this chain on this router build. |
| Parse-signature log lines | none | — |
| Verification | Verdict | Providers OK/failed | Notes |
|---|---|---|---|
| chain-id | OK | 6/6 (3 https + 3 wss) | expected_value "0" matched on every upstream |
| pruning | OK | 12/12 (2 values × 3 upstreams × 2 node-urls) | base value (latest_distance 500) and archive value (expected_value "32570") both verified on every upstream — all 3 mainnet nodes are genuinely full-history |
Parse-directive & verification runtime check (Step 3.5) — testnet (XRPT)
| Check | Verdict | Evidence |
|---|---|---|
| GET_BLOCKNUM | OK | smartrouter_latest_block=22447784 (rising); fetch_latest_success=5, 0 fails (via the surviving https node-url) |
| Verification | Verdict | Providers OK/failed | Notes |
|---|---|---|---|
| chain-id | OK | 2/2 (https + wss) | expected_value "1" matched on both node-urls |
| pruning | PARTIAL | 1/2 node-urls | https://s.altnet.rippletest.net:51234 OK; wss://s.altnet.rippletest.net:51233 FAILED at boot: GET_BLOCKNUM Failed to parse Response ... result:{closed:{ledger:{...}}}. Confirmed independently: the same ledger/ledger_index:"validated" call returns the modern flat result.ledger.* shape over HTTP but the legacy nested result.closed.ledger.* / result.open.ledger.* shape over WS on this specific public altnet node (no api_version pinned) — a response-shape quirk of that one public endpoint, not a spec defect. Effect: the router excluded the wss node-url from block-tracking/serving (only the https url's fingerprint shows up in rpc_endpoint_url_latest_block/url_block_tracking), leaving no working ws upstream for XRPT in this configuration (altnet is the only public XRPL testnet JSON-RPC, so a different ws candidate could not be substituted here). |
Addon & extension coverage (Step 1c + probes)
| Name | Type | Upstreams supporting | Standalone | Boot verification | Router probe | Classification |
|---|---|---|---|---|---|---|
| archive | extension | all 3 (xrplcluster, s1.ripple.com, s2.ripple.com) | — | OK (12/12, see pruning above) | PASS (ledger at ledger_index 40000 via router with lava-extension: archive returned valid historical data, matching the no-header call since all upstreams are full-history) |
TESTED_OK |
No add_on (disjoint add-on collection) is declared anywhere in ripple.json — only the archive extension exists.
Method probe (mainnet, through router at localhost:3360)
Live inputs resolved before probing: latest validated ledger (~108432565+), a historical tx hash from a recent ledger, funded mainnet account rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh, earliest ledger 32570, a real mainnet AMM pair (XRP/USD via issuer rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B).
| Method | Classification | Upstream notes | Notes |
|---|---|---|---|
| account_info | PASS | ||
| gateway_balances | PASS | ||
| account_lines | PASS | ||
| account_channels | PASS | ||
| account_currencies | PASS | ||
| account_tx | PASS | ||
| submit | SKIP | stateful — would broadcast a transaction | |
| submit_multisigned | SKIP | stateful — would broadcast a transaction | |
| server_state | PASS | ||
| fee | PASS | ||
| tx | PASS | ||
| ledger | PASS | ||
| ledger_closed | PASS | ||
| ledger_current | PASS | ||
| server_info | PASS | chain-id verification also exercises this | |
| book_offers | PASS | ||
| ripple_path_find | PASS | ||
| account_nfts | PASS | (account has 0 NFTs; empty array is still a PASS result) | |
| account_objects | PASS | ||
| account_offers | PASS | ||
| noripple_check | PASS | ||
| ledger_data | PASS | ||
| ledger_entry | PASS-existence | entryNotFound (98) | plausible index, not an actual ledger-entry key — method recognized and parsed correctly |
| transaction_entry | PASS-existence | transactionNotFound | tx hash was from a different ledger than queried — method exists |
| amm_info | PASS | resolved a real live AMM pair | |
| deposit_authorized | PASS | ||
| nft_buy_offers | PASS-existence | invalidParams (31) | placeholder NFTokenID rejected by format check; method recognized |
| nft_sell_offers | PASS-existence | invalidParams (31) | same |
| path_find | WARN | notSupported (75) on xrplcluster; unknownCmd on s1/s2.ripple.com | path_find is WS-only per rippled design (confirmed: ripple_path_find is the HTTP one-shot equivalent). xrplcluster (clio) returns an explicit notSupported: ... WebSocket-only message over HTTP; s1/s2.ripple.com (plain rippled) don't even register an HTTP handler and return unknownCmd. Node disagreement is explainable by server-type difference, not a spec defect — not re-probed over WS since the classification is input-independent. |
| ping | PASS | ||
| random | PASS | ||
| server_definitions | PASS | ||
| manifest | PASS-existence | invalidParams (31) | method recognized, no manifest on file for the given key |
| nft_history | PASS-existence | invalidParams "nft_idMalformed" | |
| nft_info | PASS-existence | invalidParams "nft_idMalformed" | |
| nfts_by_issuer | PASS | ||
| feature | PASS | ||
| channel_authorize | WARN | notSupported (75) "Signing is not supported by this server." | admin/signing disabled on public nodes — maps to the noPermission/notImpl class, not a FAIL |
| channel_verify | PASS-existence | channelMalformed (45) | placeholder channel id not a real channel; method recognized |
| vault_info | PASS-existence | entryNotFound "vault object not found." | confirmed with a correctly-formatted 64-hex vault_id; SingleAssetVault/LendingProtocol amendments are supported-but-disabled network-wide (via feature), consistent with "not found" rather than "unsupported" |
| subscribe | FAIL | router: could not start subscription ... json: cannot unmarshal object into Go value of type string |
Router-side defect, not a spec defect — see dedicated section below |
| unsubscribe | FAIL | router: failed to extract subscription ID: could not extract subscription ID from params |
Same root cause — no subscription ever succeeded to unsubscribe from |
Subscribe/unsubscribe finding (important, router-side)
The spec's own UNSUBSCRIBE function_template (and the equivalent method-style shape for subscribe) is {"jsonrpc":"2.0","id":1,"method":"subscribe","params":[{"streams":["ledger"]}]} — i.e. a JSON-RPC envelope with an object-shaped streams parameter, which is exactly how rippled's WS protocol works. This was verified correct independently:
- Sent directly to
wss://xrplcluster.com, both the native{"id":1,"command":"subscribe","streams":[...]}form AND the spec's{"method":"subscribe","params":[{"streams":[...]}]}form succeed immediately with a subscribe-confirmation frame followed by streamingledgerClosedmessages. - Sent to the router's WS listener (
ws://localhost:3360) in the spec's own form, the router logs show it DOES route it throughDirectWSSubscriptionManager(not the generic HTTP relay), but fails withupstream subscribe failed: json: cannot unmarshal object into Go value of type string. Variants tried:params:[{"streams":["ledger"]}](spec shape) → object-unmarshal error;params:["ledger"](array of bare strings, EVM-eth_subscribe-style) →ledger unknown parameters type string;params:"ledger"(bare string) → same "unknown parameters type string".
Conclusion: the router's generic WS-subscription relay machinery expects a simple string/array-of-strings subscription parameter (the EVM eth_subscribe(["newHeads"]) shape) and cannot currently marshal XRPL's native object-shaped {"streams":[...]} parameter through to the upstream, regardless of which JSON shape the client sends. This is a pre-existing smart-router limitation for XRPL-style subscriptions, unrelated to PR #212 (the finality-field addition) — it would reproduce on any XRP spec test against this router build. Flagging prominently per instructions since subscribe/unsubscribe are declared methods, but this is not something fixable in ripple.json.
Log-scan findings (probe window)
| Level | Associated method | error excerpt |
|---|---|---|
| WARN | subscribe/unsubscribe (ws) | StartSubscription returned an error: ... json: cannot unmarshal object into Go value of type string (×3 variants tried) |
| ERROR | subscribe/unsubscribe (ws) | could not start subscription / error unsubscribing from subscription: failed to extract subscription ID |
| WARN | — | Null method malformed-JSON-RPC-response lines — all are the router retrying the misrouted ws subscribe payload against the HTTP upstreams (same root cause as above, not a separate finding) |
| WARN | — | 4× Circuit breaker: all providers exhausted — each corresponds to a method where all 3 upstreams consistently agreed on the same not-found/invalid-params/malformed-retry outcome (ledger_entry, transaction_entry, vault_info, and one subscribe retry); already reflected in the method table above, no separate finding |
| ERROR | — | 2× blockParsing - rpcInput is error — benign per the runbook: upstream returned an RPC error, not a directive defect |
| WARN | — | provider data not found, using default (×several, around the ws-subscription attempts) — router housekeeping noise tied to the same subscription failures |
No fatal/panic lines at any point; the router remained healthy and continued serving normal method calls throughout and after the subscribe-probe window.
Testnet verification pass (Step 7)
TESTNET_VERIFY: PARTIAL
| Verification | Verdict | Providers OK/failed | Notes |
|---|---|---|---|
| chain-id | OK | 2/2 | expected_value "1" matched on both https and wss node-urls |
| pruning | PARTIAL | 1/2 node-urls | https OK; wss failed due to a response-shape quirk on the public altnet node (see Step 3.5 testnet table above) — not a spec defect, but means XRPT has no working ws upstream in this configuration |
Empirical block time (Step 8)
| Network | RPC | Empirical (ms) | Spec effective (ms) | Drift | Verdict |
|---|---|---|---|---|---|
| mainnet | https://xrplcluster.com | 4090 | 4000 | +2.25% | OK |
| testnet | https://s.altnet.rippletest.net:51234 | 3410 | 4000 | -14.75% | OK (under 20% threshold) |
|
Phase 9 — parallel reviewers (3 × Three reviewers ran
Merged, deduplicated: 1 CRITICAL + 1 MEDIUM. Reviewers 2 and 3 independently found the same MEDIUM ( All three reviewers cleared this PR's own diffThe diff is exactly four added lines — CRITICAL —
|
|
Phase 10 — synthesize gaps + fix pass (+ Phase 10b smoke re-probe) Consolidated the three Phase 9 reports into Decision: no spec edits applied — recorded as an auto-decisionThis run is unattended, so the STOP-and-ask gate was auto-decided with the conservative default, and here is the reasoning. Both surviving gaps are pre-existing on
Phase 10a — offline static gates, re-run after the (empty) fix pass
The removed-field guard is the one this run's rules single out: the spec carries none of the 15 fields smart-router dropped in #218 — no spec-level governance fields, no
Disabled-API Justifications ledger: (none — no disabled APIs). Phase 10b — smoke re-probe:
|
| # | Probe | Phase 8 | Phase 10b | Verdict |
|---|---|---|---|---|
| 1 | GET_BLOCKNUM (ledger, validated) |
PASS | PASS — ledger 108432882 | no change |
| 2 | chain-id (server_info → info.network_id) |
OK (6/6) | PASS — network_id: 0 matches "0" |
no change |
| 3 | account_channels |
PASS | PASS | no change |
| 4 | account_currencies |
PASS | PASS | no change |
| 5 | account_info |
PASS | PASS | no change |
| 6 | account_lines |
PASS | PASS | no change |
| 7 | account_nfts |
PASS | PASS | no change |
| addon | archive extension (ledger @ 40000, lava-extension: archive) |
TESTED_OK | PASS — 2013 close_time returned |
no change |
PARSE: OK — smartrouter_latest_block rising, fetch_latest_success 12/upstream, 0 fails, no parse-signature lines. One transient context deadline exceeded against s1.ripple.com self-recovered on the next tick. GET_BLOCK_BY_NUM is NOT_EXERCISED again, identically to Phase 8 — this router build never periodically polls it.
VERIFY: OK — no [-] verify, no failed verification on provider startup, no Bad verification definition; all three providers logged Provider validated successfully. pruning logged 6/6 [+] verified successfully against Phase 8's 12/12; the smoke tester attributes the smaller count to a :latest-vs-:main logging difference rather than a functional gap, since the live archive probe succeeded and nothing failed. ADDONS: 1 tested-ok / 0 failed / 0 not-testable.
No fatal/panic at any point, and no genuine rate limiting. Container torn down.
|
Phase 11 — final reviewer verdict:
Per the pipeline's rule the verdict is CHANGES REQUESTED — any remaining CRITICAL or MEDIUM gap produces that verdict, and this run reports it without upgrading. The nuance below matters for deciding what to do with it, but it does not change the verdict. What the verdict is and is not aboutThe final reviewer ran in a clean context, re-verified both surviving gaps with fresh live
So the verdict reflects the state of The findings
One detail strengthens the CRITICAL: altnet's Recommendation for the human reviewerThe verdict is CHANGES REQUESTED on the file, while the change under review is clean and all three findings predate it. Two defensible paths, and this is a human call the pipeline should not make:
The pipeline took path 1 by default and left the spec untouched; nothing is blocking path 2 if you prefer it. Full final review report (
|
| Parameter | Value | Assessment |
|---|---|---|
average_block_time |
4000ms (both) | Empirically confirmed by the probe: mainnet measured 4090ms (+2.25% drift), testnet measured 3410ms (-14.75% drift), both within the 20% OK threshold. |
block_distance_for_finalized_data |
4 | Pre-existing, untouched by this PR. Not flagged. |
blocks_in_finalization_proof |
3 | Pre-existing, untouched by this PR. XRPL's RPCA consensus has a defensible case for "fast/instant" classification (validated ledgers don't reorg), which per the settled rule would permit 1 — but it also has a defensible case for "unclear," whose fallback formula (max(ceil(1000/4000),3) = 3) lands on the same value already in the file. Since both readings converge on 3, this is not raised as a finding. |
allowed_block_lag_for_qos_sync |
3 | 10000/4000 = 2.5 → ceiling 3. Correct. |
Summary
- Endpoints reviewed: 42 declared APIs in
XRP's single main collection (confirmed by
jq), cross-checked against the 42-row method probe (36 PASS/PASS-existence, 2 SKIP —
statefulsubmit/submit_multisigned, 2 FAIL —subscribe/unsubscribe, 2 WARN —
path_find/channel_authorize), plus thearchiveextension and thechain-id/pruning
verifications.XRPTdefines zero APIs of its own (pure inheritance plus achain-id
override) — correct minimal-override pattern. - Gaps by severity: CRITICAL: 1, MEDIUM: 1, MINOR: 1. All three are pre-existing on
origin/mainand independent of this PR's diff; none were introduced by PR feat(spec): name Ripple's finality field for XRP and XRPT (MAG-5339) #212. - PR feat(spec): name Ripple's finality field for XRP and XRPT (MAG-5339) #212's actual diff (
finality_field_path: "result.validated",
finality_field_final_value: "true"on bothXRPandXRPT): no defect found, re-verified
live and independently in this pass. Correct field path, correct value encoding, correct
placement on both specs, confirmed backward-compatible boot. - Readiness: PR feat(spec): name Ripple's finality field for XRP and XRPT (MAG-5339) #212's diff is ready to ship as-is. The CRITICAL (
XRPTarchive/pruning)
and MEDIUM (path_find) findings are real, live defects in the file under review, but both
are pre-existing and out of this PR's scope — they need their own follow-up ticket/PR rather
than blocking this one. The MINOR finding (subscribe/unsubscribeblock_parsing
convention) is low-impact and likewise pre-existing.
TALLY: CRITICAL=1 MEDIUM=1 MINOR=1
|
Phase 12 — closing summary checklist (tail of Phase 11; no separate Phase 12 in this run span) Legend: Run span and disposition
Run stats — this pipeline run only (Phases 8-11)These figures cover only Phases 8-11 in this workflow run — they are not a Phases 1-11 grand total. This PR was authored by hand rather than by a create_spec run, so there is no sibling Phases 1-7 run to add to them. To redo any part of this: |
What
ripple.json, XRP and XRPT: two new spec-level settings that name the field by which a Ripple node says whether the data it answered with is final.Both specs carry the settings. XRPT imports XRP, but an import brings API collections only, not spec-level values.
Why
"status": "success"and"validated": false.validatedat the top level ofresulton every reply that reads a ledger.truemeans final. With these settings the router keeps a reply as final only when the block distance says so andresult.validated, if present, istrue.Depends on smart-router #774
The settings are read by smart-router PR #774 (MAG-5339). A router without that change ignores them: specs are decoded with plain
json.Unmarshal, which skips unknown fields. So the two can merge in either order, and this one has no effect until routers run #774.Checked
main(without #774) loaded this file and served XRP normally."validated": false"validated": trueTestEveryLavaSpecHasAChainFamily, and the spec decode and loader tests intypes/specandutils/keeper.ripple.jsonbefore and after the change, give the same result: disabled-count reports 0, node-admin-rpcs and chain-identity report no new findings, unused-fields, network-params, method-schema, verifications, extensions and stateful pass.Not checked
Jira ticket: MAG-5339
🤖 Generated with Claude Code