fiber_json_types/
invoice.rs

1//! Invoice types for the Fiber Network JSON-RPC API.
2
3use crate::schema_helpers::*;
4use crate::serde_utils::{duration_hex, Hash256, Pubkey, U128Hex, U64Hex};
5use ckb_jsonrpc_types::Script;
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8use serde_with::serde_as;
9
10/// The currency of the invoice, can also used to represent the CKB network chain.
11#[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize, Default, JsonSchema)]
12pub enum Currency {
13    /// The mainnet currency of CKB.
14    Fibb,
15    /// The testnet currency of the CKB network.
16    Fibt,
17    /// The devnet currency of the CKB network.
18    #[default]
19    Fibd,
20}
21
22/// HashAlgorithm is the hash algorithm used in the hash lock.
23#[derive(Copy, Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default, Hash, JsonSchema)]
24#[serde(rename_all = "snake_case")]
25pub enum HashAlgorithm {
26    /// The default hash algorithm, CkbHash
27    #[default]
28    CkbHash,
29    /// The sha256 hash algorithm
30    Sha256,
31}
32
33/// The status of an invoice.
34#[derive(Debug, Clone, Copy, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
35pub enum CkbInvoiceStatus {
36    /// The invoice is open and can be paid.
37    Open,
38    /// The invoice is cancelled.
39    Cancelled,
40    /// The invoice is expired.
41    Expired,
42    /// The invoice is received, but not settled yet.
43    Received,
44    /// The invoice is paid.
45    Paid,
46}
47
48/// The attributes of the invoice.
49#[serde_as]
50#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
51#[serde(rename_all = "snake_case")]
52pub enum Attribute {
53    #[serde(with = "U64Hex")]
54    #[schemars(schema_with = "schema_as_uint_hex")]
55    /// This attribute is deprecated since v0.6.0, The final tlc time out, in milliseconds
56    FinalHtlcTimeout(u64),
57    #[serde(with = "U64Hex")]
58    #[schemars(schema_with = "schema_as_uint_hex")]
59    /// The final tlc minimum expiry delta, in milliseconds, default is 1 day
60    FinalHtlcMinimumExpiryDelta(u64),
61    #[serde(with = "duration_hex")]
62    #[schemars(schema_with = "schema_as_uint_hex")]
63    /// The expiry time of the invoice, in seconds
64    ExpiryTime(std::time::Duration),
65    /// The description of the invoice
66    Description(String),
67    /// The fallback address of the invoice
68    FallbackAddr(String),
69    /// The udt type script of the invoice (serialized as 0x-prefixed hex of molecule bytes)
70    UdtScript(String),
71    /// The payee public key of the invoice (validated compressed secp256k1 key, hex without 0x prefix)
72    PayeePublicKey(Pubkey),
73    /// The hash algorithm of the invoice
74    HashAlgorithm(HashAlgorithm),
75    /// The feature flags of the invoice
76    Feature(Vec<String>),
77    /// The payment secret of the invoice
78    PaymentSecret(String),
79}
80
81/// The metadata of the invoice.
82#[serde_as]
83#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
84pub struct InvoiceData {
85    /// The timestamp of the invoice
86    #[serde_as(as = "U128Hex")]
87    #[schemars(schema_with = "schema_as_uint_hex")]
88    pub timestamp: u128,
89    /// The payment hash of the invoice
90    pub payment_hash: Hash256,
91    /// The attributes of the invoice, e.g. description, expiry time, etc.
92    pub attrs: Vec<Attribute>,
93}
94
95/// Represents a syntactically and semantically correct lightning BOLT11 invoice.
96///
97/// There are three ways to construct a `CkbInvoice`:
98///  1. using [`CkbInvoiceBuilder`]
99///  2. using `str::parse::<CkbInvoice>(&str)` (see [`CkbInvoice::from_str`])
100///
101#[serde_as]
102#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
103pub struct CkbInvoice {
104    /// The currency of the invoice
105    pub currency: Currency,
106    #[serde_as(as = "Option<U128Hex>")]
107    #[schemars(schema_with = "schema_as_uint_hex_optional")]
108    /// The amount of the invoice
109    pub amount: Option<u128>,
110    /// The signature of the invoice (hex encoded)
111    pub signature: Option<String>,
112    /// The invoice data, including the payment hash, timestamp and other attributes
113    pub data: InvoiceData,
114}
115
116/// The parameter struct for generating a new invoice.
117#[serde_as]
118#[derive(Serialize, Deserialize, Default, Clone, JsonSchema)]
119pub struct NewInvoiceParams {
120    /// The amount of the invoice.
121    #[serde_as(as = "U128Hex")]
122    #[schemars(schema_with = "schema_as_uint_hex")]
123    pub amount: u128,
124    /// The description of the invoice.
125    pub description: Option<String>,
126    /// The currency of the invoice.
127    pub currency: Currency,
128    /// The preimage to settle an incoming TLC payable to this invoice. If preimage is set, hash must be absent.
129    /// If both preimage and hash are absent, a random preimage is generated.
130    pub payment_preimage: Option<Hash256>,
131    /// The hash of the preimage. If hash is set, preimage must be absent. This condition indicates a 'hold invoice'
132    /// for which the tlc must be accepted and held until the preimage becomes known.
133    pub payment_hash: Option<Hash256>,
134    /// The expiry time of the invoice, in seconds.
135    #[serde_as(as = "Option<U64Hex>")]
136    #[schemars(schema_with = "schema_as_uint_hex_optional")]
137    pub expiry: Option<u64>,
138    /// The fallback address of the invoice.
139    pub fallback_address: Option<String>,
140    /// The final HTLC timeout of the invoice, in milliseconds.
141    /// Minimal value is 16 hours, and maximal value is 14 days.
142    #[serde_as(as = "Option<U64Hex>")]
143    #[schemars(schema_with = "schema_as_uint_hex_optional")]
144    pub final_expiry_delta: Option<u64>,
145    /// The UDT type script of the invoice.
146    pub udt_type_script: Option<Script>,
147    /// The hash algorithm of the invoice.
148    pub hash_algorithm: Option<HashAlgorithm>,
149    /// Whether allow payment to use MPP
150    pub allow_mpp: Option<bool>,
151    /// Whether allow payment to use trampoline routing
152    pub allow_trampoline_routing: Option<bool>,
153}
154
155/// Result of creating a new invoice.
156#[derive(Clone, Serialize, Deserialize, Debug, JsonSchema)]
157pub struct InvoiceResult {
158    /// The encoded invoice address.
159    pub invoice_address: String,
160    /// The invoice.
161    pub invoice: CkbInvoice,
162}
163
164/// Parameters for parsing an invoice.
165#[derive(Serialize, Deserialize, JsonSchema)]
166pub struct ParseInvoiceParams {
167    /// The encoded invoice address.
168    pub invoice: String,
169}
170
171/// Result of parsing an invoice.
172#[derive(Clone, Serialize, Deserialize, JsonSchema)]
173pub struct ParseInvoiceResult {
174    /// The invoice.
175    pub invoice: CkbInvoice,
176}
177
178/// Parameters for getting an invoice by payment hash.
179#[derive(Serialize, Deserialize, Debug, JsonSchema)]
180pub struct InvoiceParams {
181    /// The payment hash of the invoice.
182    pub payment_hash: Hash256,
183}
184
185/// Parameters for settling an invoice.
186#[derive(Serialize, Deserialize, Debug, JsonSchema)]
187pub struct SettleInvoiceParams {
188    /// The payment hash of the invoice.
189    pub payment_hash: Hash256,
190    /// The payment preimage of the invoice.
191    pub payment_preimage: Hash256,
192}
193
194/// Result of settling an invoice.
195#[derive(Serialize, Deserialize, Debug, Clone, JsonSchema)]
196pub struct SettleInvoiceResult {}
197
198/// The status of the invoice.
199#[derive(Clone, Serialize, Deserialize, JsonSchema)]
200pub struct GetInvoiceResult {
201    /// The encoded invoice address.
202    pub invoice_address: String,
203    /// The invoice.
204    pub invoice: CkbInvoice,
205    /// The invoice status
206    pub status: CkbInvoiceStatus,
207}
fiber_json_types/invoice.rs

fiber_json_types/
invoice.rs
