Skip to main content

qualia_core_db/net/qdnf/economics/
adapter.rs

1//! In-process settlement adapter (E18.4). Live rails stay Unsupported.
2
3use crate::net::qdnf::errors::QdnfError;
4use crate::net::qdnf::types::StrongDigest;
5
6use super::classify::ActingClass;
7use super::obligation::Obligation;
8use super::reserve::reserve_hold;
9#[cfg(test)]
10use super::settle::live_payment_rail;
11use super::settle::{finalise, settlement_receipt, SettlementReceipt};
12
13/// Selected settlement systems. Only [`Self::InProcess`] may settle here.
14#[repr(u8)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub enum SettlementRail {
17    InProcess = 1,
18    LiveStripe = 2,
19    LiveIlp = 3,
20}
21
22/// Capped local micro-charges. Pending cannot exceed `cap`.
23#[derive(Debug, PartialEq, Eq)]
24pub struct MicropaymentAggregate {
25    pending: u64,
26    cap: u64,
27}
28
29impl MicropaymentAggregate {
30    /// Creates a default `MicropaymentAggregate`.
31    pub fn new(cap: u64) -> Result<Self, QdnfError> {
32        if cap == 0 {
33            return Err(QdnfError::Malformed);
34        }
35        Ok(Self { pending: 0, cap })
36    }
37
38    #[inline]
39    /// `MicropaymentAggregate::pending`.
40    pub const fn pending(&self) -> u64 {
41        self.pending
42    }
43
44    #[inline]
45    /// `MicropaymentAggregate::cap`.
46    pub const fn cap(&self) -> u64 {
47        self.cap
48    }
49}
50
51/// Live Stripe adapter. Never a fake success path.
52#[inline]
53pub fn live_stripe_adapter() -> Result<(), QdnfError> {
54    Err(QdnfError::Unsupported)
55}
56
57/// Live Interledger adapter. Never a fake success path.
58#[inline]
59pub fn live_ilp_adapter() -> Result<(), QdnfError> {
60    Err(QdnfError::Unsupported)
61}
62
63/// Any live rail API is Unsupported. In-process settlement is not a live rail.
64#[inline]
65pub fn live_rail(_rail: SettlementRail) -> Result<(), QdnfError> {
66    Err(QdnfError::Unsupported)
67}
68
69/// Accumulate a micro charge. Exceeding the cap is Denied, never a silent enlarge.
70pub fn aggregate_micro(agg: &mut MicropaymentAggregate, amount: u64) -> Result<u64, QdnfError> {
71    if amount == 0 {
72        return Ok(agg.pending);
73    }
74    let next = agg.pending.checked_add(amount).ok_or(QdnfError::Range)?;
75    if next > agg.cap {
76        return Err(QdnfError::Denied);
77    }
78    agg.pending = next;
79    Ok(agg.pending)
80}
81
82/// Funded in-process settlement. Live rails do not mutate the obligation.
83pub fn settle_in_process(
84    ob: &mut Obligation,
85    rail: SettlementRail,
86    class: ActingClass,
87    quote_a: u64,
88    op_id: StrongDigest,
89) -> Result<SettlementReceipt, QdnfError> {
90    match rail {
91        SettlementRail::InProcess => {}
92        SettlementRail::LiveStripe | SettlementRail::LiveIlp => {
93            return Err(QdnfError::Unsupported);
94        }
95    }
96    let held = reserve_hold(ob, quote_a, class, op_id)?;
97    if held == 0 {
98        return Err(QdnfError::Denied);
99    }
100    finalise(ob, held, op_id, false)?;
101    Ok(settlement_receipt(ob, op_id, held))
102}
103
104/// Drain a capped aggregate through the in-process adapter.
105pub fn settle_aggregate(
106    ob: &mut Obligation,
107    agg: &mut MicropaymentAggregate,
108    class: ActingClass,
109    op_id: StrongDigest,
110) -> Result<SettlementReceipt, QdnfError> {
111    if agg.pending == 0 {
112        return Err(QdnfError::Incomplete);
113    }
114    let amount = agg.pending;
115    let receipt = settle_in_process(ob, SettlementRail::InProcess, class, amount, op_id)?;
116    agg.pending = 0;
117    Ok(receipt)
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123    use crate::crypto::network::digest::sha384;
124
125    fn open(t: u64) -> Obligation {
126        Obligation::open(sha384(b"e18-adapter-ob"), t).unwrap()
127    }
128
129    fn op(tag: u8) -> StrongDigest {
130        sha384(&[tag])
131    }
132
133    #[test]
134    fn live_rails_stay_unsupported_and_do_not_mutate() {
135        let mut ob = open(8);
136        let rev = ob.revision;
137        assert_eq!(live_payment_rail(), Err(QdnfError::Unsupported));
138        assert_eq!(live_stripe_adapter(), Err(QdnfError::Unsupported));
139        assert_eq!(live_ilp_adapter(), Err(QdnfError::Unsupported));
140        assert_eq!(
141            live_rail(SettlementRail::InProcess),
142            Err(QdnfError::Unsupported)
143        );
144        assert_eq!(
145            live_rail(SettlementRail::LiveStripe),
146            Err(QdnfError::Unsupported)
147        );
148        assert_eq!(
149            live_rail(SettlementRail::LiveIlp),
150            Err(QdnfError::Unsupported)
151        );
152        assert_eq!(
153            settle_in_process(
154                &mut ob,
155                SettlementRail::LiveStripe,
156                ActingClass::Corporate,
157                4,
158                op(1)
159            ),
160            Err(QdnfError::Unsupported)
161        );
162        assert_eq!(
163            settle_in_process(
164                &mut ob,
165                SettlementRail::LiveIlp,
166                ActingClass::Corporate,
167                4,
168                op(2)
169            ),
170            Err(QdnfError::Unsupported)
171        );
172        assert_eq!(ob.revision, rev);
173        assert_eq!(ob.holds_h, 0);
174        assert_eq!(ob.settled_s, 0);
175    }
176
177    #[test]
178    fn in_process_settle_emits_receipt() {
179        let mut ob = open(6);
180        let rcpt = settle_in_process(
181            &mut ob,
182            SettlementRail::InProcess,
183            ActingClass::Corporate,
184            6,
185            op(3),
186        )
187        .unwrap();
188        assert_eq!(rcpt.obligation_id, ob.id);
189        assert_eq!(rcpt.op_id, op(3));
190        assert_eq!(rcpt.amount, 6);
191        assert_eq!(ob.settled_s, 6);
192        assert!(ob.fulfilled);
193        assert_eq!(
194            settle_in_process(
195                &mut ob,
196                SettlementRail::InProcess,
197                ActingClass::Corporate,
198                1,
199                op(4)
200            ),
201            Err(QdnfError::Denied)
202        );
203    }
204
205    #[test]
206    fn aggregation_cap_then_in_process_settle() {
207        let mut agg = MicropaymentAggregate::new(10).unwrap();
208        assert_eq!(aggregate_micro(&mut agg, 4).unwrap(), 4);
209        assert_eq!(aggregate_micro(&mut agg, 3).unwrap(), 7);
210        assert_eq!(aggregate_micro(&mut agg, 4), Err(QdnfError::Denied));
211        assert_eq!(agg.pending(), 7);
212        let mut ob = open(10);
213        let rcpt = settle_aggregate(&mut ob, &mut agg, ActingClass::Corporate, op(5)).unwrap();
214        assert_eq!(rcpt.amount, 7);
215        assert_eq!(agg.pending(), 0);
216        assert_eq!(ob.settled_s, 7);
217        assert_eq!(
218            settle_aggregate(&mut ob, &mut agg, ActingClass::Corporate, op(6)),
219            Err(QdnfError::Incomplete)
220        );
221        assert_eq!(MicropaymentAggregate::new(0), Err(QdnfError::Malformed));
222    }
223}