lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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 }