Skip to content

docs: coinage management component design #122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
TorstenStueber wants to merge 184 commits into
base: main
Choose a base branch
from
Draft

docs: coinage management component design #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
184 commits
Select commit Hold shift + click to select a range
61c61f5
docs: add coinage management component design
TorstenStueber May 20, 2026
c7483b7
Merge branch 'main' into add-coinage-design
filvecchiato May 21, 2026
bedc7ae
docs: add coinage layer design and Quint formal spec
TorstenStueber May 22, 2026
6a3dc3d
Merge branch 'add-coinage-design' of github.com:paritytech/truapi int…
TorstenStueber May 22, 2026
4773f77
docs: deepen coinage layer Quint spec — deterministic selection, mult…
TorstenStueber May 24, 2026
1289ee2
coinage-layer: Verus pilot for purse-lifecycle primitives
TorstenStueber May 24, 2026
19166cd
coinage-layer: rename_purse, delete_purse, and coin referential-integ…
TorstenStueber May 25, 2026
8788b76
coinage-layer: add_coin primitive with coin-idx invariant
TorstenStueber May 25, 2026
b86141c
coinage-layer: top_up_purse plus coin lifecycle states
TorstenStueber May 25, 2026
5f65008
docs: consolidate Verus pilot status and proof patterns
TorstenStueber May 25, 2026
e23d0f9
coinage-layer: exec coin Vec backing (stage 5a-c)
TorstenStueber May 25, 2026
7eeb7fe
coinage-layer: purge_coins_of_purse (stage 5d)
TorstenStueber May 25, 2026
faff146
coinage-layer: delete_purse composes purge_coins_of_purse (stage 5e)
TorstenStueber May 25, 2026
90272f7
coinage-layer: real query_purse.spendable via Vec scan (stage 5f)
TorstenStueber May 25, 2026
010c6b5
coinage-layer: select_coin primitive (stage 5g)
TorstenStueber May 25, 2026
f9be6dc
coinage-layer: transfer composite operation
TorstenStueber May 25, 2026
235dcf8
docs: update Verus pilot status and patterns for post-stage-5 state
TorstenStueber May 25, 2026
9f32793
coinage-layer: rebalance composite operation
TorstenStueber May 25, 2026
196fe5c
coinage-layer: recycler entry data extension (stage 6a)
TorstenStueber May 25, 2026
67e49ca
coinage-layer: add_entry primitive (stage 6b)
TorstenStueber May 25, 2026
dc2c026
coinage-layer: purge_entries_of_purse + delete_purse composition (sta…
TorstenStueber May 25, 2026
44bfa82
coinage-layer: set_entry_on_chain transition (stage 6d)
TorstenStueber May 25, 2026
edf1818
coinage-layer: coin Pending state + mark_coin_observed (stage 7a)
TorstenStueber May 25, 2026
dbaf461
coinage-layer: EntryLocal lifecycle (stage 7b)
TorstenStueber May 25, 2026
46513d5
coinage-layer: value-based spendable (stage 7c)
TorstenStueber May 25, 2026
ee65986
coinage-layer: full Error enum from design §10 (stage 7d)
TorstenStueber May 25, 2026
84bb38e
coinage-layer: multi-coin selection for amount (greedy)
TorstenStueber May 25, 2026
4015b1d
coinage-layer: split_coin composite operation
TorstenStueber May 25, 2026
cf86537
coinage-layer: unload_via_entry composite (Tier-3-style)
TorstenStueber May 25, 2026
f0dea74
coinage-layer: reserve_entries bulk allocation
TorstenStueber May 25, 2026
6e066e6
coinage-layer: gap-limit recovery scan (Appendix C)
TorstenStueber May 25, 2026
b65272d
coinage-layer: reverse_pending_spend (cancellation)
TorstenStueber May 25, 2026
ac3563b
coinage-layer: stages 1-4 of remaining mechanical extension
TorstenStueber May 25, 2026
e7e551e
coinage-layer: B7 — operations subsystem
TorstenStueber May 25, 2026
70bda80
coinage-layer: Phase 1a partial — pow2_nat spec defined, exec deferred
TorstenStueber May 25, 2026
ee87738
coinage-layer: Phase 1b — LockedFor(OpHandle) coin state
TorstenStueber May 25, 2026
645976c
coinage-layer: Phase 1c — LocalLockedFor(OpHandle) on entries
TorstenStueber May 25, 2026
cfd45b3
coinage-layer Phase 1d: thread OpHandle through unload_via_entry
TorstenStueber May 25, 2026
0ce64fd
coinage-layer Phase 2a: full OpStatus phase order
TorstenStueber May 25, 2026
d2e6d9a
coinage-layer Phase 2b: cancellation primitives (per-key release)
TorstenStueber May 25, 2026
cca9af8
coinage-layer Phase 3 (part 1): tier-2 split cover + single-coin comp…
TorstenStueber May 25, 2026
aad2412
coinage-layer: list memberKey alongside account/age in CoinRec deferr…
TorstenStueber May 25, 2026
f1cbc8a
coinage-layer Phase 4a: add CoinRec.age field with global allocator
TorstenStueber May 25, 2026
8cc1207
coinage-layer Phase 4b: complete CoinRec/EntryRec fields
TorstenStueber May 25, 2026
e562d35
coinage-layer Phase 5 (part 1): add_entry_with_meta chain-aware alloc…
TorstenStueber May 25, 2026
4996da1
coinage-layer Phase 5 (part 2): add_coin_with_account chain-aware all…
TorstenStueber May 25, 2026
8e31ab4
coinage-layer Phase 5 (part 3): top_up_via_entry — Quint topUp action
TorstenStueber May 25, 2026
acc96a1
coinage-layer Phase 5 (part 4): find_entry_ready selectable-entry wit…
TorstenStueber May 25, 2026
3ad3746
coinage-layer Phase 5 (part 5): pursePending aggregation + query_purs…
TorstenStueber May 25, 2026
4a4dab5
coinage-layer Phase 5 (part 6): sum_ready_in + strict-spendable wiring
TorstenStueber May 25, 2026
7bf5bb2
coinage-layer Phase 5 (part 7): tracked_top_up_via_entry lifecycle wr…
TorstenStueber May 25, 2026
3447e5c
coinage-layer Phase 5 (part 8): tracked_unload_via_entry lifecycle wr…
TorstenStueber May 25, 2026
8305a61
coinage-layer Phase 5 (part 9): tracked_rebalance lifecycle wrapper
TorstenStueber May 25, 2026
64e90ec
coinage-layer Phase 5 (part 10): classify_incoming_payment spec
TorstenStueber May 25, 2026
9123c53
coinage-layer: complete OpKind variants (Export, Import, Maintenance,…
TorstenStueber May 25, 2026
63a878e
coinage-layer Phase 5 (part 11): find_coin_with_account exec lookup
TorstenStueber May 25, 2026
233ea41
coinage-layer Phase 5 (part 12): classify_incoming_payment_exec
TorstenStueber May 25, 2026
7a45a4a
coinage-layer Phase 5 (part 13): export_coin + import_coin
TorstenStueber May 25, 2026
45d8366
coinage-layer Phase 5 (part 14): tracked_export_coin + tracked_import…
TorstenStueber May 25, 2026
287c816
coinage-layer Phase 6 (part 1): anonymity-floor transition wrappers
TorstenStueber May 25, 2026
4e5f735
coinage-layer Phase 6 (part 2): start_op_locking_coin atomic composite
TorstenStueber May 25, 2026
0b54729
coinage-layer Phase 6 (part 3): start_op_locking_entry atomic composite
TorstenStueber May 25, 2026
5766903
coinage-layer Phase 6 (part 4): cancel_op_releasing_{coin,entry}
TorstenStueber May 25, 2026
0a6e619
coinage-layer Phase 6 (part 5): commit_op_consuming_locked_coin
TorstenStueber May 25, 2026
12f364f
coinage-layer Phase 6 (part 6): commit_op_consuming_locked_entry
TorstenStueber May 25, 2026
3425481
coinage-layer Phase 6 (part 7): coin_priority_lt + find_top_priority_…
TorstenStueber May 25, 2026
d36bf23
coinage-layer Phase 6 (part 8): entry priority order + find_top_prior…
TorstenStueber May 25, 2026
ad078f3
coinage-layer Phase 6 (part 9): op-status classification predicates
TorstenStueber May 25, 2026
7a0a2c7
coinage-layer Phase 7 (part 1): bring crate-level doc comment up to date
TorstenStueber May 25, 2026
e66b495
coinage-layer Phase 6 (part 10): tracked_split_coin + contract tighte…
TorstenStueber May 25, 2026
8d48766
coinage-layer Phase 7 (part 2): export Quint design constants
TorstenStueber May 25, 2026
96aed86
coinage-layer Phase 7 (part 3): coin_state + op_status query helpers
TorstenStueber May 25, 2026
0b67921
coinage-layer Phase 7 (part 4): entry_local_state + entry_on_chain_st…
TorstenStueber May 25, 2026
173f9e7
coinage-layer Phase 7 (part 5): coin_count_available + entry_count_se…
TorstenStueber May 25, 2026
ba2a609
coinage-layer: silence unused-variable warnings on release_locked_{co…
TorstenStueber May 25, 2026
427b2e9
coinage-layer task #85: cross-state lock refint invariant — formulati…
TorstenStueber May 25, 2026
9de4245
coinage-layer task #85: extend lock_refint preservation across lock p…
TorstenStueber May 25, 2026
488eccb
coinage-layer task #86 (foundations): Vec length preservation contracts
TorstenStueber May 25, 2026
7ff3698
coinage-layer task #86 (step): release_one_*_lock_for — bulk-sweep bu…
TorstenStueber May 25, 2026
2c254f3
coinage-layer: count_*_locks_in_vec spec functions
TorstenStueber May 25, 2026
3eb45fa
coinage-layer Phase 6 (part 11): coin/entry count_for_handle exec agg…
TorstenStueber May 25, 2026
bb178bf
coinage-layer task #87 (step): find_two_coin_exact_cover
TorstenStueber May 25, 2026
8a43651
coinage-layer Phase 7 (part 6): op_meta query — (kind, purse) lookup
TorstenStueber May 25, 2026
65becf8
coinage-layer Phase 7 (part 7): total_* size accessors
TorstenStueber May 25, 2026
eba50b4
coinage-layer Phase 7 (part 8): coin_record + entry_record whole-reco…
TorstenStueber May 25, 2026
89812ea
coinage-layer Phase 7 (part 9): Result-returning query variants
TorstenStueber May 25, 2026
0dd7f5c
coinage-layer Phase 7 (part 10): query_entry_record + query_op_meta R…
TorstenStueber May 25, 2026
c3d2095
coinage-layer Phase 7 (part 11): has_op_targeting_purse pre-flight guard
TorstenStueber May 25, 2026
77b047f
coinage-layer Phase 7 (part 12): has_in_flight_op_for_purse — narrowe…
TorstenStueber May 25, 2026
a1498ac
coinage-layer task #88 (step): find_coin_entry_exact_cover
TorstenStueber May 25, 2026
56ba4b1
coinage-layer task #84 (step): lemma_pow2_monotone
TorstenStueber May 25, 2026
bbf50bd
coinage-layer task #84 (step): pow2_u64_exec + lemma_pow2_at_30
TorstenStueber May 25, 2026
90ba910
coinage-layer task #84 (step): coin_value_pow2_exec wrapper
TorstenStueber May 25, 2026
acb0ed1
coinage-layer: silence unused-variable warnings on has_*_op_for_purse…
TorstenStueber May 25, 2026
da44ea6
coinage-layer task #84 (step): read_coin_value_real exec consumer
TorstenStueber May 25, 2026
966b9ab
coinage-layer task #84 (step): sum_available_real_in real-value aggre…
TorstenStueber May 25, 2026
a74e7de
coinage-layer task #84 (step): sum_pending_real_in + sum_ready_real_in
TorstenStueber May 25, 2026
8d011d8
coinage-layer task #84 (step): query_purse_real — end-to-end real-val…
TorstenStueber May 25, 2026
5218d97
coinage-layer task #84 (step): read_entry_value_real — entry parallel…
TorstenStueber May 25, 2026
8f0004a
coinage-layer task #84 (step): spendable_when_ready_real — crosses 20…
TorstenStueber May 25, 2026
9fbb6ba
coinage-layer Phase 7 (part 13): coin/entry_count_in_purse total aggr…
TorstenStueber May 25, 2026
c0535c3
coinage-layer Phase 7 (part 14): op_count_in_flight diagnostic
TorstenStueber May 25, 2026
52a84d6
coinage-layer Phase 7 (part 15): check_has_live_coin_in pre-flight guard
TorstenStueber May 25, 2026
17e79a0
coinage-layer Phase 7 (part 16): delete_purse_safe — checks + delete …
TorstenStueber May 25, 2026
610f0e2
coinage-layer: silence unused-variable warning on check_has_live_coin…
TorstenStueber May 25, 2026
1a783de
coinage-layer task #87 (step): sharper find_two_coin_exact_cover None
TorstenStueber May 25, 2026
68e137d
coinage-layer task #90: fee account — State extension fully landed
TorstenStueber May 25, 2026
580b1b9
coinage-layer Phase 7: next_extrinsic_id chain-counter
TorstenStueber May 25, 2026
087297f
coinage-layer task #92: events Vec — the biggest cascade landed
TorstenStueber May 25, 2026
e97bc0a
coinage-layer Phase 6/7: total_in / total_out / paid_ring_membership …
TorstenStueber May 25, 2026
7685592
coinage-layer task #89: unload tokens — final State extension this se…
TorstenStueber May 25, 2026
115b71c
coinage-layer task #91: find_purse_needing_maintenance autonomous tri…
TorstenStueber May 25, 2026
6f2a091
coinage-layer Phase 7: mark_op_*_with_event emitting wrappers
TorstenStueber May 25, 2026
4da243d
coinage-layer Phase 7: start_op_with_event — OperationStarted emitter
TorstenStueber May 25, 2026
b95220c
coinage-layer Phase 7: coin/entry lifecycle event emitters
TorstenStueber May 25, 2026
8fd1ae8
coinage-layer Phase 7: top_up_via_entry / consume_entry event emitters
TorstenStueber May 25, 2026
18fe464
coinage-layer task #93 (foundations): chain_coins + recovery primitives
TorstenStueber May 25, 2026
57c5d7b
coinage-layer task #93: chain_entries mirror state — cascade-only commit
TorstenStueber May 25, 2026
86ad130
coinage-layer task #93: chain_entries mirror + entry-side recovery pr…
TorstenStueber May 25, 2026
f73f6d7
coinage-layer task #93: restore_chain_coin primitive
TorstenStueber May 25, 2026
7e8676b
coinage-layer task #93: restore_chain_entry primitive
TorstenStueber May 25, 2026
1a49b4b
coinage-layer task #93: find_restorable_missing_chain_coin
TorstenStueber May 25, 2026
8a28813
coinage-layer task #93: recover_scan_step composers + entry-side find…
TorstenStueber May 25, 2026
d7e158f
coinage-layer: wire CoinAvailable emit into mark_coin_observed
TorstenStueber May 25, 2026
c038184
coinage-layer: wire CoinSpent emit into mark_coin_spent
TorstenStueber May 25, 2026
b3d2c63
coinage-layer: wire EntryReadinessChanged emit into mark_entry_ready
TorstenStueber May 25, 2026
b35601b
coinage-layer: wire entry-lifecycle event emits into primitives
TorstenStueber May 25, 2026
1880afc
coinage-layer: wire OperationStarted emit into start_op
TorstenStueber May 25, 2026
59f9792
coinage-layer: wire OperationProgress emit into mark_op_submitted
TorstenStueber May 25, 2026
1fc1e58
coinage-layer: wire OperationCompleted emit into mark_op_done + set_o…
TorstenStueber May 25, 2026
6baad8e
coinage-layer task #84 (foundation): MAX_EXPONENT bound now a State i…
TorstenStueber May 26, 2026
89b9166
coinage-layer task #84: flip coin_value to real 2^exp arithmetic
TorstenStueber May 26, 2026
7ccb3e6
coinage-layer task #87: 3-coin exact subset-sum with sharp None
TorstenStueber May 26, 2026
08d76a9
coinage-layer task #87: 4-coin exact subset-sum with sharp None
TorstenStueber May 26, 2026
997934c
coinage-layer task #87: composite find_subset_sum_up_to_4 + SubsetSum…
TorstenStueber May 26, 2026
830af37
coinage-layer task #88: strengthen find_coin_entry_exact_cover to sha…
TorstenStueber May 26, 2026
999b739
coinage-layer task #88: 2-coin+1-entry and 1-coin+2-entry covers
TorstenStueber May 26, 2026
872b4ef
coinage-layer task #88: pure-entry covers (1e, 2e) with sharp None
TorstenStueber May 26, 2026
a35269e
coinage-layer task #88: composite find_tier3_cover_up_to_3 + Tier3Cov…
TorstenStueber May 26, 2026
fcf7275
coinage-layer task #94: Quint→Verus refinement methodology PoC
TorstenStueber May 26, 2026
e328e9d
coinage-layer task #94: extend QuintViewState shadow to full coverage…
TorstenStueber May 26, 2026
40539d4
coinage-layer task #94: refinement step lemmas for entry/op lifecycle
TorstenStueber May 26, 2026
3cb20f1
coinage-layer task #94: accumulator refinements + findings comment
TorstenStueber May 26, 2026
e1b3b6c
coinage-layer task #94: lemma_start_op_refines + extended findings
TorstenStueber May 26, 2026
f862869
coinage-layer task #94: strengthen create_purse + refinement lemma
TorstenStueber May 26, 2026
a34165e
coinage-layer task #94: refine mark_coin_pending_spend + reverse_pend…
TorstenStueber May 26, 2026
1e72193
coinage-layer task #94: refine lock_coin + release_locked_coin + lock…
TorstenStueber May 26, 2026
1bf452f
coinage-layer task #94: refine set_entry_on_chain + set_entry_local +…
TorstenStueber May 26, 2026
b346180
coinage-layer task #94: refine mark_op_in_block + mark_op_finalized +…
TorstenStueber May 26, 2026
fcaf40a
coinage-layer task #94: strengthen and refine alloc_extrinsic_id
TorstenStueber May 26, 2026
e32f571
coinage-layer task #94: refine restore_chain_coin + restore_chain_entry
TorstenStueber May 26, 2026
529ff45
coinage-layer task #94: strengthen and refine add_coin_with_account
TorstenStueber May 26, 2026
773e153
coinage-layer task #94: refine add_entry_with_meta
TorstenStueber May 26, 2026
af2173d
coinage-layer task #94: strengthen and refine top_up_fee_account + de…
TorstenStueber May 26, 2026
e5d137b
coinage-layer task #94: strengthen and refine mint_token + consume_to…
TorstenStueber May 26, 2026
b80ae5d
coinage-layer task #94: strengthen and refine top_up_via_entry
TorstenStueber May 26, 2026
7e2a7f8
coinage-layer task #94: refine unlock_coin + commit_locked_coin + mar…
TorstenStueber May 26, 2026
59080eb
coinage-layer task #94: strengthen and refine add_coin + add_entry (c…
TorstenStueber May 26, 2026
11becd3
coinage-layer task #94: strengthen and refine rename_purse (success/f…
TorstenStueber May 26, 2026
a0ef0bb
coinage-layer task #94: strengthen and refine recover_scan_step_coin/…
TorstenStueber May 26, 2026
ef8b716
coinage-layer task #94: refine release_one_coin/entry_lock_for (some/…
TorstenStueber May 26, 2026
6cb9225
coinage-layer task #94: strengthen and refine cancel_op_releasing_coi…
TorstenStueber May 26, 2026
55e1468
coinage-layer task #94: strengthen and refine start_op_locking_coin/e…
TorstenStueber May 26, 2026
c3b1fe0
coinage-layer task #94: strengthen and refine commit_op_consuming_loc…
TorstenStueber May 26, 2026
825bedb
coinage-layer task #94: strengthen and refine export_coin + import_coin
TorstenStueber May 26, 2026
53fe400
coinage-layer task #94: strengthen and refine delete_purse + delete_p…
TorstenStueber May 26, 2026
598badc
coinage-layer task #94: strengthen and refine unload_via_entry
TorstenStueber May 26, 2026
62a468a
coinage-layer task #94: strengthen and refine rebalance
TorstenStueber May 26, 2026
c652439
coinage-layer task #94: strengthen and refine transfer (some/none) wi…
TorstenStueber May 26, 2026
746babc
coinage-layer task #94: strengthen and refine tracked_export_coin
TorstenStueber May 26, 2026
8cef3ce
coinage-layer task #94: strengthen and refine tracked_import_coin
TorstenStueber May 26, 2026
1810f31
coinage-layer task #94: strengthen and refine tracked_rebalance
TorstenStueber May 26, 2026
58cd30d
coinage-layer task #94: strengthen and refine tracked_transfer (some-…
TorstenStueber May 26, 2026
bdbd8e6
coinage-layer task #94: strengthen and refine tracked_unload_via_entry
TorstenStueber May 26, 2026
a54023f
coinage-layer task #94: refine purge_coins_of_purse + purge_entries_o…
TorstenStueber May 26, 2026
d819a19
coinage-layer task #94: strengthen and refine top_up_purse (bulk-loop…
TorstenStueber May 26, 2026
515d5e1
coinage-layer task #94: strengthen and refine reserve_entries (bulk-l…
TorstenStueber May 26, 2026
60e5edb
coinage-layer task #94: strengthen and refine split_coin + tracked_sp…
TorstenStueber May 26, 2026
de1bd98
coinage-layer task #94: strengthen and refine tracked_top_up_via_entry
TorstenStueber May 26, 2026
5628319
coinage-layer: split refinement layer into refinement.rs
TorstenStueber May 26, 2026
7b2ea32
coinage-layer: split top-level into types.rs / spec_helpers.rs / pow2.rs
TorstenStueber May 26, 2026
6e998f3
coinage-layer: split impl State into 16 category modules (state_*.rs)
TorstenStueber May 26, 2026
19a1d5b
coinage-layer: rewrite lib.rs as module manifest with module map doc
TorstenStueber May 26, 2026
5cd0184
Merge branch 'main' into add-coinage-design
filvecchiato May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 106 additions & 2 deletions Cargo.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

745 changes: 745 additions & 0 deletions docs/design/coinage-layer.md
View file
Open in desktop

Large diffs are not rendered by default.

Loading
Loading