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
170 lines
10 KiB
Markdown
170 lines
10 KiB
Markdown
<div align="center">
|
|
<img src="assets/brand/logo.png" alt="Ration" width="120" />
|
|
|
|
# Ration
|
|
|
|
[](LICENSE)
|
|
[](services/gateway/go.mod)
|
|
[](services/ledger-core/Cargo.toml)
|
|
</div>
|
|
|
|
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](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](docs/ARCHITECTURE.md) for the full design,
|
|
[docs/AGENT-DESIGN.md](docs/AGENT-DESIGN.md) for the agent/policy design,
|
|
and [docs/AIRWALLEX-SETUP.md](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
|
|
|
|
```bash
|
|
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`](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](https://github.com/caelum0x/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](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](docs/DEMO-SCRIPT.md). The submission writeup is in
|
|
[docs/SUBMISSION.md](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](docs/AGENT-DESIGN.md) for the exact rules it must
|
|
never violate.
|
|
|
|
## License
|
|
|
|
Apache-2.0 — see [LICENSE](LICENSE).
|
|
## More from this account
|
|
|
|
- [Scribase](https://scribase.com) — hosted Postgres, one backend instead of stitching together Supabase + Neon + Clerk + Resend
|
|
- [Toolgate](https://toolgate.scribase.com) — one key for agent tools, pay only for what you call
|
|
- All repos: [git.ereboslab.com/caelum0x](https://git.ereboslab.com/caelum0x)
|