core-lightning/doc/lightning-decode.7

.TH "LIGHTNING-DECODE" "7" "" "" "lightning-decode"
.SH NAME
lightning-decode - Command for decoding an invoice string (low-level)
.SH SYNOPSIS

\fB(WARNING: experimental-offers 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<rusty@rustcorp.com.au\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:4a01fe92de9520e78656495ff9093184cdf4836283af7102ee6b50ab0c826132