rippled-zig: the five gates as a release-readiness contract

2026-05-18 · project rippled-zig

This is a lab notebook entry, not an announcement post. Format is claim → the five gates → what each one gates against → the toolkit scope → honest non-goals → reproducibility. Every claim is graded against the controlled evidence vocabulary; every assertion is footnoted to the [rippled-zig][repo] repo's README, PROJECT_STATUS.md, or CHANGELOG.md. The substrate under examination is a Zig implementation of the XRP Ledger protocol — specifically a toolkit and library, not a node — gated behind five distinct release-readiness checks (Gates A through E) plus a deterministic-cluster Sim gate.

[repo]: https://github.com/SMC17/rippled-zig

1. The claim

rippled-zig ships a compact Zig implementation of core XRPL protocol surfaces — canonical transaction encoding, signing-hash generation, secp256k1 / Ed25519 signature verification, and a six-method live RPC subset — gated behind a five-gate release-readiness process plus a deterministic local-cluster simulation gate. The current release tag is v1.0.1¹; the full v1 XRPL Toolkit release decision is NO-GO at the date of writing, with specific blockers named in PROJECT_STATUS.md².

The surface covered by the five gates, as enumerated in the README³:

| Gate | Name | What it proves | | -----— | -------------------------------— | --------------------------------------------------------------------— | | A | Build + Unit / Integration | zig build and the unit / integration test suite pass on the required OS matrix | | B | Deterministic Serialization / Hash| Serialization and hash vectors reproduce against a committed SHA-256 fixture manifest | | C | Cross-Implementation Parity | RPC fixture parity against rippled reference + strict crypto verification (3 positive + 3 negative secp256k1 vectors) | | D | Live Testnet Conformance | Live server_info, fee, ledger, ledger_current, account_info against an actual XRPL testnet endpoint | | E | Security / Fuzz / Static | Security suites pass with zero runtime-safety violations, fuzz budget thresholds enforced, crash-free markers | | Sim | Deterministic Local Cluster | Multi-node simulation cluster runs deterministically with profile-based thresholds |

<!— runnable-claim: rippled-zig-five-gates —>

Evidence grade: differential-tested. Gate C is the gate that earns this grade: cross-implementation parity against the canonical rippled C++ reference, plus strict crypto verification against positive and negative vectors. The other gates contribute different evidence shapes (build, determinism, live conformance, security) that together form the release contract.

2. Why five gates instead of "passes its tests"

Most blockchain implementations claim "passes its tests" as the shipping bar. That bar is insufficient for a consensus-critical codebase, because the failure modes are not the ones unit tests exercise. The five-gate structure is the substrate that addresses this honestly. Each gate guards against a specific class of failure mode that the previous gate cannot see.

The README's own framing³:

Every commit to main must pass Gates A through E. Gate D accepts

an explicit skip artifact when testnet secrets are unavailable.

And from PROJECT_STATUS.md's policy section⁴:

No unqualified percentage claims. Every technical claim must map to

objective, reproducible evidence. Experimental modules are excluded

from all release claims. Gate results older than 14 days without a

follow-up run are considered stale.

Three things to read off this:

1. The gates are sequenced, not parallel. Gate A produces the

binary; B asserts the wire format is deterministic; C compares that wire format against the C++ reference; D drives it against live infrastructure; E guards the security surface. A failure at any single gate fails the release.

1. **Gate D accepts an explicit SKIPPED artifact when testnet

secrets are unavailable.** This is the right pattern: a missing reference is not silently green, it produces a published skip marker. The CI artifact records the skip explicitly so a future contributor or auditor can see which run skipped live conformance, and why.

1. Stale-evidence policy is part of the contract. Gate results

older than 14 days without a follow-up run are considered stale. The release contract is a trending contract, not a single-pass one.

3. What each gate gates against — failure modes by gate

The interesting engineering question is not "what does each gate do?" but "what specific kind of bug would silently ship if this gate weren't here?" The PROJECT_STATUS.md gate definitions enumerate the pass criteria; the failure-mode reading below is the implication⁵.

3.1 Gate A — Build + Unit / Integration

Pass criteria (from PROJECT_STATUS.md)⁵:

• scripts/gates/gate_a.sh exits 0 on the required OS matrix.
• Zig version equals 0.14.1.

Failure mode this gates against. Toolchain drift. The repo's risk register lists R-001: Toolchain drift breaks reproducibility as a High-severity open risk, mitigated by enforcing .tool-versions and a CI check⁶. A repo that compiles under "any sufficiently new Zig" silently accepts language-level semantics changes; pinning to 0.14.1 means the wire format and the binary output reproduce against a known compiler.

(A note on the toolchain pin: PROJECT_STATUS.md and the README both pin Zig 0.14.1 as the build-tested toolchain; build.zig.zon's minimum_zig_version reads 0.16.0 as a lower bound.⁷ The gate enforces the README's pin, which is the canonical statement.)

3.2 Gate B — Deterministic Serialization / Hash

Pass criteria⁵:

• scripts/gates/gate_b.sh exits 0.
• Serialization and hash suites pass for all declared transaction types.
• Fixture SHA-256 manifest generated and matches committed baseline

(test_data/fixture_manifest.sha256).

• Vector hash evidence emitted for each deterministic vector (VL

boundaries, drops encoding, mixed-field ordering).

Failure mode this gates against. A canonical-encoding regression that produces equivalent but not byte-identical output. XRPL binary serialization specifies field ordering, VL-length prefix encoding for variable-length fields (the 192 / 193 and 12480 / 12481 boundary classes the README enumerates⁸), and amount encoding shapes that a careless emitter can get wrong in ways that pass equality tests but break signature verification on the network. The fixture SHA-256 manifest in test_data/ is the committed witness: a future change that touches the codec but forgets to update the manifest fails the gate, even if every in-source unit test still passes.

The CHANGELOG's history is the right shape here. Multiple Gate B fixes shipped during the v1.0 cycle⁹:

• Fix Gate B vector hash output for Zig 0.15.1 fmt API
• Fix Gate B mixed vector expected bytes and hash
• Fix Gate B canonical vector 2 expected ordering/hash
• Fix Gate B ArrayList initialization for Zig 0.15.1
• Fix Gate B shadowing and consolidate status docs
• Refresh fixture manifest after secp provenance update

The pattern — each commit names the specific vector it pins — is the right discipline for canonical-encoding work.

3.3 Gate C — Cross-Implementation Parity

Pass criteria⁵:

• scripts/gates/gate_c.sh exits 0.
• RPC fixture parity checks pass (stable fields, cross-fixture

consistency).

• secp256k1 strict verification with GATE_C_STRICT_CRYPTO=true:

3 positive vectors, 3 negative vectors.

• Signing-domain correctness: SHA512Half(STX || canonical) equals

expected signing hash; regression checks against wrong-prefix and body-only hashes.

Failure mode this gates against. The single most consequential class of failure in any consensus-critical implementation: an implementation that "passes its tests" but silently disagrees with the reference on byte-level encoding or signature verification. The STX prefix domain-separator is the specific surface where a port can quietly drop bytes or hash the wrong thing; the SHA512Half(STX || canonical) regression checks against wrong-prefix and body-only hashes mean a missing-prefix bug fails the gate. The 3-positive / 3-negative secp256k1 split asserts the verifier accepts what it should and rejects what it should — both sides of the gate.

This is the gate that earns the differential-tested evidence grade. A failure here means the Zig implementation disagrees with rippled (C++) on whether a transaction is valid, which is the failure mode that produces a fork. The CHANGELOG names "Strengthen Gate C with secp256k1 fixture value and DER checks" and "Expand Gate C with 3 positive and 3 negative secp vectors" as the closure work that produced the current Gate C surface⁹.

3.4 Gate D — Live Testnet Conformance

Pass criteria⁵:

• scripts/gates/gate_d.sh exits 0 with TESTNET_RPC_URL and

TESTNET_WS_URL configured.

• Live server_info, fee, ledger, ledger_current,

account_info fields validated.

• Trend success-rate floor and p95 latency ceiling enforced from a

7-day rolling summary.

• Operator runbook: docs/GATE_D_OPERATOR_RUNBOOK.md.

Failure mode this gates against. The canonical "works in unit tests, breaks against the production network" gap. A six-method JSON-RPC client that decodes fixtures perfectly can still fail against a real testnet endpoint if the live response shape has optional fields the fixture didn't cover, or if a chunked-transfer encoding behaviour bites. The trend-summary enforcement — success- rate floor and p95 latency ceiling over a 7-day rolling window — catches degradation against the live endpoint, not just single-cycle pass / fail.

The live testnet endpoints, from the README¹¹:

export TESTNET_RPC_URL="https://s.altnet.rippletest.net:51234/"
export TESTNET_WS_URL="wss://s.altnet.rippletest.net:51233/"
scripts/gates/gate_d.sh artifacts/gate-d-live

The 7-day rolling trend is what makes Gate D a contract rather than a one-shot check. A regression that breaks live conformance for one day on a weekend doesn't fail the gate; a regression that breaks it for an accumulated week's worth of runs does. The CHANGELOG names "Fix Gate D secret precheck" as the closure work for the secret-handling path; "add policy snapshot drift checks and account_info positive Gate D coverage" is the closure for the trend side⁹.

3.5 Gate E — Security / Fuzz / Static

Pass criteria⁵:

• scripts/gates/gate_e.sh exits 0.
• Security suites pass with zero runtime-safety violations.
• Fuzz budget enforcement with profile-based thresholds (pr vs

nightly).

• Crash-free marker enforcement.
• Trend success-rate, crash-free-rate, p95 runtime, and avg fuzz

budget floors from a 7-day summary.

Failure mode this gates against. Latent crash paths and fuzz-discoverable input handling bugs. A canonical-encoding parser that handles every well-formed transaction perfectly can still panic on a maliciously-shaped input — wrong VL prefix, oversized length field, truncated body. The profile-based fuzz-budget thresholds mean PR-cycle runs have a lower budget (for fast feedback) while nightly runs have a heavier budget (for catching slow-to-find issues). The crash-free marker is the single bit that distinguishes "the fuzzer ran" from "the fuzzer ran and didn't find anything."

3.6 Sim — Deterministic Local Cluster

Pass criteria⁵:

• scripts/gates/gate_sim.sh exits 0.
• Profile-based thresholds enforced (pr vs nightly).
• 7-day trend drift checks for success-rate, p95 latency, avg nodes.

Failure mode this gates against. State-machine determinism under multi-node replay. The CHANGELOG names "add manifest-driven consensus experiment matrix runner" and "extend invariant probe with total_coins and ledger hash checks" as the substrate this gate exercises¹⁰. A consensus implementation that produces deterministic single-node output can still drift on a multi-node replay if any non-deterministic dependency (clock, syscall ordering, allocator behaviour) leaks into the state transition.

The invariant probe checks two specific load-bearing properties: total_coins (the conservation invariant — the XRPL native asset supply is fixed, every transaction must conserve total drops across sender + receiver + fees burned), and ledger hash (each ledger close produces the same hash given the same input transactions in the same order). A failure on either is exactly the class of bug that makes a consensus implementation unsafe.

4. The release decision — current status is NO-GO

The single most important data point from PROJECT_STATUS.md, the release-decision row²:

| Field | Value | | ---------------— | -----------— | | Release Candidate | NO | | Decision | NO-GO | | Decision Date | Pending | | Decision Owner | Engineering Lead |

This is the right way for a consensus-critical implementation to state its status. The five gates are green at the snapshot date — each one individually passes its script — but the release decision requires sustained gate evidence across a minimum 4-week window, a v1 transaction-set codec complete, signed release artifact policy satisfied, and no unresolved HIGH severity risks in the register¹³.

The current blockers, also from PROJECT_STATUS.md¹⁴:

• Canonical codec and signing / verification surfaces not yet

complete for the declared v1 transaction set.

• Repository messaging repositioning in progress (#46).
• Production-readiness evidence incomplete (audit, sustained soak).
• Need sustained green runs over a time window, not a single-cycle

pass.

The v1.0 and v1.0.1 tags that exist today are hygiene-and-policy releases, not the v1 XRPL Toolkit release:

• v1.0.0 (2026-05-13) — the v1 XRPL Toolkit release shipped as a

feature wave (AMM, pathfinding, multi-sign, NFT, Prometheus, AI fee, simulation in the v1.4 wave; cross-compilation, Docker, trust lines, DEX, WASM lib, result codes in v1.3; SHAMap, ledger objects, fee engine, constant-time crypto, safe arithmetic in v1.2; Ed25519 signing, wallet, benchmarks, field defs, deserializer in v1.1)¹². This was the "complete overhaul for shipping quality" cycle; the v1 toolkit release decision still requires the 4-week sustained-green window.

• v1.0.1 (2026-05-13) — hygiene patch only, non-breaking. Added

SECURITY.md (coordinated disclosure policy), .github/dependabot.yml (github-actions monthly, 3-PR cap), .github/CODEOWNERS routing review to @SMC17¹.

This is the substrate-versus-release distinction. The substrate exists and is gated; the release decision is gated on sustained evidence, not a single tag.

5. What's in v1 and what's NOT

The toolkit's v1 scope, from the README's "What It Does" / "What It Does Not Do" tables¹⁵:

In v1 scope:

| Capability | Detail | | ---------------------------— | ----------------------------------------------------------— | | Canonical transaction encoding| Payment, AccountSet, OfferCreate, OfferCancel | | Signing-hash generation | SHA-512Half with XRPL STX prefix domain separation | | Signature verification | secp256k1 (via libsecp256k1) + Ed25519 (via Zig std) | | Live RPC conformance | server_info, fee, ledger, ledger_current, account_info, submit | | Base58Check encoding | XRPL address encode / decode with RIPEMD-160 | | Deterministic serialization | Canonical field ordering per XRPL binary format spec | | CLI surface | Build, test, run, gate execution |

Explicitly NOT in v1:

| Surface | Status | | ---------------------------— | ----------------------------------------------------------— | | Validator or full node operation | Outside scope | | P2P overlay / peer protocol | Outside scope (experimental modules remain, no correctness claims) | | Ledger sync / history | Outside scope | | Consensus participation | Outside scope | | Persistent storage | Outside scope |

The README is explicit about this: "It is a toolkit and library, not a node. It does not participate in consensus, sync ledgers, or operate as a validator. For production node operation, use the official rippled."¹⁵

This is exactly the right scope for a Zig port. Implementing the toolkit surface — canonical encoding + crypto + RPC client — in ~25 K LOC of native Zig with a vendored libsecp256k1 dependency is tractable; implementing the full node + consensus + P2P stack is the ~3 M LOC of C++ work that rippled itself represents. The toolkit scope is the load-bearing demarcation that makes "Zig XRPL implementation" honest.

6. The pure-Zig stack discipline (and where the discipline ends)

The README's architecture diagram⁸ enumerates the modules that compose the toolkit:

src/canonical_tx.zig    -- canonical XRPL field ordering and binary encoding
src/transaction.zig     -- transaction modeling and serialization
src/serialization.zig   -- variable-length encoding boundaries
src/crypto.zig          -- signing-hash generation and key utilities
src/secp256k1.zig       -- ECDSA signature verification
src/secp256k1_binding   -- libsecp256k1 bindings
src/ripemd160.zig       -- RIPEMD-160 (Zig)
src/base58.zig          -- Base58Check address encoding (Zig)
src/rpc.zig             -- JSON-RPC server
src/rpc_methods.zig     -- RPC method implementations

Five things to read off honestly:

1. **RIPEMD-160, Base58Check, and the canonical-encoding /

transaction / RPC layers are all native Zig.** No C dep for the wire-format work; the substrate that produces the bytes Gate B pins is fully in-tree.

1. Ed25519 verification uses Zig's standard library. No external

crypto for the Ed25519 path; the std library's std.crypto surface is the dependency.

1. secp256k1 verification uses libsecp256k1. The README is

explicit: "secp256k1 (via libsecp256k1)" — the strict-crypto path Gate C exercises with the 3-positive / 3-negative vectors shells out to a vendored libsecp256k1 build. The default build uses -Dsecp256k1=false, with libsecp256k1 marked as an optional dependency for the strict ECDSA verification paths¹¹. The CHANGELOG also names "CI/CD FIX: Make secp256k1 optional dependency" as the closure work for that optional-dep posture⁹.

1. The audit surface is dramatically smaller than rippled's.

The toolkit scope (canonical encoding + crypto + six RPC methods) is the auditable substrate; the C++ reference's full node + consensus + P2P stack is not part of this audit surface.

1. **Experimental modules remain in the repo with no correctness

claims.** PROJECT_STATUS.md's capability matrix explicitly names peer_protocol.zig, ledger_sync.zig, consensus.zig, storage.zig, and database.zig as "Experimental — research only"¹⁶. They are not gated by the five gates and they are not part of the v1 release claim.

7. The auditability claim — and what it isn't

A common temptation in Zig-port narrative is "fewer LOC than the C++ original, therefore safer." That framing is not what rippled-zig makes, and this entry will not make it. The honest framing is the one PROJECT_STATUS.md itself ships¹⁷:

Several codec and verification paths require evidence-backed

closure before release. Live testnet conformance is environment-

dependent; must run in controlled CI with secrets. Experimental

modules remain in the repo but carry no correctness claims. **No

independent security audit has been performed.** No long-horizon

soak evidence exists yet.

"Smaller audit surface" is a claim about substrate area, not audit completion. Five-gate enforcement at every commit is a substantial substrate-level discipline that the C++ original does not enforce in exactly the same shape — but enforcement of a substrate discipline is not a substitute for an independent audit. The repo names both, distinctly.

The "Smaller audit surface" claim that can be made honestly: the toolkit-scope Zig implementation is auditable as a unit by a single reader in a finite amount of time, because the v1 surface deliberately excludes the consensus and P2P layers that drive most of rippled's C++ LOC. That is the substrate-area claim; the "production-ready" claim is gated on the 4-week sustained-green window that PROJECT_STATUS.md makes explicit¹³.

8. Honest limitations — six gaps the README and PROJECT_STATUS name

Lifted directly from the repo's own documentation, not invented:

1. Release decision is NO-GO at the snapshot date. The five

gates pass individually, but the release contract requires sustained-green runs across a 4-week window plus codec closure²¹³.

1. **C-007 (canonical encoding for the declared v1 transaction set)

and C-009 (Ed25519 signing and verification) are both IN PROGRESS in the claim-to-evidence register**¹⁸. The deterministic-vectors + fixture-manifest surface (C-007) and the Ed25519 unit-test surface (C-009) are not yet at the evidence-bar the release decision requires.

1. No independent security audit has been performed. Named

explicitly under "Known Limitations"¹⁷.

1. No long-horizon soak evidence exists yet. Same source. The

stale-evidence policy (14-day re-run window) is in place; the accumulated trending evidence is not yet at the v1-release bar.

1. secp256k1 is an optional dependency. The default build uses

-Dsecp256k1=false; strict ECDSA verification requires building with the libsecp256k1 dependency enabled¹¹. Production-network use cases need the strict path, which means the strict-path build is the one that matters for any production posture.

1. Open HIGH-severity risks remain. From the risk

register⁶:

• R-001: Toolchain drift breaks reproducibility (Open).
• R-002: Repo messaging overstates partial node surfaces (In

Progress).

• R-003: Partial codec / crypto paths block release claim

(Open).

• R-004: Live RPC subset and release packaging incomplete

(Open).

The pre-release security framing from the README is the right posture¹⁹:

This is pre-release software. It has not been independently

security audited. Do not use with real value without extensive

independent validation. Do not deploy as infrastructure. Report

security issues via GitHub Security Advisories.

9. The version contract

The v1.x tag line ratchets specifically through the hygiene-and-policy axis (SECURITY.md, Dependabot, CODEOWNERS) plus the substrate work (canonical encoding, signing, RPC subset). The v1 XRPL Toolkit release is a separate decision, gated by the five-gate sustained-green window, codec closure, and audit completion¹³.

The release-cycle plan is on the public roadmap, from PROJECT_STATUS.md's execution tranches²⁰:

| Tranche | Issues | Target | Description | | ---------------------------— | ----------— | --------— | -----------------------------------------------------— | | 1. Scope freeze | #46, #47, #61| 2026-03-31 | Reposition docs, prune examples, lock toolchain | | 2. Codec + crypto | #48-#54 | 2026-05-15 | Canonical encoding and verification for declared tx set | | 3. Live + RPC | #55-#57 | 2026-06-15 | RPC subset hardening, live conformance evidence | | 4. Public surface | #58-#60 | 2026-07-10 | API / CLI stability, examples, packaging | | 5. Release | #62 | 2026-07-31 | Signed artifacts, release checklist, final evidence |

This is the right release-cycle shape: gated by evidence at each tranche, not by calendar pressure. The "v1 XRPL Toolkit" release date in the README is "Not yet" with a target of 2026-07-31, and all maturity claims are explicitly considered "untrusted unless backed by reproducible gate evidence"²¹.

10. Reproducibility

The full reproduction recipe, from the README¹¹:

git clone https://github.com/SMC17/rippled-zig.git
cd rippled-zig
zig build
zig build test

# Toolkit CLI
zig build run -- help
zig build run -- version
zig build run -- encode-tx rAddr1 rAddr2 1000000 12 1
zig build run -- hash-tx <hex_bytes>
zig build run -- verify-sig <hash_hex> <sig_hex> <pubkey_hex>
zig build run -- encode-address <hex_account_id>

Per-gate reproduction:

scripts/gates/gate_a.sh artifacts/gate-a-local
scripts/gates/gate_b.sh artifacts/gate-b-local
scripts/gates/gate_c.sh artifacts/gate-c-local
scripts/gates/gate_e.sh artifacts/gate-e-local

# Live testnet (Gate D) — requires testnet secrets
export TESTNET_RPC_URL="https://s.altnet.rippletest.net:51234/"
export TESTNET_WS_URL="wss://s.altnet.rippletest.net:51233/"
scripts/gates/gate_d.sh artifacts/gate-d-live

Each gate emits its evidence artifact under artifacts/<gate-name>-local/. The published CI artifacts are the canonical source of truth; the local-run artifacts are reproducible witnesses against a clean build.

11. Status footer

• Evidence grade: differential-tested. Gate C — cross-

implementation parity against rippled plus strict crypto with 3-positive / 3-negative secp256k1 vectors — earns this grade. The other gates contribute build / determinism / live-conformance / security evidence shapes that together form the release contract.

• Reproducible: true. The commands in §10 are the canonical

reproduction recipe; Zig 0.14.1 is the pinned build toolchain per the README and PROJECT_STATUS.md.

• Last verified: 2026-05-18, against the README and

PROJECT_STATUS.md at v1.0.1. The current release decision is NO-GO; the substrate exists, the gates pass individually, and the 4-week sustained-green window is the next milestone.

• Open gaps: codec closure for the v1 transaction set

(C-007); Ed25519 verification surface closure (C-009); signed-release-artifact-policy verifier closure; sustained-green 4-week window across all five gates + Sim; independent security audit. All filed in PROJECT_STATUS.md's claim-to-evidence register and risk register.

12. Cross-references

• Repository: SMC17/rippled-zig
• License: ISC (same as rippled, see LICENSE)
• Companion repo in the Sovereign Stack:

zeth — EVM in Zig; the consensus-critical Zig pair.

• External references:
• Official rippled (C++) reference implementation, the parity

target for Gate C²².

• XRPL binary serialization spec, the canonical-encoding spec

Gate B pins against²³.

• XRPL JSON-RPC method documentation, the six-method surface Gate

D drives²⁴.

• This lab entry's design contract:

~/codex/methods/stax-dev-portfolio-design-system.md — the evidence vocabulary applied to every claim.

Footnotes