hyprstream_pay/types.rs
1//! Shared types for the settlement/tariff protocol (#1399).
2//!
3//! These types are the **MIT-licensed protocol surface** that
4//! `cyberdione-product` (and any other consumer) links against. The AGPL
5//! service implementation in `hyprstream::services::pay` consumes these traits
6//! and provides the real settlement-store + ledger-credit path.
7
8use serde::{Deserialize, Serialize};
9
10/// A resource unit reference — the unit names its issuer (INV-1 from the
11/// ledger crate). Carried in the protocol so a tariff quote can name the exact
12/// credit unit that will be issued.
13#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
14pub struct UnitRef {
15 /// The issuer's DID (the liability holder for this unit).
16 pub issuer_did: String,
17 /// e.g. `"gpu.h100.seconds"`.
18 pub resource_class: String,
19}
20
21/// A request to issue credits from a verified settlement (#1399, PAY-06).
22///
23/// The `attestation` is a PQ-hybrid-signed blob proving a committed settlement
24/// row exists in the restricted settlement store. The server re-verifies it
25/// against the issuer's key material before calling the ledger's internal
26/// credit path. A client assertion of "paid" is never sufficient.
27#[derive(Debug, Clone, Serialize, Deserialize)]
28pub struct IssueRequest {
29 /// Internal settlement row id (opaque to the product layer; the server
30 /// resolves it against its own restricted settlement store).
31 pub settlement_id: String,
32 /// PQ-hybrid-signed settlement attestation (COSE composite). The server
33 /// verifies this before issuing any credits.
34 pub attestation: Vec<u8>,
35 /// The unit to issue.
36 pub unit: UnitRef,
37 /// The DID of the credit destination (the purchaser's pseudonymous
38 /// identity — never legal identity, per PAY-00 #6).
39 pub destination_did: String,
40 /// Amount in minor units (u128 as hi/lo since JSON/capnp don't natively
41 /// carry u128). The server re-derives this from the settlement row; a
42 /// client-supplied value is never trusted.
43 pub amount_minor_lo: u64,
44 pub amount_minor_hi: u64,
45 /// The allocation grant CID this issuance backs (opaque bytes — the ledger
46 /// correlates but never parses it).
47 pub grant_cid: Vec<u8>,
48}
49
50impl IssueRequest {
51 /// The full u128 amount.
52 pub fn amount(&self) -> u128 {
53 ((self.amount_minor_hi as u128) << 64) | (self.amount_minor_lo as u128)
54 }
55}
56
57/// The response from an issuance request.
58#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
59pub struct IssueResponse {
60 /// The deterministic transfer id (idempotent: same `settlement_id` → same
61 /// transfer id across retries/crashes).
62 pub transfer_id_lo: u64,
63 pub transfer_id_hi: u64,
64 /// The journal sequence that recorded this outcome.
65 pub outcome_seq: u64,
66 /// Whether the issuance succeeded.
67 pub ok: bool,
68 /// Human-readable error detail if `!ok`.
69 pub error: Option<String>,
70}
71
72impl IssueResponse {
73 /// The full u128 transfer id.
74 pub fn transfer_id(&self) -> u128 {
75 ((self.transfer_id_hi as u128) << 64) | (self.transfer_id_lo as u128)
76 }
77}
78
79/// A tariff quote request — the product asks "what does this cost?" and the
80/// server owns the price, catalog, and ceiling (#1399, PAY-00 #3).
81#[derive(Debug, Clone, Serialize, Deserialize)]
82pub struct TariffRequest {
83 /// e.g. `"gpu.h100.seconds"`.
84 pub resource_class: String,
85 /// How many units of the resource.
86 pub quantity: u64,
87 /// The DID of the subject who will pay (for tier/allowance resolution).
88 pub subject_did: String,
89 /// Pinned catalog version (the product may carry a cached version; the
90 /// server validates it's still current).
91 pub catalog_version: String,
92}
93
94/// A server-owned priced quote with a finite maximum quantum.
95#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
96pub struct TariffQuote {
97 /// The unit that will be issued/debited.
98 pub unit: UnitRef,
99 /// Price in minor units (u128 as hi/lo).
100 pub price_minor_lo: u64,
101 pub price_minor_hi: u64,
102 /// Quote expiry (unix seconds). The reservation must be placed before this.
103 pub expires_at: u64,
104 /// The catalog version this quote was computed against.
105 pub catalog_version: String,
106 /// Server-imposed ceiling on the quantum for a single operation.
107 pub max_quantum: u64,
108}
109
110impl TariffQuote {
111 /// The full u128 price.
112 pub fn price(&self) -> u128 {
113 ((self.price_minor_hi as u128) << 64) | (self.price_minor_lo as u128)
114 }
115
116 /// Whether this quote is still valid at the given unix time.
117 pub fn is_valid_at(&self, now_unix: u64) -> bool {
118 now_unix < self.expires_at
119 }
120}