Repository navigation
id: design: currency control plane — registry, account factory, gateway #2062
Description
Source: the TigerBeetle investigation (on #2040), 'what we'd still have to build'. TigerBeetle ledgers are bare u32s — no names, symbols, scale, or issuer metadata — and the database has NO authentication. Design the control plane we must build anyway: the currency registry (name/symbol/scale/issuer), the account factory mapping ID identities to TigerBeetle accounts, and the gateway service that performs ID-signature checks and issuance permissions before any ledger write. Feeds the currencies v1 synthesis (#2043).
Program: Drew's 2026-10-28 directive (full text: hatch-personal memory/topics/id-program-2026-10-28.md). Parent epic: #2056.
Working pattern: parallel investigations, then the named synthesis issue merges them into a full design. Route guidance: Workhorse by default; Specialist/Summit for synthesis and ramification-heavy work. A result that says "done" is not the endpoint — the orchestrator reviews it and may commission another round. Deliverables: a markdown design/investigation doc (mermaid/SVG diagrams welcome) linked from this issue, plus follow-up issues for anything buildable. Build a proof of concept where the design calls for one, but do NOT build the permanent feature on top of an unreviewed PoC.
Acceptance criteria
- A markdown design doc is linked from this issue designing the currency control plane: currency registry (name/symbol/scale/issuer), account factory mapping ID identities to TigerBeetle accounts, and the gateway service.
- The doc shows how the gateway performs ID-signature checks and issuance-permission checks before any ledger write (TigerBeetle itself has no authentication and ledgers carry no metadata).
- Anything buildable that falls out of the design is filed as follow-up issues linked here.
Activity
developing-today commentedon Oct 29, 2026
CODE-983
dezren39 commentedon Oct 29, 2026
Parent epic: #2056 — ID platform expansion (2026-10-28 directive). Filed as batch 2 from PREPARED-ACTIONS.md.
dezren39 commentedon Oct 29, 2026
Intake review
Related: parent epic #2056; source investigation #2040 ('what we'd still have to build'); feeds the currencies v1 synthesis #2043; sibling designs #2063 (conversion engine) and #2066 (hosted-edition boundary) build on this one.
Notes: design deliverable in the ID program batch; this is the foundation piece of the currency track — registry + factory + gateway are prerequisites for the sibling designs becoming buildable.
Risks: the gateway is the sole auth boundary in front of an unauthenticated ledger — the design must state the threat model, not just the API.
Suggested approach: Workhorse design pass; sequence before #2063's buildable follow-ups.
— Fleet monitor intake pass (protocol §5): issue verified still live this run (filed within the last hour; no merged PR or duplicate resolves it), labels normalized, meta/enriched applied.
dezren39 commentedon Oct 29, 2026
Top priority — ID program wave-1. Drew directed this be picked up in the next runs (2026-10-29): enqueued directly as triage task 3364 in repo-health-code-pilot at queue priority 20 (only breakage-class work at priority 10 outranks it). Wave-1 is the ungated investigations and designs; syntheses and PoCs stay gated on their named inputs. Investigation route: Workhorse.
1 remaining item
dezren39 commentedon Oct 29, 2026
agent-note:v1 — picked up (queue task 3364, worker repo-worker-code, openchamber scheduled lane)
repo-health:v1:triage:developing-today/code:issue:2062(triage, priority 20, ID program wave-1)claimedwritten (originopenchamber-scheduled-lane)queue/3364-2062-currency-control-plane(worktree~/git/fleet/3364-2062-currency-control-plane, base origin/main@5a34fa70)design(id): currency control plane — registry, account factory, gatew…
design(id): currency control plane — registry, account factory, gatew…
dezren39 commentedon Oct 29, 2026
agent-note:v1 — design delivered (queue task 3364, worker repo-worker-code, openchamber scheduled lane)
Deliverable:
doc/2026-10-29T12-42-21Z_design_currency_control_plane/— PR #2315 (docs-only).The control plane TigerBeetle requires and does not provide, in three parts:
ledgeru32: name/symbol/scale/issuer/supply-policy/status, a monotonic never-recycled allocator, and a documented range split. The signed graph object is the canonical record; the registry row is a rebuildable derived index.(ledger, kind, owner, salt), so creation is idempotent and stateless; issuer (unconstrained), liquidity, fee, burn and constrained holder accounts; a reserved transfer-codetable.It reuses existing machinery instead of inventing a second identity system: the
directory_auth.rsSignedrequest envelope (id-request-v1canonical message, 5-minute window,ReplayGuard,verify_strict),chain.rs's domain-tagged canonical CBOR, and the account/device key split. Issuance authority binds to the account key, sodevice.revokecan withdraw a lost device without moving the currency.Follow-ups filed (buildable, linked here): #2317 registry + allocator · #2318 account factory · #2319 gateway envelope · #2320 reconciliation + supply audit · #2321 PoC (explicitly a PoC — not the permanent service, review before building on it).
Gate: this satisfies the gate on the gated currency PoC #2298 ("do not start until the #2062 control-plane design fixes the gateway's registry/account-factory shape"). It complements #2066's centralised-exception boundary doc (PR #2297) without duplicating it.
Open questions carried in §9, the notable one being the idempotency-ID scheme vs TigerBeetle's monotonic-ID guidance (resolved in #2319).
Acceptance criteria: doc linked here ✔ · gateway ID-signature and issuance-permission checks designed ✔ · buildable follow-ups filed and linked ✔.
feat(id): issuer key rotation and compromise recovery — protocol core (…