diff --git a/doc/lightning-decode.7 b/doc/lightning-decode.7 index 0b4e80e4d..a497de756 100644 --- a/doc/lightning-decode.7 +++ b/doc/lightning-decode.7 @@ -17,140 +17,385 @@ other formats in future\. .SH RETURN VALUE -On success, an object is returned with a \fItype\fR member indicating the -type of the decoding: +On success, an object is returned, containing: - -\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. +.IP \[bu] +\fBtype\fR (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice") +.IP \[bu] +\fBvalid\fR (boolean): if this is false, you \fIMUST\fR not use the result except for diagnostics! + +.RE + +If \fBtype\fR is "bolt12 offer", and \fBvalid\fR is \fItrue\fR: + +.RS +.IP \[bu] +\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) +.IP \[bu] +\fBnode_id\fR (pubkey32): x-only public key of the offering node +.IP \[bu] +\fBsignature\fR (bip340sig): BIP-340 signature of the \fInode_id\fR on this offer +.IP \[bu] +\fBdescription\fR (string): the description of the purpose of the offer +.IP \[bu] +\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): +.RS +.IP \[bu] +the genesis blockhash (always 64 characters) + +.RE + +.IP \[bu] +\fBcurrency\fR (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters) +.IP \[bu] +\fBminor_unit\fR (u32, optional): the number of decimal places to apply to amount (if currency known) +.IP \[bu] +\fBamount\fR (u64, optional): the amount in the \fIcurrency\fR adjusted by \fIminor_unit\fR, if any +.IP \[bu] +\fBamount_msat\fR (msat, optional): the amount in bitcoin (if specified, and no \fIcurrency\fR) +.IP \[bu] +\fBsend_invoice\fR (boolean, optional): present if this is a send_invoice offer (always \fItrue\fR) +.IP \[bu] +\fBrefund_for\fR (hex, optional): the \fIpayment_preimage\fR of invoice this is a refund for (always 64 characters) +.IP \[bu] +\fBvendor\fR (string, optional): the name of the vendor for this offer +.IP \[bu] +\fBfeatures\fR (hex, optional): the array of feature bits for this offer +.IP \[bu] +\fBabsolute_expiry\fR (u64, optional): UNIX timestamp of when this offer expires +.IP \[bu] +\fBpaths\fR (array of objects, optional): Paths to the destination: +.RS +.IP \[bu] +\fBblinding\fR (pubkey): blinding factor for this path +.IP \[bu] +\fBpath\fR (array of objects): an individual path: +.RS +.IP \[bu] +\fBnode_id\fR (pubkey): node_id of the hop +.IP \[bu] +\fBenctlv\fR (hex): encrypted TLV entry for this hop + +.RE .RE -.fi - -\fItype\fR: "bolt12 invoice" - -.nf +.IP \[bu] +\fBquantity_min\fR (u64, optional): the minimum quantity +.IP \[bu] +\fBquantity_max\fR (u64, optional): the maximum quantity +.IP \[bu] +\fBrecurrence\fR (object, optional): how often to this offer should be used: .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. +.IP \[bu] +\fBtime_unit\fR (u32): the BOLT12 time unit +.IP \[bu] +\fBperiod\fR (u32): how many \fItime_unit\fR per payment period +.IP \[bu] +\fBtime_unit_name\fR (string, optional): the name of \fItime_unit\fR (if valid) +.IP \[bu] +\fBbasetime\fR (u64, optional): period starts at this UNIX timestamp +.IP \[bu] +\fBstart_any_period\fR (u64, optional): you can start at any period (only if \fBbasetime\fR present) +.IP \[bu] +\fBlimit\fR (u32, optional): maximum period number for recurrence +.IP \[bu] +\fBpaywindow\fR (object, optional): when within a period will payment be accepted (default is prior and during the period): +.RS +.IP \[bu] +\fBseconds_before\fR (u32): seconds prior to period start +.IP \[bu] +\fBseconds_after\fR (u32): seconds after to period start +.IP \[bu] +\fBproportional_amount\fR (boolean, optional): amount should be scaled if payed after period start (always \fItrue\fR) + +.RE .RE -.fi - -\fItype\fR: "bolt12 invoice_request" - -.nf +.IP \[bu] +the following warnings are possible: .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. +.IP \[bu] +\fBwarning_offer_unknown_currency\fR: The currency code is unknown (so no \fBminor_unit\fR) + +.RE .RE -.fi +If \fBtype\fR is "bolt12 offer", and \fBvalid\fR is \fIfalse\fR: -\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. +.IP \[bu] +the following warnings are possible: +.RS +.IP \[bu] +\fBwarning_offer_missing_description\fR: No \fBdescription\fR + +.RE .RE -.fi +If \fBtype\fR is "bolt12 invoice", and \fBvalid\fR is \fItrue\fR: -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. +.IP \[bu] +\fBnode_id\fR (pubkey32): x-only public key of the offering node +.IP \[bu] +\fBsignature\fR (bip340sig): BIP-340 signature of the \fInode_id\fR on this offer +.IP \[bu] +\fBamount_msat\fR (msat): the amount in bitcoin +.IP \[bu] +\fBdescription\fR (string): the description of the purpose of the offer +.IP \[bu] +\fBtimestamp\fR (u64): the UNIX timestamp of the invoice +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR (always 64 characters) +.IP \[bu] +\fBrelative_expiry\fR (u32): the number of seconds after \fItimestamp\fR when this expires +.IP \[bu] +\fBmin_final_cltv_expiry\fR (u32): the number of blocks required by destination +.IP \[bu] +\fBoffer_id\fR (hex, optional): the id of this offer (merkle hash of non-signature fields) (always 64 characters) +.IP \[bu] +\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): +.RS +.IP \[bu] +the genesis blockhash (always 64 characters) + +.RE + +.IP \[bu] +\fBsend_invoice\fR (boolean, optional): present if this offer was a send_invoice offer (always \fItrue\fR) +.IP \[bu] +\fBrefund_for\fR (hex, optional): the \fIpayment_preimage\fR of invoice this is a refund for (always 64 characters) +.IP \[bu] +\fBvendor\fR (string, optional): the name of the vendor for this offer +.IP \[bu] +\fBfeatures\fR (hex, optional): the array of feature bits for this offer +.IP \[bu] +\fBpaths\fR (array of objects, optional): Paths to the destination: +.RS +.IP \[bu] +\fBblinding\fR (pubkey): blinding factor for this path +.IP \[bu] +\fBpath\fR (array of objects): an individual path: +.RS +.IP \[bu] +\fBnode_id\fR (pubkey): node_id of the hop +.IP \[bu] +\fBenctlv\fR (hex): encrypted TLV entry for this hop + +.RE .RE -.fi +.IP \[bu] +\fBquantity\fR (u64, optional): the quantity ordered +.IP \[bu] +\fBrecurrence_counter\fR (u32, optional): the 0-based counter for a recurring payment +.IP \[bu] +\fBrecurrence_start\fR (u32, optional): the optional start period for a recurring payment +.IP \[bu] +\fBrecurrence_basetime\fR (u32, optional): the UNIX timestamp of the first recurrence period start +.IP \[bu] +\fBpayer_key\fR (pubkey32, optional): the transient key which identifies the payer +.IP \[bu] +\fBpayer_info\fR (hex, optional): the payer-provided blob to derive payer_key +.IP \[bu] +\fBfallbacks\fR (array of objects, optional): onchain addresses: +.RS +.IP \[bu] +\fBversion\fR (u8): Segwit address version +.IP \[bu] +\fBhex\fR (hex): Raw encoded segwit address +.IP \[bu] +\fBaddress\fR (string, optional): bech32 segwit address + +.RE + +.IP \[bu] +\fBrefund_signature\fR (bip340sig, optional): the payer key signature to get a refund + +.RE + +If \fBtype\fR is "bolt12 invoice", and \fBvalid\fR is \fIfalse\fR: + +.RS +.IP \[bu] +\fBfallbacks\fR (array of objects, optional): +.RS +.IP \[bu] +the following warnings are possible: +.RS +.IP \[bu] +\fBwarning_invoice_fallbacks_version_invalid\fR: \fBversion\fR is > 16 + +.RE + + +.RE + +.IP \[bu] +the following warnings are possible: +.RS +.IP \[bu] +\fBwarning_invoice_missing_amount\fR: *\fIamount_msat\fR missing +.IP \[bu] +\fBwarning_invoice_missing_description\fR: No \fBdescription\fR +.IP \[bu] +\fBwarning_invoice_missing_blinded_payinfo\fR: Has \fBpaths\fR without payinfo +.IP \[bu] +\fBwarning_invoice_invalid_blinded_payinfo\fR: Does not have exactly one payinfo for each of \fBpaths\fR +.IP \[bu] +\fBwarning_invoice_missing_recurrence_basetime\fR: Has \fBrecurrence_counter\fR without \fBrecurrence_basetime\fR +.IP \[bu] +\fBwarning_invoice_missing_timestamp\fR: Missing \fBtimestamp\fR +.IP \[bu] +\fBwarning_invoice_missing_payment_hash\fR: Missing \fBpayment_hash\fR +.IP \[bu] +\fBwarning_invoice_refund_signature_missing_payer_key\fR: Missing \fBpayer_key\fR for refund_signature +.IP \[bu] +\fBwarning_invoice_refund_signature_invalid\fR: \fBrefund_signature\fR incorrect +.IP \[bu] +\fBwarning_invoice_refund_missing_signature\fR: No \fBrefund_signature\fR + +.RE + + +.RE + +If \fBtype\fR is "bolt12 invoice_request", and \fBvalid\fR is \fItrue\fR: + +.RS +.IP \[bu] +\fBoffer_id\fR (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) +.IP \[bu] +\fBpayer_key\fR (pubkey32): the transient key which identifies the payer +.IP \[bu] +\fBchains\fR (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): +.RS +.IP \[bu] +the genesis blockhash (always 64 characters) + +.RE + +.IP \[bu] +\fBamount_msat\fR (msat, optional): the amount in bitcoin +.IP \[bu] +\fBfeatures\fR (hex, optional): the array of feature bits for this offer +.IP \[bu] +\fBquantity\fR (u64, optional): the quantity ordered +.IP \[bu] +\fBrecurrence_counter\fR (u32, optional): the 0-based counter for a recurring payment +.IP \[bu] +\fBrecurrence_start\fR (u32, optional): the optional start period for a recurring payment +.IP \[bu] +\fBpayer_info\fR (hex, optional): the payer-provided blob to derive payer_key +.IP \[bu] +\fBrecurrence_signature\fR (bip340sig, optional): the payer key signature + +.RE + +If \fBtype\fR is "bolt12 invoice_request", and \fBvalid\fR is \fIfalse\fR: + +.RS +.IP \[bu] +the following warnings are possible: +.RS +.IP \[bu] +\fBwarning_invoice_request_missing_offer_id\fR: No \fBoffer_id\fR +.IP \[bu] +\fBwarning_invoice_request_missing_payer_key\fR: No \fBpayer_key\fR +.IP \[bu] +\fBwarning_invoice_request_missing_recurrence_signature\fR: No \fBrecurrence_signature\fR +.IP \[bu] +\fBwarning_invoice_request_invalid_recurrence_signature\fR: \fBrecurrence_signature\fR incorrect + +.RE + + +.RE + +If \fBtype\fR is "bolt11 invoice", and \fBvalid\fR is \fItrue\fR: + +.RS +.IP \[bu] +\fBcurrency\fR (string): the BIP173 name for the currency +.IP \[bu] +\fBcreated_at\fR (u64): the UNIX-style timestamp of the invoice +.IP \[bu] +\fBexpiry\fR (u64): the number of seconds this is valid after \fItimestamp\fR +.IP \[bu] +\fBpayee\fR (pubkey): the public key of the recipient +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR (always 64 characters) +.IP \[bu] +\fBsignature\fR (signature): signature of the \fIpayee\fR on this invoice +.IP \[bu] +\fBmin_final_cltv_expiry\fR (u32): the minimum CLTV delay for the final node +.IP \[bu] +\fBamount_msat\fR (msat, optional): Amount the invoice asked for +.IP \[bu] +\fBdescription\fR (string, optional): the description of the purpose of the purchase +.IP \[bu] +\fBdescription_hash\fR (hex, optional): the hash of the description, in place of \fIdescription\fR (always 64 characters) +.IP \[bu] +\fBpayment_secret\fR (hex, optional): the secret to hand to the payee node (always 64 characters) +.IP \[bu] +\fBfeatures\fR (hex, optional): the features bitmap for this invoice +.IP \[bu] +\fBfallbacks\fR (array of objects, optional): onchain addresses: +.RS +.IP \[bu] +\fBtype\fR (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH") +.IP \[bu] +\fBhex\fR (hex): Raw encoded address +.IP \[bu] +\fBaddr\fR (string, optional): the address in appropriate format for \fItype\fR + +.RE + +.IP \[bu] +\fBroutes\fR (array of arrays, optional): Route hints to the \fIpayee\fR: +.RS +.IP \[bu] +hops in the route: +.RS +.IP \[bu] +\fBpubkey\fR (pubkey): the public key of the node +.IP \[bu] +\fBshort_channel_id\fR (short_channel_id): a channel to the next peer +.IP \[bu] +\fBfee_base_msat\fR (u32): the base fee for payments +.IP \[bu] +\fBfee_proportional_millionths\fR (u32): the parts-per-million fee for payments +.IP \[bu] +\fBcltv_expiry_delta\fR (u32): the CLTV delta across this hop + +.RE + + +.RE + +.IP \[bu] +\fBextra\fR (array of objects, optional): Any extra fields we didn't know how to parse: +.RS +.IP \[bu] +\fBtag\fR (string): The bech32 letter which identifies this field (always 1 characters) +.IP \[bu] +\fBdata\fR (string): The bech32 data for this field + +.RE + + +.RE .SH AUTHOR Rusty Russell \fI is mainly responsible\. @@ -169,4 +414,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:4a01fe92de9520e78656495ff9093184cdf4836283af7102ee6b50ab0c826132 +\" SHA256STAMP:403b7cf3cadd8b260b8b2b02746c76d7d21a8319fe386b4174f4f58b3e5dcdbd diff --git a/doc/lightning-decode.7.md b/doc/lightning-decode.7.md index 6966b9ecc..356162493 100644 --- a/doc/lightning-decode.7.md +++ b/doc/lightning-decode.7.md @@ -19,99 +19,149 @@ other formats in future. RETURN VALUE ------------ -On success, an object is returned with a *type* member indicating the -type of the decoding: +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **type** (string): what kind of object it decoded to (one of "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice") +- **valid** (boolean): if this is false, you *MUST* not use the result except for diagnostics! -*type*: "bolt12 offer" - - *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. +If **type** is "bolt12 offer", and **valid** is *true*: + - **offer_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) + - **node_id** (pubkey32): x-only public key of the offering node + - **signature** (bip340sig): BIP-340 signature of the *node_id* on this offer + - **description** (string): the description of the purpose of the offer + - **chains** (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): + - the genesis blockhash (always 64 characters) + - **currency** (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters) + - **minor_unit** (u32, optional): the number of decimal places to apply to amount (if currency known) + - **amount** (u64, optional): the amount in the *currency* adjusted by *minor_unit*, if any + - **amount_msat** (msat, optional): the amount in bitcoin (if specified, and no *currency*) + - **send_invoice** (boolean, optional): present if this is a send_invoice offer (always *true*) + - **refund_for** (hex, optional): the *payment_preimage* of invoice this is a refund for (always 64 characters) + - **vendor** (string, optional): the name of the vendor for this offer + - **features** (hex, optional): the array of feature bits for this offer + - **absolute_expiry** (u64, optional): UNIX timestamp of when this offer expires + - **paths** (array of objects, optional): Paths to the destination: + - **blinding** (pubkey): blinding factor for this path + - **path** (array of objects): an individual path: + - **node_id** (pubkey): node_id of the hop + - **enctlv** (hex): encrypted TLV entry for this hop + - **quantity_min** (u64, optional): the minimum quantity + - **quantity_max** (u64, optional): the maximum quantity + - **recurrence** (object, optional): how often to this offer should be used: + - **time_unit** (u32): the BOLT12 time unit + - **period** (u32): how many *time_unit* per payment period + - **time_unit_name** (string, optional): the name of *time_unit* (if valid) + - **basetime** (u64, optional): period starts at this UNIX timestamp + - **start_any_period** (u64, optional): you can start at any period (only if **basetime** present) + - **limit** (u32, optional): maximum period number for recurrence + - **paywindow** (object, optional): when within a period will payment be accepted (default is prior and during the period): + - **seconds_before** (u32): seconds prior to period start + - **seconds_after** (u32): seconds after to period start + - **proportional_amount** (boolean, optional): amount should be scaled if payed after period start (always *true*) + - the following warnings are possible: + - **warning_offer_unknown_currency**: The currency code is unknown (so no **minor_unit**) -*type*: "bolt12 invoice" - - *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. +If **type** is "bolt12 offer", and **valid** is *false*: + - the following warnings are possible: + - **warning_offer_missing_description**: No **description** -*type*: "bolt12 invoice_request" - - *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. +If **type** is "bolt12 invoice", and **valid** is *true*: + - **node_id** (pubkey32): x-only public key of the offering node + - **signature** (bip340sig): BIP-340 signature of the *node_id* on this offer + - **amount_msat** (msat): the amount in bitcoin + - **description** (string): the description of the purpose of the offer + - **timestamp** (u64): the UNIX timestamp of the invoice + - **payment_hash** (hex): the hash of the *payment_preimage* (always 64 characters) + - **relative_expiry** (u32): the number of seconds after *timestamp* when this expires + - **min_final_cltv_expiry** (u32): the number of blocks required by destination + - **offer_id** (hex, optional): the id of this offer (merkle hash of non-signature fields) (always 64 characters) + - **chains** (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): + - the genesis blockhash (always 64 characters) + - **send_invoice** (boolean, optional): present if this offer was a send_invoice offer (always *true*) + - **refund_for** (hex, optional): the *payment_preimage* of invoice this is a refund for (always 64 characters) + - **vendor** (string, optional): the name of the vendor for this offer + - **features** (hex, optional): the array of feature bits for this offer + - **paths** (array of objects, optional): Paths to the destination: + - **blinding** (pubkey): blinding factor for this path + - **path** (array of objects): an individual path: + - **node_id** (pubkey): node_id of the hop + - **enctlv** (hex): encrypted TLV entry for this hop + - **quantity** (u64, optional): the quantity ordered + - **recurrence_counter** (u32, optional): the 0-based counter for a recurring payment + - **recurrence_start** (u32, optional): the optional start period for a recurring payment + - **recurrence_basetime** (u32, optional): the UNIX timestamp of the first recurrence period start + - **payer_key** (pubkey32, optional): the transient key which identifies the payer + - **payer_info** (hex, optional): the payer-provided blob to derive payer_key + - **fallbacks** (array of objects, optional): onchain addresses: + - **version** (u8): Segwit address version + - **hex** (hex): Raw encoded segwit address + - **address** (string, optional): bech32 segwit address + - **refund_signature** (bip340sig, optional): the payer key signature to get a refund -*type*: "bolt11 invoice" - - *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. +If **type** is "bolt12 invoice", and **valid** is *false*: + - **fallbacks** (array of objects, optional): + - the following warnings are possible: + - **warning_invoice_fallbacks_version_invalid**: **version** is > 16 + - the following warnings are possible: + - **warning_invoice_missing_amount**: **amount_msat* missing + - **warning_invoice_missing_description**: No **description** + - **warning_invoice_missing_blinded_payinfo**: Has **paths** without payinfo + - **warning_invoice_invalid_blinded_payinfo**: Does not have exactly one payinfo for each of **paths** + - **warning_invoice_missing_recurrence_basetime**: Has **recurrence_counter** without **recurrence_basetime** + - **warning_invoice_missing_timestamp**: Missing **timestamp** + - **warning_invoice_missing_payment_hash**: Missing **payment_hash** + - **warning_invoice_refund_signature_missing_payer_key**: Missing **payer_key** for refund_signature + - **warning_invoice_refund_signature_invalid**: **refund_signature** incorrect + - **warning_invoice_refund_missing_signature**: No **refund_signature** -Some invalid strings can still be parsed, and warnings will be given: - - "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. +If **type** is "bolt12 invoice_request", and **valid** is *true*: + - **offer_id** (hex): the id of this offer (merkle hash of non-signature fields) (always 64 characters) + - **payer_key** (pubkey32): the transient key which identifies the payer + - **chains** (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only): + - the genesis blockhash (always 64 characters) + - **amount_msat** (msat, optional): the amount in bitcoin + - **features** (hex, optional): the array of feature bits for this offer + - **quantity** (u64, optional): the quantity ordered + - **recurrence_counter** (u32, optional): the 0-based counter for a recurring payment + - **recurrence_start** (u32, optional): the optional start period for a recurring payment + - **payer_info** (hex, optional): the payer-provided blob to derive payer_key + - **recurrence_signature** (bip340sig, optional): the payer key signature + +If **type** is "bolt12 invoice_request", and **valid** is *false*: + - the following warnings are possible: + - **warning_invoice_request_missing_offer_id**: No **offer_id** + - **warning_invoice_request_missing_payer_key**: No **payer_key** + - **warning_invoice_request_missing_recurrence_signature**: No **recurrence_signature** + - **warning_invoice_request_invalid_recurrence_signature**: **recurrence_signature** incorrect + +If **type** is "bolt11 invoice", and **valid** is *true*: + - **currency** (string): the BIP173 name for the currency + - **created_at** (u64): the UNIX-style timestamp of the invoice + - **expiry** (u64): the number of seconds this is valid after *timestamp* + - **payee** (pubkey): the public key of the recipient + - **payment_hash** (hex): the hash of the *payment_preimage* (always 64 characters) + - **signature** (signature): signature of the *payee* on this invoice + - **min_final_cltv_expiry** (u32): the minimum CLTV delay for the final node + - **amount_msat** (msat, optional): Amount the invoice asked for + - **description** (string, optional): the description of the purpose of the purchase + - **description_hash** (hex, optional): the hash of the description, in place of *description* (always 64 characters) + - **payment_secret** (hex, optional): the secret to hand to the payee node (always 64 characters) + - **features** (hex, optional): the features bitmap for this invoice + - **fallbacks** (array of objects, optional): onchain addresses: + - **type** (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH") + - **hex** (hex): Raw encoded address + - **addr** (string, optional): the address in appropriate format for *type* + - **routes** (array of arrays, optional): Route hints to the *payee*: + - hops in the route: + - **pubkey** (pubkey): the public key of the node + - **short_channel_id** (short_channel_id): a channel to the next peer + - **fee_base_msat** (u32): the base fee for payments + - **fee_proportional_millionths** (u32): the parts-per-million fee for payments + - **cltv_expiry_delta** (u32): the CLTV delta across this hop + - **extra** (array of objects, optional): Any extra fields we didn't know how to parse: + - **tag** (string): The bech32 letter which identifies this field (always 1 characters) + - **data** (string): The bech32 data for this field +[comment]: # (GENERATE-FROM-SCHEMA-END) AUTHOR ------ @@ -133,3 +183,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:733d22404e5230882682b846ace92451d8988cf028fa903d735f61b7c61f1c08) diff --git a/doc/lightning-decodepay.7 b/doc/lightning-decodepay.7 index ad51e9d79..e491f7348 100644 --- a/doc/lightning-decodepay.7 +++ b/doc/lightning-decodepay.7 @@ -12,46 +12,77 @@ specified by the BOLT 11 specification\. .SH RETURN VALUE -On success, an object is returned with the following fields, as -specified by BOLT11: +On success, an object is returned, containing: .RS .IP \[bu] -\fIcurrency\fR: the BIP173 name for the currency\. +\fBcurrency\fR (string): the BIP173 name for the currency .IP \[bu] -\fItimestamp\fR: the UNIX-style timestamp of the invoice\. +\fBcreated_at\fR (u64): the UNIX-style timestamp of the invoice .IP \[bu] -\fIexpiry\fR: the number of seconds this is valid after \fItimestamp\fR\. +\fBexpiry\fR (u64): the number of seconds this is valid after \fItimestamp\fR .IP \[bu] -\fIpayee\fR: the public key of the recipient\. +\fBpayee\fR (pubkey): the public key of the recipient .IP \[bu] -\fIpayment_hash\fR: the payment hash of the request\. +\fBpayment_hash\fR (hex): the hash of the \fIpayment_preimage\fR (always 64 characters) .IP \[bu] -\fIsignature\fR: the DER-encoded signature\. +\fBsignature\fR (signature): signature of the \fIpayee\fR on this invoice .IP \[bu] -\fIdescription\fR: the description of the purpose of the purchase (see -below) +\fBmin_final_cltv_expiry\fR (u32): the minimum CLTV delay for the final node +.IP \[bu] +\fBamount_msat\fR (msat, optional): Amount the invoice asked for +.IP \[bu] +\fBdescription\fR (string, optional): the description of the purpose of the purchase +.IP \[bu] +\fBdescription_hash\fR (hex, optional): the hash of the description, in place of \fIdescription\fR (always 64 characters) +.IP \[bu] +\fBpayment_secret\fR (hex, optional): the secret to hand to the payee node (always 64 characters) +.IP \[bu] +\fBfeatures\fR (hex, optional): the features bitmap for this invoice +.IP \[bu] +\fBfallbacks\fR (array of objects, optional): onchain addresses: +.RS +.IP \[bu] +\fBtype\fR (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH") +.IP \[bu] +\fBhex\fR (hex): Raw encoded address +.IP \[bu] +\fBaddr\fR (string, optional): the address in appropriate format for \fItype\fR .RE -The following fields are optional: - +.IP \[bu] +\fBroutes\fR (array of arrays, optional): Route hints to the \fIpayee\fR: .RS .IP \[bu] -\fImsatoshi\fR: the number of millisatoshi requested (if any)\. +hops in the route: +.RS .IP \[bu] -\fIamount_msat\fR: the same as above, with \fImsat\fR appended (if any)\. +\fBpubkey\fR (pubkey): the public key of the node .IP \[bu] -\fIfallbacks\fR: array of fallback address object containing a \fIhex\fR -string, and both \fItype\fR and \fIaddr\fR if it is recognized as one of -\fIP2PKH\fR, \fIP2SH\fR, \fIP2WPKH\fR, or \fIP2WSH\fR\. +\fBshort_channel_id\fR (short_channel_id): a channel to the next peer .IP \[bu] -\fIroutes\fR: an array of routes\. Each route is an arrays of objects, -each containing \fIpubkey\fR, \fIshort_channel_id\fR, \fIfee_base_msat\fR, -\fIfee_proportional_millionths\fR and \fIcltv_expiry_delta\fR\. +\fBfee_base_msat\fR (u32): the base fee for payments .IP \[bu] -\fIextra\fR: an array of objects representing unknown fields, each with -one-character \fItag\fR and a \fIdata\fR bech32 string\. +\fBfee_proportional_millionths\fR (u32): the parts-per-million fee for payments +.IP \[bu] +\fBcltv_expiry_delta\fR (u32): the CLTV delta across this hop + +.RE + + +.RE + +.IP \[bu] +\fBextra\fR (array of objects, optional): Any extra fields we didn't know how to parse: +.RS +.IP \[bu] +\fBtag\fR (string): The bech32 letter which identifies this field (always 1 characters) +.IP \[bu] +\fBdata\fR (string): The bech32 data for this field + +.RE + .RE @@ -76,4 +107,4 @@ Rusty Russell \fI is mainly responsible\. Main web site: \fIhttps://github.com/ElementsProject/lightning\fR -\" SHA256STAMP:d3944c14e16584577e0336dda8c2689881524717428eb921e23f8831144ec566 +\" SHA256STAMP:1b0e5c34291b3c252c651e952109f57fe68a90770fecaa0eeebf9070ed8c2dad diff --git a/doc/lightning-decodepay.7.md b/doc/lightning-decodepay.7.md index 695315171..786a692ef 100644 --- a/doc/lightning-decodepay.7.md +++ b/doc/lightning-decodepay.7.md @@ -15,28 +15,35 @@ specified by the BOLT 11 specification. RETURN VALUE ------------ -On success, an object is returned with the following fields, as -specified by BOLT11: -- *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 description of the purpose of the purchase (see - below) - -The following fields are optional: -- *msatoshi*: the number of millisatoshi requested (if any). -- *amount\_msat*: the same as above, with *msat* appended (if any). -- *fallbacks*: 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*: 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*: an array of objects representing unknown fields, each with - one-character *tag* and a *data* bech32 string. +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object is returned, containing: +- **currency** (string): the BIP173 name for the currency +- **created_at** (u64): the UNIX-style timestamp of the invoice +- **expiry** (u64): the number of seconds this is valid after *timestamp* +- **payee** (pubkey): the public key of the recipient +- **payment_hash** (hex): the hash of the *payment_preimage* (always 64 characters) +- **signature** (signature): signature of the *payee* on this invoice +- **min_final_cltv_expiry** (u32): the minimum CLTV delay for the final node +- **amount_msat** (msat, optional): Amount the invoice asked for +- **description** (string, optional): the description of the purpose of the purchase +- **description_hash** (hex, optional): the hash of the description, in place of *description* (always 64 characters) +- **payment_secret** (hex, optional): the secret to hand to the payee node (always 64 characters) +- **features** (hex, optional): the features bitmap for this invoice +- **fallbacks** (array of objects, optional): onchain addresses: + - **type** (string): the address type (if known) (one of "P2PKH", "P2SH", "P2WPKH", "P2WSH") + - **hex** (hex): Raw encoded address + - **addr** (string, optional): the address in appropriate format for *type* +- **routes** (array of arrays, optional): Route hints to the *payee*: + - hops in the route: + - **pubkey** (pubkey): the public key of the node + - **short_channel_id** (short_channel_id): a channel to the next peer + - **fee_base_msat** (u32): the base fee for payments + - **fee_proportional_millionths** (u32): the parts-per-million fee for payments + - **cltv_expiry_delta** (u32): the CLTV delta across this hop +- **extra** (array of objects, optional): Any extra fields we didn't know how to parse: + - **tag** (string): The bech32 letter which identifies this field (always 1 characters) + - **data** (string): The bech32 data for this field +[comment]: # (GENERATE-FROM-SCHEMA-END) Technically, the *description* field is optional if a *description\_hash* field is given, but in this case **decodepay** will @@ -61,3 +68,4 @@ RESOURCES Main web site: +[comment]: # ( SHA256STAMP:33a160a1d9e56690e59b71c4d9d3e141bf7604c111cd5a5624bda692b85c9026) diff --git a/doc/schemas/decode.schema.json b/doc/schemas/decode.schema.json new file mode 100644 index 000000000..f76db5357 --- /dev/null +++ b/doc/schemas/decode.schema.json @@ -0,0 +1,806 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "type", "valid" ], + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 offer", "bolt12 invoice", "bolt12 invoice_request", "bolt11 invoice" ], + "description": "what kind of object it decoded to" + }, + "valid": { + "type": "boolean", + "description": "if this is false, you *MUST* not use the result except for diagnostics!" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 offer" ] + }, + "valid": { + "type": "boolean", + "enum": [ true ] + } + } + }, + "then": { + "required": [ "offer_id", "node_id", "signature", "description" ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { + "type": "hex", + "description": "the id of this offer (merkle hash of non-signature fields)", + "maxLength": 64, + "minLength": 64 + }, + "node_id": { + "type": "pubkey32", + "description": "x-only public key of the offering node" + }, + "signature": { + "type": "bip340sig", + "description": "BIP-340 signature of the *node_id* on this offer" + }, + "chains": { + "type": "array", + "description": "which blockchains this offer is for (missing implies bitcoin mainnet only)", + "items": { + "type": "hex", + "description": "the genesis blockhash", + "maxLength": 64, + "minLength": 64 + } + }, + "currency": { + "type": "string", + "description": "ISO 4217 code of the currency (missing implies Bitcoin)", + "maxLength": 3, + "minLength": 3 + }, + "minor_unit": { + "type": "u32", + "description": "the number of decimal places to apply to amount (if currency known)" + }, + "warning_offer_unknown_currency": { + "type": "string", + "description": "The currency code is unknown (so no **minor_unit**)" + }, + "amount": { + "type": "u64", + "description": "the amount in the *currency* adjusted by *minor_unit*, if any" + }, + "amount_msat": { + "type": "msat", + "description": "the amount in bitcoin (if specified, and no *currency*)" + }, + "send_invoice": { + "type": "boolean", + "description": "present if this is a send_invoice offer", + "enum" : [ true ] + }, + "refund_for": { + "type": "hex", + "description": "the *payment_preimage* of invoice this is a refund for", + "maxLength": 64, + "minLength": 64 + }, + "description": { + "type": "string", + "description": "the description of the purpose of the offer" + }, + "vendor": { + "type": "string", + "description": "the name of the vendor for this offer" + }, + "features": { + "type": "hex", + "description": "the array of feature bits for this offer" + }, + "absolute_expiry": { + "type": "u64", + "description": "UNIX timestamp of when this offer expires" + }, + "paths": { + "type": "array", + "description": "Paths to the destination", + "items": { + "type": "object", + "required": [ "blinding", "path" ], + "additionalProperties": false, + "properties": { + "blinding": { + "type": "pubkey", + "description": "blinding factor for this path" + }, + "path": { + "type": "array", + "description": "an individual path", + "items": { + "type": "object", + "required": [ "node_id", "enctlv" ], + "additionalProperties": false, + "properties": { + "node_id": { + "type": "pubkey", + "description": "node_id of the hop" + }, + "enctlv": { + "type": "hex", + "description": "encrypted TLV entry for this hop" + } + } + } + } + } + } + }, + "quantity_min": { + "type": "u64", + "description": "the minimum quantity" + }, + "quantity_max": { + "type": "u64", + "description": "the maximum quantity" + }, + "recurrence": { + "type": "object", + "description": "how often to this offer should be used", + "required": [ "period", "time_unit" ], + "additionalProperties": false, + "properties": { + "time_unit": { + "type": "u32", + "description": "the BOLT12 time unit" + }, + "time_unit_name": { + "type": "string", + "description": "the name of *time_unit* (if valid)" + }, + "period": { + "type": "u32", + "description": "how many *time_unit* per payment period" + }, + "basetime": { + "type": "u64", + "description": "period starts at this UNIX timestamp" + }, + "start_any_period": { + "type": "u64", + "description": "you can start at any period (only if **basetime** present)" + }, + "limit": { + "type": "u32", + "description": "maximum period number for recurrence" + }, + "paywindow": { + "type": "object", + "description": "when within a period will payment be accepted (default is prior and during the period)", + "required": [ "seconds_before", "seconds_after" ], + "additionalProperties": false, + "properties": { + "seconds_before": { + "type": "u32", + "description": "seconds prior to period start" + }, + "seconds_after": { + "type": "u32", + "description": "seconds after to period start" + }, + "proportional_amount": { + "type": "boolean", + "enum": [ true ], + "description": "amount should be scaled if payed after period start" + } + } + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 offer" ] + }, + "valid": { + "type": "boolean", + "enum": [false ] + } + } + }, + "then": { + "required": [ ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { }, + "node_id": { }, + "signature": { }, + "chains": { }, + "currency": { }, + "minor_unit": { }, + "warning_offer_unknown_currency": { }, + "amount": { }, + "amount_msat": { }, + "send_invoice": { }, + "refund_for": { }, + "description": { }, + "vendor": { }, + "features": { }, + "absolute_expiry": { }, + "paths": { }, + "quantity_min": { }, + "quantity_max": { }, + "recurrence": { }, + "warning_offer_missing_description": { + "type": "string", + "description": "No **description**" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 invoice" ] + }, + "valid": { + "type": "boolean", + "enum": [ true ] + } + } + }, + "then": { + "required": [ "node_id", "signature", "amount_msat", "description", "timestamp", "payment_hash", "relative_expiry", "min_final_cltv_expiry" ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { + "type": "hex", + "description": "the id of this offer (merkle hash of non-signature fields)", + "maxLength": 64, + "minLength": 64 + }, + "node_id": { + "type": "pubkey32", + "description": "x-only public key of the offering node" + }, + "signature": { + "type": "bip340sig", + "description": "BIP-340 signature of the *node_id* on this offer" + }, + "chains": { + "type": "array", + "description": "which blockchains this offer is for (missing implies bitcoin mainnet only)", + "items": { + "type": "hex", + "description": "the genesis blockhash", + "maxLength": 64, + "minLength": 64 + } + }, + "amount_msat": { + "type": "msat", + "description": "the amount in bitcoin" + }, + "send_invoice": { + "type": "boolean", + "description": "present if this offer was a send_invoice offer", + "enum" : [ true ] + }, + "refund_for": { + "type": "hex", + "description": "the *payment_preimage* of invoice this is a refund for", + "maxLength": 64, + "minLength": 64 + }, + "description": { + "type": "string", + "description": "the description of the purpose of the offer" + }, + "vendor": { + "type": "string", + "description": "the name of the vendor for this offer" + }, + "features": { + "type": "hex", + "description": "the array of feature bits for this offer" + }, + "paths": { + "type": "array", + "description": "Paths to the destination", + "items": { + "type": "object", + "required": [ "blinding", "path" ], + "additionalProperties": false, + "properties": { + "blinding": { + "type": "pubkey", + "description": "blinding factor for this path" + }, + "path": { + "type": "array", + "description": "an individual path", + "items": { + "type": "object", + "required": [ "node_id", "enctlv" ], + "additionalProperties": false, + "properties": { + "node_id": { + "type": "pubkey", + "description": "node_id of the hop" + }, + "enctlv": { + "type": "hex", + "description": "encrypted TLV entry for this hop" + } + } + } + } + } + } + }, + "quantity": { + "type": "u64", + "description": "the quantity ordered" + }, + "recurrence_counter": { + "type": "u32", + "description": "the 0-based counter for a recurring payment" + }, + "recurrence_start": { + "type": "u32", + "description": "the optional start period for a recurring payment" + }, + "recurrence_basetime": { + "type": "u32", + "description": "the UNIX timestamp of the first recurrence period start" + }, + "payer_key": { + "type": "pubkey32", + "description": "the transient key which identifies the payer" + }, + "payer_info": { + "type": "hex", + "description": "the payer-provided blob to derive payer_key" + }, + "timestamp": { + "type": "u64", + "description": "the UNIX timestamp of the invoice" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage*", + "maxLength": 64, + "minLength": 64 + }, + "relative_expiry": { + "type": "u32", + "description": "the number of seconds after *timestamp* when this expires" + }, + "min_final_cltv_expiry": { + "type": "u32", + "description": "the number of blocks required by destination" + }, + "fallbacks": { + "type": "array", + "description": "onchain addresses", + "items": { + "type": "object", + "required": ["version", "hex"], + "additionalProperties": false, + "properties": { + "version": { + "type": "u8", + "description": "Segwit address version" + }, + "hex": { + "type": "hex", + "description": "Raw encoded segwit address" + }, + "address": { + "type": "string", + "description": "bech32 segwit address" + } + } + } + }, + "refund_signature": { + "type": "bip340sig", + "description": "the payer key signature to get a refund" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 invoice" ] + }, + "valid": { + "type": "boolean", + "enum": [ false ] + } + } + }, + "then": { + "required": [ ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { }, + "node_id": { }, + "signature": { }, + "chains": { }, + "amount_msat": { }, + "send_invoice": { }, + "refund_for": { }, + "description": { }, + "vendor": { }, + "features": { }, + "paths": { }, + "quantity": { }, + "recurrence_counter": { }, + "recurrence_start": { }, + "recurrence_basetime": { }, + "payer_key": { }, + "payer_info": { }, + "timestamp": { }, + "payment_hash": { }, + "relative_expiry": { }, + "min_final_cltv_expiry": { }, + "fallbacks": { }, + "refund_signature": { }, + "warning_invoice_missing_amount": { + "type": "string", + "description": "**amount_msat* missing" + }, + "warning_invoice_missing_description": { + "type": "string", + "description": "No **description**" + }, + "warning_invoice_missing_blinded_payinfo": { + "type": "string", + "description": "Has **paths** without payinfo" + }, + "warning_invoice_invalid_blinded_payinfo": { + "type": "string", + "description": "Does not have exactly one payinfo for each of **paths**" + }, + "warning_invoice_missing_recurrence_basetime": { + "type": "string", + "description": "Has **recurrence_counter** without **recurrence_basetime**" + }, + "warning_invoice_missing_timestamp": { + "type": "string", + "description": "Missing **timestamp**" + }, + "warning_invoice_missing_payment_hash": { + "type": "string", + "description": "Missing **payment_hash**" + }, + "warning_invoice_refund_signature_missing_payer_key": { + "type": "string", + "description": "Missing **payer_key** for refund_signature" + }, + "warning_invoice_refund_signature_invalid": { + "type": "string", + "description": "**refund_signature** incorrect" + }, + "warning_invoice_refund_missing_signature": { + "type": "string", + "description": "No **refund_signature**" + }, + "fallbacks": { + "type": "array", + "items": { + "type": "object", + "required": ["version", "hex"], + "properties": { + "version": { }, + "hex": { }, + "address": { }, + "warning_invoice_fallbacks_version_invalid": { + "type": "string", + "description": "**version** is > 16" + } + } + } + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 invoice_request" ] + }, + "valid": { + "type": "boolean", + "enum": [ true ] + } + } + }, + "then": { + "required": [ "offer_id", "payer_key" ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { + "type": "hex", + "description": "the id of this offer (merkle hash of non-signature fields)", + "maxLength": 64, + "minLength": 64 + }, + "chains": { + "type": "array", + "description": "which blockchains this offer is for (missing implies bitcoin mainnet only)", + "items": { + "type": "hex", + "description": "the genesis blockhash", + "maxLength": 64, + "minLength": 64 + } + }, + "amount_msat": { + "type": "msat", + "description": "the amount in bitcoin" + }, + "features": { + "type": "hex", + "description": "the array of feature bits for this offer" + }, + "quantity": { + "type": "u64", + "description": "the quantity ordered" + }, + "recurrence_counter": { + "type": "u32", + "description": "the 0-based counter for a recurring payment" + }, + "recurrence_start": { + "type": "u32", + "description": "the optional start period for a recurring payment" + }, + "payer_key": { + "type": "pubkey32", + "description": "the transient key which identifies the payer" + }, + "payer_info": { + "type": "hex", + "description": "the payer-provided blob to derive payer_key" + }, + "recurrence_signature": { + "type": "bip340sig", + "description": "the payer key signature" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt12 invoice_request" ] + }, + "valid": { + "type": "boolean", + "enum": [ false ] + } + } + }, + "then": { + "required": [ ], + "additionalProperties": false, + "properties": { + "type": { }, + "valid": { }, + "offer_id": { }, + "chains": { }, + "amount_msat": { }, + "features": { }, + "quantity": { }, + "recurrence_counter": { }, + "recurrence_start": { }, + "payer_key": { }, + "payer_info": { }, + "recurrence_signature": { }, + "warning_invoice_request_missing_offer_id": { + "type": "string", + "description": "No **offer_id**" + }, + "warning_invoice_request_missing_payer_key": { + "type": "string", + "description": "No **payer_key**" + }, + "warning_invoice_request_missing_recurrence_signature": { + "type": "string", + "description": "No **recurrence_signature**" + }, + "warning_invoice_request_invalid_recurrence_signature": { + "type": "string", + "description": "**recurrence_signature** incorrect" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "type": "string", + "enum": [ "bolt11 invoice" ] + }, + "valid": { + "type": "boolean", + "enum": [ true ] + } + } + }, + "then": { + "required": [ "currency", "created_at", "expiry", "payee", "min_final_cltv_expiry", "payment_hash", "signature" ], + "additionalProperties": false, + "properties": { + "currency": { + "type": "string", + "description": "the BIP173 name for the currency" + }, + "created_at": { + "type": "u64", + "description": "the UNIX-style timestamp of the invoice" + }, + "expiry": { + "type": "u64", + "description": "the number of seconds this is valid after *timestamp*" + }, + "payee": { + "type": "pubkey", + "description": "the public key of the recipient" + }, + "msatoshi": { + "type": "u64", + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "Amount the invoice asked for" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage*", + "maxLength": 64, + "minLength": 64 + }, + "signature": { + "type": "signature", + "description": "signature of the *payee* on this invoice" + }, + "description": { + "type": "string", + "description": "the description of the purpose of the purchase" + }, + "description_hash": { + "type": "hex", + "description": "the hash of the description, in place of *description*", + "maxLength": 64, + "minLength": 64 + }, + "min_final_cltv_expiry": { + "type": "u32", + "description": "the minimum CLTV delay for the final node" + }, + "payment_secret": { + "type": "hex", + "description": "the secret to hand to the payee node", + "maxLength": 64, + "minLength": 64 + }, + "features": { + "type": "hex", + "description": "the features bitmap for this invoice" + }, + "fallbacks": { + "type": "array", + "description": "onchain addresses", + "items": { + "type": "object", + "required": ["type", "hex"], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "description": "the address type (if known)", + "enum": [ "P2PKH", "P2SH", "P2WPKH", "P2WSH" ] + }, + "addr": { + "type": "string", + "description": "the address in appropriate format for *type*" + }, + "hex": { + "type": "hex", + "description": "Raw encoded address" + } + } + } + }, + "routes": { + "type": "array", + "description": "Route hints to the *payee*", + "items": { + "type": "array", + "description": "hops in the route", + "items": { + "type": "object", + "required": [ "pubkey", "short_channel_id", "fee_base_msat", "fee_proportional_millionths", "cltv_expiry_delta" ], + "additionalProperties": false, + "properties": { + "pubkey": { + "type": "pubkey", + "description": "the public key of the node" + }, + "short_channel_id": { + "type": "short_channel_id", + "description": "a channel to the next peer" + }, + "fee_base_msat": { + "type": "u32", + "description": "the base fee for payments" + }, + "fee_proportional_millionths": { + "type": "u32", + "description": "the parts-per-million fee for payments" + }, + "cltv_expiry_delta": { + "type": "u32", + "description": "the CLTV delta across this hop" + } + } + } + } + }, + "extra": { + "type": "array", + "description": "Any extra fields we didn't know how to parse", + "items": { + "type": "object", + "required": [ "tag", "data" ], + "additionalProperties": false, + "properties": { + "tag": { + "type": "string", + "description": "The bech32 letter which identifies this field", + "maxLength": 1, + "minLength": 1 + }, + "data": { + "type": "string", + "description": "The bech32 data for this field" + } + } + } + } + } + } + } + ] +} diff --git a/doc/schemas/decodepay.schema.json b/doc/schemas/decodepay.schema.json new file mode 100644 index 000000000..949404293 --- /dev/null +++ b/doc/schemas/decodepay.schema.json @@ -0,0 +1,146 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "required": [ "currency", "created_at", "expiry", "payee", "min_final_cltv_expiry", "payment_hash", "signature" ], + "additionalProperties": false, + "properties": { + "currency": { + "type": "string", + "description": "the BIP173 name for the currency" + }, + "created_at": { + "type": "u64", + "description": "the UNIX-style timestamp of the invoice" + }, + "expiry": { + "type": "u64", + "description": "the number of seconds this is valid after *timestamp*" + }, + "payee": { + "type": "pubkey", + "description": "the public key of the recipient" + }, + "msatoshi": { + "type": "u64", + "deprecated": true + }, + "amount_msat": { + "type": "msat", + "description": "Amount the invoice asked for" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the *payment_preimage*", + "maxLength": 64, + "minLength": 64 + }, + "signature": { + "type": "signature", + "description": "signature of the *payee* on this invoice" + }, + "description": { + "type": "string", + "description": "the description of the purpose of the purchase" + }, + "description_hash": { + "type": "hex", + "description": "the hash of the description, in place of *description*", + "maxLength": 64, + "minLength": 64 + }, + "min_final_cltv_expiry": { + "type": "u32", + "description": "the minimum CLTV delay for the final node" + }, + "payment_secret": { + "type": "hex", + "description": "the secret to hand to the payee node", + "maxLength": 64, + "minLength": 64 + }, + "features": { + "type": "hex", + "description": "the features bitmap for this invoice" + }, + "fallbacks": { + "type": "array", + "description": "onchain addresses", + "items": { + "type": "object", + "required": ["type", "hex"], + "additionalProperties": false, + "properties": { + "type": { + "type": "string", + "description": "the address type (if known)", + "enum": [ "P2PKH", "P2SH", "P2WPKH", "P2WSH" ] + }, + "addr": { + "type": "string", + "description": "the address in appropriate format for *type*" + }, + "hex": { + "type": "hex", + "description": "Raw encoded address" + } + } + } + }, + "routes": { + "type": "array", + "description": "Route hints to the *payee*", + "items": { + "type": "array", + "description": "hops in the route", + "items": { + "type": "object", + "required": [ "pubkey", "short_channel_id", "fee_base_msat", "fee_proportional_millionths", "cltv_expiry_delta" ], + "additionalProperties": false, + "properties": { + "pubkey": { + "type": "pubkey", + "description": "the public key of the node" + }, + "short_channel_id": { + "type": "short_channel_id", + "description": "a channel to the next peer" + }, + "fee_base_msat": { + "type": "u32", + "description": "the base fee for payments" + }, + "fee_proportional_millionths": { + "type": "u32", + "description": "the parts-per-million fee for payments" + }, + "cltv_expiry_delta": { + "type": "u32", + "description": "the CLTV delta across this hop" + } + } + } + } + }, + "extra": { + "type": "array", + "description": "Any extra fields we didn't know how to parse", + "items": { + "type": "object", + "required": [ "tag", "data" ], + "additionalProperties": false, + "properties": { + "tag": { + "type": "string", + "description": "The bech32 letter which identifies this field", + "maxLength": 1, + "minLength": 1 + }, + "data": { + "type": "string", + "description": "The bech32 data for this field" + } + } + } + } + } +}