Skip to main content

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}