qualia_core_db/net/qdnf/economics/
obligation.rs1use crate::crypto::network::digest::sha384;
4use crate::net::qdnf::errors::QdnfError;
5use crate::net::qdnf::types::StrongDigest;
6
7pub(crate) const MAX_OPS: usize = 16;
9
10const ID_DOMAIN: &[u8; 20] = b"qdnf:obligation:id:1";
11
12#[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#[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 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 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 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 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
113pub 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
136pub fn remaining_recovery(ob: &Obligation) -> Result<u64, QdnfError> {
138 let used = used_swh(ob)?;
139 Ok(ob.target_t.saturating_sub(used))
140}
141
142pub fn is_funded(ob: &Obligation) -> Result<bool, QdnfError> {
144 Ok(remaining_recovery(ob)? > 0)
145}
146
147pub 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}