lightning-decode – Command for decoding an invoice string (low-level)

SYNOPSIS

decode string

DESCRIPTION

The decode RPC command checks and parses:

  • a bolt11 or bolt12 string (optionally prefixed by lightning: or LIGHTNING:) as specified by the BOLT 11 and BOLT 12 specifications.
  • a rune as created by lightning-commando-rune(7).

It may decode other formats in future.

RETURN VALUE

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”, “rune”)
  • valid (boolean): if this is false, you MUST not use the result except for diagnostics!

If type is “bolt12 offer”, and valid is true:

  • offer_id (hex): the id we use to identify this offer (always 64 characters)
  • offer_description (string): the description of the purpose of the offer
  • offer_node_id (pubkey): public key of the offering node
  • offer_chains (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
    • the genesis blockhash (always 64 characters)
  • offer_metadata (hex, optional): any metadata the creater of the offer includes
  • offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)
  • currency_minor_unit (u32, optional): the number of decimal places to apply to amount (if currency known)
  • offer_amount (u64, optional): the amount in the offer_currency adjusted by currency_minor_unit, if any
  • offer_amount_msat (msat, optional): the amount in bitcoin (if specified, and no offer_currency)
  • offer_issuer (string, optional): the description of the creator of the offer
  • offer_features (hex, optional): the feature bits of the offer
  • offer_absolute_expiry (u64, optional): UNIX timestamp of when this offer expires
  • offer_quantity_max (u64, optional): the maximum quantity (or, if 0, means any quantity)
  • offer_paths (array of objects, optional): Paths to the destination:
    • first_node_id (pubkey): the (presumably well-known) public key of the start of the path
    • blinding (pubkey): blinding factor for this path
    • path (array of objects): an individual path:
      • blinded_node_id (pubkey): node_id of the hop
      • encrypted_recipient_data (hex): encrypted TLV entry for this hop
  • offer_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)
  • unknown_offer_tlvs (array of objects, optional): Any extra fields we didn’t know how to parse:
    • type (u64): The type
    • length (u64): The length
    • value (hex): The value
  • the following warnings are possible:
    • warning_unknown_offer_currency: The currency code is unknown (so no currency_minor_unit)

If type is “bolt12 offer”, and valid is false:

  • the following warnings are possible:
    • warning_missing_offer_node_id: offer_node_id is not present
    • warning_invalid_offer_description: offer_description is not valid UTF8
    • warning_missing_offer_description: offer_description is not present
    • warning_invalid_offer_currency: offer_currency_code is not valid UTF8
    • warning_invalid_offer_issuer: offer_issuer is not valid UTF8

If type is “bolt12 invoice_request”, and valid is true:

  • offer_description (string): the description of the purpose of the offer
  • offer_node_id (pubkey): public key of the offering node
  • invreq_metadata (hex): the payer-provided blob to derive invreq_payer_id
  • invreq_payer_id (hex): the payer-provided key
  • signature (bip340sig): BIP-340 signature of the invreq_payer_id on this invoice_request
  • offer_id (hex, optional): the id we use to identify this offer (always 64 characters)
  • offer_chains (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
    • the genesis blockhash (always 64 characters)
  • offer_metadata (hex, optional): any metadata the creator of the offer includes
  • offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)
  • currency_minor_unit (u32, optional): the number of decimal places to apply to amount (if currency known)
  • offer_amount (u64, optional): the amount in the offer_currency adjusted by currency_minor_unit, if any
  • offer_amount_msat (msat, optional): the amount in bitcoin (if specified, and no offer_currency)
  • offer_issuer (string, optional): the description of the creator of the offer
  • offer_features (hex, optional): the feature bits of the offer
  • offer_absolute_expiry (u64, optional): UNIX timestamp of when this offer expires
  • offer_quantity_max (u64, optional): the maximum quantity (or, if 0, means any quantity)
  • offer_paths (array of objects, optional): Paths to the destination:
    • first_node_id (pubkey): the (presumably well-known) public key of the start of the path
    • blinding (pubkey): blinding factor for this path
    • path (array of objects): an individual path:
      • blinded_node_id (pubkey): node_id of the hop
      • encrypted_recipient_data (hex): encrypted TLV entry for this hop
  • offer_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)
  • invreq_chain (hex, optional): which blockchain this offer is for (missing implies bitcoin mainnet only) (always 64 characters)
  • invreq_amount_msat (msat, optional): the amount the invoice should be for
  • invreq_features (hex, optional): the feature bits of the invoice_request
  • invreq_quantity (u64, optional): the number of items to invoice for
  • invreq_payer_note (string, optional): a note attached by the payer
  • invreq_recurrence_counter (u32, optional): which number request this is for the same invoice
  • invreq_recurrence_start (u32, optional): when we’re requesting to start an invoice at a non-zero period
  • unknown_invoice_request_tlvs (array of objects, optional): Any extra fields we didn’t know how to parse:
    • type (u64): The type
    • length (u64): The length
    • value (hex): The value
  • the following warnings are possible:
    • warning_unknown_offer_currency: The currency code is unknown (so no currency_minor_unit)

If type is “bolt12 invoice_request”, and valid is false:

  • the following warnings are possible:
    • warning_invalid_offer_description: offer_description is not valid UTF8
    • warning_missing_offer_description: offer_description is not present
    • warning_invalid_offer_currency: offer_currency_code is not valid UTF8
    • warning_invalid_offer_issuer: offer_issuer is not valid UTF8
    • warning_missing_invreq_metadata: invreq_metadata is not present
    • warning_missing_invreq_payer_id: invreq_payer_id is not present
    • warning_invalid_invreq_payer_note: invreq_payer_note is not valid UTF8
    • warning_missing_invoice_request_signature: signature is not present
    • warning_invalid_invoice_request_signature: Incorrect signature

If type is “bolt12 invoice”, and valid is true:

  • offer_description (string): the description of the purpose of the offer
  • offer_node_id (pubkey): public key of the offering node
  • invreq_metadata (hex): the payer-provided blob to derive invreq_payer_id
  • invreq_payer_id (hex): the payer-provided key
  • invoice_paths (array of objects): Paths to pay the destination:
    • first_node_id (pubkey): the (presumably well-known) public key of the start of the path
    • blinding (pubkey): blinding factor for this path
    • path (array of objects): an individual path:
      • blinded_node_id (pubkey): node_id of the hop
      • encrypted_recipient_data (hex): encrypted TLV entry for this hop
      • fee_base_msat (msat, optional): basefee for path
      • fee_proportional_millionths (u32, optional): proportional fee for path
      • cltv_expiry_delta (u32, optional): CLTV delta for path
      • features (hex, optional): features allowed for path
  • invoice_created_at (u64): the UNIX timestamp of invoice creation
  • invoice_payment_hash (hex): the hash of the payment_preimage (always 64 characters)
  • invoice_amount_msat (msat): the amount required to fulfill invoice
  • signature (bip340sig): BIP-340 signature of the offer_node_id on this invoice
  • offer_id (hex, optional): the id we use to identify this offer (always 64 characters)
  • offer_chains (array of hexs, optional): which blockchains this offer is for (missing implies bitcoin mainnet only):
    • the genesis blockhash (always 64 characters)
  • offer_metadata (hex, optional): any metadata the creator of the offer includes
  • offer_currency (string, optional): ISO 4217 code of the currency (missing implies Bitcoin) (always 3 characters)
  • currency_minor_unit (u32, optional): the number of decimal places to apply to amount (if currency known)
  • offer_amount (u64, optional): the amount in the offer_currency adjusted by currency_minor_unit, if any
  • offer_amount_msat (msat, optional): the amount in bitcoin (if specified, and no offer_currency)
  • offer_issuer (string, optional): the description of the creator of the offer
  • offer_features (hex, optional): the feature bits of the offer
  • offer_absolute_expiry (u64, optional): UNIX timestamp of when this offer expires
  • offer_quantity_max (u64, optional): the maximum quantity (or, if 0, means any quantity)
  • offer_paths (array of objects, optional): Paths to the destination:
    • first_node_id (pubkey): the (presumably well-known) public key of the start of the path
    • blinding (pubkey): blinding factor for this path
    • path (array of objects): an individual path:
      • blinded_node_id (pubkey): node_id of the hop
      • encrypted_recipient_data (hex): encrypted TLV entry for this hop
  • offer_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)
  • invreq_chain (hex, optional): which blockchain this offer is for (missing implies bitcoin mainnet only) (always 64 characters)
  • invreq_amount_msat (msat, optional): the amount the invoice should be for
  • invreq_features (hex, optional): the feature bits of the invoice_request
  • invreq_quantity (u64, optional): the number of items to invoice for
  • invreq_payer_note (string, optional): a note attached by the payer
  • invreq_recurrence_counter (u32, optional): which number request this is for the same invoice
  • invreq_recurrence_start (u32, optional): when we’re requesting to start an invoice at a non-zero period
  • invoice_relative_expiry (u32, optional): the number of seconds after invoice_created_at when this expires
  • invoice_fallbacks (array of objects, optional): onchain addresses:
    • version (u8): Segwit address version
    • hex (hex): Raw encoded segwit address
    • address (string, optional): bech32 segwit address
  • invoice_features (hex, optional): the feature bits of the invoice
  • invoice_node_id (pubkey, optional): the id to pay (usually the same as offer_node_id)
  • invoice_recurrence_basetime (u64, optional): the UNIX timestamp to base the invoice periods on
  • unknown_invoice_tlvs (array of objects, optional): Any extra fields we didn’t know how to parse:
    • type (u64): The type
    • length (u64): The length
    • value (hex): The value
  • the following warnings are possible:
    • warning_unknown_offer_currency: The currency code is unknown (so no currency_minor_unit)

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_invalid_offer_description: offer_description is not valid UTF8
    • warning_missing_offer_description: offer_description is not present
    • warning_invalid_offer_currency: offer_currency_code is not valid UTF8
    • warning_invalid_offer_issuer: offer_issuer is not valid UTF8
    • warning_missing_invreq_metadata: invreq_metadata is not present
    • warning_invalid_invreq_payer_note: invreq_payer_note is not valid UTF8
    • warning_missing_invoice_paths: invoice_paths is not present
    • warning_missing_invoice_blindedpay: invoice_blindedpay is not present
    • warning_missing_invoice_created_at: invoice_created_at is not present
    • warning_missing_invoice_payment_hash: invoice_payment_hash is not present
    • warning_missing_invoice_amount: invoice_amount is not present
    • warning_missing_invoice_recurrence_basetime: invoice_recurrence_basetime is not present
    • warning_missing_invoice_node_id: invoice_node_id is not present
    • warning_missing_invoice_signature: signature is not present
    • warning_invalid_invoice_signature: Incorrect signature

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 created_at
  • 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
  • payment_metadata (hex, optional): the payment_metadata to put in the payment
  • 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 (msat): 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

If type is “rune”, and valid is true:

  • valid (boolean) (always true)
  • string (string): the string encoding of the rune
  • restrictions (array of objects): restrictions built into the rune: all must pass:
    • alternatives (array of strings): each way restriction can be met: any can pass:
      • the alternative of form fieldname condition fieldname
    • summary (string): human-readable summary of this restriction
  • unique_id (string, optional): unique id (always a numeric id on runes we create)
  • version (string, optional): rune version, not currently set on runes we create

If type is “rune”, and valid is false:

  • valid (boolean) (always false)
  • hex (hex, optional): the raw rune in hex
  • the following warnings are possible:
    • warning_rune_invalid_utf8: the rune contains invalid UTF-8 strings

AUTHOR

Rusty Russell <rusty@rustcorp.com.au> is mainly responsible.

SEE ALSO

lightning-pay(7), lightning-offer(7), lightning-offerout(7), lightning-fetchinvoice(7), lightning-sendinvoice(7), lightning-commando-rune(7)

BOLT #11.

BOLT #12.