idempotency_key is UNIQUE across the whole ledger_entries table, not scoped to (tenant_id, idempotency_key). apply_entry_checked's replay lookup returned the matched entry as Applied regardless of whether its tenant_id matched the caller's requested tenant_id, pairing the OTHER tenant's entry (reference/memo/amount) with THIS tenant's own unaffected balance — reporting success for a write that never actually happened, with no error anywhere. Every real caller today derives idempotency_key from a CSPRNG/UUIDv4 id (idgen.New, Uuid::new_v4), so a genuine collision across tenants is cryptographically negligible in practice — but the lookup itself never enforced that, which matters for a platform whose hackathon track is explicitly multi-tenant isolation. Add LedgerError::IdempotencyKeyTenantMismatch and fail loudly instead of silently mixing tenants. Verified: cargo build --release clean, cargo check --release --tests clean (new test type-checks), cargo fmt --check clean on touched files, cargo clippy --release exit 0, and a full cargo test --release --test idempotency run (including the new replaying_another_tenants_idempotency_key_is_rejected_not_silently_applied regression test) completed with exit code 0 on this box despite heavy concurrent sibling-agent load intermittently hanging repeat attempts at process exec (unrelated amfid/syspolicyd contention, not a code issue — confirmed via `sample` showing the test binary stuck at dyld_start, and the same stall reproducing on the already-built, previously-working main ledger-core binary too). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
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:
- A proto-regeneration collision that silently shadowed checked-in generated code.
ledger-coreand every client disagreeing on which env var carried the listen address — the stack would never actually connect with default config.- The one that mattered:
MarkDepositReceivedupdated deposit status but never credited the ledger, so every tenant's balance was permanently stuck at0. 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.
