ration/README.md
caelum0x 79a264da6a
Some checks failed
CI / Proto lint (push) Failing after 31s
CI / C (wal, ASan+UBSan) (push) Failing after 40s
CI / Rust (ledger-core) (push) Failing after 37s
CI / Discover Go modules (push) Failing after 31s
CI / Go (${{ matrix.module }}) (push) Has been skipped
Docker build / Discover service Dockerfiles (push) Failing after 29s
Docker build / Build ${{ matrix.service }} (push) Has been skipped
docs: cross-link Scribase/Toolgate ecosystem (Rithub discoverability pass, 2026-11-16)
2026-11-16 14:35:26 +00:00

10 KiB

Ration

Ration

License Go Rust

Agentic multi-tenant spend controller for the Airwallex Agentic Banking Hackathon — Starter Kit 5: Platform Spend Controller (Multi-Tenant Platforms track).

Issue customer cards and ration bridge funding when deposits arrive late.

No web dashboard. This is a systems project: a Rust ledger core backed by a hand-rolled C write-ahead log, a Go gateway that owns the Airwallex integration, a Go agent loop that makes the actual rationing decisions (policy rules + an LLM for judgment calls), dedicated Go services for tenant-scoped auth, tenant onboarding, card issuance/lifecycle, and signed-webhook ingestion, an independent append-only audit mirror, and a terminal UI for judges to watch it work live.

Engineering standard: this is built to the bar of production fintech infrastructure, not hackathon scaffolding — real crash-safety (see the WAL recovery tests), a hard-rule money-safety invariant the LLM can never override, and a scale-out roadmap (service decomposition, observability, infra-as-code, formal verification, fuzzing/chaos testing — see docs/SCALE-EXPANSION.md) aimed at unicorn-scale production use, not a weekend demo.

Architecture

                    ┌─────────────────────┐
                    │   tui / cli (Go)     │  terminal dashboard + demo driver
                    └──────────┬───────────┘
                               │ gRPC (operator/API-key credential attached)
                    ┌──────────▼───────────┐       ┌────────────────────┐
  Airwallex API <──►│   gateway (Go)        │──────►│  agent (Go)         │
  (mock or live)    │  tenant-auth BFF,     │ gRPC  │  policy + LLM loop  │
                    │  fronts every service  │◄──────│  tool-calling        │
                    └──────────┬───────────┘       └────────────────────┘
                               │ gRPC
         ┌─────────────┬───────┼───────┬──────────────┬──────────────┐
         ▼             ▼       ▼       ▼              ▼              ▼
   ┌──────────┐ ┌─────────────┐ ┌───────────┐ ┌──────────────────┐ ┌───────────┐
   │   auth    │ │  tenant-    │ │   card-   │ │     webhook-      │ │ audit-log │
   │  API keys/│ │  registry   │ │  issuance │ │     ingestion     │ │ append-   │
   │  operator │ │  tenant CRUD│ │  issue/   │ │  signed Airwallex │ │ only      │
   │  JWTs     │ │             │ │  close/   │ │  deposit webhooks │ │ mirror    │
   │           │ │             │ │  adjust   │ │                   │ │           │
   └──────────┘ └─────────────┘ └─────┬─────┘ └─────────┬─────────┘ └───────────┘
                                       │ gRPC            │ gRPC
                               ┌───────▼────────────────▼───────┐
                               │       ledger-core (Rust)         │  authoritative
                               │  double-entry, reserve-floor      │  balances,
                               │  enforcement, deposit tracking    │  deposits
                               └──────────────────┬────────────────┘
                                                   │ FFI
                                        ┌──────────▼───────────┐
                                        │  wal (C)              │  crash-safe
                                        │  write-ahead log       │  append log +
                                        └───────────────────────┘  recovery

audit-log is written to directly by ledger-core (a best-effort, never-blocking mirror of every ledger entry and agent decision — see services/ledger-core/src/audit_mirror.rs), not routed through gateway.

See docs/ARCHITECTURE.md for the full design, docs/AGENT-DESIGN.md for the agent/policy design, and docs/AIRWALLEX-SETUP.md for sandbox access status.

Services

Service Language Role
services/wal C Crash-safe write-ahead log: append, fsync, recover.
services/ledger-core Rust Double-entry ledger, reserve-floor enforcement, deposit tracking, AES-256-GCM encryption at rest. gRPC server over the C WAL.
services/auth Go Mints/verifies operator JWTs and per-tenant API keys; apikey issue/revoke/list lifecycle.
services/tenant-registry Go Tenant onboarding/CRUD (tenant create/list), operator-credential-gated.
services/card-issuance Go Card issue/get/list/adjust-limit/close against Airwallex (mock or live), file-persisted card metadata, reserve-floor-safe limit changes.
services/webhook-ingestion Go Verifies signed Airwallex deposit webhooks (HMAC + timestamp/clock-skew check), forwards to ledger-core.
services/audit-log Go Independent, append-only mirror of every money-moving decision — best-effort, never blocks the original operation.
services/gateway Go Tenant-auth BFF: fronts every service above, re-validates reserve-floor/bridge rules independently of the agent.
services/agent Go Agentic loop: watches late deposits, decides card issuance / bridge rationing, calls an LLM for non-deterministic judgment calls, executes via gateway.
services/tui Go (Bubble Tea) Terminal dashboard: tenants, deposits, cards (with in-TUI issue/adjust-limit forms), live agent activity feed.
services/cli Go Operator CLI: seed demo tenants, simulate deposits, manage tenants/API keys/cards, force late-deposit scenarios for judging.
sdk/go/ration, sdk/rust/ration-client Go, Rust Official client SDKs for external platform customers, with API-key/bearer-token auth.
proto/ Protobuf Wire contracts shared by every service.

Quickstart

make proto          # generate Go stubs from proto/
make build           # build all services
make run-demo         # starts wal-backed ledger-core, auth, tenant-registry,
                     # card-issuance (mock Airwallex), webhook-ingestion,
                     # gateway, and agent, then seeds 3 tenants
./bin/tui              # watch it live in a second terminal

NEAR Hackathon (Nov 1-14, 2026)

This submission anchors Ration's append-only, hash-chained audit trail to a NEAR smart contract we wrote and deployed ourselves, for the AI Security & Defense track at nearhackathon.com. See docs/near-hackathon/HACKATHON.md for the submission writeup and run-it-yourself steps.

Same person, two separate entries: the owner of this repo is also submitting Cred402 (Agent Economy track) to this same NEAR Hackathon — different repo, different NEAR Testnet contract, no shared code path.

Airwallex mode

AIRWALLEX_MODE=mock (default) runs entirely against an in-process fake that mirrors the real Issuing/Global Accounts/webhook contracts byte-for-byte so flipping to AIRWALLEX_MODE=live with real sandbox credentials is a one-line env change, not a rewrite. Sandbox platform access is pending organizer approval — see docs/AIRWALLEX-SETUP.md.

What integration actually found

Six services were built independently against a pinned proto/architecture spec, then integrated. Integration is where real bugs show up — compile errors are the easy part. Three were found and fixed, not papered over:

  1. A proto-regeneration collision that silently shadowed checked-in generated code.
  2. ledger-core and every client disagreeing on which env var carried the listen address — the stack would never actually connect with default config.
  3. The one that mattered: MarkDepositReceived updated deposit status but never credited the ledger, so every tenant's balance was permanently stuck at 0. Reserve-floor headroom was always negative, so the bridge-funding policy could only ever decline — the entire agentic rationing feature, the actual point of this submission, could never produce a real grant. Fixed at the ledger level with an idempotent mark-and-credit in a single WAL frame, covered by new tests.

The full, reproducible demo run (seed → simulate a late deposit → agent grants a partial bridge with a computed rationale → a second request correctly declines once the 24h velocity cap engages) is documented in docs/DEMO-SCRIPT.md. The submission writeup is in docs/SUBMISSION.md.

Contributing

Each service is its own module with its own tests — run the relevant one (go test ./... in a Go service, cargo test in ledger-core, make test in services/wal) before opening a PR. Money-path changes (anything that touches ledger-core::ledger or services/gateway/internal/bridge) need a test that exercises the reserve-floor invariant — see docs/AGENT-DESIGN.md for the exact rules it must never violate.

License

Apache-2.0 — see LICENSE.

More from this account