mirrors/core-lightning
1
0
Fork 0
mirror of https://github.com/ElementsProject/lightning.git synced 2025-01-18 05:12:45 +01:00
Code Issues Projects Releases Wiki Activity

doc/schemas: decode, decodepay

Browse Source 
One of the more complex ones.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2021-05-26 15:24:01 +09:30
parent 4b46190cc4
commit d1b42cccd1
6 changed files with 1527 additions and 240 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

459
doc/lightning-decode.7 generated
View File

@ -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<rusty@rustcorp.com.au\fR> is mainly responsible\.
@ -169,4 +414,4 @@ Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:4a01fe92de9520e78656495ff9093184cdf4836283af7102ee6b50ab0c826132
\" SHA256STAMP:403b7cf3cadd8b260b8b2b02746c76d7d21a8319fe386b4174f4f58b3e5dcdbd

227
doc/lightning-decode.7.md
View File

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:733d22404e5230882682b846ace92451d8988cf028fa903d735f61b7c61f1c08)

77
doc/lightning-decodepay.7 generated
View File

@ -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<rusty@rustcorp.com.au\fR> is mainly responsible\.
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR
\" SHA256STAMP:d3944c14e16584577e0336dda8c2689881524717428eb921e23f8831144ec566
\" SHA256STAMP:1b0e5c34291b3c252c651e952109f57fe68a90770fecaa0eeebf9070ed8c2dad

52
doc/lightning-decodepay.7.md
View File

@ -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: <https://github.com/ElementsProject/lightning>
[comment]: # ( SHA256STAMP:33a160a1d9e56690e59b71c4d9d3e141bf7604c111cd5a5624bda692b85c9026)

806
doc/schemas/decode.schema.json Normal file
View File

@ -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"
}
}
}
}
}
}
}
]
}

146
doc/schemas/decodepay.schema.json Normal file
View File

@ -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"
}
}
}
}
}
}