spacedb_meter/usage.rs
1//! What gets measured — the three resource classes, computed deterministically.
2//!
3//! SpaceDB only ever produces *amounts*, never prices: the same input gives the
4//! same number on every node, so a claim is reproducible and a host can't be
5//! over-billed. Pricing is a separate, swappable concern ([`crate::RateCard`]).
6
7use serde::{Deserialize, Serialize};
8
9/// A measured amount of one resource class over a period.
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
11pub enum Usage {
12 /// Bytes held, integrated over time and **multiplied by replica count** —
13 /// erasure/replication is real cost, so it is metered honestly.
14 Storage { byte_seconds: u128 },
15 /// On-node compute: deterministic `fuel` consumed (M6 `FunctionRun.fuel_used`)
16 /// across some number of `invocations`.
17 Compute { fuel: u64, invocations: u64 },
18 /// Bytes served to a peer — query results and sync.
19 Transit { bytes_served: u64 },
20}
21
22impl Usage {
23 /// Storage held: `bytes × seconds × replica_count`. Three replicas of the same
24 /// bytes for the same time cost three times as much, because they are.
25 pub fn storage(bytes: u64, seconds: u64, replica_count: u32) -> Usage {
26 Usage::Storage {
27 byte_seconds: bytes as u128 * seconds as u128 * replica_count as u128,
28 }
29 }
30
31 /// Compute consumed by `invocations` runs totalling `fuel` units.
32 pub fn compute(fuel: u64, invocations: u64) -> Usage {
33 Usage::Compute { fuel, invocations }
34 }
35
36 /// Transit billed at the **minimum** of what the server claims to have sent and
37 /// what the consumer acknowledges receiving — neither side can inflate it. This
38 /// is the bilateral-corroboration rule: bill what both agree on.
39 pub fn transit(server_claimed: u64, consumer_acked: u64) -> Usage {
40 Usage::Transit {
41 bytes_served: server_claimed.min(consumer_acked),
42 }
43 }
44
45 /// The resource class of this amount.
46 pub fn resource(&self) -> Resource {
47 match self {
48 Usage::Storage { .. } => Resource::Storage,
49 Usage::Compute { .. } => Resource::Compute,
50 Usage::Transit { .. } => Resource::Transit,
51 }
52 }
53}
54
55/// The class of a resource — the settlement bucket.
56#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
57pub enum Resource {
58 Storage,
59 Compute,
60 Transit,
61}
62
63impl Resource {
64 /// A stable tag used in deterministic claim ids.
65 pub fn tag(&self) -> &'static str {
66 match self {
67 Resource::Storage => "storage",
68 Resource::Compute => "compute",
69 Resource::Transit => "transit",
70 }
71 }
72}
73
74/// What kind of proof backs a claim (mirrors maestro's `ProofKind`).
75#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
76pub enum ProofKind {
77 StorageProbe,
78 ComputeAttestation,
79 TransitReceipt,
80}
81
82/// A content-addressed link to the artifact that backs a claim — e.g. a
83/// `FunctionRun` digest (M6) or a proof-of-storage probe response.
84#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
85pub struct ProofRef {
86 pub kind: ProofKind,
87 /// BLAKE3 digest of the proof artifact.
88 pub digest: [u8; 32],
89 /// Unix seconds.
90 pub at: u64,
91}