aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2025-12-19 07:04:22 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
bcabb3825fd9daa351f1d56db23eb7dde8c9ab21
lightning/doc/lightning-decode.7.md
Rusty Russell bcabb3825f Makefile: Revert ba7d4a8f6b (make-schema: don't include tools/fromschema.py in SHASUMS) 
1. If the tool changes, you need to regenerate since the output may
   change.

2. This didn't just filter that out, ignored all but the first
   dependency, which made bisecting the bookkeeper plugin a nightmare:
   it didn't regenerate the .po file, causing random crashes.

If we want this, try $(filter-out tools/fromschema.py) instead.  But I
don't think we want that.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
2022-09-08 00:36:51 +03:00

12 KiB
Raw Blame History

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 of this offer (merkle hash of non-signature fields) (always 64 characters)
  • node_id (point32): x-only public key of the offering node
  • description (string): the description of the purpose of the offer
  • signature (bip340sig, optional): BIP-340 signature of the node_id on this 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
      • encrypted_recipient_data (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)

If type is "bolt12 offer", and valid is false:

  • the following warnings are possible:
    • warning_offer_missing_description: No description

If type is "bolt12 invoice", and valid is true:

  • node_id (point32): 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
  • created_at (u64): the UNIX timestamp of invoice creation
  • payment_hash (hex): the hash of the payment_preimage (always 64 characters)
  • relative_expiry (u32): the number of seconds after created_at 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)
  • chain (hex, optional): which blockchain this invoice is for (missing implies bitcoin mainnet only) (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
      • encrypted_recipient_data (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 (point32, 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

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_created_at: Missing created_at
    • 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

If type is "bolt12 invoice_request", and valid is true:

  • offer_id (hex): the id of the offer this is requesting (merkle hash of non-signature fields) (always 64 characters)
  • payer_key (point32): the transient key which identifies the payer
  • chain (hex, optional): which blockchain this invoice_request is for (missing implies bitcoin mainnet only) (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
  • 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.

RESOURCES

Main web site: https://github.com/ElementsProject/lightning