obligation.rs (3969B)
1 //! Outstanding obligations reconcile backing and deficits without creating stock. 2 use super::{StockError, StockTicks}; 3 use core::fmt; 4 5 /// A checked remaining obligation in one fixed pool unit. Deficit is unbacked 6 /// obligation, never physical stock. Construction proves no original allocation, 7 /// permission, generation, causality or durable effect. 8 #[derive(Clone, Copy, Eq, PartialEq)] 9 pub struct ObligationBacking { 10 remaining: StockTicks, 11 backed: StockTicks, 12 deficit: StockTicks, 13 } 14 15 impl ObligationBacking { 16 /// Requires exact remaining = backed + deficit within the stock tick bound. 17 /// Zero remaining is allowed only with zero backing and zero deficit. 18 pub fn new( 19 remaining: StockTicks, 20 backed: StockTicks, 21 deficit: StockTicks, 22 ) -> Result<Self, StockError> { 23 if backed.checked_add(deficit)? != remaining { 24 return Err(StockError::ObligationMismatch); 25 } 26 Ok(Self { 27 remaining, 28 backed, 29 deficit, 30 }) 31 } 32 33 /// Exact outstanding quantity, independently of physical availability. 34 pub const fn remaining(self) -> StockTicks { 35 self.remaining 36 } 37 38 /// Outstanding quantity claimed to have retained physical backing. 39 pub const fn backed(self) -> StockTicks { 40 self.backed 41 } 42 43 /// Outstanding quantity whose physical backing is absent. 44 pub const fn deficit(self) -> StockTicks { 45 self.deficit 46 } 47 48 /// Proposes loss of original physical backing while retaining the entire 49 /// obligation. The native executor must record the physical depletion and 50 /// this deficit atomically against the same original allocation/version. 51 pub fn lose_backing(self, quantity: StockTicks) -> Result<Self, StockError> { 52 positive(quantity)?; 53 Self::new( 54 self.remaining, 55 self.backed.checked_sub(quantity)?, 56 self.deficit.checked_add(quantity)?, 57 ) 58 } 59 60 /// Proposes replacement backing for a known deficit. The executor must 61 /// actually hold that stock; this value cannot acquire physical capacity. 62 pub fn restore_backing(self, quantity: StockTicks) -> Result<Self, StockError> { 63 positive(quantity)?; 64 let deficit = self.deficit.checked_sub(quantity)?; 65 Self::new(self.remaining, self.backed.checked_add(quantity)?, deficit) 66 } 67 68 /// Proposes fulfillment of backed residual only. The authoritative handover 69 /// transaction consumes its physical backing once. A buyer receipt changes 70 /// neither this obligation nor the physical balances a second time. 71 pub fn consume_backed(self, quantity: StockTicks) -> Result<Self, StockError> { 72 positive(quantity)?; 73 Self::new( 74 self.remaining.checked_sub(quantity)?, 75 self.backed.checked_sub(quantity)?, 76 self.deficit, 77 ) 78 } 79 80 /// Proposes a nonempty authorized residual release with explicit backed and 81 /// deficit portions. Only the backed portion can return physical stock to 82 /// available. Bilateral authority, exact residual and durable identity are 83 /// checked by the executor, never inferred from this arithmetic. 84 pub fn release_residual( 85 self, 86 backed: StockTicks, 87 deficit: StockTicks, 88 ) -> Result<Self, StockError> { 89 let quantity = backed.checked_add(deficit)?; 90 positive(quantity)?; 91 Self::new( 92 self.remaining.checked_sub(quantity)?, 93 self.backed.checked_sub(backed)?, 94 self.deficit.checked_sub(deficit)?, 95 ) 96 } 97 } 98 99 fn positive(quantity: StockTicks) -> Result<(), StockError> { 100 if quantity == StockTicks::ZERO { 101 Err(StockError::ZeroMovement) 102 } else { 103 Ok(()) 104 } 105 } 106 107 impl fmt::Debug for ObligationBacking { 108 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 109 f.write_str("ObligationBacking(<private proposal>)") 110 } 111 }