Skip to main content

qualia_core_db/net/qdnf/economics/
settle.rs

1//! Finalise, chargeback and fulfilment (E17.6–E17.7). Live rails are Unsupported.
2//!
3//! Funded in-process settlement is [`crate::net::qdnf::economics::adapter`].
4//! `live_payment_rail` stays Unsupported: no fake Stripe or ILP.
5
6use crate::net::qdnf::errors::QdnfError;
7use crate::net::qdnf::types::StrongDigest;
8
9use super::obligation::{Obligation, OpState};
10
11/// Move a live hold into settled S. Duplicate callback is idempotent.
12///
13/// Fulfil when S + W == T after checked add. Fulfilment does not skip privacy.
14pub fn finalise(
15    ob: &mut Obligation,
16    hold_amount: u64,
17    op_id: StrongDigest,
18    duplicate: bool,
19) -> Result<(), QdnfError> {
20    if op_id.is_zero() {
21        return Err(QdnfError::Malformed);
22    }
23    let i = match ob.find_op(op_id) {
24        Some(i) => i,
25        None => return Err(QdnfError::Incomplete),
26    };
27    match ob.ops[i].state {
28        OpState::Finalised => {
29            if ob.ops[i].amount != hold_amount {
30                return Err(QdnfError::Conflict);
31            }
32            let _ = duplicate;
33            Ok(())
34        }
35        OpState::Held => {
36            if ob.ops[i].amount != hold_amount {
37                return Err(QdnfError::Conflict);
38            }
39            ob.holds_h = ob
40                .holds_h
41                .checked_sub(hold_amount)
42                .ok_or(QdnfError::Range)?;
43            ob.settled_s = ob
44                .settled_s
45                .checked_add(hold_amount)
46                .ok_or(QdnfError::Denied)?;
47            ob.ops[i].state = OpState::Finalised;
48            let sw = ob
49                .settled_s
50                .checked_add(ob.discharged_w)
51                .ok_or(QdnfError::Range)?;
52            if sw == ob.target_t {
53                ob.fulfilled = true;
54            }
55            ob.bump_revision()
56        }
57        OpState::Empty => Err(QdnfError::Incomplete),
58        OpState::Cancelled | OpState::Reversed => Err(QdnfError::Denied),
59    }
60}
61
62/// Reverse settled S only. T is unchanged; fulfilment stays terminal.
63///
64/// Cannot resurrect unlimited creation debt. Duplicate reverse is idempotent.
65pub fn reverse(ob: &mut Obligation, amount: u64, op_id: StrongDigest) -> Result<(), QdnfError> {
66    if op_id.is_zero() {
67        return Err(QdnfError::Malformed);
68    }
69    let i = ob.find_op(op_id).ok_or(QdnfError::Incomplete)?;
70    match ob.ops[i].state {
71        OpState::Reversed => {
72            if ob.ops[i].amount != amount {
73                return Err(QdnfError::Conflict);
74            }
75            Ok(())
76        }
77        OpState::Finalised => {
78            if ob.ops[i].amount != amount {
79                return Err(QdnfError::Conflict);
80            }
81            ob.settled_s = ob.settled_s.checked_sub(amount).ok_or(QdnfError::Denied)?;
82            ob.ops[i].state = OpState::Reversed;
83            ob.bump_revision()
84        }
85        OpState::Held | OpState::Cancelled | OpState::Empty => Err(QdnfError::Denied),
86    }
87}
88
89/// Fulfilment never returns a flag that skips bilateral privacy.
90#[inline]
91pub fn fulfilment_bypasses_bilateral() -> bool {
92    false
93}
94
95/// E18.4 live settlement adapters are not in this foundation.
96#[inline]
97pub fn live_payment_rail() -> Result<(), QdnfError> {
98    Err(QdnfError::Unsupported)
99}
100
101/// Public settlement evidence. No patient / clinical label fields.
102#[repr(C)]
103#[derive(Clone, Copy, Debug, PartialEq, Eq)]
104pub struct SettlementReceipt {
105    pub obligation_id: StrongDigest,
106    pub op_id: StrongDigest,
107    pub amount: u64,
108}
109
110/// Builds the settlement receipt.
111pub fn settlement_receipt(ob: &Obligation, op_id: StrongDigest, amount: u64) -> SettlementReceipt {
112    SettlementReceipt {
113        obligation_id: ob.id,
114        op_id,
115        amount,
116    }
117}
118
119/// Public settlement must not include patient labels.
120#[inline]
121pub fn settlement_contains_patient_label() -> bool {
122    false
123}
124
125#[cfg(test)]
126mod tests {
127    use super::*;
128    use crate::crypto::network::digest::sha384;
129    use crate::net::qdnf::economics::classify::recovery_for_class;
130    use crate::net::qdnf::economics::classify::ActingClass;
131    use crate::net::qdnf::economics::reserve::reserve_hold;
132
133    fn open(t: u64) -> Obligation {
134        Obligation::open(sha384(b"settle-ob"), t).unwrap()
135    }
136
137    fn op(tag: u8) -> StrongDigest {
138        sha384(&[tag])
139    }
140
141    #[test]
142    fn econ_c_finalise_and_duplicate_callback() {
143        let mut ob = open(5);
144        let held = reserve_hold(&mut ob, 5, ActingClass::Corporate, op(1)).unwrap();
145        assert_eq!(held, 5);
146        finalise(&mut ob, 5, op(1), false).unwrap();
147        assert!(ob.fulfilled);
148        assert_eq!(ob.settled_s, 5);
149        assert_eq!(ob.holds_h, 0);
150        finalise(&mut ob, 5, op(1), true).unwrap();
151        assert_eq!(ob.settled_s, 5);
152        assert_eq!(ob.revision, 2);
153        assert!(!fulfilment_bypasses_bilateral());
154    }
155
156    #[test]
157    fn cross_provider_replay_same_op_id_is_idempotent() {
158        let mut ob = open(4);
159        reserve_hold(&mut ob, 2, ActingClass::Corporate, op(9)).unwrap();
160        finalise(&mut ob, 2, op(9), false).unwrap();
161        assert_eq!(
162            reserve_hold(&mut ob, 2, ActingClass::Corporate, op(9)).unwrap(),
163            2
164        );
165        assert_eq!(ob.settled_s, 2);
166        assert_eq!(ob.holds_h, 0);
167        finalise(&mut ob, 2, op(9), true).unwrap();
168        assert_eq!(ob.settled_s, 2);
169    }
170
171    #[test]
172    fn chargeback_reverses_s_only_and_does_not_grow_t() {
173        let mut ob = open(8);
174        reserve_hold(&mut ob, 8, ActingClass::Corporate, op(2)).unwrap();
175        finalise(&mut ob, 8, op(2), false).unwrap();
176        assert!(ob.fulfilled);
177        let t = ob.target_t;
178        reverse(&mut ob, 8, op(2)).unwrap();
179        assert_eq!(ob.settled_s, 0);
180        assert_eq!(ob.target_t, t);
181        assert!(ob.fulfilled);
182        assert_eq!(
183            recovery_for_class(ActingClass::Corporate, ob.fulfilled, 8),
184            0
185        );
186        reverse(&mut ob, 8, op(2)).unwrap();
187        assert_eq!(ob.target_t, 8);
188        assert_eq!(
189            reserve_hold(&mut ob, 8, ActingClass::Corporate, op(3)).unwrap(),
190            0
191        );
192        assert_eq!(ob.holds_h, 0);
193        assert_eq!(ob.target_t, 8);
194    }
195
196    #[test]
197    fn econ_f_fulfilment_does_not_bypass_bilateral() {
198        let mut ob = open(1);
199        reserve_hold(&mut ob, 1, ActingClass::Corporate, op(4)).unwrap();
200        finalise(&mut ob, 1, op(4), false).unwrap();
201        assert!(ob.fulfilled);
202        assert!(!fulfilment_bypasses_bilateral());
203        assert!(!settlement_contains_patient_label());
204        let rcpt = settlement_receipt(&ob, op(4), 1);
205        assert_eq!(rcpt.obligation_id, ob.id);
206        assert_eq!(live_payment_rail(), Err(QdnfError::Unsupported));
207    }
208
209    #[test]
210    fn unknown_finalise_is_incomplete() {
211        let mut ob = open(1);
212        assert_eq!(
213            finalise(&mut ob, 1, op(7), false),
214            Err(QdnfError::Incomplete)
215        );
216    }
217}