forked from ElementsProject/lightning
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlightning-decode.7
172 lines (129 loc) · 8.22 KB
/
lightning-decode.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
.TH "LIGHTNING-DECODE" "7" "" "" "lightning-decode"
.SH NAME
lightning-decode - Command for decoding an invoice string (low-level)
.SH SYNOPSIS
\fIEXPERIMENTAL_FEATURES only\fR
\fBdecode\fR \fIstring\fR
.SH DESCRIPTION
The \fBdecode\fR RPC command checks and parses a \fIbolt11\fR or \fIbolt12\fR
string (optionally prefixed by \fBlightning:\fR or \fBLIGHTNING:\fR) as
specified by the BOLT 11 and BOLT 12 specifications\. It may decode
other formats in future\.
.SH RETURN VALUE
On success, an object is returned with a \fItype\fR member indicating the
type of the decoding:
\fItype\fR: "bolt12 offer"
.nf
.RS
- *offer_id*: the id of this offer (merkle hash of non-signature fields)
- *chains* (optional): if set, an array of genesis hashes of supported chains. (Unset implies bitcoin mainnet).
- *currency* (optional): ISO 4217 code of the currency.
- *minor_unit* (optional): the number of decimal places to apply to amount (if currency known)
- *amount* (optional): the amount in the *currency* adjusted by *minor_unit*, if any.
- *amount_msat* (optional): the amount (with "msat" appended) if there is no *currency*.
- *send_invoice* (optional): `true` if this is a send_invoice offer.
- *refund_for* (optional): the sha256 payment_preimage of invoice this is a refund for.
- *description* (optional): the UTF-8 description of the purpose of the offer.
- *vendor* (optional): the UTF-8 name of the vendor for this offer.
- *features* (optional): hex array of feature bits.
- *absolute_expiry* (optional): UNIX timestamp of when this offer expires.
- *paths* (optional): Array of objects containing *blinding*, *path* array; each *path* entry contains an object with *node_id* and *enctlv*.
- *quantity_min* (optional): minimum valid quantity for offer responses
- *quantity_max* (optional): maximum valid quantity for offer responses
- *recurrence* (optional): an object containing *time_unit*, *time_unit_name* (optional, a string), *period*, *basetime* (optional), *start_any_period* (optional), *limit* (optional), and *paywindow* (optional) object containing *seconds_before*, *seconds_after* and *proportional_amount* (optional).
- *node_id*: 32-byte (x-only) public key of the offering node.
- *signature*: BIP-340 signature of the *node_id* on this offer.
.RE
.fi
\fItype\fR: "bolt12 invoice"
.nf
.RS
- *chains* (optional): if set, an array of genesis hashes of supported chains. (Unset implies bitcoin mainnet).
- *offer_id* (optional): id of the offer this invoice is for.
- *amount_msat* (optional): the amount (with "msat" appended).
- *description* (optional): the UTF-8 description of the purpose of the offer.
- *vendor* (optional): the UTF-8 name of the vendor for this offer.
- *features* (optional): hex array of feature bits.
- *paths* (optional): Array of objects containing *blinding*, *path* array; each *path* entry contains an object with *node_id*, *enctlv*, *fee_base_msat* (optional), *fee_proportional_millionths* (optional), *cltv_expiry_delta* (optional), and *features* (optional).
- *quantity* (optional): quantity of items.
- *send_invoice* (optional): `true` if this is a response to a send_invoice offer.
- *refund_for* (optional): the sha256 payment_preimage of invoice this is a refund for.
- *recurrence_counter* (optional): the zero-based number of the invoice for a recurring offer.
- *recurrence_start* (optional): the zero-based offet of the first invoice for the recurring offer.
- *recurrence_basetime* (optional): the UNIX timestamp of the first period of the offer.
- *payer_key* (optional): the 32-byte (x-only) id of the payer.
- *payer_info* (optional): a variable-length blob for the payer to derive their key.
- *timestamp* (optional): the UNIX timestamp of the invoice.
- *payment_hash* (optional): the hex SHA256 of the payment_preimage.
- *expiry* (optional): seconds from *timestamp* when invoice expires.
- *min_final_cltv_expiry*: required CLTV for final hop.
- *fallbacks* (optional): an array containing objects with *version*, and *hex* fields for each fallback address, and *address* (optional) if it's parsable.
- *refund_signature* (optional): BIP-340 signature of the *payer_key* on this offer.
- *node_id*: 32-byte (x-only) public key of the invoicing node.
- *signature*: BIP-340 signature of the *node_id* on this invoice.
.RE
.fi
\fItype\fR: "bolt12 invoice_request"
.nf
.RS
- *chains* (optional): if set, an array of genesis hashes of supported chains. (Unset implies bitcoin mainnet).
- *offer_id* (optional): id of the offer this invoice is for.
- *amount_msat* (optional): the amount (with "msat" appended).
- *features* (optional): hex array of feature bits.
- *quantity* (optional): quantity of items.
- *recurrence_counter* (optional): the zero-based number of the invoice for a recurring offer.
- *recurrence_start* (optional): the zero-based offet of the first invoice for the recurring offer.
- *payer_key* (optional): the 32-byte (x-only) id of the payer.
- *payer_info* (optional): a variable-length blob for the payer to derive their key.
- *recurrence_signature* (optional): BIP-340 signature of the *payer_key* on this offer.
.RE
.fi
\fItype\fR: "bolt11 invoice"
.nf
.RS
- *currency*: the BIP173 name for the currency.
- *timestamp*: the UNIX-style timestamp of the invoice.
- *expiry*: the number of seconds this is valid after *timestamp*.
- *payee*: the public key of the recipient.
- *payment_hash*: the payment hash of the request.
- *signature*: the DER-encoded signature.
- *description*: the UTF-8 description of the purpose of the purchase.
- *msatoshi* (optional): the number of millisatoshi requested (if any).
- *amount_msat* (optional): the same as above, with *msat* appended (if any).
- *fallbacks* (optional): array of fallback address object containing a *hex* string, and both *type* and *addr* if it is recognized as one of *P2PKH*, *P2SH*, *P2WPKH*, or *P2WSH*.
- *routes* (optional): an array of routes. Each route is an arrays of objects, each containing *pubkey*, *short_channel_id*, *fee_base_msat*, *fee_proportional_millionths* and *cltv_expiry_delta*.
- *extra* (optional): an array of objects representing unknown fields, each with one-character *tag* and a *data* bech32 string.
.RE
.fi
Some invalid strings can still be parsed, and warnings will be given:
.nf
.RS
- "warning_offer_unknown_currency": unknown or invalid *currency* code.
- "warning_offer_missing_description": invalid due to missing description.
- "warning_invoice_invalid_blinded_payinfo": blinded_payinfo does not match paths.
- "warning_invoice_fallbacks_version_invalid": a fallback version is not a valid segwit version
- "warning_invoice_fallbacks_address_invalid": a fallback address is not a valid segwit address (within an object in the *fallback* array)
- "warning_invoice_missing_amount": amount field is missing.
- "warning_invoice_missing_description": description field is missing.
- "warning_invoice_missing_blinded_payinfo": blindedpay is missing.
- "warning_invoice_missing_recurrence_basetime: recurrence_basetime is missing.
- "warning_invoice_missing_timestamp": timestamp is missing.
- "warning_invoice_missing_payment_hash": payment hash is missing.
- "warning_invoice_refund_signature_missing_payer_key": payer_key is missing for refund_signature.
- "warning_invoice_refund_signature_invalid": refund_signature does not match.
- "warning_invoice_refund_missing_signature": refund_signature is missing.
- "warning_invoice_request_missing_offer_id": offer_id is missing.
- "warning_invoice_request_missing_payer_key": payer_key is missing.
- "warning_invoice_request_invalid_recurrence_signature": recurrence_signature does not match.
- "warning_invoice_request_missing_recurrence_signature": recurrence_signature is missing.
.RE
.fi
.SH AUTHOR
Rusty Russell \fI<[email protected]\fR> is mainly responsible\.
.SH SEE ALSO
\fBlightning-pay\fR(7), \fBlightning-offer\fR(7), \fBlightning-offerout\fR(7), \fBlightning-fetchinvoice\fR(7), \fBlightning-sendinvoice\fR(7)
\fBBOLT #11\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md\fR)\.
\fBBOLT #12\fR (\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/12-offer-encoding.md\fR)\.
.SH RESOURCES
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:6920ea3b5e3fe8c193ce149b813496370fbc249649911595ea857f5cfb7d6e89