Repository navigation
id: design: graph token object formats + snapshot anchoring spec (from #2041) #2251
Description
From the #2041 investigation (token issuance in the ID graph)
Investigation #2041 (queue task 3352, result posted on that issue 2026-10-29) designed the graph-side token model on top of the #2040 TigerBeetle findings: currency identity = (issuer ID, definition hash); signed definition/issuance/transfer/burn/rate-offer/conversion-receipt/snapshot objects; two bindings (graph-native folds vs ledger-anchored via TigerBeetle user_data_128 cross-links); snapshot anchoring; the app-facing function surface (define_currency, issue, award, pay, accept_payment, convert, snapshot). This issue is the design spec that makes those shapes concrete. Spec only — no permanent feature is built on the unreviewed #2041 investigation (program rule, epic #2056).
Spec to produce (doc in pkgs/id/doc/ per repo convention, linked from this issue)
- Wire formats for the seven object types from id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041, as extensions of the existing signed-event envelope (
pkgs/id/src/chain.rs), including the currency-ID derivation and exact rational rate representation. - Fold rules for graph-native balances/supply: ordering, overdraft and fork treatment (consistent with
event_storeapplied/void semantics), and what a counting view (id: investigate: trust/visibility model — servers accept all signed objects; views count only allowed writers #2030) needs to refuse over-cap issuance. - Snapshot format + anchoring join: fields, balance-root construction, cadence options, and the mechanical reconciliation between graph objects and TigerBeetle transfers via
user_data_128(per id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040). - App-function API surface: signatures and error semantics for
define_currency/issue/award/pay/balance/supply/accept_payment/convert/snapshot, identical across both bindings, with the binding-specific verification steps spelled out. - Conversion execution checklist: offer-version citation, frontier freshness check, rounding/spread leg treatment, receipt emission — matching id: investigate: TigerBeetle — multi-currency ledgers, conversions, per-coin vs balance model, 3-node cluster topology #2040 §2's linked-pair pattern.
Acceptance criteria
- Spec doc landed in
pkgs/id/doc/and linked from this issue, covering all five points - Each id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041 abuse case (1–7) traced to a spec mechanism or an explicitly accepted residual risk
- Questions the spec cannot settle (snapshot signer/cadence for the developing-today deployment, issuer key rotation) are listed for the id: design: ID currencies v1 #2043 synthesis, not decided silently
- Implementation work, if any, is filed as its own issue(s) — this issue delivers the spec only
Program: ID platform expansion, epic #2056. Parent investigation: #2041. Related: #2040 (TigerBeetle), #2042 (tokens for real services — still open), #2043 (currencies v1 design, gated on #2042), #2030, #2037.
Activity
developing-today commentedon Oct 29, 2026
CODE-1116
dezren39 commentedon Oct 30, 2026
Agent note — picked up (queue task 3406, openchamber scheduled lane)
Claimed 2026-10-30 ~11:51Z for revalidation. Fresh GitHub check: issue OPEN (priority/high), no PR references it, no live branch. This is a 120m spec-writing task (spec doc to land in
pkgs/id/doc/), beyond this ~30m lane — parking untouched (no branch, no worktree, no edits).dezren39 commentedon Oct 30, 2026
Agent note — parked untouched (needs a full-budget shift)
doc/content underpkgs/id/on origin/main. Deliverable is a landed spec doc (wire formats, fold rules, API signatures for the id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041 token model) plus id: investigate: token issuance in the ID graph — per-ID issuance, issuer snapshots, authorized conversion rates #2041 abuse-case tracing and open questions routed to id: design: ID currencies v1 #2043 synthesis — a single design-writing shift, not a short-lane slice.queue/queued+status/needs-triage, so this pass sets the parked end-state directly (queue/parked+status/parked+work/assigned, queued/needs-triage removed).ghhosts.yml token was stale in this session; notes posted with transient GH_TOKEN from vault keygithub-cli.hosts-yml.36 remaining items
dezren39 commentedon Oct 31, 2026
🤖 Agent note · parked
Connection closed by UNKNOWN port 65535;tailscale statuscannot finish connecting). Spec edits must run on the laptop worktree per the fleet runbook, so the fix could not be applied this shift.a8c05171raised exactly 2 P2s, both genuine, amendments drafted and recorded in the task checkpoint: (1) taker-signed authorization — §1.6 gains ataker_intentfield, §5 step 3 gains a taker-authorization requirement, §2 fold refuses anchored receipts with no valid taker intent; (2) atomic cap check-and-reserve — §5 step 6 makes the steps 2–3 cap check and the reservation one atomic offer-scoped operation (reservation write = linearization point). All round 1–4 threads are resolved; only CI check on the PR is CodeRabbit (NEUTRAL). After pushing the fix: reply + resolve both threads, park on Codex re-review, merge when clean.a8c05171id: address Codex round-5 P2s on the graph token spec (#2251)
dezren39 commentedon Oct 31, 2026
🤖 Agent note · parked
e1feebd97on PR id: graph token object formats + snapshot anchoring spec (#2251) #2741 (verified as PR head via gh) implements the checkpoint draft verbatim — F1 taker-signed intent (§1.6taker_intentrow, §5 step 3 Taker authorization, §2 fold-input rule) and F2 atomic cap check-and-reserve (§5 step 6 + step 2 cross-ref). Both round-5 threads (PRRT…LOjz, PRRT…LOj1) replied to with the fix and resolved;@codex reviewrequested for round 6.e1feebd97. If clean: merge PR id: graph token object formats + snapshot anchoring spec (#2251) #2741 (doc-only; CodeRabbit is the only check) and complete task 3954. If new findings: fix per the same reply/resolve/re-review loop.chatgpt-codex-connector commentedon Oct 31, 2026
To use Codex here, create an environment for this repo.
dezren39 commentedon Oct 31, 2026
🤖 Agent note · picked up (resume)
e1feebd97completed clean ("Didn't find any major issues", codex-review-state has_unresolved_findings=false, zero unresolved review threads — verified fresh via gh). pkgs/id/doc placement verified:pkgs/id/docis a tracked symlink to../../doc, so the spec atdoc/2026-10-30T13-25-00Z_design_graph_token_formats_snapshot_anchoring.mdis reachable at the required path. Only check is CodeRabbit (skipping/neutral, docs-only PR). Proceeding to merge.Merge pull request #2741 from developing-today/queue/3406-2251-graph-…
dezren39 commentedon Oct 31, 2026
🤖 Agent note · done
83edec8a9ab0d0e2d58c7d602f6360f9489a0d57, heade1feebd97). Codex rounds 1-6 all dispositioned: rounds 1-5 findings fixed in spec commits and threads replied+resolved; round-6 review of the final head completed clean ("Didn't find any major issues", no unresolved findings/threads). Spec covers all five points, abuse-case trace, and id: design: ID currencies v1 #2043-routed open questions; placement atpkgs/id/doc/holds via the trackedpkgs/id/doc -> ../../docsymlink. Docs only, no behaviour change. Closing this design issue — implementation, if pursued, is filed as its own issue(s) per the acceptance criteria.