lib

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

movements.rs (5780B)


      1 //! Pure movement proposals; durable admission and original allocation proof are external.
      2 use super::{PoolBalances, StockError, StockTicks};
      3 
      4 /// Physical backing held for an original operation or installed obligation.
      5 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
      6 pub enum HeldStockCategory {
      7     /// Original preparation whose issuance is not resolved.
      8     Preparatory,
      9     /// Remaining backing of an installed commitment.
     10     Committed,
     11     /// Backing retained under unresolved signature or business risk.
     12     Quarantined,
     13 }
     14 
     15 /// Depletion of genuinely present held stock, without deleting its obligation.
     16 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
     17 pub enum HeldStockLoss {
     18     /// Move the physical quantity into cumulative waste.
     19     Spoilage,
     20     /// Move the physical quantity into cumulative removed stock.
     21     Removal,
     22 }
     23 
     24 enum Destination {
     25     Available,
     26     Committed,
     27     Quarantined,
     28     Consumed,
     29     Waste,
     30     Removed,
     31 }
     32 
     33 impl PoolBalances {
     34     /// Proposes release of authorized unconsumed committed backing. The executor
     35     /// must prove the exact residual and bilateral authority and atomically
     36     /// retain the release movement; a timeout or missing ACK proves neither.
     37     pub fn release_committed(self, quantity: StockTicks) -> Result<Self, StockError> {
     38         self.transfer_held(
     39             HeldStockCategory::Committed,
     40             Destination::Available,
     41             quantity,
     42         )
     43     }
     44 
     45     /// Proposes physical consumption of original committed backing. Exactly-once
     46     /// handover identity, authority, residual and version checks belong to the
     47     /// atomic executor. Buyer receipts must never call this movement again.
     48     pub fn consume_committed(self, quantity: StockTicks) -> Result<Self, StockError> {
     49         self.transfer_held(
     50             HeldStockCategory::Committed,
     51             Destination::Consumed,
     52             quantity,
     53         )
     54     }
     55 
     56     /// Proposes retention of preparatory backing under unresolved issuance risk.
     57     /// Expiry cannot release it or establish nonissuance.
     58     pub fn quarantine_preparatory(self, quantity: StockTicks) -> Result<Self, StockError> {
     59         self.transfer_held(
     60             HeldStockCategory::Preparatory,
     61             Destination::Quarantined,
     62             quantity,
     63         )
     64     }
     65 
     66     /// Proposes retention of installed backing under unresolved risk. Original
     67     /// allocation and obligation linkage must survive the actual transaction.
     68     pub fn quarantine_committed(self, quantity: StockTicks) -> Result<Self, StockError> {
     69         self.transfer_held(
     70             HeldStockCategory::Committed,
     71             Destination::Quarantined,
     72             quantity,
     73         )
     74     }
     75 
     76     /// Proposes restoration to committed backing after qualified reconciliation.
     77     /// This value neither resolves unknown issuance nor authorizes a retry.
     78     pub fn restore_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> {
     79         self.transfer_held(
     80             HeldStockCategory::Quarantined,
     81             Destination::Committed,
     82             quantity,
     83         )
     84     }
     85 
     86     /// Proposes a release after original nonissuance or authorized residual
     87     /// resolution is proven. An expired lease, query or absent record is no proof.
     88     pub fn release_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> {
     89         self.transfer_held(
     90             HeldStockCategory::Quarantined,
     91             Destination::Available,
     92             quantity,
     93         )
     94     }
     95 
     96     /// Proposes consumption after original handover evidence is reconciled. The
     97     /// executor must install the same handover once, retaining its original claim.
     98     pub fn consume_quarantined(self, quantity: StockTicks) -> Result<Self, StockError> {
     99         self.transfer_held(
    100             HeldStockCategory::Quarantined,
    101             Destination::Consumed,
    102             quantity,
    103         )
    104     }
    105 
    106     /// Proposes depletion of actually present backing. It preserves lifetime
    107     /// introduced stock and never releases capacity. The executor must retain
    108     /// affected original claims and reconcile any outstanding obligation to a
    109     /// deficit in the same transaction; this physical value cannot delete it.
    110     pub fn deplete_held(
    111         self,
    112         category: HeldStockCategory,
    113         loss: HeldStockLoss,
    114         quantity: StockTicks,
    115     ) -> Result<Self, StockError> {
    116         let destination = match loss {
    117             HeldStockLoss::Spoilage => Destination::Waste,
    118             HeldStockLoss::Removal => Destination::Removed,
    119         };
    120         self.transfer_held(category, destination, quantity)
    121     }
    122 
    123     fn transfer_held(
    124         self,
    125         category: HeldStockCategory,
    126         destination: Destination,
    127         quantity: StockTicks,
    128     ) -> Result<Self, StockError> {
    129         if quantity == StockTicks::ZERO {
    130             return Err(StockError::ZeroMovement);
    131         }
    132         let mut physical = self.physical();
    133         let source = match category {
    134             HeldStockCategory::Preparatory => &mut physical.preparatory_hold,
    135             HeldStockCategory::Committed => &mut physical.committed_hold,
    136             HeldStockCategory::Quarantined => &mut physical.physical_quarantine,
    137         };
    138         *source = source.checked_sub(quantity)?;
    139         let target = match destination {
    140             Destination::Available => &mut physical.available,
    141             Destination::Committed => &mut physical.committed_hold,
    142             Destination::Quarantined => &mut physical.physical_quarantine,
    143             Destination::Consumed => &mut physical.consumed,
    144             Destination::Waste => &mut physical.waste,
    145             Destination::Removed => &mut physical.removed,
    146         };
    147         *target = target.checked_add(quantity)?;
    148         Self::new(self.introduced(), physical)
    149     }
    150 }