raio

An open-source, Pix-inspired instant-payment foundation in Rust — built for interoperability across providers, currencies, and borders.

Landing page · Journal (posts + newsletter)

raio learns from Brazil's Pix — alias-based pay-to-key (the "DICT"), 24/7 instant transfer, the "copia e cola" QR Code, immediate confirmation — and packages those ideas as a correct, federatable foundation anyone can build interoperable payment rails on, in any market. Pix is the inspiration; correctness and interoperability are the point. It is currency-aware (a broad, growing set of currencies, including zero-decimal ones like the CFA franc zones) and standards-aware: the EMVCo QR Code, ISO 20022, the GSMA Mobile Money API, and PAPSS are among the real-world seams raio is designed to interoperate with (ADR-0011).

It is not a bank, not a payment processor, and not affiliated with Pix or the Banco Central do Brasil (see SECURITY.md). raio ships the root-of-trust types and the trait seams; real settlement, durable storage, and transport are left to deployments.

_{45s overview — full-quality video}

Crate map

raio-core         IO-free root of trust: Money, ids, keys, TxState, SettlementProvider trait
raio-brcode       BR Code codec (Pix "copia e cola", EMV TLV + CRC16-CCITT), pure and fuzzable
raio-qr           EMVCo QR codec (Merchant-Presented Mode + CRC16-CCITT) — the interoperable QR
raio-ledger       double-entry, append-only, event-sourced ledger + LedgerStore trait
raio-ledger-redb  durable LedgerStore (pure-Rust redb; the first real backend)
raio-dict         key directory (alias → account) + KeyDirectory trait
raio-dict-redb    durable KeyDirectory (pure-Rust redb; the DICT backend)
raio-examples     not published; NaiveSettlement + the settlement_demo

Each crate compiles and is published independently — depend on just raio-core for the types, or pull in the ledger and codec as needed.

Quickstart

git clone https://github.com/andrewSarr/raio
cd raio
cargo test --workspace
cargo run --example settlement_demo

The demo resolves email:ana@example.org to BankB, settles a R$ 25.00 payment from BankA via the naive SettlementProvider, prints before/after balances, and emits the BR Code "copia e cola" string.

Windows (x86_64-pc-windows-gnu) — set this before building: export RUSTFLAGS='--cfg=getrandom_backend="windows_legacy"' (MSVC and Unix are unaffected.)

What raio is / isn't

Is	Isn't
a Money type with checked integer arithmetic	a float-based money lib
an append-only, double-entry ledger model	a hosted ledger service
a SettlementProvider trait + a naive example	a central bank / custody
a BR Code codec	a wallet app
a foundation designed for community extension	a turnkey payment product

Documentation

The full book (concepts, architecture, protocol, getting started, ADRs) lives in docs/ and renders as mdbook. It also reads fine as Markdown on GitHub:

• docs/src/introduction.md
• docs/src/architecture.md
• docs/src/roadmap.md — what to build next
• docs/src/scaling.md — from the in-memory impls to a durable, sharded deployment
• docs/src/currencies.md — supported currencies (incl. zero-decimal XOF/XAF/UGX/RWF/GNF) and how to add one
• docs/src/adr/ — 11 Architecture Decision Records

Roadmap

raio ships the foundation; the layers above it are community-owned. The highest-value next steps (full detail in docs/src/roadmap.md):

• M1 — a durable LedgerStore — 🟢 shipped as raio-ledger-redb (pure-Rust redb, no C toolchain). SQLite/Postgres backends are welcome community crates on the same seam.
• M2 — a durable KeyDirectory — 🟢 shipped as raio-dict-redb (pure-Rust redb, no C toolchain). SQLite/Postgres backends are welcome community crates on the same seam.
• M3 — the interoperable QR codec — 🟢 shipped as raio-qr (EMVCo Merchant-Presented Mode). The QR standard mobile-money and bank apps use worldwide, alongside the Pix raio-brcode.
• M4 — a Transport trait + exactly-once delivery — ISO 20022 messaging (the global bank-to-bank standard) + mobile-money adapters behind a sync seam.
• M5 — raio-rail, the HTTP clearing-house + participant nodes.
• M6 — a production SettlementProvider adapter — a card network, an RTGS, PAPSS, or custody.
• M7 — SDK + operator CLI.

Each slots into an existing trait seam — no IO ever goes into raio-core.

Contributing

raio is a foundation by design: the layers above it (HTTP rails, durable storage, real settlement, SDKs) are intentionally left to the community. See CONTRIBUTING.md and docs/src/contributing.md for where things go and the lint gate.

License

Dual-licensed under MIT OR Apache-2.0, at your option. See LICENSE-MIT and LICENSE-APACHE.

Security

See SECURITY.md. Short version: the naive SettlementProvider in the examples is not for production money movement — never deploy it without a real settlement backend.