Skip to main content

qualia_core_db/net/qdnf/economics/
router.rs

1//! Funded in-process “turn on router” (E18.6). Live rails stay Unsupported.
2
3use crate::net::peer::runtime::ResourceBudget;
4use crate::net::qdnf::errors::QdnfError;
5use crate::net::qdnf::types::StrongDigest;
6
7use super::adapter::{settle_in_process, SettlementRail};
8use super::classify::ActingClass;
9use super::meters::{meter_admits_service, MeterReading};
10use super::obligation::Obligation;
11use super::roles::{role_admits_router, RoleGrant};
12use super::settle::SettlementReceipt;
13
14/// In-process router. Off until a funded settlement admits the routing role.
15#[derive(Debug, PartialEq, Eq)]
16pub struct InProcessRouter {
17    on: bool,
18    remaining: ResourceBudget,
19    funding_source: StrongDigest,
20}
21
22impl InProcessRouter {
23    /// An off router with a zero budget and no funding source — it can
24    /// only be switched on by [`turn_on_router`] with a funded
25    /// settlement.
26    pub const fn new() -> Self {
27        Self {
28            on: false,
29            remaining: ResourceBudget::ZERO,
30            funding_source: StrongDigest::ZERO,
31        }
32    }
33
34    /// True once a funded settlement has admitted the routing role.
35    #[inline]
36    pub const fn is_on(&self) -> bool {
37        self.on
38    }
39
40    /// Unspent budget granted by the role grant; decremented by
41    /// [`admit_router_work`]. Zero while off.
42    #[inline]
43    pub const fn remaining_budget(&self) -> ResourceBudget {
44        self.remaining
45    }
46
47    /// Digest identifying the settlement that funded this router;
48    /// `StrongDigest::ZERO` while off.
49    #[inline]
50    pub const fn funding_source(&self) -> StrongDigest {
51        self.funding_source
52    }
53}
54
55impl Default for InProcessRouter {
56    /// Equivalent to [`InProcessRouter::new`].
57    fn default() -> Self {
58        Self::new()
59    }
60}
61
62/// Component-wise `have - cost` over bytes/work/io; any underflow
63/// yields `BudgetExhausted` rather than wrapping.
64fn subtract_budget(
65    have: ResourceBudget,
66    cost: ResourceBudget,
67) -> Result<ResourceBudget, QdnfError> {
68    Ok(ResourceBudget {
69        bytes: have
70            .bytes
71            .checked_sub(cost.bytes)
72            .ok_or(QdnfError::BudgetExhausted)?,
73        work: have
74            .work
75            .checked_sub(cost.work)
76            .ok_or(QdnfError::BudgetExhausted)?,
77        io: have
78            .io
79            .checked_sub(cost.io)
80            .ok_or(QdnfError::BudgetExhausted)?,
81    })
82}
83
84/// Admit routing from a funded in-process settlement. Role and meter gates apply first.
85pub fn turn_on_router(
86    router: &mut InProcessRouter,
87    ob: &mut Obligation,
88    grant: RoleGrant,
89    meter: MeterReading,
90    class: ActingClass,
91    quote_a: u64,
92    op_id: StrongDigest,
93) -> Result<SettlementReceipt, QdnfError> {
94    if router.on {
95        return Err(QdnfError::Conflict);
96    }
97    role_admits_router(&grant)?;
98    let _ = meter_admits_service(meter)?;
99    let receipt = settle_in_process(ob, SettlementRail::InProcess, class, quote_a, op_id)?;
100    router.on = true;
101    router.remaining = grant.budget;
102    router.funding_source = grant.funding_source;
103    Ok(receipt)
104}
105
106/// Charge remaining provider budget. Exhaustion does not turn the router off.
107pub fn admit_router_work(
108    router: &mut InProcessRouter,
109    cost: ResourceBudget,
110) -> Result<(), QdnfError> {
111    if !router.on {
112        return Err(QdnfError::Denied);
113    }
114    router.remaining = subtract_budget(router.remaining, cost)?;
115    Ok(())
116}
117
118#[cfg(test)]
119mod tests {
120    use super::*;
121    use crate::crypto::network::digest::sha384;
122    use crate::net::qdnf::authority::ObservationQuality;
123    use crate::net::qdnf::economics::adapter::{live_ilp_adapter, live_rail, live_stripe_adapter};
124    use crate::net::qdnf::economics::meters::MeterKind;
125    use crate::net::qdnf::economics::roles::{
126        activate_role, natural_person_wallet_required, FundedRole,
127    };
128    use crate::net::qdnf::economics::settle::live_payment_rail;
129
130    fn funded_ob() -> Obligation {
131        Obligation::open(sha384(b"e18-router-ob"), 10).unwrap()
132    }
133
134    fn budget() -> ResourceBudget {
135        ResourceBudget {
136            bytes: 64,
137            work: 4,
138            io: 4,
139        }
140    }
141
142    fn routing_grant() -> RoleGrant {
143        activate_role(FundedRole::Routing, budget(), sha384(b"commons-fund")).unwrap()
144    }
145
146    fn measured_net() -> MeterReading {
147        MeterReading {
148            kind: MeterKind::NetBytes,
149            milli_units: 8,
150            quality: ObservationQuality::Measured,
151        }
152    }
153
154    fn op(tag: u8) -> StrongDigest {
155        sha384(&[tag])
156    }
157
158    #[test]
159    fn funded_obligation_turns_on_in_process_router_and_emits_receipt() {
160        let mut router = InProcessRouter::new();
161        let mut ob = funded_ob();
162        let grant = routing_grant();
163        let rcpt = turn_on_router(
164            &mut router,
165            &mut ob,
166            grant,
167            measured_net(),
168            ActingClass::Corporate,
169            5,
170            op(1),
171        )
172        .unwrap();
173        assert!(router.is_on());
174        assert_eq!(rcpt.obligation_id, ob.id);
175        assert_eq!(rcpt.op_id, op(1));
176        assert_eq!(rcpt.amount, 5);
177        assert_eq!(ob.settled_s, 5);
178        assert_eq!(router.remaining_budget(), budget());
179        assert_eq!(router.funding_source(), grant.funding_source);
180        assert!(!natural_person_wallet_required());
181        assert_eq!(live_payment_rail(), Err(QdnfError::Unsupported));
182        assert_eq!(live_stripe_adapter(), Err(QdnfError::Unsupported));
183        assert_eq!(live_ilp_adapter(), Err(QdnfError::Unsupported));
184        assert_eq!(
185            live_rail(SettlementRail::LiveStripe),
186            Err(QdnfError::Unsupported)
187        );
188        assert_eq!(
189            turn_on_router(
190                &mut router,
191                &mut ob,
192                grant,
193                measured_net(),
194                ActingClass::Corporate,
195                1,
196                op(9)
197            ),
198            Err(QdnfError::Conflict)
199        );
200    }
201
202    #[test]
203    fn unfunded_obligation_cannot_turn_router_on() {
204        let mut router = InProcessRouter::new();
205        let mut empty = Obligation::open(sha384(b"e18-unfunded"), 0).unwrap();
206        assert_eq!(
207            turn_on_router(
208                &mut router,
209                &mut empty,
210                routing_grant(),
211                measured_net(),
212                ActingClass::Corporate,
213                5,
214                op(2)
215            ),
216            Err(QdnfError::Denied)
217        );
218        assert!(!router.is_on());
219        let mut humanitarian = funded_ob();
220        assert_eq!(
221            turn_on_router(
222                &mut router,
223                &mut humanitarian,
224                routing_grant(),
225                measured_net(),
226                ActingClass::Humanitarian,
227                5,
228                op(3)
229            ),
230            Err(QdnfError::Denied)
231        );
232        assert!(!router.is_on());
233        assert_eq!(humanitarian.settled_s, 0);
234        assert_eq!(humanitarian.holds_h, 0);
235    }
236
237    #[test]
238    fn role_and_meter_gates_still_apply() {
239        let src = sha384(b"commons-fund");
240        let mut router = InProcessRouter::new();
241        let mut ob = funded_ob();
242        let relay = activate_role(FundedRole::Relay, budget(), src).unwrap();
243        assert_eq!(
244            turn_on_router(
245                &mut router,
246                &mut ob,
247                relay,
248                measured_net(),
249                ActingClass::Corporate,
250                5,
251                op(4)
252            ),
253            Err(QdnfError::Denied)
254        );
255        assert!(!router.is_on());
256        assert_eq!(ob.settled_s, 0);
257
258        let unknown = MeterReading {
259            kind: MeterKind::NetBytes,
260            milli_units: 8,
261            quality: ObservationQuality::Unknown,
262        };
263        assert_eq!(
264            turn_on_router(
265                &mut router,
266                &mut ob,
267                routing_grant(),
268                unknown,
269                ActingClass::Corporate,
270                5,
271                op(5)
272            ),
273            Err(QdnfError::Incomplete)
274        );
275        assert!(!router.is_on());
276        assert_eq!(ob.holds_h, 0);
277
278        let empty_budget = activate_role(FundedRole::Routing, ResourceBudget::ZERO, src).unwrap();
279        assert_eq!(
280            turn_on_router(
281                &mut router,
282                &mut ob,
283                empty_budget,
284                measured_net(),
285                ActingClass::Corporate,
286                5,
287                op(6)
288            ),
289            Err(QdnfError::BudgetExhausted)
290        );
291        assert!(!router.is_on());
292
293        let grant = routing_grant();
294        turn_on_router(
295            &mut router,
296            &mut ob,
297            grant,
298            measured_net(),
299            ActingClass::Corporate,
300            5,
301            op(7),
302        )
303        .unwrap();
304        admit_router_work(&mut router, grant.budget).unwrap();
305        assert_eq!(
306            admit_router_work(
307                &mut router,
308                ResourceBudget {
309                    bytes: 1,
310                    work: 0,
311                    io: 0
312                }
313            ),
314            Err(QdnfError::BudgetExhausted)
315        );
316        assert!(router.is_on());
317        assert_eq!(router.remaining_budget(), ResourceBudget::ZERO);
318    }
319}