1use crate::errors::LedgerError;
15use crate::types::{
16 Account, AccountId, AccountSpec, IssueTransfer, PendingReservation, PendingState, Purpose,
17 Transfer, TransferId, TransferResult,
18};
19
20pub const MIN_TIMEOUT_S: u32 = 1;
22pub const MAX_TIMEOUT_S: u32 = 24 * 60 * 60;
24
25pub trait StateView {
29 fn account(&self, id: AccountId) -> Option<&Account>;
31 fn pending(&self, id: TransferId) -> Option<&PendingReservation>;
33 fn now(&self) -> u64;
36}
37
38#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
42pub enum Op {
43 OpenAccount(Box<AccountSpec>),
47 Credit(IssueTransfer),
49 Debit(Transfer),
51 Reserve {
53 transfer: Transfer,
55 timeout_s: u32,
57 },
58 Post {
60 id: TransferId,
62 pending: TransferId,
64 amount: Option<u128>,
66 },
67 Void {
69 id: TransferId,
71 pending: TransferId,
73 },
74 Expire {
77 pending: TransferId,
79 },
80}
81
82impl Op {
83 pub fn idempotency_id(&self) -> Option<TransferId> {
86 #[allow(clippy::match_same_arms)]
89 match self {
90 Op::OpenAccount(_) | Op::Expire { .. } => None,
91 Op::Credit(t) => Some(t.id),
92 Op::Debit(t) => Some(t.id),
93 Op::Reserve { transfer, .. } => Some(transfer.id),
94 Op::Post { id, .. } | Op::Void { id, .. } => Some(*id),
95 }
96 }
97}
98
99#[derive(Debug, Clone, PartialEq, Eq)]
101pub enum Delta {
102 Account(Account),
104 Pending(PendingReservation),
106}
107
108#[derive(Debug, Clone, PartialEq, Eq)]
113pub struct Staged {
114 pub result: Result<TransferResult, LedgerError>,
116 pub deltas: Vec<Delta>,
118}
119
120impl Staged {
121 fn err(e: LedgerError) -> Self {
122 Staged {
123 result: Err(e),
124 deltas: Vec::new(),
125 }
126 }
127}
128
129pub fn stage(view: &dyn StateView, op: &Op) -> Staged {
131 match op {
132 Op::OpenAccount(spec) => stage_open(view, spec),
133 Op::Credit(t) => stage_credit(view, t),
134 Op::Debit(t) => stage_debit(view, t),
135 Op::Reserve {
136 transfer,
137 timeout_s,
138 } => stage_reserve(view, transfer, *timeout_s),
139 Op::Post {
140 pending, amount, ..
141 } => stage_second_phase(view, *pending, Phase::Post(*amount)),
142 Op::Void { pending, .. } => stage_second_phase(view, *pending, Phase::Void),
143 Op::Expire { pending } => stage_second_phase(view, *pending, Phase::Expire),
144 }
145}
146
147fn stage_open(view: &dyn StateView, spec: &AccountSpec) -> Staged {
148 let id = match spec.account_id() {
149 Ok(id) => id,
150 Err(e) => return Staged::err(e),
151 };
152 if let Some(existing) = view.account(id) {
153 if existing.unit != spec.unit {
154 return Staged::err(LedgerError::AccountUnitConflict { id });
155 }
156 return Staged {
159 result: Ok(TransferResult::Opened),
160 deltas: Vec::new(),
161 };
162 }
163 let account = Account::new(id, spec.unit.clone(), spec.purpose.clone(), spec.flags);
164 Staged {
165 result: Ok(TransferResult::Opened),
166 deltas: vec![Delta::Account(account)],
167 }
168}
169
170fn stage_credit(view: &dyn StateView, t: &IssueTransfer) -> Staged {
171 if t.amount == 0 {
172 return Staged::err(LedgerError::ZeroAmount);
173 }
174 let (liability, dest) = match (
175 view.account(t.issuer_liability),
176 view.account(t.destination),
177 ) {
178 (Some(l), Some(d)) => (l, d),
179 (None, _) => return Staged::err(LedgerError::UnknownAccount(t.issuer_liability)),
180 (_, None) => return Staged::err(LedgerError::UnknownAccount(t.destination)),
181 };
182 if t.issuer_liability == t.destination {
184 return Staged::err(LedgerError::AccountsMustDiffer(t.issuer_liability));
185 }
186 if liability.purpose != Purpose::IssuerLiability {
187 return Staged::err(LedgerError::NotIssuerLiability(t.issuer_liability));
188 }
189 if let Err(e) = check_unit(liability, &t.unit) {
190 return Staged::err(e);
191 }
192 if let Err(e) = check_unit(dest, &t.unit) {
193 return Staged::err(e);
194 }
195 let mut liability = liability.clone();
196 let mut dest = dest.clone();
197 liability.debits_posted = liability.debits_posted.saturating_add(t.amount);
198 dest.credits_posted = dest.credits_posted.saturating_add(t.amount);
199 Staged {
200 result: Ok(TransferResult::Issued),
201 deltas: vec![Delta::Account(liability), Delta::Account(dest)],
202 }
203}
204
205fn stage_debit(view: &dyn StateView, t: &Transfer) -> Staged {
206 let (debit, credit) = match resolve_pair(view, t.debit_account, t.credit_account, &t.unit) {
207 Ok(p) => p,
208 Err(e) => return Staged::err(e),
209 };
210 if t.amount == 0 {
211 return Staged::err(LedgerError::ZeroAmount);
212 }
213 if debit.is_debit_constrained() && t.amount > debit.available() {
214 return Staged::err(LedgerError::InsufficientBalance {
215 account: debit.id,
216 needed: t.amount,
217 available: debit.available(),
218 });
219 }
220 let mut debit = debit.clone();
221 let mut credit = credit.clone();
222 debit.debits_posted = debit.debits_posted.saturating_add(t.amount);
223 credit.credits_posted = credit.credits_posted.saturating_add(t.amount);
224 Staged {
225 result: Ok(TransferResult::Applied {
226 posted: t.amount,
227 released: 0,
228 }),
229 deltas: vec![Delta::Account(debit), Delta::Account(credit)],
230 }
231}
232
233fn stage_reserve(view: &dyn StateView, t: &Transfer, timeout_s: u32) -> Staged {
234 if !(MIN_TIMEOUT_S..=MAX_TIMEOUT_S).contains(&timeout_s) {
235 return Staged::err(LedgerError::TimeoutOutOfBounds(timeout_s));
236 }
237 let (debit, credit) = match resolve_pair(view, t.debit_account, t.credit_account, &t.unit) {
238 Ok(p) => p,
239 Err(e) => return Staged::err(e),
240 };
241 if t.amount == 0 {
242 return Staged::err(LedgerError::ZeroAmount);
243 }
244 if debit.is_debit_constrained() && t.amount > debit.available() {
247 return Staged::err(LedgerError::InsufficientBalance {
248 account: debit.id,
249 needed: t.amount,
250 available: debit.available(),
251 });
252 }
253 let mut debit = debit.clone();
254 let mut credit = credit.clone();
255 debit.debits_pending = debit.debits_pending.saturating_add(t.amount);
256 credit.credits_pending = credit.credits_pending.saturating_add(t.amount);
257 let reservation = PendingReservation {
258 transfer: t.clone(),
259 deadline: view.now().saturating_add(timeout_s as u64),
260 state: PendingState::Pending,
261 };
262 Staged {
263 result: Ok(TransferResult::Reserved),
264 deltas: vec![
265 Delta::Account(debit),
266 Delta::Account(credit),
267 Delta::Pending(reservation),
268 ],
269 }
270}
271
272enum Phase {
275 Post(Option<u128>),
276 Void,
277 Expire,
278}
279
280fn stage_second_phase(view: &dyn StateView, pending_id: TransferId, phase: Phase) -> Staged {
281 let reservation = match view.pending(pending_id) {
282 Some(r) => r,
283 None => return Staged::err(LedgerError::UnknownPendingTransfer(pending_id)),
284 };
285
286 match reservation.state {
289 PendingState::Pending => {}
290 PendingState::Posted => {
291 return Staged::err(LedgerError::PendingTransferAlreadyPosted(pending_id))
292 }
293 PendingState::Voided => {
294 return Staged::err(LedgerError::PendingTransferAlreadyVoided(pending_id))
295 }
296 PendingState::Expired => {
297 return Staged::err(LedgerError::PendingTransferExpired(pending_id))
298 }
299 }
300
301 let t = &reservation.transfer;
302 let debit = match view.account(t.debit_account) {
303 Some(a) => a,
304 None => return Staged::err(LedgerError::UnknownAccount(t.debit_account)),
305 };
306 let credit = match view.account(t.credit_account) {
307 Some(a) => a,
308 None => return Staged::err(LedgerError::UnknownAccount(t.credit_account)),
309 };
310
311 let expired_now = view.now() >= reservation.deadline;
316 if matches!(phase, Phase::Expire) || expired_now {
317 let released = release(debit, credit, t.amount);
318 let mut res = reservation.clone();
319 res.state = PendingState::Expired;
320 let deltas = vec![released.0, released.1, Delta::Pending(res)];
321 let result = if matches!(phase, Phase::Expire) {
324 Ok(TransferResult::Expired)
325 } else {
326 Err(LedgerError::PendingTransferExpired(pending_id))
327 };
328 return Staged { result, deltas };
329 }
330
331 match phase {
332 Phase::Void => {
333 let (d_delta, c_delta) = release(debit, credit, t.amount);
334 let mut res = reservation.clone();
335 res.state = PendingState::Voided;
336 Staged {
337 result: Ok(TransferResult::Voided),
338 deltas: vec![d_delta, c_delta, Delta::Pending(res)],
339 }
340 }
341 Phase::Post(amount) => {
342 let reserved = t.amount;
343 let post_amt = amount.unwrap_or(reserved);
344 if post_amt == 0 {
345 return Staged::err(LedgerError::ZeroAmount);
346 }
347 if post_amt > reserved {
348 return Staged::err(LedgerError::PostExceedsReservation {
349 requested: post_amt,
350 reserved,
351 });
352 }
353 let released = reserved - post_amt;
354 let mut debit = debit.clone();
355 let mut credit = credit.clone();
356 debit.debits_pending = debit.debits_pending.saturating_sub(reserved);
359 credit.credits_pending = credit.credits_pending.saturating_sub(reserved);
360 debit.debits_posted = debit.debits_posted.saturating_add(post_amt);
361 credit.credits_posted = credit.credits_posted.saturating_add(post_amt);
362 let mut res = reservation.clone();
363 res.state = PendingState::Posted;
364 Staged {
365 result: Ok(TransferResult::Applied {
366 posted: post_amt,
367 released,
368 }),
369 deltas: vec![
370 Delta::Account(debit),
371 Delta::Account(credit),
372 Delta::Pending(res),
373 ],
374 }
375 }
376 Phase::Expire => unreachable_expire(),
377 }
378}
379
380fn release(debit: &Account, credit: &Account, amount: u128) -> (Delta, Delta) {
382 let mut debit = debit.clone();
383 let mut credit = credit.clone();
384 debit.debits_pending = debit.debits_pending.saturating_sub(amount);
385 credit.credits_pending = credit.credits_pending.saturating_sub(amount);
386 (Delta::Account(debit), Delta::Account(credit))
387}
388
389fn unreachable_expire() -> Staged {
393 Staged::err(LedgerError::Internal(
394 "expire reached the non-expired second-phase arm".to_owned(),
395 ))
396}
397
398fn resolve_pair<'a>(
399 view: &'a dyn StateView,
400 debit_id: AccountId,
401 credit_id: AccountId,
402 unit: &crate::types::UnitId,
403) -> Result<(&'a Account, &'a Account), LedgerError> {
404 if debit_id == credit_id {
405 return Err(LedgerError::AccountsMustDiffer(debit_id));
406 }
407 let debit = view
408 .account(debit_id)
409 .ok_or(LedgerError::UnknownAccount(debit_id))?;
410 let credit = view
411 .account(credit_id)
412 .ok_or(LedgerError::UnknownAccount(credit_id))?;
413 check_unit(debit, unit)?;
414 check_unit(credit, unit)?;
415 Ok((debit, credit))
416}
417
418fn check_unit(account: &Account, unit: &crate::types::UnitId) -> Result<(), LedgerError> {
419 if &account.unit != unit {
420 return Err(LedgerError::UnitMismatch {
421 transfer: unit.clone(),
422 account: account.unit.clone(),
423 });
424 }
425 Ok(())
426}