Skip to main content

bolt12_common/
model.rs

1use serde::Serialize;
2
3/// Curated decode of a BOLT 12 string.
4#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
5#[serde(tag = "type", rename_all = "snake_case")]
6#[allow(clippy::large_enum_variant)]
7pub enum Decoded {
8    Offer(Offer),
9    Invoice(Invoice),
10    PayerProof(PayerProof),
11}
12
13#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
14pub struct Offer {
15    pub offer_id: String,
16    pub chains: Vec<String>,
17    #[serde(skip_serializing_if = "Option::is_none")]
18    pub metadata: Option<String>,
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub amount: Option<Amount>,
21    #[serde(skip_serializing_if = "Option::is_none")]
22    pub description: Option<String>,
23    #[serde(skip_serializing_if = "Option::is_none")]
24    pub features: Option<String>,
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub absolute_expiry: Option<u64>,
27    #[serde(skip_serializing_if = "Vec::is_empty")]
28    pub paths: Vec<BlindedPath>,
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub issuer: Option<String>,
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub quantity_max: Option<u64>,
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub issuer_id: Option<String>,
35}
36
37#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
38pub struct Invoice {
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub offer_id: Option<String>,
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub offer_chains: Option<Vec<String>>,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub metadata: Option<String>,
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub offer_amount: Option<Amount>,
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub description: Option<String>,
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub offer_features: Option<String>,
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub absolute_expiry: Option<u64>,
53    #[serde(skip_serializing_if = "Vec::is_empty")]
54    pub offer_paths: Vec<BlindedPath>,
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub issuer: Option<String>,
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub quantity_max: Option<u64>,
59    #[serde(skip_serializing_if = "Option::is_none")]
60    pub issuer_id: Option<String>,
61    pub chain: String,
62    #[serde(skip_serializing_if = "Option::is_none")]
63    pub payer_metadata: Option<String>,
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub invoice_request_features: Option<String>,
66    #[serde(skip_serializing_if = "Option::is_none")]
67    pub quantity: Option<u64>,
68    pub payer_id: String,
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub payer_note: Option<String>,
71    #[serde(skip_serializing_if = "Vec::is_empty")]
72    pub payment_paths: Vec<BlindedPath>,
73    pub created_at: u64,
74    pub relative_expiry: u64,
75    pub payment_hash: String,
76    pub amount_msat: u64,
77    #[serde(skip_serializing_if = "Vec::is_empty")]
78    pub fallbacks: Vec<String>,
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub invoice_features: Option<String>,
81    pub node_id: String,
82    pub signature: String,
83    #[serde(skip_serializing_if = "Vec::is_empty")]
84    pub unknown_invoice_tlvs: Vec<UnknownTlv>,
85}
86
87/// Unknown TLV in the invoice type range (160–239).
88#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
89pub struct UnknownTlv {
90    #[serde(rename = "type")]
91    pub type_id: u64,
92    pub length: u64,
93    pub value: String,
94}
95
96#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
97pub struct PayerProof {
98    pub payer_id: String,
99    pub issuer_id: String,
100    pub payment_hash: String,
101    pub payment_preimage: String,
102    pub merkle_root: String,
103    pub invoice_signature: String,
104    pub proof_signature: String,
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub amount_msat: Option<u64>,
107    #[serde(skip_serializing_if = "Option::is_none")]
108    pub description: Option<String>,
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub issuer: Option<String>,
111    #[serde(skip_serializing_if = "Option::is_none")]
112    pub created_at: Option<u64>,
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub proof_note: Option<String>,
115}
116
117/// Blinded message or payment path without onion ciphertext.
118#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
119pub struct BlindedPath {
120    pub introduction_node: IntroductionNode,
121    pub blinding_point: String,
122    pub hops: Vec<BlindedHop>,
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub payinfo: Option<BlindedPayInfo>,
125}
126
127#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
128#[serde(tag = "type", rename_all = "snake_case")]
129pub enum IntroductionNode {
130    Node {
131        node_id: String,
132    },
133    ShortChannelId {
134        short_channel_id: String,
135        direction: String,
136    },
137}
138
139#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
140pub struct BlindedHop {
141    pub blinded_node_id: String,
142}
143
144#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
145pub struct BlindedPayInfo {
146    pub fee_base_msat: u32,
147    pub fee_proportional_millionths: u32,
148    pub cltv_expiry_delta: u16,
149    pub htlc_minimum_msat: u64,
150    pub htlc_maximum_msat: u64,
151    #[serde(skip_serializing_if = "Option::is_none")]
152    pub features: Option<String>,
153}
154
155#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
156#[serde(untagged)]
157pub enum Amount {
158    Bitcoin { msat: u64 },
159    Currency { currency: String, amount: u64 },
160}
161
162#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
163#[serde(rename_all = "snake_case")]
164pub enum VerifyKind {
165    PayerProof,
166    Payment,
167}
168
169#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
170pub struct VerifyReport {
171    pub valid: bool,
172    pub kind: VerifyKind,
173    pub checks: Vec<Check>,
174}
175
176#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
177pub struct Check {
178    pub name: String,
179    pub passed: bool,
180    #[serde(skip_serializing_if = "Option::is_none")]
181    pub message: Option<String>,
182}
183
184impl Check {
185    pub fn pass(name: impl Into<String>) -> Self {
186        Self {
187            name: name.into(),
188            passed: true,
189            message: None,
190        }
191    }
192
193    pub fn fail(name: impl Into<String>, message: impl Into<String>) -> Self {
194        Self {
195            name: name.into(),
196            passed: false,
197            message: Some(message.into()),
198        }
199    }
200}
201
202impl VerifyReport {
203    pub fn new(kind: VerifyKind, checks: Vec<Check>) -> Self {
204        let valid = !checks.is_empty() && checks.iter().all(|check| check.passed);
205        Self {
206            valid,
207            kind,
208            checks,
209        }
210    }
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216
217    #[test]
218    fn empty_report_is_not_valid() {
219        let report = VerifyReport::new(VerifyKind::PayerProof, Vec::new());
220        assert!(!report.valid);
221    }
222}