core-lightning/doc/schemas/lightning-decode.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "added": "v23.05",
  "rpc": "decode",
  "title": "Command for decoding an invoice string (low-level)",
  "description": [
    "The **decode** RPC command checks and parses `bolt11`, `bolt12`, `rune` or `emergency_recover`. It may decode other formats in future."
  ],
  "request": {
    "required": [
      "string"
    ],
    "properties": {
      "string": {
        "type": "string",
        "description": [
          "Value to be decoded:",
          "    * 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).",
          "    * an *emergency_recover* string generated by hsmtool like `lightning-hsmtool getemergencyrecover <path/to/emergency.recover>`. It holds `emergency.recover` contents and starts with `clnemerg1`."
        ]
      }
    }
  },
  "response": {
    "required": [
      "type",
      "valid"
    ],
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "bolt12 offer",
          "bolt12 invoice",
          "bolt12 invoice_request",
          "bolt11 invoice",
          "rune",
          "emergency recover"
        ],
        "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"
          ],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "offer_id": {
              "type": "hex",
              "description": [
                "The id we use to identify this offer."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "offer_chains": {
              "type": "array",
              "description": [
                "Which blockchains this offer is for (missing implies bitcoin mainnet only)."
              ],
              "items": {
                "type": "hash",
                "description": [
                  "The genesis blockhash."
                ]
              }
            },
            "offer_metadata": {
              "type": "hex",
              "description": [
                "Any metadata the creator of the offer includes."
              ]
            },
            "offer_currency": {
              "type": "string",
              "description": [
                "ISO 4217 code of the currency (missing implies Bitcoin)."
              ],
              "maxLength": 3,
              "minLength": 3
            },
            "warning_unknown_offer_currency": {
              "type": "string",
              "description": [
                "The currency code is unknown (so no `currency_minor_unit`)."
              ]
            },
            "currency_minor_unit": {
              "type": "u32",
              "description": [
                "The number of decimal places to apply to amount (if currency known)."
              ]
            },
            "offer_amount": {
              "type": "u64",
              "description": [
                "The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
              ]
            },
            "offer_amount_msat": {
              "type": "msat",
              "description": [
                "The amount in bitcoin (if specified, and no `offer_currency`)."
              ]
            },
            "offer_description": {
              "type": "string",
              "description": [
                "The description of the purpose of the offer."
              ]
            },
            "offer_issuer": {
              "type": "string",
              "description": [
                "The description of the creator of the offer."
              ]
            },
            "offer_features": {
              "type": "hex",
              "description": [
                "The feature bits of the offer."
              ]
            },
            "offer_absolute_expiry": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when this offer expires."
              ]
            },
            "offer_quantity_max": {
              "type": "u64",
              "description": [
                "The maximum quantity (or, if 0, means any quantity)."
              ]
            },
            "offer_paths": {
              "type": "array",
              "description": [
                "Paths to the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v23.05",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v23.05",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "path": {
                    "type": "array",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "warning_empty_blinded_path": {
              "added": "v24.08",
              "type": "string",
              "description": [
                "The blinded path has 0 hops."
              ]
            },
            "offer_node_id": {
              "type": "pubkey",
              "deprecated": [
                "v24.08",
                "v24.11"
              ],
              "description": [
                "Obsolete name for offer_issuer_id."
              ]
            },
            "offer_issuer_id": {
              "type": "pubkey",
              "added": "v24.08",
              "description": [
                "The pubkey associated with the offer (can be a node id)."
              ]
            },
            "offer_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": "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 paid after period start."
                      ]
                    }
                  }
                }
              }
            },
            "unknown_offer_tlvs": {
              "type": "array",
              "description": [
                "Any extra fields we didn't know how to parse."
              ],
              "items": {
                "type": "object",
                "required": [
                  "type",
                  "length",
                  "value"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "u64",
                    "description": [
                      "The type."
                    ]
                  },
                  "length": {
                    "type": "u64",
                    "description": [
                      "The length."
                    ]
                  },
                  "value": {
                    "type": "hex",
                    "description": [
                      "The value."
                    ]
                  }
                }
              }
            }
          }
        }
      },
      {
        "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_unknown_offer_currency": {},
            "amount": {},
            "amount_msat": {},
            "send_invoice": {},
            "description": {},
            "vendor": {},
            "features": {},
            "absolute_expiry": {},
            "paths": {},
            "quantity_max": {},
            "unknown_offer_tlvs": {},
            "recurrence": {},
            "warning_missing_offer_node_id": {
              "type": "string",
              "deprecated": [
                "v24.08",
                "v24.11"
              ],
              "description": [
                "`offer_node_id` is not present."
              ]
            },
            "warning_missing_offer_issuer_id": {
              "type": "string",
              "added": "v24.08",
              "description": [
                "`offer_issuer_id` is not present and there are no offer_paths"
              ]
            },
            "warning_invalid_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not valid UTF8."
              ]
            },
            "warning_missing_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not present."
              ]
            },
            "warning_invalid_offer_currency": {
              "type": "string",
              "description": [
                "`offer_currency_code` is not valid UTF8."
              ]
            },
            "warning_invalid_offer_issuer": {
              "type": "string",
              "description": [
                "`offer_issuer` is not valid UTF8."
              ]
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bolt12 invoice_request"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            }
          }
        },
        "then": {
          "required": [
            "invreq_metadata",
            "invreq_payer_id",
            "signature"
          ],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "offer_id": {
              "type": "hex",
              "description": [
                "The id we use to identify this offer."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "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
              }
            },
            "offer_metadata": {
              "type": "hex",
              "description": [
                "Any metadata the creator of the offer includes."
              ]
            },
            "offer_currency": {
              "type": "string",
              "description": [
                "ISO 4217 code of the currency (missing implies Bitcoin)."
              ],
              "maxLength": 3,
              "minLength": 3
            },
            "warning_unknown_offer_currency": {
              "type": "string",
              "description": [
                "The currency code is unknown (so no `currency_minor_unit`)."
              ]
            },
            "currency_minor_unit": {
              "type": "u32",
              "description": [
                "The number of decimal places to apply to amount (if currency known)."
              ]
            },
            "offer_amount": {
              "type": "u64",
              "description": [
                "The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
              ]
            },
            "offer_amount_msat": {
              "type": "msat",
              "description": [
                "The amount in bitcoin (if specified, and no `offer_currency`)."
              ]
            },
            "offer_description": {
              "type": "string",
              "description": [
                "The description of the purpose of the offer."
              ]
            },
            "offer_issuer": {
              "type": "string",
              "description": [
                "The description of the creator of the offer."
              ]
            },
            "offer_features": {
              "type": "hex",
              "description": [
                "The feature bits of the offer."
              ]
            },
            "offer_absolute_expiry": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when this offer expires."
              ]
            },
            "offer_quantity_max": {
              "type": "u64",
              "description": [
                "The maximum quantity (or, if 0, means any quantity)."
              ]
            },
            "offer_paths": {
              "type": "array",
              "description": [
                "Paths to the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v23.05",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v23.05",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "path": {
                    "type": "array",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "offer_node_id": {
              "type": "pubkey",
              "deprecated": [
                "v24.08",
                "v24.11"
              ],
              "description": [
                "Public key of the offering node."
              ]
            },
            "offer_issuer_id": {
              "type": "pubkey",
              "added": "v24.08",
              "description": [
                "Public key of the offering node (can be a node id)."
              ]
            },
            "offer_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": "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 paid after period start."
                      ]
                    }
                  }
                }
              }
            },
            "invreq_metadata": {
              "type": "hex",
              "description": [
                "The payer-provided blob to derive invreq_payer_id."
              ]
            },
            "invreq_payer_id": {
              "type": "hex",
              "description": [
                "The payer-provided key."
              ]
            },
            "invreq_chain": {
              "type": "hex",
              "description": [
                "Which blockchain this offer is for (missing implies bitcoin mainnet only)."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "invreq_amount_msat": {
              "type": "msat",
              "description": [
                "The amount the invoice should be for."
              ]
            },
            "invreq_features": {
              "type": "hex",
              "description": [
                "The feature bits of the invoice_request."
              ]
            },
            "invreq_quantity": {
              "type": "u64",
              "description": [
                "The number of items to invoice for."
              ]
            },
            "invreq_payer_note": {
              "type": "string",
              "description": [
                "A note attached by the payer."
              ]
            },
            "invreq_paths": {
              "type": "array",
              "added": "v24.08",
              "description": [
                "Paths to the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "added": "v24.08",
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v24.08",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v24.08",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "added": "v24.08",
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "path": {
                    "type": "array",
                    "added": "v24.08",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "added": "v24.08",
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "added": "v24.08",
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "invreq_recurrence_counter": {
              "type": "u32",
              "description": [
                "Which number request this is for the same invoice."
              ]
            },
            "invreq_recurrence_start": {
              "type": "u32",
              "description": [
                "When we're requesting to start an invoice at a non-zero period."
              ]
            },
            "signature": {
              "type": "bip340sig",
              "description": [
                "BIP-340 signature of the `invreq_payer_id` on this invoice_request."
              ]
            },
            "unknown_invoice_request_tlvs": {
              "type": "array",
              "description": [
                "Any extra fields we didn't know how to parse."
              ],
              "items": {
                "type": "object",
                "required": [
                  "type",
                  "length",
                  "value"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "u64",
                    "description": [
                      "The type."
                    ]
                  },
                  "length": {
                    "type": "u64",
                    "description": [
                      "The length."
                    ]
                  },
                  "value": {
                    "type": "hex",
                    "description": [
                      "The value."
                    ]
                  }
                }
              }
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bolt12 invoice_request"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                false
              ]
            }
          }
        },
        "then": {
          "required": [],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "offer_id": {},
            "offer_chains": {},
            "offer_metadata": {},
            "offer_currency": {},
            "warning_unknown_offer_currency": {},
            "currency_minor_unit": {},
            "offer_amount": {},
            "offer_amount_msat": {},
            "offer_description": {},
            "offer_issuer": {},
            "offer_features": {},
            "offer_absolute_expiry": {},
            "offer_quantity_max": {},
            "offer_paths": {},
            "offer_node_id": {},
            "offer_issuer_id": {},
            "offer_recurrence": {},
            "invreq_metadata": {},
            "invreq_payer_id": {},
            "invreq_chain": {},
            "invreq_amount_msat": {},
            "invreq_features": {},
            "invreq_quantity": {},
            "invreq_payer_note": {},
            "invreq_paths": {},
            "invreq_recurrence_counter": {},
            "invreq_recurrence_start": {},
            "warning_invalid_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not valid UTF8."
              ]
            },
            "warning_missing_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not present."
              ]
            },
            "warning_invalid_offer_currency": {
              "type": "string",
              "description": [
                "`offer_currency_code` is not valid UTF8."
              ]
            },
            "warning_invalid_offer_issuer": {
              "type": "string",
              "description": [
                "`offer_issuer` is not valid UTF8."
              ]
            },
            "warning_missing_invreq_metadata": {
              "type": "string",
              "description": [
                "`invreq_metadata` is not present."
              ]
            },
            "warning_missing_invreq_payer_id": {
              "type": "string",
              "description": [
                "`invreq_payer_id` is not present."
              ]
            },
            "warning_invalid_invreq_payer_note": {
              "type": "string",
              "description": [
                "`invreq_payer_note` is not valid UTF8."
              ]
            },
            "warning_missing_invoice_request_signature": {
              "type": "string",
              "description": [
                "`signature` is not present."
              ]
            },
            "warning_invalid_invoice_request_signature": {
              "type": "string",
              "description": [
                "Incorrect `signature`."
              ]
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bolt12 invoice"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            }
          }
        },
        "then": {
          "required": [
            "invreq_metadata",
            "invreq_payer_id",
            "invoice_paths",
            "invoice_created_at",
            "invoice_payment_hash",
            "invoice_amount_msat",
            "signature"
          ],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "offer_id": {
              "type": "hex",
              "description": [
                "The id we use to identify this offer."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "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
              }
            },
            "offer_metadata": {
              "type": "hex",
              "description": [
                "Any metadata the creator of the offer includes."
              ]
            },
            "offer_currency": {
              "type": "string",
              "description": [
                "ISO 4217 code of the currency (missing implies Bitcoin)."
              ],
              "maxLength": 3,
              "minLength": 3
            },
            "warning_unknown_offer_currency": {
              "type": "string",
              "description": [
                "The currency code is unknown (so no `currency_minor_unit`)."
              ]
            },
            "currency_minor_unit": {
              "type": "u32",
              "description": [
                "The number of decimal places to apply to amount (if currency known)."
              ]
            },
            "offer_amount": {
              "type": "u64",
              "description": [
                "The amount in the `offer_currency` adjusted by `currency_minor_unit`, if any."
              ]
            },
            "offer_amount_msat": {
              "type": "msat",
              "description": [
                "The amount in bitcoin (if specified, and no `offer_currency`)."
              ]
            },
            "offer_description": {
              "type": "string",
              "description": [
                "The description of the purpose of the offer."
              ]
            },
            "offer_issuer": {
              "type": "string",
              "description": [
                "The description of the creator of the offer."
              ]
            },
            "offer_features": {
              "type": "hex",
              "description": [
                "The feature bits of the offer."
              ]
            },
            "offer_absolute_expiry": {
              "type": "u64",
              "description": [
                "UNIX timestamp of when this offer expires."
              ]
            },
            "offer_quantity_max": {
              "type": "u64",
              "description": [
                "The maximum quantity (or, if 0, means any quantity)."
              ]
            },
            "offer_paths": {
              "type": "array",
              "description": [
                "Paths to the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v23.05",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v23.05",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "path": {
                    "type": "array",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "offer_node_id": {
              "type": "pubkey",
              "deprecated": [
                "v24.08",
                "v24.11"
              ],
              "description": [
                "Public key of the offering node."
              ]
            },
            "offer_issuer_id": {
              "type": "pubkey",
              "added": "v24.08",
              "description": [
                "Public key of the offering node (can be a node id)."
              ]
            },
            "offer_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": "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 paid after period start."
                      ]
                    }
                  }
                }
              }
            },
            "invreq_metadata": {
              "type": "hex",
              "description": [
                "The payer-provided blob to derive invreq_payer_id."
              ]
            },
            "invreq_payer_id": {
              "type": "hex",
              "description": [
                "The payer-provided key."
              ]
            },
            "invreq_chain": {
              "type": "hex",
              "description": [
                "Which blockchain this offer is for (missing implies bitcoin mainnet only)."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "invreq_amount_msat": {
              "type": "msat",
              "description": [
                "The amount the invoice should be for."
              ]
            },
            "invreq_features": {
              "type": "hex",
              "description": [
                "The feature bits of the invoice_request."
              ]
            },
            "invreq_quantity": {
              "type": "u64",
              "description": [
                "The number of items to invoice for."
              ]
            },
            "invreq_payer_note": {
              "type": "string",
              "description": [
                "A note attached by the payer."
              ]
            },
            "invreq_paths": {
              "type": "array",
              "added": "v24.08",
              "description": [
                "Paths to the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "added": "v24.08",
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v24.08",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v24.08",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "added": "v24.08",
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "path": {
                    "type": "array",
                    "added": "v24.08",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "added": "v24.08",
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "added": "v24.08",
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "invreq_recurrence_counter": {
              "type": "u32",
              "description": [
                "Which number request this is for the same invoice."
              ]
            },
            "invreq_recurrence_start": {
              "type": "u32",
              "description": [
                "When we're requesting to start an invoice at a non-zero period."
              ]
            },
            "invoice_paths": {
              "type": "array",
              "description": [
                "Paths to pay the destination."
              ],
              "items": {
                "type": "object",
                "required": [
                  "blinding",
                  "payinfo",
                  "path"
                ],
                "additionalProperties": false,
                "properties": {
                  "first_node_id": {
                    "type": "pubkey",
                    "description": [
                      "The (presumably well-known) public key of the start of the path."
                    ]
                  },
                  "first_scid": {
                    "added": "v23.05",
                    "type": "short_channel_id",
                    "description": [
                      "the short channel id of the start of the path (alternative to first_node_id)"
                    ]
                  },
                  "first_scid_dir": {
                    "added": "v23.05",
                    "type": "u32",
                    "description": [
                      "which end of the first_scid is the start of the path"
                    ]
                  },
                  "blinding": {
                    "type": "pubkey",
                    "description": [
                      "Blinding factor for this path."
                    ]
                  },
                  "payinfo": {
                    "type": "object",
                    "required": [
                      "fee_base_msat",
                      "fee_proportional_millionths",
                      "cltv_expiry_delta",
                      "features"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "fee_base_msat": {
                        "type": "msat",
                        "description": [
                          "Basefee for path."
                        ]
                      },
                      "fee_proportional_millionths": {
                        "type": "u32",
                        "description": [
                          "Proportional fee for path."
                        ]
                      },
                      "cltv_expiry_delta": {
                        "type": "u32",
                        "description": [
                          "CLTV delta for path."
                        ]
                      },
                      "features": {
                        "type": "hex",
                        "description": [
                          "Features allowed for path."
                        ]
                      }
                    }
                  },
                  "path": {
                    "type": "array",
                    "description": [
                      "An individual path."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "blinded_node_id",
                        "encrypted_recipient_data"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "blinded_node_id": {
                          "type": "pubkey",
                          "description": [
                            "Node_id of the hop."
                          ]
                        },
                        "encrypted_recipient_data": {
                          "type": "hex",
                          "description": [
                            "Encrypted TLV entry for this hop."
                          ]
                        }
                      }
                    }
                  }
                }
              }
            },
            "invoice_created_at": {
              "type": "u64",
              "description": [
                "The UNIX timestamp of invoice creation."
              ]
            },
            "invoice_relative_expiry": {
              "type": "u32",
              "description": [
                "The number of seconds after *invoice_created_at* when this expires."
              ]
            },
            "invoice_payment_hash": {
              "type": "hex",
              "description": [
                "The hash of the *payment_preimage*."
              ],
              "maxLength": 64,
              "minLength": 64
            },
            "invoice_amount_msat": {
              "type": "msat",
              "description": [
                "The amount required to fulfill invoice."
              ]
            },
            "invoice_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."
                    ]
                  }
                }
              }
            },
            "invoice_features": {
              "type": "hex",
              "description": [
                "The feature bits of the invoice."
              ]
            },
            "invoice_node_id": {
              "type": "pubkey",
              "description": [
                "The id to pay (usually the same as offer_issuer_id)."
              ]
            },
            "invoice_recurrence_basetime": {
              "type": "u64",
              "description": [
                "The UNIX timestamp to base the invoice periods on."
              ]
            },
            "signature": {
              "type": "bip340sig",
              "description": [
                "BIP-340 signature of the `offer_issuer_id` on this invoice."
              ]
            },
            "unknown_invoice_tlvs": {
              "type": "array",
              "description": [
                "Any extra fields we didn't know how to parse."
              ],
              "items": {
                "type": "object",
                "required": [
                  "type",
                  "length",
                  "value"
                ],
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "type": "u64",
                    "description": [
                      "The type."
                    ]
                  },
                  "length": {
                    "type": "u64",
                    "description": [
                      "The length."
                    ]
                  },
                  "value": {
                    "type": "hex",
                    "description": [
                      "The value."
                    ]
                  }
                }
              }
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bolt12 invoice"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                false
              ]
            }
          }
        },
        "then": {
          "required": [],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "offer_id": {},
            "offer_chains": {},
            "offer_metadata": {},
            "offer_currency": {},
            "warning_unknown_offer_currency": {},
            "currency_minor_unit": {},
            "offer_amount": {},
            "offer_amount_msat": {},
            "offer_description": {},
            "offer_issuer": {},
            "offer_features": {},
            "offer_absolute_expiry": {},
            "offer_quantity_max": {},
            "offer_paths": {},
            "offer_node_id": {},
            "offer_issuer_id": {},
            "offer_recurrence": {},
            "invreq_metadata": {},
            "invreq_payer_id": {},
            "invreq_chain": {},
            "invreq_amount_msat": {},
            "invreq_features": {},
            "invreq_quantity": {},
            "invreq_payer_note": {},
            "invreq_paths": {},
            "invreq_node_id": {},
            "invreq_recurrence_counter": {},
            "invreq_recurrence_start": {},
            "warning_invalid_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not valid UTF8."
              ]
            },
            "warning_missing_offer_description": {
              "type": "string",
              "description": [
                "`offer_description` is not present."
              ]
            },
            "warning_invalid_offer_currency": {
              "type": "string",
              "description": [
                "`offer_currency_code` is not valid UTF8."
              ]
            },
            "warning_invalid_offer_issuer": {
              "type": "string",
              "description": [
                "`offer_issuer` is not valid UTF8."
              ]
            },
            "warning_missing_invreq_metadata": {
              "type": "string",
              "description": [
                "`invreq_metadata` is not present."
              ]
            },
            "warning_invalid_invreq_payer_note": {
              "type": "string",
              "description": [
                "`invreq_payer_note` is not valid UTF8."
              ]
            },
            "warning_missing_invoice_paths": {
              "type": "string",
              "description": [
                "`invoice_paths` is not present."
              ]
            },
            "warning_missing_invoice_blindedpay": {
              "type": "string",
              "description": [
                "`invoice_blindedpay` is not present."
              ]
            },
            "warning_missing_invoice_created_at": {
              "type": "string",
              "description": [
                "`invoice_created_at` is not present."
              ]
            },
            "warning_missing_invoice_payment_hash": {
              "type": "string",
              "description": [
                "`invoice_payment_hash` is not present."
              ]
            },
            "warning_missing_invoice_amount": {
              "type": "string",
              "description": [
                "`invoice_amount` is not present."
              ]
            },
            "warning_missing_invoice_recurrence_basetime": {
              "type": "string",
              "description": [
                "`invoice_recurrence_basetime` is not present."
              ]
            },
            "warning_missing_invoice_node_id": {
              "type": "string",
              "description": [
                "`invoice_node_id` is not present."
              ]
            },
            "warning_missing_invoice_signature": {
              "type": "string",
              "description": [
                "`signature` is not present."
              ]
            },
            "warning_invalid_invoice_signature": {
              "type": "string",
              "description": [
                "Incorrect `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": [
                "bolt11 invoice"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            }
          }
        },
        "then": {
          "required": [
            "currency",
            "created_at",
            "expiry",
            "payee",
            "min_final_cltv_expiry",
            "payment_hash",
            "signature"
          ],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "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 `created_at`."
              ]
            },
            "payee": {
              "type": "pubkey",
              "description": [
                "The public key of the recipient."
              ]
            },
            "amount_msat": {
              "type": "msat",
              "description": [
                "Amount the invoice asked for."
              ]
            },
            "payment_hash": {
              "type": "hash",
              "description": [
                "The hash of the *payment_preimage*."
              ]
            },
            "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": "hash",
              "description": [
                "The hash of the description, in place of *description*."
              ]
            },
            "min_final_cltv_expiry": {
              "type": "u32",
              "description": [
                "The minimum CLTV delay for the final node."
              ]
            },
            "payment_secret": {
              "type": "secret",
              "description": [
                "The secret to hand to the payee node."
              ]
            },
            "features": {
              "type": "hex",
              "description": [
                "The features bitmap for this invoice."
              ]
            },
            "payment_metadata": {
              "type": "hex",
              "description": [
                "The payment_metadata to put in the payment."
              ]
            },
            "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",
                      "P2TR"
                    ]
                  },
                  "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": "msat",
                      "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."
                    ]
                  }
                }
              }
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "rune"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            }
          }
        },
        "then": {
          "required": [
            "string",
            "restrictions",
            "valid"
          ],
          "additionalProperties": false,
          "properties": {
            "unique_id": {
              "type": "string",
              "description": [
                "Unique id (always a numeric id on runes we create)."
              ]
            },
            "version": {
              "type": "string",
              "description": [
                "Rune version, not currently set on runes we create."
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            },
            "type": {},
            "string": {
              "type": "string",
              "description": [
                "The string encoding of the rune."
              ]
            },
            "restrictions": {
              "type": "array",
              "description": [
                "Restrictions built into the rune: all must pass."
              ],
              "items": {
                "type": "object",
                "required": [
                  "alternatives",
                  "summary"
                ],
                "additionalProperties": false,
                "properties": {
                  "alternatives": {
                    "type": "array",
                    "description": [
                      "Each way restriction can be met: any can pass."
                    ],
                    "items": {
                      "type": "string",
                      "description": [
                        "The alternative of form fieldname condition fieldname."
                      ]
                    }
                  },
                  "summary": {
                    "type": "string",
                    "description": [
                      "Human-readable summary of this restriction."
                    ]
                  }
                }
              }
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "rune"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                false
              ]
            }
          }
        },
        "then": {
          "required": [
            "valid"
          ],
          "additionalProperties": false,
          "properties": {
            "valid": {
              "type": "boolean",
              "enum": [
                false
              ]
            },
            "type": {},
            "warning_rune_invalid_utf8": {
              "type": "string",
              "description": [
                "The rune contains invalid UTF-8 strings."
              ]
            },
            "hex": {
              "type": "hex",
              "description": [
                "The raw rune in hex."
              ]
            }
          }
        }
      },
      {
        "if": {
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "emergency recover"
              ]
            },
            "valid": {
              "type": "boolean",
              "enum": [
                true
              ]
            }
          }
        },
        "then": {
          "required": [
            "decrypted"
          ],
          "additionalProperties": false,
          "properties": {
            "type": {},
            "valid": {},
            "decrypted": {
              "type": "hex",
              "description": [
                "The decrypted value of the provided bech32 of emergency.recover."
              ],
              "added": "v23.11"
            }
          }
        }
      }
    ]
  },
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
  ],
  "see_also": [
    "lightning-pay(7)",
    "lightning-offer(7)",
    "lightning-fetchinvoice(7)",
    "lightning-sendinvoice(7)",
    "lightning-commando-rune(7)"
  ],
  "resources": [
    "[BOLT #11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)",
    "",
    "[BOLT #12](https://github.com/rustyrussell/lightning-rfc/blob/guilt/offers/12-offer-encoding.md)",
    "(experimental, [bolt](https://github.com/lightning/bolts) #798)",
    "",
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:decode#1",
        "method": "decode",
        "params": [
          "zFMd1fjhrAYxUeFA54TjloZqOt8JrA_i_nYwIgXkag49MA=="
        ]
      },
      "response": {
        "type": "rune",
        "unique_id": "0",
        "string": "cc531dd5f8e1ac063151e140e784e396866a3adf09ac0fe2fe76302205e46a0e:=0",
        "restrictions": [],
        "valid": true
      }
    },
    {
      "request": {
        "id": "example:decode#2",
        "method": "decode",
        "params": [
          "lnbcrt2u1pn2s3xxsp5cpcdj2cy5wpd2nphp2evrp9kqymxf9434zftkmdd6dlgmy8cu78qpp58yq5qf3h0694xwymzjs5e8eejce83vjmxv6cpwqv8cs9e05dxe4qdqcdserygryv4ekxunfwp6xjmmwxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqqduqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgq9wlpxf8ur0q798646w94tduf6wfkaw7m0ecmxepgatd4utvsyvcy0pku9t8m39rlsjzhe8x53mup5jkn0f84clfj3ctc6qj09t35wxspycpup2"
        ]
      },
      "response": {
        "type": "bolt11 invoice",
        "currency": "bcrt",
        "created_at": 1722303686,
        "expiry": 604800,
        "payee": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
        "amount_msat": 200000,
        "description": "l22 description",
        "min_final_cltv_expiry": 5,
        "payment_secret": "c070d92b04a382d54c370ab2c184b601366496b1a892bb6dadd37e8d90f8e78e",
        "features": "02024100",
        "routes": [
          [
            {
              "pubkey": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
              "short_channel_id": "111x1x0",
              "fee_base_msat": 1,
              "fee_proportional_millionths": 10,
              "cltv_expiry_delta": 6
            }
          ]
        ],
        "payment_hash": "39014026377e8b53389b14a14c9f39963278b25b333580b80c3e205cbe8d366a",
        "signature": "304402202bbe1324fc1bc1e29f55d38b55b789d3936ebbdb7e71b36428eadb5e2d90233002204786dc2acfb8947f84857c9cd48ef81a4ad37a4f5c7d328e178d024f2ae3471a",
        "valid": true
      }
    }
  ]
}