escrow_machines 0.7.2
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/Cargo.lock +314 -0
- data/Cargo.toml +24 -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/Cargo.toml +17 -0
- data/ext/escrow_machines_native/core/README.md +64 -0
- data/ext/escrow_machines_native/core/src/frame.rs +243 -0
- data/ext/escrow_machines_native/core/src/lib.rs +453 -0
- data/ext/escrow_machines_native/core/src/merge.rs +132 -0
- data/ext/escrow_machines_native/core/src/ops.rs +180 -0
- data/ext/escrow_machines_native/core/src/table.rs +108 -0
- data/ext/escrow_machines_native/extconf.rb +2 -0
- data/ext/escrow_machines_native/ffi/Cargo.toml +21 -0
- data/ext/escrow_machines_native/ffi/extconf.rb +14 -0
- data/ext/escrow_machines_native/ffi/src/init.rs +70 -0
- data/ext/escrow_machines_native/ffi/src/lib.rs +343 -0
- data/lib/escrow_machines/version.rb +4 -0
- data/lib/escrow_machines.rb +60 -0
- data/sig/escrow_machines.rbs +112 -0
- metadata +90 -0
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
//! Thin binding to the bounded-counter escrow.
|
|
2
|
+
mod init;
|
|
3
|
+
|
|
4
|
+
use init::classes;
|
|
5
|
+
|
|
6
|
+
use escrow_machines::{Accepted, ConfigError, Escrow, Mark, Receipt, Refusal, Transfer};
|
|
7
|
+
use magnus::{Error, RString, Ruby, Symbol, Value, prelude::*, typed_data::Obj};
|
|
8
|
+
use matryona_machines::ruby::{
|
|
9
|
+
SymbolNames, bytes_with, class_name, exact_array, exact_fields, exact_typed_with, integer,
|
|
10
|
+
keep, symbol,
|
|
11
|
+
};
|
|
12
|
+
use std::cell::RefCell;
|
|
13
|
+
|
|
14
|
+
/// Replicas one compiled escrow can hold.
|
|
15
|
+
const CAPACITY: usize = 8;
|
|
16
|
+
|
|
17
|
+
type Core = Escrow<CAPACITY>;
|
|
18
|
+
|
|
19
|
+
matryona_machines::symbols! {
|
|
20
|
+
/// The symbol each refusal comes back to Ruby as. Several variants carry
|
|
21
|
+
/// data, so the table names them and never parses one back.
|
|
22
|
+
Refusals for Refusal as "a refusal" => names_only {
|
|
23
|
+
ZeroAmount => "zero_amount",
|
|
24
|
+
Insufficient { .. } => "insufficient",
|
|
25
|
+
ExceedsSpent { .. } => "exceeds_spent",
|
|
26
|
+
UnknownReplica => "unknown_replica",
|
|
27
|
+
SelfTransfer => "self_transfer",
|
|
28
|
+
StaleId { .. } => "stale_id",
|
|
29
|
+
IdConflict { .. } => "id_conflict",
|
|
30
|
+
Malformed => "malformed",
|
|
31
|
+
Forged => "forged",
|
|
32
|
+
ConfigMismatch => "config_mismatch",
|
|
33
|
+
Diverged => "diverged",
|
|
34
|
+
Overdrawn => "overdrawn",
|
|
35
|
+
Overflow => "overflow",
|
|
36
|
+
Truncated => "truncated",
|
|
37
|
+
WrongStructure => "wrong_structure",
|
|
38
|
+
WrongShape => "wrong_shape",
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/// The refusal's symbol.
|
|
43
|
+
fn refusal(ruby: &Ruby, refused: &Refusal) -> Symbol {
|
|
44
|
+
Refusals::symbol(ruby, refused)
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
fn receipt_from(ruby: &Ruby, value: Value) -> Result<Receipt, Error> {
|
|
48
|
+
// Exactly a Receipt: sealing cannot stop a subclass being bound, and a
|
|
49
|
+
// value that skipped `initialize` (`Marshal.load`) is re-checked below.
|
|
50
|
+
// The fields are read natively: no reader runs.
|
|
51
|
+
let class = classes(ruby)?.receipt.get(ruby);
|
|
52
|
+
let [from, to, id, amount, total] =
|
|
53
|
+
exact_fields::<5>(ruby, value, class, "expected an EscrowMachines::Receipt")?;
|
|
54
|
+
let (from, to, id) = (
|
|
55
|
+
integer(from, "from")?,
|
|
56
|
+
integer(to, "to")?,
|
|
57
|
+
integer(id, "id")?,
|
|
58
|
+
);
|
|
59
|
+
let (amount, total) = (integer(amount, "amount")?, integer(total, "total")?);
|
|
60
|
+
Receipt::new(from, to, id, amount, total).ok_or_else(|| inconsistent_receipt(ruby))
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/// The `RangeError` for receipt fields `Receipt::new` turns down.
|
|
64
|
+
fn inconsistent_receipt(ruby: &Ruby) -> Error {
|
|
65
|
+
Error::new(
|
|
66
|
+
ruby.exception_range_error(),
|
|
67
|
+
"a receipt names two replicas and moves 1..=total rights",
|
|
68
|
+
)
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/// `Receipt.new`'s private hook: the fields as `Receipt::new` accepts them.
|
|
72
|
+
fn checked_receipt(
|
|
73
|
+
ruby: &Ruby,
|
|
74
|
+
from: Value,
|
|
75
|
+
to: Value,
|
|
76
|
+
id: Value,
|
|
77
|
+
amount: Value,
|
|
78
|
+
total: Value,
|
|
79
|
+
) -> Result<(u64, u64, u64, u64, u64), Error> {
|
|
80
|
+
let (from, to, id) = (
|
|
81
|
+
integer(from, "from")?,
|
|
82
|
+
integer(to, "to")?,
|
|
83
|
+
integer(id, "id")?,
|
|
84
|
+
);
|
|
85
|
+
let (amount, total) = (integer(amount, "amount")?, integer(total, "total")?);
|
|
86
|
+
let receipt =
|
|
87
|
+
Receipt::new(from, to, id, amount, total).ok_or_else(|| inconsistent_receipt(ruby))?;
|
|
88
|
+
Ok(fields(receipt))
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/// A receipt's fields in `Receipt.new`'s order.
|
|
92
|
+
const fn fields(receipt: Receipt) -> (u64, u64, u64, u64, u64) {
|
|
93
|
+
(
|
|
94
|
+
receipt.from(),
|
|
95
|
+
receipt.to(),
|
|
96
|
+
receipt.id(),
|
|
97
|
+
receipt.amount(),
|
|
98
|
+
receipt.total(),
|
|
99
|
+
)
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/// `Mark.new`'s private hook: the fields as `Mark::new` accepts them.
|
|
103
|
+
fn checked_mark(ruby: &Ruby, id: Value, amount: Value) -> Result<(u64, u64), Error> {
|
|
104
|
+
let (id, amount) = (integer(id, "id")?, integer(amount, "amount")?);
|
|
105
|
+
let mark = Mark::new(id, amount).ok_or_else(|| {
|
|
106
|
+
Error::new(
|
|
107
|
+
ruby.exception_range_error(),
|
|
108
|
+
"a mark records a transfer of at least 1 right",
|
|
109
|
+
)
|
|
110
|
+
})?;
|
|
111
|
+
Ok((mark.id(), mark.amount()))
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/// `Transfer::Applied.new` and `Transfer::Replayed.new`'s private hook: the
|
|
115
|
+
/// receipt must be an `EscrowMachines::Receipt`, already valid by its own
|
|
116
|
+
/// constructor.
|
|
117
|
+
fn checked_transfer(ruby: &Ruby, receipt: Value) -> Result<Value, Error> {
|
|
118
|
+
receipt_from(ruby, receipt)?;
|
|
119
|
+
Ok(receipt)
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
#[magnus::wrap(class = "EscrowMachines::Escrow", free_immediately, size)]
|
|
123
|
+
struct Wrapper {
|
|
124
|
+
core: RefCell<Core>,
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
impl Wrapper {
|
|
128
|
+
/// The escrow `merge` and `recover` read: exactly an
|
|
129
|
+
/// `EscrowMachines::Escrow`, a subclass instance refused with `TypeError`
|
|
130
|
+
/// naming the class received.
|
|
131
|
+
fn partner(ruby: &Ruby, other: Value) -> Result<Obj<Self>, Error> {
|
|
132
|
+
let class = classes(ruby)?.escrow.get(ruby);
|
|
133
|
+
exact_typed_with(ruby, other, class, || {
|
|
134
|
+
format!(
|
|
135
|
+
"other must be an EscrowMachines::Escrow, not {}",
|
|
136
|
+
class_name(other)
|
|
137
|
+
)
|
|
138
|
+
})
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
fn new(ruby: &Ruby, local: Value, allotted: Value) -> Result<Self, Error> {
|
|
142
|
+
let local = integer(local, "local")?;
|
|
143
|
+
let allotted = exact_array(ruby, allotted, "allotted must be an Array of Integers")?;
|
|
144
|
+
let range = |message: &'static str| Error::new(ruby.exception_range_error(), message);
|
|
145
|
+
if allotted.len() > CAPACITY {
|
|
146
|
+
return Err(range("more replicas than EscrowMachines::CAPACITY"));
|
|
147
|
+
}
|
|
148
|
+
let mut shares = [0_u64; CAPACITY];
|
|
149
|
+
let shares = &mut shares[..allotted.len()];
|
|
150
|
+
for (index, share) in (0_isize..).zip(shares.iter_mut()) {
|
|
151
|
+
*share = integer(allotted.entry(index)?, "allotted")?;
|
|
152
|
+
}
|
|
153
|
+
let core = Core::new(local, shares).map_err(|error| {
|
|
154
|
+
range(match error {
|
|
155
|
+
ConfigError::NoReplicas => "allotted must name at least one replica",
|
|
156
|
+
ConfigError::TooManyReplicas => "more replicas than EscrowMachines::CAPACITY",
|
|
157
|
+
ConfigError::UnknownReplica => "local must index into allotted",
|
|
158
|
+
ConfigError::SupplyOverflow => "allotted must add up to at most 2**64-1",
|
|
159
|
+
})
|
|
160
|
+
})?;
|
|
161
|
+
Ok(Self {
|
|
162
|
+
core: RefCell::new(core),
|
|
163
|
+
})
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
fn decode(ruby: &Ruby, frame: Value) -> Result<Self, Error> {
|
|
167
|
+
let frame = bytes_with(frame, || {
|
|
168
|
+
format!("bytes must be a String, not {}", class_name(frame))
|
|
169
|
+
})?;
|
|
170
|
+
let core = Core::decode(&frame).map_err(|refused| {
|
|
171
|
+
Error::new(
|
|
172
|
+
ruby.exception_range_error(),
|
|
173
|
+
format!("the frame is refused: {}", Refusals::name(&refused)),
|
|
174
|
+
)
|
|
175
|
+
})?;
|
|
176
|
+
Ok(Self {
|
|
177
|
+
core: RefCell::new(core),
|
|
178
|
+
})
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/// The frame `Escrow::encode` writes. Its buffer is `ENCODED_LEN` long,
|
|
182
|
+
/// which every escrow fits; an encode that still refused would answer the
|
|
183
|
+
/// empty string, a frame `decode` raises on rather than one that restores
|
|
184
|
+
/// the wrong state.
|
|
185
|
+
fn encode(ruby: &Ruby, this: &Self) -> RString {
|
|
186
|
+
let mut frame = [0_u8; Core::ENCODED_LEN];
|
|
187
|
+
let written = this
|
|
188
|
+
.core
|
|
189
|
+
.borrow()
|
|
190
|
+
.encode(&mut frame)
|
|
191
|
+
.unwrap_or_else(|error| {
|
|
192
|
+
debug_assert!(false, "a frame of ENCODED_LEN takes every escrow: {error}");
|
|
193
|
+
0
|
|
194
|
+
});
|
|
195
|
+
ruby.str_from_slice(&frame[..written])
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
fn amount_or_refusal(ruby: &Ruby, outcome: Result<u64, Refusal>) -> Value {
|
|
199
|
+
match outcome {
|
|
200
|
+
Ok(left) => ruby.into_value(left),
|
|
201
|
+
Err(refused) => refusal(ruby, &refused).as_value(),
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
fn spend(ruby: &Ruby, this: Obj<Self>, amount: Value) -> Result<Value, Error> {
|
|
206
|
+
this.check_frozen()?;
|
|
207
|
+
let amount = integer(amount, "amount")?;
|
|
208
|
+
let outcome = this.core.borrow_mut().spend(amount);
|
|
209
|
+
Ok(Self::amount_or_refusal(ruby, outcome))
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
fn refund(ruby: &Ruby, this: Obj<Self>, amount: Value) -> Result<Value, Error> {
|
|
213
|
+
this.check_frozen()?;
|
|
214
|
+
let amount = integer(amount, "amount")?;
|
|
215
|
+
let outcome = this.core.borrow_mut().refund(amount);
|
|
216
|
+
Ok(Self::amount_or_refusal(ruby, outcome))
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
fn transfer(
|
|
220
|
+
ruby: &Ruby,
|
|
221
|
+
this: Obj<Self>,
|
|
222
|
+
to: Value,
|
|
223
|
+
id: Value,
|
|
224
|
+
amount: Value,
|
|
225
|
+
) -> Result<Value, Error> {
|
|
226
|
+
this.check_frozen()?;
|
|
227
|
+
let (to, id, amount) = (
|
|
228
|
+
integer(to, "to")?,
|
|
229
|
+
integer(id, "id")?,
|
|
230
|
+
integer(amount, "amount")?,
|
|
231
|
+
);
|
|
232
|
+
// The classes were resolved at init, and the answer is built from a
|
|
233
|
+
// copy kept only once it exists.
|
|
234
|
+
let classes = classes(ruby)?;
|
|
235
|
+
keep(
|
|
236
|
+
ruby,
|
|
237
|
+
this,
|
|
238
|
+
&this.core,
|
|
239
|
+
|core| core.transfer(to, id, amount),
|
|
240
|
+
|outcome| {
|
|
241
|
+
let (variant, receipt) = match outcome {
|
|
242
|
+
Ok(Transfer::Applied(receipt)) => (classes.applied, receipt),
|
|
243
|
+
Ok(Transfer::Replayed(receipt)) => (classes.replayed, receipt),
|
|
244
|
+
Err(refused) => return Ok(refusal(ruby, &refused).as_value()),
|
|
245
|
+
};
|
|
246
|
+
let receipt: Value = classes.receipt.get(ruby).funcall("new", fields(receipt))?;
|
|
247
|
+
variant.get(ruby).funcall("new", (receipt,))
|
|
248
|
+
},
|
|
249
|
+
)
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
fn accept(ruby: &Ruby, this: Obj<Self>, receipt: Value) -> Result<Symbol, Error> {
|
|
253
|
+
this.check_frozen()?;
|
|
254
|
+
let receipt = receipt_from(ruby, receipt)?;
|
|
255
|
+
let outcome = this.core.borrow_mut().accept(&receipt);
|
|
256
|
+
Ok(match outcome {
|
|
257
|
+
Ok(Accepted::Applied) => symbol(ruby, "applied"),
|
|
258
|
+
Ok(Accepted::Replayed) => symbol(ruby, "replayed"),
|
|
259
|
+
Err(refused) => refusal(ruby, &refused),
|
|
260
|
+
})
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
fn joined(ruby: &Ruby, outcome: Result<(), Refusal>, honoured: &'static str) -> Symbol {
|
|
264
|
+
outcome.map_or_else(
|
|
265
|
+
|refused| refusal(ruby, &refused),
|
|
266
|
+
|()| symbol(ruby, honoured),
|
|
267
|
+
)
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
fn merge(ruby: &Ruby, this: Obj<Self>, other: Value) -> Result<Symbol, Error> {
|
|
271
|
+
this.check_frozen()?;
|
|
272
|
+
// Copied out first: `other` may be `this`.
|
|
273
|
+
let other = *Self::partner(ruby, other)?.core.borrow();
|
|
274
|
+
let outcome = this.core.borrow_mut().merge(&other);
|
|
275
|
+
Ok(Self::joined(ruby, outcome, "merged"))
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
fn recover(ruby: &Ruby, this: Obj<Self>, other: Value) -> Result<Symbol, Error> {
|
|
279
|
+
this.check_frozen()?;
|
|
280
|
+
let other = *Self::partner(ruby, other)?.core.borrow();
|
|
281
|
+
let outcome = this.core.borrow_mut().recover(&other);
|
|
282
|
+
Ok(Self::joined(ruby, outcome, "recovered"))
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
fn local(&self) -> u64 {
|
|
286
|
+
self.core.borrow().local()
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
fn replicas(&self) -> usize {
|
|
290
|
+
self.core.borrow().replicas()
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
const fn capacity(_: &Self) -> usize {
|
|
294
|
+
CAPACITY
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
fn supply(&self) -> u64 {
|
|
298
|
+
self.core.borrow().supply()
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
fn available(&self) -> u64 {
|
|
302
|
+
self.core.borrow().available()
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
fn allotted(&self, replica: Value) -> Result<Option<u64>, Error> {
|
|
306
|
+
let replica = integer(replica, "replica")?;
|
|
307
|
+
Ok(self.core.borrow().allotted(replica))
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
fn balance(&self, replica: Value) -> Result<Option<i128>, Error> {
|
|
311
|
+
let replica = integer(replica, "replica")?;
|
|
312
|
+
Ok(self.core.borrow().balance(replica))
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
fn spent(&self, replica: Value) -> Result<Option<u64>, Error> {
|
|
316
|
+
let replica = integer(replica, "replica")?;
|
|
317
|
+
Ok(self.core.borrow().spent(replica))
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
fn refunded(&self, replica: Value) -> Result<Option<u64>, Error> {
|
|
321
|
+
let replica = integer(replica, "replica")?;
|
|
322
|
+
Ok(self.core.borrow().refunded(replica))
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
fn outstanding(&self, replica: Value) -> Result<Option<u64>, Error> {
|
|
326
|
+
let replica = integer(replica, "replica")?;
|
|
327
|
+
Ok(self.core.borrow().outstanding(replica))
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
fn granted(&self, from: Value, to: Value) -> Result<Option<u64>, Error> {
|
|
331
|
+
let (from, to) = (integer(from, "from")?, integer(to, "to")?);
|
|
332
|
+
Ok(self.core.borrow().granted(from, to))
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
fn last_transfer(ruby: &Ruby, this: &Self, from: Value, to: Value) -> Result<Value, Error> {
|
|
336
|
+
let (from, to) = (integer(from, "from")?, integer(to, "to")?);
|
|
337
|
+
let class = classes(ruby)?.mark.get(ruby);
|
|
338
|
+
let Some(mark) = this.core.borrow().last_transfer(from, to) else {
|
|
339
|
+
return Ok(ruby.qnil().as_value());
|
|
340
|
+
};
|
|
341
|
+
class.funcall("new", (mark.id(), mark.amount()))
|
|
342
|
+
}
|
|
343
|
+
}
|
|
@@ -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
|
|
@@ -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,90 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: escrow_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.7.2
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: rb_sys
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - "~>"
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: '0.9'
|
|
19
|
+
- - ">="
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: 0.9.130
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - "~>"
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: '0.9'
|
|
29
|
+
- - ">="
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: 0.9.130
|
|
32
|
+
description: 'A fixed set of replicas shares a fixed supply; each spends only from
|
|
33
|
+
the rights it holds and moves rights by transfer, so merges in any order agree and
|
|
34
|
+
the total spent never exceeds the supply. Bound to Ruby from the no_std escrow-machines
|
|
35
|
+
crate: the accounting only, with the transport and durable storage left to the caller.'
|
|
36
|
+
email:
|
|
37
|
+
- oss@seuros.com
|
|
38
|
+
executables: []
|
|
39
|
+
extensions:
|
|
40
|
+
- ext/escrow_machines_native/extconf.rb
|
|
41
|
+
extra_rdoc_files: []
|
|
42
|
+
files:
|
|
43
|
+
- CHANGELOG.md
|
|
44
|
+
- Cargo.lock
|
|
45
|
+
- Cargo.toml
|
|
46
|
+
- LICENSE.txt
|
|
47
|
+
- README.md
|
|
48
|
+
- ext/escrow_machines_native/core/CHANGELOG.md
|
|
49
|
+
- ext/escrow_machines_native/core/Cargo.toml
|
|
50
|
+
- ext/escrow_machines_native/core/README.md
|
|
51
|
+
- ext/escrow_machines_native/core/src/frame.rs
|
|
52
|
+
- ext/escrow_machines_native/core/src/lib.rs
|
|
53
|
+
- ext/escrow_machines_native/core/src/merge.rs
|
|
54
|
+
- ext/escrow_machines_native/core/src/ops.rs
|
|
55
|
+
- ext/escrow_machines_native/core/src/table.rs
|
|
56
|
+
- ext/escrow_machines_native/extconf.rb
|
|
57
|
+
- ext/escrow_machines_native/ffi/Cargo.toml
|
|
58
|
+
- ext/escrow_machines_native/ffi/extconf.rb
|
|
59
|
+
- ext/escrow_machines_native/ffi/src/init.rs
|
|
60
|
+
- ext/escrow_machines_native/ffi/src/lib.rs
|
|
61
|
+
- lib/escrow_machines.rb
|
|
62
|
+
- lib/escrow_machines/version.rb
|
|
63
|
+
- sig/escrow_machines.rbs
|
|
64
|
+
homepage: https://github.com/seuros/escrow_machines
|
|
65
|
+
licenses:
|
|
66
|
+
- MIT
|
|
67
|
+
metadata:
|
|
68
|
+
source_code_uri: https://github.com/seuros/escrow_machines
|
|
69
|
+
rubygems_mfa_required: 'true'
|
|
70
|
+
cargo_crate_name: escrow_machines_native
|
|
71
|
+
cargo_manifest_path: ext/escrow_machines_native/ffi/Cargo.toml
|
|
72
|
+
rdoc_options: []
|
|
73
|
+
require_paths:
|
|
74
|
+
- lib
|
|
75
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
76
|
+
requirements:
|
|
77
|
+
- - ">="
|
|
78
|
+
- !ruby/object:Gem::Version
|
|
79
|
+
version: 4.0.0
|
|
80
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
81
|
+
requirements:
|
|
82
|
+
- - ">="
|
|
83
|
+
- !ruby/object:Gem::Version
|
|
84
|
+
version: '0'
|
|
85
|
+
requirements: []
|
|
86
|
+
rubygems_version: 4.0.20
|
|
87
|
+
specification_version: 4
|
|
88
|
+
summary: 'Bounded-counter escrow for Ruby: conserved rights, local spends, replay-safe
|
|
89
|
+
transfers'
|
|
90
|
+
test_files: []
|