Repository navigation
id: design: conversion engine — linked transfer pairs, rate authorisation, liquidity accounts #2063
Description
Source: the TigerBeetle investigation (on #2040): conversions are NOT native — cross-ledger transfers are forbidden, so a conversion is an application-composed pair of atomically linked same-ledger transfers through a liquidity provider's two accounts, at a rate the application computes; the link between legs must be stamped into user_data_128 ourselves. Design: rate authorisation objects (issuer-set, per pair — e.g. ABC to 123 at 0.8123), who may act as liquidity provider, failure/rollback semantics mid-pair, and rate expiry. Feeds #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 conversion engine as application-composed, atomically linked same-ledger transfer pairs through a liquidity provider's two accounts.
- The doc covers: rate authorisation objects (issuer-set, per pair, with expiry), who may act as liquidity provider, failure/rollback semantics mid-pair, and how the leg link is stamped into
user_data_128. - Anything buildable that falls out of the design is filed as follow-up issues linked here.
Metadata
Metadata
Assignees
Labels
Package/app: id (pkgs/ or apps/ in this repo)Medium: expected under 1 day of workIntake review done: acceptance criteria, links, and normalized labels addedImportant and time-sensitiveOrdinary priority (the default)Filed directly by a humanTriaged and routed (see agent note)Queue packet kind: verify, reproduce, and route this item
Activity
developing-today commentedon Oct 29, 2026
CODE-984
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 (conversions are not native to TigerBeetle); feeds #2043; depends on the control-plane design #2062 for account/liquidity-provider representation.
Notes: design deliverable in the ID program batch; the linked-pair + user_data_128 stamping approach is already pinned by the source investigation, so the open work is authorisation and failure semantics.
Risks: mid-pair failure semantics are the hard part — a half-completed conversion must never be silently inconsistent; the doc should name the recovery invariant.
Suggested approach: Workhorse design pass after/alongside #2062; rate-expiry and rollback cases enumerated explicitly.
— 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 3365 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.
24 remaining items
dezren39 commentedon Nov 2, 2026
agent-note:v1 — task 5239 (Lane C worker) results for the #2289 conversion-executor PoC, requested by this issue's §4 demo set:
PR #3873 merged 2026-11-02T01:46Z (merge commit fb0824a). PoC in pkgs/id/src/currency_poc/: write-ahead intent, linked batch (T1 / optional fee / T3, user_data_128 = conversion_id on all legs), recovery scanner, step-0 single-replica TigerBeetle harness (binary pinned 0.17.9).
Test results (laptop, cargo test --lib currency_poc, against current main after merge-conflict resolution): 13 passed, 0 failed, 1 ignored (the live-cluster smoke test). Cases: posted conversion findable by user_data_128; atomic leg failure moves nothing; crash after submission recovers without double-posting; crash before submission resubmits the same IDs; insufficient LP inventory fails pre-flight; plus 6 regression tests for the PR's Codex findings (all 8 P2 findings fixed and replied to on PR #3873).
Honest framing, per #2289: this is a PoC, not the permanent feature. The scenario suite runs against the TigerBeetle-semantics in-memory backend; the one remaining gap is a LedgerBackend binding over the official Rust client so the same scenarios run against the live harness cluster — enqueued as a follow-up queue task on #2289.
dezren39 commentedon Nov 2, 2026
agent-note:v1 — correction to the results note above (task 5239): the client-binding follow-on could not be enqueued as a separate queue task (the v1 fix dedupe key for #2289 returns task 5239 itself). It is tracked on #2289 and in the code backlog as a FOLLOW-ON entry instead. Everything else in the results note stands.
Merge pull request #3844 from developing-today/design/id-2063
developing-today commentedon Nov 3, 2026
agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 7283 (triage, queued, priority 50) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03
dezren39 commentedon Nov 3, 2026
🤖 Agent note · results linked
Results for issue #2289 (conversion-executor PoC, live TigerBeetle binding)
PR #5072 merged (d99399c): the currency_poc
LedgerBackendnow runs over the official TigerBeetle Rust client against the live single-replica harness cluster (pinned 0.17.9). Live scenario suite 8/8 serial (posted conversion legs findable byuser_data_128; idempotent re-execution posts once), in-memory suite 44/44 (atomic failure, crash-recovery reconciliation). Codex review of the final head completed with no findings after five dispositioned findings across earlier heads. Full results note is on issue #2289, which closes on its acceptance.dezren39 commentedon Nov 3, 2026
agent-note:v1
event: done — closing with evidence
task: 7283 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 02cafe76-eafd-4d0b-aaa6-2b7a737d68dc)
Triage verdict: delivered; closing
Fresh verification on 2026-11-03 (GitHub + current
origin/main9380bf6d7):doc/2026-11-01_design_id2063.mdis on main, landed by PR design(id): #2063 conversion engine linked pairs #3844 (MERGED2026-11-02T15:49:53Z), and was linked from this issue. The doc designs the conversion engine as application-composed, atomically linked same-ledger transfer pairs through an LP's two accounts.user_data_128 = conversion_idleg linkage with receipt metadata kept graph-side.Follow-on state now: #2289 CLOSED (PoC merged in PR #3873; live TigerBeetle binding merged in PR #5072). #3800 CLOSED (rate-authorisation + revoke types/fold, PR #3888). #3801 OPEN/blocked and #3802 OPEN/parked — both track their own work and do not belong to this design issue. #2290 remains OPEN with
user/escalatedfor the platform-emergency-revocation question (recommended: issuer-only graph revocation + platform local suspension); that ruling does not block this design.Nothing in #2063 remains unbuilt or undecided at this issue's scope. Closing.
dezren39 commentedon Nov 3, 2026
agent-note:v1
event: picked_up
task: 7283 (repo-health-code-pilot; worker repo-worker-code; OpenChamber scheduled lane 02cafe76-eafd-4d0b-aaa6-2b7a737d68dc)
state: claimed for current-state verification; design PR #3844 and follow-on state were checked before completing and closing issue #2063 in the same short pass.
Merge pull request #5777 from developing-today/queue/9603-5536-conver…