escrow_machines 0.7.2-aarch64-linux
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/CHANGELOG.md +88 -0
- data/LICENSE.txt +21 -0
- data/README.md +254 -0
- data/ext/escrow_machines_native/core/CHANGELOG.md +59 -0
- data/ext/escrow_machines_native/core/README.md +64 -0
- data/ext/escrow_machines_native/extconf.rb +2 -0
- data/lib/escrow_machines/version.rb +4 -0
- data/lib/escrow_machines.rb +60 -0
- data/lib/escrow_machines_native/escrow_machines_native.so +0 -0
- data/sig/escrow_machines.rbs +112 -0
- metadata +64 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: '0277184e829ca0e999251b466a7815f25c7de70c3efa466492513f39989829be'
|
|
4
|
+
data.tar.gz: 818776eb2f70dc1106cae4371d35f27c99f8c53ec18f0eee658280030ff80b47
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 7d8c3f036099854be93661e05162e30b4ff34dd66d9d9e5974babc4dd24117c0b2851dd5d2150609454bea003627b7d37e6523d68789a87a3dfd4e0863dacbca
|
|
7
|
+
data.tar.gz: db99428c4afd5d18ba90b8ef67eaf2d7188b0371fe26d84f80161c7e3b61e2445d6144970c9452bf9367774683a99f030088862525b2e62f863fd18466325c09
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.7.2](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.7.1...escrow_machines/v0.7.2) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* fix wrapped classes at load so building a value runs no Ruby ([3e0238a](https://github.com/seuros/escrow_machines/commit/3e0238a43954f3fe90537ac42df5c48cd77868c5))
|
|
9
|
+
|
|
10
|
+
## [0.7.1](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.7.0...escrow_machines/v0.7.1) (2026-11-16)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### Bug Fixes
|
|
14
|
+
|
|
15
|
+
* refuse merges that disagree on a transfer's cumulative total ([cbcafa5](https://github.com/seuros/escrow_machines/commit/cbcafa54cbb866a9f5c425dbcbbad90b09694f6e))
|
|
16
|
+
|
|
17
|
+
## [0.7.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.6.0...escrow_machines/v0.7.0) (2026-11-16)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
### ⚠ BREAKING CHANGES
|
|
21
|
+
|
|
22
|
+
* fold FrameError into Refusal, new 0xE6 frame of plain tallies
|
|
23
|
+
|
|
24
|
+
### Features
|
|
25
|
+
|
|
26
|
+
* fold FrameError into Refusal, new 0xE6 frame of plain tallies ([04c0d32](https://github.com/seuros/escrow_machines/commit/04c0d32b6be44d1fdff8a3cec23cd39fbbf54233))
|
|
27
|
+
|
|
28
|
+
## [0.6.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.5.0...escrow_machines/v0.6.0) (2026-11-14)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### ⚠ BREAKING CHANGES
|
|
32
|
+
|
|
33
|
+
* escrow partner refusals name the class received
|
|
34
|
+
|
|
35
|
+
### Features
|
|
36
|
+
|
|
37
|
+
* escrow partner refusals name the class received ([0efa5da](https://github.com/seuros/escrow_machines/commit/0efa5dae455c8a2b571983024753116c57f3c89f))
|
|
38
|
+
|
|
39
|
+
## [0.5.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.4.0...escrow_machines/v0.5.0) (2026-11-14)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### ⚠ BREAKING CHANGES
|
|
43
|
+
|
|
44
|
+
* adopt matryona 0.3: decode takes exactly a String, names_only refusals
|
|
45
|
+
|
|
46
|
+
### Features
|
|
47
|
+
|
|
48
|
+
* adopt matryona 0.3: decode takes exactly a String, names_only refusals ([73f1174](https://github.com/seuros/escrow_machines/commit/73f1174ac829f6b089626409483be444de4ae562))
|
|
49
|
+
|
|
50
|
+
## [0.4.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.3.0...escrow_machines/v0.4.0) (2026-11-14)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
### ⚠ BREAKING CHANGES
|
|
54
|
+
|
|
55
|
+
* adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged
|
|
56
|
+
|
|
57
|
+
### Features
|
|
58
|
+
|
|
59
|
+
* adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged ([78045e6](https://github.com/seuros/escrow_machines/commit/78045e6f0722a55c2804920207ae197a1e472ac9))
|
|
60
|
+
|
|
61
|
+
## [0.3.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.2.0...escrow_machines/v0.3.0) (2026-11-14)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
### ⚠ BREAKING CHANGES
|
|
65
|
+
|
|
66
|
+
* private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound
|
|
67
|
+
|
|
68
|
+
### Features
|
|
69
|
+
|
|
70
|
+
* private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound ([223b8cb](https://github.com/seuros/escrow_machines/commit/223b8cb5dcb34e5cb615c8f7667b17bb7eac8e16))
|
|
71
|
+
|
|
72
|
+
## [0.2.0](https://github.com/seuros/escrow_machines/compare/escrow_machines/v0.1.1...escrow_machines/v0.2.0) (2026-11-13)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
### ⚠ BREAKING CHANGES
|
|
76
|
+
|
|
77
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. replica/dump/load are local/encode/decode; transfer answers Transfer::Applied or Transfer::Replayed.
|
|
78
|
+
|
|
79
|
+
### Features
|
|
80
|
+
|
|
81
|
+
* Ruby uses the core's names and positional arguments, Transfer variants as values ([8d83f20](https://github.com/seuros/escrow_machines/commit/8d83f20731ca496ebfb251480f9895e7726b3367))
|
|
82
|
+
|
|
83
|
+
## [0.1.1](https://github.com/seuros/escrow_machines/compare/escrow_machines-v0.1.0...escrow_machines/v0.1.1) (2026-11-12)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
### Features
|
|
87
|
+
|
|
88
|
+
* initial extraction ([d0edc22](https://github.com/seuros/escrow_machines/commit/d0edc223cc69da6ca9b35d07940545a439464356))
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Abdelkader Boudih
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
# EscrowMachines
|
|
2
|
+
|
|
3
|
+
> You cannot sell the seat twice if you only ever sell the seats you are holding. 🏦
|
|
4
|
+
|
|
5
|
+
A rights ledger for Ruby replicas that can't always talk to each other. A fixed set of replicas shares a fixed supply: seats, credits, stock, quota. Each replica holds part of it and spends only from its own part, with no round trip to anyone. Rights move between replicas by transfer, never by wishful thinking. Merge the replicas in any order, any number of times, and they agree. The total spent never exceeds the supply, partitioned or not.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
gem 'escrow_machines'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
# 100 seats, three regions. Every region builds the same allotment.
|
|
15
|
+
paris = EscrowMachines::Escrow.new(0, [60, 30, 10])
|
|
16
|
+
tokyo = EscrowMachines::Escrow.new(2, [60, 30, 10])
|
|
17
|
+
|
|
18
|
+
tokyo.spend(8) # => 2, seats left in Tokyo
|
|
19
|
+
tokyo.spend(5) # => :insufficient. Paris has 60. Tokyo has 2.
|
|
20
|
+
|
|
21
|
+
receipt = paris.transfer(2, 1, 20).receipt
|
|
22
|
+
save(paris.encode) # persist before the receipt leaves the building
|
|
23
|
+
tokyo.accept(receipt) # => :applied
|
|
24
|
+
tokyo.accept(receipt) # => :replayed, the relay stuttered
|
|
25
|
+
tokyo.spend(5) # => 17
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
One escrow per replica. `Escrow.new` takes what the core's constructor takes, in its order: `local`, the index of this replica, and `allotted`, every replica's starting rights. `transfer` takes `to`, `id` and `amount`. Amounts, replica indexes and transfer ids are Integers. No clock, no network, no storage: you bring those.
|
|
29
|
+
|
|
30
|
+
## A Message to the Resistance
|
|
31
|
+
|
|
32
|
+
So you have a hundred seats and three regions, and you put the count in a replicated counter because the conference talk said CRDTs never conflict. They don't. Each region decremented happily through a forty-second partition, the counters merged without a single conflict, and the merged value was minus eleven. Eleven people are now standing in a lobby holding a confirmation email.
|
|
33
|
+
|
|
34
|
+
A PN-counter converges. Converging on a negative number is still converging. What it can't do is say no, because saying no requires knowing something about the other replicas, and the entire point was not asking them.
|
|
35
|
+
|
|
36
|
+
The other fix is asking them: a lock, a leader, a quorum on every sale. Now Tokyo can't sell a seat while the link to Paris is down, which is the outage you bought replicas to avoid.
|
|
37
|
+
|
|
38
|
+
There's a third option from 1986. Split the hundred up front. Each replica owns a share and sells from its share alone. A replica that runs low asks a neighbour for some of theirs, and the neighbour gives away only what it still holds. Nobody ever needs a global answer, because nobody ever spends a right they aren't holding. That's escrow, and the bookkeeping for it is this gem.
|
|
39
|
+
|
|
40
|
+
## Chapter 1: Stardate 2026.316, the AMS O'Neil
|
|
41
|
+
|
|
42
|
+
> **AMS O'Neil**, NCC-4233, *O'Neil*-class treasury escort.
|
|
43
|
+
> The hold carries what was counted aboard. Nothing more is for sale.
|
|
44
|
+
|
|
45
|
+
The escort doesn't make money. It moves a counted amount between stations and refuses to let anyone spend a chit that isn't physically in the hold. Each station's strongbox has one keyholder. A station can hand chits to another station and log the handover; it cannot reach into someone else's box, and it cannot print.
|
|
46
|
+
|
|
47
|
+
On a bridge somewhere, a cadet volunteers:
|
|
48
|
+
|
|
49
|
+
```ruby
|
|
50
|
+
def sell(region, seats)
|
|
51
|
+
counter = PNCounter.for(:seats)
|
|
52
|
+
return :sold_out if counter.value < seats
|
|
53
|
+
counter.decrement(region, seats)
|
|
54
|
+
end
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
"That," says the escort's purser, "checks a number three stations are changing, and then changes it. You've sold the same eleven seats in three time zones."
|
|
58
|
+
|
|
59
|
+
## The Flight Plan
|
|
60
|
+
|
|
61
|
+
Every right in the supply is in exactly one place at any moment:
|
|
62
|
+
|
|
63
|
+
```mermaid
|
|
64
|
+
stateDiagram-v2
|
|
65
|
+
[*] --> held: allotted at construction
|
|
66
|
+
held --> spent: spend, by the holder only
|
|
67
|
+
spent --> held: refund, by the replica that spent it
|
|
68
|
+
held --> in_flight: transfer, giver deducts at once
|
|
69
|
+
in_flight --> held: accept or merge, receiver credits
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Held plus spent plus in flight always equals the supply. Nothing mints, nothing leaks, and an in-flight right belongs to nobody until its receipt lands.
|
|
73
|
+
|
|
74
|
+
And the afternoon Tokyo ran low while the relay was repeating itself:
|
|
75
|
+
|
|
76
|
+
```mermaid
|
|
77
|
+
sequenceDiagram
|
|
78
|
+
participant T as Tokyo
|
|
79
|
+
participant P as Paris
|
|
80
|
+
participant D as Paris disk
|
|
81
|
+
|
|
82
|
+
T->>P: need 20, transfer id 1
|
|
83
|
+
P->>P: transfer(2, 1, 20)
|
|
84
|
+
P->>D: encode
|
|
85
|
+
P-->>T: Receipt (lost in the relay)
|
|
86
|
+
|
|
87
|
+
T->>P: need 20, transfer id 1 (retry)
|
|
88
|
+
P->>P: transfer(2, 1, 20)
|
|
89
|
+
Note over P: same id, same Receipt, nothing moves twice
|
|
90
|
+
P-->>T: Receipt
|
|
91
|
+
P-->>T: Receipt (the relay finds the first one)
|
|
92
|
+
|
|
93
|
+
T->>T: accept → :applied
|
|
94
|
+
T->>T: accept → :replayed
|
|
95
|
+
Note over T: 20 seats, once.
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## How the Escrow Works
|
|
99
|
+
|
|
100
|
+
### Spend
|
|
101
|
+
|
|
102
|
+
```ruby
|
|
103
|
+
escrow = EscrowMachines::Escrow.new(0, [10, 5])
|
|
104
|
+
|
|
105
|
+
escrow.spend(7) # => 3, what this replica has left
|
|
106
|
+
escrow.spend(4) # => :insufficient
|
|
107
|
+
escrow.available # => 3
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`spend` looks at one number: what this replica holds. The other replica's 5 are not part of the question. A refused spend changes nothing.
|
|
111
|
+
|
|
112
|
+
### Refund
|
|
113
|
+
|
|
114
|
+
```ruby
|
|
115
|
+
escrow.refund(2) # => 5, back in this replica's hold
|
|
116
|
+
escrow.refund(6) # => :exceeds_spent
|
|
117
|
+
escrow.outstanding(0) # => 5, spent and not refunded
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
A refund returns rights this replica spent. It can't return more than that, because that would be printing. Refund where you spent: the rights come back to the replica that let them go.
|
|
121
|
+
|
|
122
|
+
### Transfer
|
|
123
|
+
|
|
124
|
+
```ruby
|
|
125
|
+
left = EscrowMachines::Escrow.new(0, [10, 0])
|
|
126
|
+
right = EscrowMachines::Escrow.new(1, [10, 0])
|
|
127
|
+
|
|
128
|
+
transfer = left.transfer(1, 1, 4)
|
|
129
|
+
transfer # => #<data EscrowMachines::Transfer::Applied receipt=...>
|
|
130
|
+
receipt = transfer.receipt
|
|
131
|
+
receipt # => #<data EscrowMachines::Receipt from=0, to=1, id=1, amount=4, total=4>
|
|
132
|
+
left.available # => 6, deducted now
|
|
133
|
+
|
|
134
|
+
again = left.transfer(1, 1, 4)
|
|
135
|
+
again.class # => EscrowMachines::Transfer::Replayed. Nothing moved again.
|
|
136
|
+
again.receipt == receipt # => true, the same Receipt
|
|
137
|
+
left.transfer(1, 1, 9) # => :id_conflict
|
|
138
|
+
left.transfer(1, 0, 4) # => :stale_id
|
|
139
|
+
left.transfer(1, 2, 7) # => :insufficient
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`transfer` answers the core's `Transfer`: a `Transfer::Applied` when the rights moved now, a `Transfer::Replayed` when this id had already moved them. Both carry the `receipt` to deliver, so `transfer.receipt` works either way. You choose the id. It has to go up for each destination, and a retry reuses the one it's retrying. The latest id is answered `Transfer::Replayed` with its original receipt for as long as it stays the latest. Anything older is `:stale_id`: refused, not repeated.
|
|
143
|
+
|
|
144
|
+
```ruby
|
|
145
|
+
left.last_transfer(0, 1) # => #<data EscrowMachines::Mark id=1, amount=4>
|
|
146
|
+
left.last_transfer(1, 0) # => nil, nothing has gone that way
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Accept
|
|
150
|
+
|
|
151
|
+
```ruby
|
|
152
|
+
right.accept(receipt) # => :applied
|
|
153
|
+
right.accept(receipt) # => :replayed
|
|
154
|
+
right.available # => 4
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
A receipt says how much `from` has granted `to` in total, not "add four". Deliver it twice, deliver it after a newer one, deliver it to a bystander: the answer is the same grant. A receipt that contradicts what the replica already knows is `:malformed`, `:id_conflict`, or `:forged`, and changes nothing.
|
|
158
|
+
|
|
159
|
+
### Merge
|
|
160
|
+
|
|
161
|
+
```ruby
|
|
162
|
+
right.spend(1)
|
|
163
|
+
left.merge(right) # => :merged
|
|
164
|
+
left.balance(1) # => 3, what left now believes right holds
|
|
165
|
+
left.available # => 6, still only its own
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`merge` folds in everything another replica knows. Any order, any number of times, any gossip topology. It never makes someone else's rights spendable here. `balance` for another replica is an estimate, and it can be negative when you've seen rights leave a replica before you've seen them arrive there.
|
|
169
|
+
|
|
170
|
+
### Persist, and what happens when you didn't
|
|
171
|
+
|
|
172
|
+
```ruby
|
|
173
|
+
frame = left.encode # binary String, Escrow::ENCODED_LEN bytes
|
|
174
|
+
left = EscrowMachines::Escrow.decode(frame) # RangeError if it isn't a sane frame
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
A replica that restarts from an old frame has forgotten spends it already made. The first peer that remembers them proves it:
|
|
178
|
+
|
|
179
|
+
```ruby
|
|
180
|
+
stale = EscrowMachines::Escrow.decode(old_frame)
|
|
181
|
+
stale.merge(right) # => :diverged, and stale is untouched
|
|
182
|
+
stale.recover(right) # => :recovered, adopts what right saw of it
|
|
183
|
+
# => :overdrawn if the two histories can't both be true
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`recover` is a decision, which is why it isn't `merge`. It restores what some peer witnessed. A spend that never left the lost replica is gone, and no method can find it.
|
|
187
|
+
|
|
188
|
+
### Capacity
|
|
189
|
+
|
|
190
|
+
```ruby
|
|
191
|
+
EscrowMachines::CAPACITY # => 8
|
|
192
|
+
EscrowMachines::Escrow.new(0, [1] * 9) # RangeError
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Up to eight replicas, fixed when you build the escrow. The set doesn't grow, shrink, or rename itself afterwards.
|
|
196
|
+
|
|
197
|
+
### What each verb can answer
|
|
198
|
+
|
|
199
|
+
Escrow takes no clock, so no answer records one: every honoured answer, repeats included, depends only on the state and the arguments.
|
|
200
|
+
|
|
201
|
+
| Verb | Honoured | Refusals |
|
|
202
|
+
| --- | --- | --- |
|
|
203
|
+
| `spend` | the Integer left | `:zero_amount`, `:insufficient`, `:overflow` |
|
|
204
|
+
| `refund` | the Integer now held | `:zero_amount`, `:exceeds_spent`, `:overflow` |
|
|
205
|
+
| `transfer` | a `Transfer::Applied`, or the repeat `Transfer::Replayed` | `:zero_amount`, `:unknown_replica`, `:self_transfer`, `:stale_id`, `:id_conflict`, `:insufficient`, `:overflow` |
|
|
206
|
+
| `accept` | `:applied`, or the repeat `:replayed` | `:unknown_replica`, `:malformed`, `:id_conflict`, `:forged`, `:overflow` |
|
|
207
|
+
| `merge` | `:merged` | `:config_mismatch`, `:diverged`, `:overflow` |
|
|
208
|
+
| `recover` | `:recovered` | `:config_mismatch`, `:diverged`, `:overdrawn`, `:overflow` |
|
|
209
|
+
|
|
210
|
+
`Receipt`, `Mark`, `Transfer::Applied` and `Transfer::Replayed` are frozen `Data` values with the fields of the core types they are named after. Method names are the core's: `local`, `replicas`, `supply`, `allotted`, `available`, `balance`, `spent`, `refunded`, `outstanding`, `granted`, `last_transfer`, `encode`, `decode`. The core's `Refusal` has sixteen variants, each with its own symbol and no catch-all. Thirteen come back from calls; the three frame refusals (`:truncated`, `:wrong_structure`, `:wrong_shape`), like a `:malformed` frame, appear only in `decode`'s `RangeError` message, `"the frame is refused: wrong_shape"`. Four of them carry a number in the core (`Insufficient { available }`, `ExceedsSpent { outstanding }`, `StaleId { latest }`, `IdConflict { amount }`); a refusal in Ruby is a bare symbol, and the same numbers are what the readers answer: `available` for `:insufficient`, `outstanding(local)` for `:exceeds_spent`, `last_transfer(local, to).id` for `:stale_id` and `last_transfer(from, to).amount` for `:id_conflict`.
|
|
211
|
+
|
|
212
|
+
`Receipt`, `Mark` and the `Transfer` values are checked by the core when they are built, by hand or by the escrow alike: a receipt naming one replica on both ends, moving zero, or moving more than its `total` raises `RangeError`, as does a `Mark` of zero; a non-Integer field raises `TypeError`, and a `Transfer` value holding anything but a `Receipt` raises `TypeError`. So `accept` never sees a receipt that contradicts itself (the core's `Receipt` has private fields for the same reason), and `:self_transfer` is `transfer`'s answer alone. The four classes are sealed: subclassing one raises `TypeError` and `allocate` is undefined. Sealing stops accidents, not reflection (a named subclass's constant is bound before the raise, `Marshal.load` skips `initialize`), so the binding is the authority: a receipt it reads must be exactly a `Receipt` and is checked by `Receipt::new` again, raising `TypeError` or `RangeError` before the core sees it.
|
|
213
|
+
|
|
214
|
+
## The Rules of the Escort
|
|
215
|
+
|
|
216
|
+
- **Everything is an Integer** in `0..2**64-1`: amounts, replica indexes, ids. Floats, nil and strings raise `TypeError`. Out of range raises `RangeError`. So does an allotment that adds up past `2**64-1`, a frame `decode` cannot read, and a `Receipt` or `Mark` the core would not build. Nothing raises `ArgumentError` except Ruby itself, for a wrong number of arguments.
|
|
217
|
+
- **A raise changes nothing.** Every argument is checked before the core is called, and every class was resolved once when the extension loaded, so a call that raises left the escrow untouched.
|
|
218
|
+
- **Same allotment everywhere.** Every replica is built from the same `allotted` array. Views built from different ones answer `:config_mismatch` and don't merge.
|
|
219
|
+
- **The binding never loses work.** Every argument is read before the core is called. `transfer` builds its answer from a copy of the escrow kept only once the `Transfer` exists: a build that raises moves no rights, one that freezes the escrow raises `FrozenError`, and one that changes the escrow meanwhile (a redefined `new` calling back in) raises `RuntimeError`; in each case the outer transfer is not applied.
|
|
220
|
+
- **Refusals don't raise.** `:insufficient`, `:exceeds_spent`, `:zero_amount`, `:unknown_replica`, `:self_transfer`, `:stale_id`, `:id_conflict`, `:malformed`, `:forged`, `:config_mismatch`, `:diverged`, `:overdrawn` and `:overflow` are answers. A refused call leaves the escrow exactly as it was.
|
|
221
|
+
- **Counters are lifetime totals.** Grants and spends only count up. A pair that has moved `2**64-1` rights between them over the years answers `:overflow` instead of wrapping.
|
|
222
|
+
- **Frozen means frozen.** `freeze` the escrow and `spend`, `refund`, `transfer`, `accept`, `merge` and `recover` raise `FrozenError`, before any argument is read.
|
|
223
|
+
|
|
224
|
+
## What You Think You're Doing vs Reality
|
|
225
|
+
|
|
226
|
+
### You Think: "CRDTs can't conflict, so my counter is safe."
|
|
227
|
+
### Reality: It merged cleanly to minus eleven.
|
|
228
|
+
|
|
229
|
+
Convergence means everyone ends up with the same number. It doesn't mean the number is one you can live with. An invariant like "never below zero" is a promise about the sum of decisions made by replicas that can't see each other, and the only way to keep it without asking is to hand each replica a budget in advance. That's the difference between a counter and an escrow: one records what happened, the other can refuse.
|
|
230
|
+
|
|
231
|
+
### You Think: "The transfer timed out, so I'll send it again with a new id."
|
|
232
|
+
### Reality: Now two transfers happened.
|
|
233
|
+
|
|
234
|
+
The id is the transfer's name. A retry is the same transfer, so it has the same name. A new id is a new transfer, and Paris will cheerfully send another twenty.
|
|
235
|
+
|
|
236
|
+
## What's Yours
|
|
237
|
+
|
|
238
|
+
This is an early release of a policy core. The API will change. It decides; it doesn't run anything.
|
|
239
|
+
|
|
240
|
+
**Durable replica identity is yours.** `encode` the escrow and get it onto disk before you act on a successful `spend`, `refund` or `transfer`, and before a receipt leaves the process. A replica that comes back from an older frame under the same index can spend the same rights twice, and `:diverged` only tells you after a peer notices. Never run two live processes as the same replica.
|
|
241
|
+
|
|
242
|
+
**Transfer ids are yours.** Per destination, strictly increasing, reused on retry. Only the latest id for a pair replays; keep your retries ahead of your next request.
|
|
243
|
+
|
|
244
|
+
**Transport is yours.** Receipts and frames are values. How they cross the wire, who asks whom for rights, and how much to ask for are your call. Rights in flight are spendable by nobody until the receipt or a merge arrives, so a lost receipt strands rights until gossip catches up.
|
|
245
|
+
|
|
246
|
+
**Authenticity is yours.** `accept` and `merge` catch contradictions, not liars. A fabricated receipt from a replica that never granted anything will be believed. Don't accept frames from anyone you wouldn't hand the strongbox key.
|
|
247
|
+
|
|
248
|
+
**Membership is yours.** The replica set is fixed. Retiring a replica means transferring its rights out first and never using the index again.
|
|
249
|
+
|
|
250
|
+
## License
|
|
251
|
+
|
|
252
|
+
MIT License. See [LICENSE.txt](LICENSE.txt) for details.
|
|
253
|
+
|
|
254
|
+
**Remember: the counter will merge either way. The question is whether it ever said no.**
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.6.1](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.6.0...escrow-machines-v0.6.1) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* refuse merges that disagree on a transfer's cumulative total ([cbcafa5](https://github.com/seuros/escrow_machines/commit/cbcafa54cbb866a9f5c425dbcbbad90b09694f6e))
|
|
9
|
+
|
|
10
|
+
## [0.6.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.5.0...escrow-machines-v0.6.0) (2026-11-16)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### ⚠ BREAKING CHANGES
|
|
14
|
+
|
|
15
|
+
* fold FrameError into Refusal, new 0xE6 frame of plain tallies
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* fold FrameError into Refusal, new 0xE6 frame of plain tallies ([04c0d32](https://github.com/seuros/escrow_machines/commit/04c0d32b6be44d1fdff8a3cec23cd39fbbf54233))
|
|
20
|
+
|
|
21
|
+
## [0.5.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.4.0...escrow-machines-v0.5.0) (2026-11-14)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### ⚠ BREAKING CHANGES
|
|
25
|
+
|
|
26
|
+
* adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged
|
|
27
|
+
|
|
28
|
+
### Features
|
|
29
|
+
|
|
30
|
+
* adopt matryona-machines 0.2: exact Receipt fields, exact-class Escrow partners, honoured replays proven unchanged ([78045e6](https://github.com/seuros/escrow_machines/commit/78045e6f0722a55c2804920207ae197a1e472ac9))
|
|
31
|
+
|
|
32
|
+
## [0.4.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.3.0...escrow-machines-v0.4.0) (2026-11-14)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
### ⚠ BREAKING CHANGES
|
|
36
|
+
|
|
37
|
+
* private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound
|
|
38
|
+
|
|
39
|
+
### Features
|
|
40
|
+
|
|
41
|
+
* private Mark/Receipt fields, sealed validated values, clone-then-keep transfer, compile-time frame bound ([223b8cb](https://github.com/seuros/escrow_machines/commit/223b8cb5dcb34e5cb615c8f7667b17bb7eac8e16))
|
|
42
|
+
|
|
43
|
+
## [0.3.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.2.0...escrow-machines-v0.3.0) (2026-11-13)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
### ⚠ BREAKING CHANGES
|
|
47
|
+
|
|
48
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats, Ruby mirrors the core. No compatibility aliases. replica/dump/load are local/encode/decode; transfer answers Transfer::Applied or Transfer::Replayed.
|
|
49
|
+
|
|
50
|
+
### Features
|
|
51
|
+
|
|
52
|
+
* Ruby uses the core's names and positional arguments, Transfer variants as values ([8d83f20](https://github.com/seuros/escrow_machines/commit/8d83f20731ca496ebfb251480f9895e7726b3367))
|
|
53
|
+
|
|
54
|
+
## [0.2.0](https://github.com/seuros/escrow_machines/compare/escrow-machines-v0.1.0...escrow-machines-v0.2.0) (2026-11-12)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
### Features
|
|
58
|
+
|
|
59
|
+
* initial extraction ([d0edc22](https://github.com/seuros/escrow_machines/commit/d0edc223cc69da6ca9b35d07940545a439464356))
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# escrow-machines
|
|
2
|
+
|
|
3
|
+
> **AMS O'Neil**, NCC-4233, *O'Neil*-class treasury escort.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: move counted rights between stations and never spend what is not in the hold.
|
|
6
|
+
|
|
7
|
+
Allocation-free `no_std` bounded-counter CRDT. A fixed set of up to `N` replicas
|
|
8
|
+
shares a fixed supply of rights. `Escrow<N>` is one replica's view: a matrix of
|
|
9
|
+
cumulative grants between replicas plus per-replica spent and refunded counters.
|
|
10
|
+
`spend` and `transfer` are checked against the rights the local replica holds,
|
|
11
|
+
so the total spent cannot exceed the supply under any partition. `refund`
|
|
12
|
+
returns only what the local replica itself spent. Nothing is minted after
|
|
13
|
+
construction.
|
|
14
|
+
|
|
15
|
+
`merge` is a cell-wise join: commutative, associative, idempotent. `transfer`
|
|
16
|
+
takes a caller-chosen id, strictly increasing per `(from, to)` pair; repeating
|
|
17
|
+
the latest id returns the original `Receipt` and moves nothing. Receipts carry
|
|
18
|
+
the cumulative grant, so `accept` is idempotent and order-insensitive. Every
|
|
19
|
+
refusal is a `Refusal` value and leaves the state untouched; counters refuse at
|
|
20
|
+
`u64::MAX` instead of wrapping.
|
|
21
|
+
|
|
22
|
+
`Escrow` implements the `merge-machines` `Merge` trait. Replica ids are
|
|
23
|
+
dense, `0..replicas` with `replicas <= N`, so every per-replica table is a
|
|
24
|
+
plain `[T; N]` read through a position that is below `N` by construction: a
|
|
25
|
+
lookup cannot miss. The counters are such tables, one `u64` cell per replica
|
|
26
|
+
joined by `max`, so raising one never needs a free slot and its only refusal
|
|
27
|
+
is `Overflow`. Frame refusals are `Refusal` variants like every other
|
|
28
|
+
(`Truncated`, `WrongStructure`, `WrongShape`, `Malformed`); there is no second
|
|
29
|
+
error type. The frame stores each counter as `N` 64-bit fields; it leads with
|
|
30
|
+
`0xE6`, and a frame from before (`0xE5`, which embedded `merge-machines`
|
|
31
|
+
counter frames) is `WrongStructure`.
|
|
32
|
+
|
|
33
|
+
The escrow adds what a PN-counter lacks: writes are restricted to the local
|
|
34
|
+
replica's own cells and bounded by its balance.
|
|
35
|
+
|
|
36
|
+
Contracts the caller owns:
|
|
37
|
+
|
|
38
|
+
- **Durable replica identity.** Persist `encode`'s fixed-length frame before
|
|
39
|
+
acting on a successful call. A replica restarted from an older frame can
|
|
40
|
+
double-spend; `merge` answers `Diverged` once a peer proves it, and `recover`
|
|
41
|
+
adopts the peer's record explicitly (`Overdrawn` if the histories cannot both
|
|
42
|
+
hold). Spends no peer saw are unrecoverable.
|
|
43
|
+
- **Transfer ids.** Monotonic per destination, reused on retry. Only the latest
|
|
44
|
+
id per pair replays; older ids answer `StaleId`.
|
|
45
|
+
- **Authenticity and transport.** Contradictory receipts and frames are refused;
|
|
46
|
+
fabricated but self-consistent ones are not detectable here.
|
|
47
|
+
- **Membership.** The replica set and allotment are fixed at construction and
|
|
48
|
+
must be identical on every replica.
|
|
49
|
+
|
|
50
|
+
`Receipt::new` and `Mark::new` build only values some call could produce
|
|
51
|
+
(`None` for a receipt naming one replica twice, moving zero or more than its
|
|
52
|
+
`total`, and for a mark of zero). Their fields are private, read through
|
|
53
|
+
`from()`, `to()`, `id()`, `amount()`, `total()`, so no receipt contradicts
|
|
54
|
+
itself and `accept` needs no check for one: its `Malformed` is a receipt that
|
|
55
|
+
contradicts the grants already seen.
|
|
56
|
+
|
|
57
|
+
No call takes a clock, so no answer records one.
|
|
58
|
+
|
|
59
|
+
The Ruby gem mirrors `Receipt` and `Mark` as `Data` values of the same names,
|
|
60
|
+
validated through those constructors, and `Transfer` as one `Data` per
|
|
61
|
+
variant, `Transfer::Applied` and `Transfer::Replayed`, each carrying the
|
|
62
|
+
`receipt`.
|
|
63
|
+
|
|
64
|
+
Pre-1.0: breaking changes land in minor versions. No clock, I/O, hashing, or randomness.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'escrow_machines/version'
|
|
4
|
+
|
|
5
|
+
module EscrowMachines
|
|
6
|
+
# Proof of one transfer. `total` is everything `from` has ever granted `to`,
|
|
7
|
+
# so delivering a receipt twice, late, or out of order changes nothing.
|
|
8
|
+
# Like the core's `Receipt::new`, it cannot be built contradicting itself:
|
|
9
|
+
# `from == to`, `amount` zero or `amount` above `total` raise RangeError,
|
|
10
|
+
# a non-Integer TypeError.
|
|
11
|
+
Receipt = Data.define(:from, :to, :id, :amount, :total) do
|
|
12
|
+
def initialize(from:, to:, id:, amount:, total:)
|
|
13
|
+
from, to, id, amount, total = EscrowMachines.__send__(:__receipt, from, to, id, amount, total)
|
|
14
|
+
super
|
|
15
|
+
end
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# What a transfer request did: one of two values, each carrying the
|
|
19
|
+
# `receipt` to deliver, which must be a Receipt (TypeError otherwise).
|
|
20
|
+
module Transfer
|
|
21
|
+
# The rights moved now.
|
|
22
|
+
Applied = Data.define(:receipt) do
|
|
23
|
+
def initialize(receipt:)
|
|
24
|
+
super(receipt: EscrowMachines.__send__(:__transfer, receipt))
|
|
25
|
+
end
|
|
26
|
+
end
|
|
27
|
+
# This id already moved these rights; nothing moved again.
|
|
28
|
+
Replayed = Data.define(:receipt) do
|
|
29
|
+
def initialize(receipt:)
|
|
30
|
+
super(receipt: EscrowMachines.__send__(:__transfer, receipt))
|
|
31
|
+
end
|
|
32
|
+
end
|
|
33
|
+
end
|
|
34
|
+
|
|
35
|
+
# The latest transfer one replica made to another. Like the core's
|
|
36
|
+
# `Mark::new`, an `amount` of zero raises RangeError.
|
|
37
|
+
Mark = Data.define(:id, :amount) do
|
|
38
|
+
def initialize(id:, amount:)
|
|
39
|
+
id, amount = EscrowMachines.__send__(:__mark, id, amount)
|
|
40
|
+
super
|
|
41
|
+
end
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
# Native is required: no algorithm fallback. It validates and builds the Data
|
|
46
|
+
# values above, so they must exist first.
|
|
47
|
+
require 'escrow_machines_native/escrow_machines_native'
|
|
48
|
+
|
|
49
|
+
module EscrowMachines
|
|
50
|
+
private_class_method :__receipt, :__mark, :__transfer
|
|
51
|
+
|
|
52
|
+
# The values are final. `initialize` is where each validates, and a subclass
|
|
53
|
+
# could override it, or `allocate` build an instance that never ran it:
|
|
54
|
+
# subclassing raises TypeError (as subclassing Class does) and `allocate`
|
|
55
|
+
# is gone. `new`, keywords, `with` and `dup` all still run the check.
|
|
56
|
+
[Receipt, Transfer::Applied, Transfer::Replayed, Mark].each do |value|
|
|
57
|
+
value.singleton_class.undef_method(:allocate)
|
|
58
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
59
|
+
end
|
|
60
|
+
end
|
|
Binary file
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
module EscrowMachines
|
|
2
|
+
VERSION: String
|
|
3
|
+
CAPACITY: Integer
|
|
4
|
+
|
|
5
|
+
# Every refusal symbol. A refused call changed nothing. Each method below
|
|
6
|
+
# lists exactly the ones it can answer. No answer records a clock: escrow
|
|
7
|
+
# takes none. Four refusals carry a number in the core and are bare symbols
|
|
8
|
+
# here; read the number instead: :insufficient from `available`,
|
|
9
|
+
# :exceeds_spent from `outstanding(local)`, :stale_id from
|
|
10
|
+
# `last_transfer(local, to).id`, :id_conflict from `last_transfer(from,
|
|
11
|
+
# to).amount`.
|
|
12
|
+
type refusal = :zero_amount | :insufficient | :exceeds_spent | :unknown_replica | :self_transfer
|
|
13
|
+
| :stale_id | :id_conflict | :malformed | :forged | :config_mismatch | :diverged
|
|
14
|
+
| :overdrawn | :overflow
|
|
15
|
+
|
|
16
|
+
# Validated like the core's `Receipt::new`: RangeError when `from == to`,
|
|
17
|
+
# `amount` is zero or `amount` exceeds `total`, or a field is outside
|
|
18
|
+
# 0..2**64-1; TypeError for a non-Integer.
|
|
19
|
+
class Receipt < Data
|
|
20
|
+
attr_reader from: Integer
|
|
21
|
+
attr_reader to: Integer
|
|
22
|
+
attr_reader id: Integer
|
|
23
|
+
attr_reader amount: Integer
|
|
24
|
+
attr_reader total: Integer
|
|
25
|
+
def self.new: (Integer from, Integer to, Integer id, Integer amount, Integer total) -> Receipt
|
|
26
|
+
| (from: Integer, to: Integer, id: Integer, amount: Integer, total: Integer) -> Receipt
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# Mirrors the core's `Transfer`: one `Data` per variant, each carrying the
|
|
30
|
+
# receipt to deliver. TypeError unless `receipt` is a Receipt.
|
|
31
|
+
module Transfer
|
|
32
|
+
class Applied < Data
|
|
33
|
+
attr_reader receipt: Receipt
|
|
34
|
+
def self.new: (Receipt receipt) -> Applied
|
|
35
|
+
| (receipt: Receipt) -> Applied
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
class Replayed < Data
|
|
39
|
+
attr_reader receipt: Receipt
|
|
40
|
+
def self.new: (Receipt receipt) -> Replayed
|
|
41
|
+
| (receipt: Receipt) -> Replayed
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
type transfer = Transfer::Applied | Transfer::Replayed
|
|
46
|
+
|
|
47
|
+
# Mirrors the core's `Mark`, validated like `Mark::new`: RangeError for an
|
|
48
|
+
# `amount` of zero or a field outside 0..2**64-1, TypeError for a
|
|
49
|
+
# non-Integer.
|
|
50
|
+
class Mark < Data
|
|
51
|
+
attr_reader id: Integer
|
|
52
|
+
attr_reader amount: Integer
|
|
53
|
+
def self.new: (Integer id, Integer amount) -> Mark
|
|
54
|
+
| (id: Integer, amount: Integer) -> Mark
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
class Escrow
|
|
58
|
+
# Bytes of an `encode` frame.
|
|
59
|
+
ENCODED_LEN: Integer
|
|
60
|
+
|
|
61
|
+
# The arguments of the core's `Escrow::new`, in order: the local replica
|
|
62
|
+
# and every replica's starting rights. Raises RangeError when the core
|
|
63
|
+
# answers `ConfigError`: no replica, more than CAPACITY, a `local` outside
|
|
64
|
+
# `allotted`, or a supply past 2**64-1.
|
|
65
|
+
def self.new: (Integer local, Array[Integer] allotted) -> Escrow
|
|
66
|
+
# Raises RangeError for a frame the core cannot decode, TypeError for a
|
|
67
|
+
# non-String.
|
|
68
|
+
def self.decode: (String bytes) -> Escrow
|
|
69
|
+
def encode: () -> String
|
|
70
|
+
# Honoured: the rights this replica has left. Refused: :zero_amount,
|
|
71
|
+
# :insufficient, :overflow.
|
|
72
|
+
def spend: (Integer amount) -> (Integer | :zero_amount | :insufficient | :overflow)
|
|
73
|
+
# Honoured: the rights this replica now holds. Refused: :zero_amount,
|
|
74
|
+
# :exceeds_spent, :overflow.
|
|
75
|
+
def refund: (Integer amount) -> (Integer | :zero_amount | :exceeds_spent | :overflow)
|
|
76
|
+
# Honoured: a Transfer::Applied, or the repeat Transfer::Replayed. Refused:
|
|
77
|
+
# :zero_amount, :unknown_replica, :self_transfer, :stale_id, :id_conflict,
|
|
78
|
+
# :insufficient, :overflow.
|
|
79
|
+
def transfer: (Integer to, Integer id, Integer amount)
|
|
80
|
+
-> (transfer | :zero_amount | :unknown_replica | :self_transfer | :stale_id | :id_conflict
|
|
81
|
+
| :insufficient | :overflow)
|
|
82
|
+
# Honoured: :applied, or the repeat :replayed. Refused: :unknown_replica,
|
|
83
|
+
# :malformed, :id_conflict, :forged, :overflow. A Receipt cannot name one
|
|
84
|
+
# replica twice, so :self_transfer is `transfer`'s alone.
|
|
85
|
+
def accept: (Receipt receipt)
|
|
86
|
+
-> (:applied | :replayed | :unknown_replica | :malformed | :id_conflict | :forged | :overflow)
|
|
87
|
+
# Honoured: :merged. Refused: :config_mismatch, :diverged, :overflow.
|
|
88
|
+
def merge: (Escrow other) -> (:merged | :config_mismatch | :diverged | :overflow)
|
|
89
|
+
# Honoured: :recovered. Refused: :config_mismatch, :diverged, :overdrawn,
|
|
90
|
+
# :overflow.
|
|
91
|
+
def recover: (Escrow other) -> (:recovered | :config_mismatch | :diverged | :overdrawn | :overflow)
|
|
92
|
+
def local: () -> Integer
|
|
93
|
+
def replicas: () -> Integer
|
|
94
|
+
def capacity: () -> Integer
|
|
95
|
+
def supply: () -> Integer
|
|
96
|
+
def available: () -> Integer
|
|
97
|
+
def allotted: (Integer replica) -> Integer?
|
|
98
|
+
def balance: (Integer replica) -> Integer?
|
|
99
|
+
def spent: (Integer replica) -> Integer?
|
|
100
|
+
def refunded: (Integer replica) -> Integer?
|
|
101
|
+
def outstanding: (Integer replica) -> Integer?
|
|
102
|
+
def granted: (Integer from, Integer to) -> Integer?
|
|
103
|
+
def last_transfer: (Integer from, Integer to) -> Mark?
|
|
104
|
+
end
|
|
105
|
+
|
|
106
|
+
# Private native hooks each Data value's `initialize` validates through and
|
|
107
|
+
# stores the answer of.
|
|
108
|
+
private def self.__receipt: (Integer from, Integer to, Integer id, Integer amount, Integer total)
|
|
109
|
+
-> [Integer, Integer, Integer, Integer, Integer]
|
|
110
|
+
private def self.__mark: (Integer id, Integer amount) -> [Integer, Integer]
|
|
111
|
+
private def self.__transfer: (Receipt receipt) -> Receipt
|
|
112
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: escrow_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.7.2
|
|
5
|
+
platform: aarch64-linux
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
autorequire:
|
|
9
|
+
bindir: bin
|
|
10
|
+
cert_chain: []
|
|
11
|
+
date: 2026-11-16 00:00:00.000000000 Z
|
|
12
|
+
dependencies: []
|
|
13
|
+
description: 'A fixed set of replicas shares a fixed supply; each spends only from
|
|
14
|
+
the rights it holds and moves rights by transfer, so merges in any order agree and
|
|
15
|
+
the total spent never exceeds the supply. Bound to Ruby from the no_std escrow-machines
|
|
16
|
+
crate: the accounting only, with the transport and durable storage left to the caller.'
|
|
17
|
+
email:
|
|
18
|
+
- oss@seuros.com
|
|
19
|
+
executables: []
|
|
20
|
+
extensions: []
|
|
21
|
+
extra_rdoc_files: []
|
|
22
|
+
files:
|
|
23
|
+
- CHANGELOG.md
|
|
24
|
+
- LICENSE.txt
|
|
25
|
+
- README.md
|
|
26
|
+
- ext/escrow_machines_native/core/CHANGELOG.md
|
|
27
|
+
- ext/escrow_machines_native/core/README.md
|
|
28
|
+
- ext/escrow_machines_native/extconf.rb
|
|
29
|
+
- lib/escrow_machines.rb
|
|
30
|
+
- lib/escrow_machines/version.rb
|
|
31
|
+
- lib/escrow_machines_native/escrow_machines_native.so
|
|
32
|
+
- sig/escrow_machines.rbs
|
|
33
|
+
homepage: https://github.com/seuros/escrow_machines
|
|
34
|
+
licenses:
|
|
35
|
+
- MIT
|
|
36
|
+
metadata:
|
|
37
|
+
source_code_uri: https://github.com/seuros/escrow_machines
|
|
38
|
+
rubygems_mfa_required: 'true'
|
|
39
|
+
cargo_crate_name: escrow_machines_native
|
|
40
|
+
cargo_manifest_path: ext/escrow_machines_native/ffi/Cargo.toml
|
|
41
|
+
post_install_message:
|
|
42
|
+
rdoc_options: []
|
|
43
|
+
require_paths:
|
|
44
|
+
- lib
|
|
45
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
46
|
+
requirements:
|
|
47
|
+
- - ">="
|
|
48
|
+
- !ruby/object:Gem::Version
|
|
49
|
+
version: '4.0'
|
|
50
|
+
- - "<"
|
|
51
|
+
- !ruby/object:Gem::Version
|
|
52
|
+
version: 4.1.dev
|
|
53
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
54
|
+
requirements:
|
|
55
|
+
- - ">="
|
|
56
|
+
- !ruby/object:Gem::Version
|
|
57
|
+
version: '0'
|
|
58
|
+
requirements: []
|
|
59
|
+
rubygems_version: 3.5.23
|
|
60
|
+
signing_key:
|
|
61
|
+
specification_version: 4
|
|
62
|
+
summary: 'Bounded-counter escrow for Ruby: conserved rights, local spends, replay-safe
|
|
63
|
+
transfers'
|
|
64
|
+
test_files: []
|