caelum0x f5b6c6a75e feat(near-anchor): add scheduled auto-anchoring (near-anchor schedule)
Audit-log's NEAR Testnet anchoring was manual-only (an operator running
`near-anchor commit` by hand). Add a `schedule` subcommand that repeats
the decide-then-anchor flow on a fixed interval
(RATION_NEAR_ANCHOR_INTERVAL, default 5m) until SIGINT/SIGTERM:

- Batching is structural, not buffered: anchoring the current hash-chain
  tip already cryptographically commits every record appended since the
  last anchor, so one tick = one anchor tx no matter how many new
  records landed.
- Idempotent / skips when nothing new: decideAnchor compares the local
  tip's sequence against the contract's own get_latest_anchor() (a free
  view call) before ever signing a transaction, so a tick with no new
  records costs nothing and two concurrent anchorers can't double-commit
  (the contract's own sequence guard is the backstop either way).
- Survives restarts with zero checkpoint state: every tick re-reads the
  real local file and the real on-chain state fresh, so a crash
  mid-tick is safe — the next tick just re-decides from the chain
  itself.

Verified for real against NEAR Testnet (dedicated demo account
ration-demo-23bd92e5.testnet, never the primary submission account):
found a real pre-existing backlog of 3 un-anchored local records
(sequence 2 on-chain vs. sequence 5 local), ran the scheduler, and
confirmed exactly one batched anchor tx closed the gap
(tx HP5VcN88FbDzTw3VBD7fgaftgzhoM5f8fc6Yibx5w9qM, sequence 6), with a
second tick correctly skipping. A follow-up run (tx
6w6FUTWTSKGhnmJWqzYGuNBrZrkFW6Ux4g32wqEP9SDq, sequence 8) re-confirmed
the same batch-then-skip behavior after fixing a race the first attempt
surfaced (back-to-back ticks faster than RPC view-propagation lag can
see a stale on-chain state — safe, since no corruption/double-anchor
occurred, but real and worth a comment; irrelevant at any real
multi-minute interval). All on-chain state independently re-verified via
raw JSON-RPC against rpc.testnet.fastnear.com outside the Go tooling.

On branch feat/auto-anchoring — not merged to main, since the NEAR
hackathon entry is submitted from main and must not change before then.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-11-10 17:13:37 +03:00

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

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.

Description
Agentic multi-tenant spend controller for the Airwallex hackathon — Rust/C/Go, no web frontend
Readme Apache-2.0 13 MiB
Languages
Go 67.5%
Rust 20.3%
HCL 4.6%
C 3.3%
Shell 2.4%
Other 1.9%