Skip to main content

qualia_core_db/net/qdnf/economics/
obligation.rs

1//! Stable project-obligation owner (E17.1–E17.2). Copied milli-units are not this.
2
3use crate::crypto::network::digest::sha384;
4use crate::net::qdnf::errors::QdnfError;
5use crate::net::qdnf::types::StrongDigest;
6
7/// Bounded operation table. Duplicate `op_id` is looked up here, not hashed.
8pub(crate) const MAX_OPS: usize = 16;
9
10const ID_DOMAIN: &[u8; 20] = b"qdnf:obligation:id:1";
11
12/// Lifecycle of one operation against the obligation.
13#[repr(u8)]
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub(crate) enum OpState {
16    Empty = 0,
17    Held = 1,
18    Finalised = 2,
19    Cancelled = 3,
20    Reversed = 4,
21}
22
23#[derive(Clone, Copy, Debug, PartialEq, Eq)]
24pub(crate) struct OpRecord {
25    pub op_id: StrongDigest,
26    pub amount: u64,
27    pub state: OpState,
28}
29
30impl OpRecord {
31    pub(crate) const EMPTY: Self = Self {
32        op_id: StrongDigest::ZERO,
33        amount: 0,
34        state: OpState::Empty,
35    };
36}
37
38/// Durable obligation identity and finite recovery accounting.
39///
40/// T = target, S = settled recovery, W = authorised non-cash discharge, H = holds.
41/// Invariant: S + W + H <= T. Not `Copy`: the owner is this record, not a copied balance.
42#[derive(Debug, PartialEq, Eq)]
43pub struct Obligation {
44    pub id: StrongDigest,
45    pub target_t: u64,
46    pub settled_s: u64,
47    pub discharged_w: u64,
48    pub holds_h: u64,
49    pub fulfilled: bool,
50    pub revision: u64,
51    pub(crate) ops: [OpRecord; MAX_OPS],
52}
53
54impl Obligation {
55    /// Open a new owner. Identity is a SHA-384 digest; zero is Malformed.
56    pub fn open(id: StrongDigest, target_t: u64) -> Result<Self, QdnfError> {
57        if id.is_zero() {
58            return Err(QdnfError::Malformed);
59        }
60        Ok(Self {
61            id,
62            target_t,
63            settled_s: 0,
64            discharged_w: 0,
65            holds_h: 0,
66            fulfilled: target_t == 0,
67            revision: 0,
68            ops: [OpRecord::EMPTY; MAX_OPS],
69        })
70    }
71
72    /// Slot index of obligation `op_id`, or `None`.
73    pub(crate) fn find_op(&self, op_id: StrongDigest) -> Option<usize> {
74        let mut i = 0;
75        while i < MAX_OPS {
76            if self.ops[i].state != OpState::Empty && self.ops[i].op_id == op_id {
77                return Some(i);
78            }
79            i += 1;
80        }
81        None
82    }
83
84    /// Inserts an obligation; error at capacity.
85    pub(crate) fn insert_op(
86        &mut self,
87        op_id: StrongDigest,
88        amount: u64,
89        state: OpState,
90    ) -> Result<usize, QdnfError> {
91        let mut i = 0;
92        while i < MAX_OPS {
93            if self.ops[i].state == OpState::Empty {
94                self.ops[i] = OpRecord {
95                    op_id,
96                    amount,
97                    state,
98                };
99                return Ok(i);
100            }
101            i += 1;
102        }
103        Err(QdnfError::Capacity)
104    }
105
106    /// Bumps the revision counter.
107    pub(crate) fn bump_revision(&mut self) -> Result<(), QdnfError> {
108        self.revision = self.revision.checked_add(1).ok_or(QdnfError::Range)?;
109        Ok(())
110    }
111}
112
113/// SHA-384 identity covering project, providers, funding source and version.
114pub fn bind_obligation_id(
115    project: &StrongDigest,
116    providers: &StrongDigest,
117    funding_source: &StrongDigest,
118    version: u64,
119) -> StrongDigest {
120    let mut buf = [0u8; 20 + 48 + 48 + 48 + 8];
121    buf[..20].copy_from_slice(ID_DOMAIN);
122    buf[20..68].copy_from_slice(&project.0);
123    buf[68..116].copy_from_slice(&providers.0);
124    buf[116..164].copy_from_slice(&funding_source.0);
125    buf[164..172].copy_from_slice(&version.to_be_bytes());
126    sha384(&buf)
127}
128
129fn used_swh(ob: &Obligation) -> Result<u64, QdnfError> {
130    ob.settled_s
131        .checked_add(ob.discharged_w)
132        .and_then(|x| x.checked_add(ob.holds_h))
133        .ok_or(QdnfError::Range)
134}
135
136/// Remaining recoverable creation cost: max(0, T − S − W − H) with checked adds.
137pub fn remaining_recovery(ob: &Obligation) -> Result<u64, QdnfError> {
138    let used = used_swh(ob)?;
139    Ok(ob.target_t.saturating_sub(used))
140}
141
142/// True when unused recovery remains to fund an in-process settlement.
143pub fn is_funded(ob: &Obligation) -> Result<bool, QdnfError> {
144    Ok(remaining_recovery(ob)? > 0)
145}
146
147/// Authorised non-cash discharge W. Denied if it would exceed remaining T.
148pub fn authorise_discharge(ob: &mut Obligation, amount: u64) -> Result<(), QdnfError> {
149    if amount == 0 {
150        return Ok(());
151    }
152    let remaining = remaining_recovery(ob)?;
153    if amount > remaining {
154        return Err(QdnfError::Denied);
155    }
156    ob.discharged_w = ob
157        .discharged_w
158        .checked_add(amount)
159        .ok_or(QdnfError::Denied)?;
160    let sw = ob
161        .settled_s
162        .checked_add(ob.discharged_w)
163        .ok_or(QdnfError::Range)?;
164    if sw == ob.target_t {
165        ob.fulfilled = true;
166    }
167    ob.bump_revision()
168}
169
170#[cfg(test)]
171mod tests {
172    use super::*;
173
174    fn id() -> StrongDigest {
175        sha384(b"ob-econ-a")
176    }
177
178    #[test]
179    fn econ_a_checked_remaining_and_units() {
180        let mut ob = Obligation::open(id(), 10).unwrap();
181        assert_eq!(remaining_recovery(&ob).unwrap(), 10);
182        ob.settled_s = 3;
183        ob.discharged_w = 2;
184        ob.holds_h = 1;
185        assert_eq!(remaining_recovery(&ob).unwrap(), 4);
186        ob.settled_s = 10;
187        ob.discharged_w = 1;
188        ob.holds_h = 0;
189        assert_eq!(remaining_recovery(&ob).unwrap(), 0);
190        ob.settled_s = u64::MAX;
191        ob.discharged_w = 1;
192        ob.holds_h = 0;
193        assert_eq!(remaining_recovery(&ob), Err(QdnfError::Range));
194    }
195
196    #[test]
197    fn zero_identity_is_malformed() {
198        assert_eq!(
199            Obligation::open(StrongDigest::ZERO, 1).err(),
200            Some(QdnfError::Malformed)
201        );
202    }
203
204    #[test]
205    fn identity_is_sha384_and_field_sensitive() {
206        let p = sha384(b"project");
207        let r = sha384(b"providers");
208        let f = sha384(b"funding");
209        let a = bind_obligation_id(&p, &r, &f, 1);
210        let b = bind_obligation_id(&p, &r, &f, 1);
211        let c = bind_obligation_id(&p, &r, &f, 2);
212        assert_eq!(a, b);
213        assert_ne!(a, c);
214        assert_ne!(a, StrongDigest::ZERO);
215        assert_eq!(a.0.len(), 48);
216    }
217
218    #[test]
219    fn discharge_cannot_exceed_remaining() {
220        let mut ob = Obligation::open(id(), 5).unwrap();
221        assert!(authorise_discharge(&mut ob, 5).is_ok());
222        assert!(ob.fulfilled);
223        assert_eq!(remaining_recovery(&ob).unwrap(), 0);
224        assert_eq!(authorise_discharge(&mut ob, 1), Err(QdnfError::Denied));
225        assert_eq!(ob.target_t, 5);
226    }
227
228    #[test]
229    fn open_target_is_funded_zero_target_is_not() {
230        let funded = Obligation::open(id(), 5).unwrap();
231        assert!(is_funded(&funded).unwrap());
232        let empty = Obligation::open(id(), 0).unwrap();
233        assert!(!is_funded(&empty).unwrap());
234    }
235}