An XRPL Protocol Toolkit in Zig -- canonical transaction encoding, signing-hash generation, signature verification, and live RPC conformance for a declared subset of the XRP Ledger protocol.
Evidence note (2026-05-14): the previous five static
brightgreenshields were decorative badge images, not live CI status. They have been replaced with the live GitHub Actions badge above so that the README reflects the actual workflow result on every push. The trend-window gates (C / D / E / Sim) require three consecutive successful CI runs after the persistence fix in PR #TBD lands before their rolling-window thresholds can converge honestly. Until that soak completes onmain, treat any "A–E green" phrasing in lower sections as describing the gate-definition level, not the trend-window pass level.
rippled-zig is a compact, auditable Zig implementation of core XRPL protocol surfaces: binary transaction encoding, cryptographic signing and verification, and a selected set of JSON-RPC methods tested against live testnet endpoints.
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.
| Capability | Scope | Status |
|---|---|---|
| Canonical transaction encoding | Payment, AccountSet, OfferCreate, OfferCancel | Gate B verified |
| Signing-hash generation | SHA-512Half with XRPL STX prefix domain separation |
Gate B/C verified |
| Signature verification | secp256k1 (via libsecp256k1) + Ed25519 (via Zig std) | Gate C strict crypto |
| Live RPC conformance | server_info, fee, ledger, ledger_current, account_info, submit |
Gate D verified |
| Base58Check encoding | XRPL address encode/decode with RIPEMD-160 | Unit tested |
| Deterministic serialization | Canonical field ordering per XRPL binary format spec | Gate B fixture manifest |
| CLI surface | Build, test, run, gate execution | Stable |
- Validator or full node operation
- P2P overlay / peer protocol
- Ledger sync or history
- Consensus participation
- Persistent storage
These are explicitly outside the v1 release claim. See PROJECT_STATUS.md for the exact boundary.
Requirements
- Zig 0.14.1
libsecp256k1for strict ECDSA verification paths- C compiler (Zig ships one, or use system
cc)
git clone https://github.com/SMC17/rippled-zig.git
cd rippled-zigBuild and test
zig build
zig build testRun the 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>Run quality gates locally
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-localRun live testnet conformance (Gate D)
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-liveEncode a canonical Payment transaction
# Via CLI
zig build run -- encode-tx rN7n7otQDd6FczFgLdlqtyMVrn3X66B4T rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh 1000000 12 1
# Or build with -Dexperimental=true for full node modules
zig build -Dexperimental=trueThe toolkit's primary surfaces are importable Zig modules:
src/canonical_tx.zig -- canonical XRPL field ordering and binary encoding
src/transaction.zig -- transaction modeling and serialization
src/crypto.zig -- signing-hash generation and key utilities
src/secp256k1.zig -- ECDSA signature verification
src/base58.zig -- Base58Check address encoding
src/rpc.zig -- JSON-RPC server with selected method handlers
src/rpc_methods.zig -- RPC method implementations
+-----------------------+
| CLI / Library |
| (main.zig) |
+----------+------------+
|
+--------------+--------------+
| |
+---------v----------+ +----------v---------+
| Codec Layer | | RPC Layer |
| | | |
| canonical_tx.zig | | rpc.zig |
| transaction.zig | | rpc_methods.zig |
| serialization.zig | +--------------------+
+--------+-----------+
|
+--------v-----------+
| Crypto Layer |
| |
| crypto.zig |
| secp256k1.zig |
| secp256k1_binding |
| ripemd160.zig |
| base58.zig |
+--------------------+
Codec Layer -- Canonical binary encoding of XRPL transactions. Field ordering follows the XRPL serialization specification. Variable-length encoding handles all VL boundary classes (192/193, 12480/12481).
Crypto Layer -- SHA-512Half signing-hash generation with STX prefix domain separation. secp256k1 ECDSA verification via system libsecp256k1. Ed25519 via Zig standard library. RIPEMD-160 for AccountID derivation. Base58Check for address encoding.
RPC Layer -- HTTP JSON-RPC server handling server_info, fee, ledger, ledger_current, account_info, and submit for the declared transaction subset.
The repository also contains experimental modules (consensus, peer protocol, ledger sync, storage) that are not part of the v1 release surface. They remain for research purposes and carry no correctness claims.
Every commit to main is required to pass Gates A through E and Sim before
release tagging. Gate D accepts an explicit skip artifact when testnet
secrets are unavailable. The live status of each run is visible via the
Quality Gates badge above and in the Actions tab.
| Gate | What It Proves | Script | Evidence Level | Artifacts |
|---|---|---|---|---|
| A | Build + unit/integration tests pass on Linux + macOS matrix | gate_a.sh |
unit-tested per run |
Build log, test results |
| B | Deterministic serialization and hash vectors reproduce | gate_b.sh |
audited (fixture manifest) |
Fixture SHA-256 manifest, vector hashes |
| C | Cross-implementation parity with rippled fixtures; strict secp256k1 verification | gate_c.sh |
integration-tested per run, trend window converging post-2026-05-14 persistence fix |
Parity results, signing-domain checks, 7-day trend summary |
| D | Live testnet conformance for declared RPC subset | gate_d.sh |
integration-tested when secrets present, skip otherwise; trend window per Gate C |
Endpoint health, trend summaries |
| E | Security scans (panic() / @setRuntimeSafety(false) / security TODOs), fuzz budget, crash-free markers |
gate_e.sh |
audited (static) + unit-tested (fuzz), trend window per Gate C |
Security metrics, fuzz artifacts |
| Sim | Deterministic local multi-node simulation + protocol invariants | gate_sim.sh |
integration-tested per run, trend window per Gate C |
Simulation summary, round events, invariant probe |
Trend-window claims (C/D/E/Sim) accumulate via actions/cache-backed
history. As of 2026-05-14, the persistence layer was missing from
the workflow; the rolling windows therefore had a structural floor of 1
data point. With the layer in place (PR #TBD), each window needs three
consecutive scheduled-cron green runs (~3 days at the daily 17:03 UTC
cadence) before the MIN_CONSEC_STRICT_PASSES=3 threshold can converge
honestly.
Gate results, trend summaries, and ops digests are published as CI artifacts on every run. See PROJECT_STATUS.md for the evidence register.
| Method | Mode | Gate Coverage |
|---|---|---|
server_info |
Live + fixture | D, C |
fee |
Live + fixture | D, C |
ledger |
Live + fixture | D, C |
ledger_current |
Live + fixture | D, C |
account_info |
Live + fixture | D, C |
submit |
Narrow transaction subset | D, C |
All methods return deterministic error contracts for malformed or unsupported input.
| Type | Canonical Encoding | Signing Hash | Verification |
|---|---|---|---|
| Payment | Yes | Yes | Yes |
| AccountSet | Yes | Yes | Yes |
| OfferCreate | Yes | Yes | Yes |
| OfferCancel | Yes | Yes | Yes |
- Release candidate: Not yet. Active development toward v1.
- Target date: 2026-07-31
- Milestone:
v1 XRPL Toolkit(Epic #45) - Canonical status: PROJECT_STATUS.md
All maturity claims are considered untrusted unless backed by reproducible gate evidence.
Contributions are welcome. See CONTRIBUTING.md for guidelines.
Current priorities (in delivery order):
- Scope freeze -- #46, #47, #61: Reposition docs, prune examples, lock toolchain
- Codec and crypto correctness -- #48-#54: Complete canonical encoding and verification for declared transaction set
- Live conformance and release -- #55-#62: RPC subset hardening, CLI surface, signed release artifacts
To contribute:
- Fork the repository
- Create a feature branch
- Ensure all gates pass locally (
scripts/gates/gate_a.shthroughgate_e.sh) - Open a pull request against
main
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
For production XRPL operations, use rippled.
If any other document conflicts with PROJECT_STATUS.md, PROJECT_STATUS.md is authoritative.
ISC License -- same as rippled. See LICENSE.
- Official rippled: https://github.com/XRPLF/rippled
- XRPL Documentation: https://xrpl.org/docs
- Zig Language: https://ziglang.org/
A small portfolio of solo-built Zig protocol implementations and infrastructure.
- zeth — EVM in Zig (companion blockchain implementation)
- zig-cobs, zig-graph, zig-h3 — composable Zig substrate libraries
See github.com/SMC17 for the full portfolio.