mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-22 14:42:40 +01:00
c8660c85ba
For BOLT12 invoices, the "description" is field missing in the invoice responses. Update the schemas accordingly: - `doc/schemas/lightning-waitanyinvoice.json` - `doc/schemas/lightning-waitinvoice.json` Also commit the generated msggen, cln-grpc, cln-rpc and pyln-grpc-proto files. Changelog-Fixed: schemas: Make description in `Wait(any)invoiceResponse` optional to handle BOLT12
275 lines
8.7 KiB
JSON
275 lines
8.7 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"rpc": "waitanyinvoice",
|
|
"title": "Command for waiting for payments",
|
|
"description": [
|
|
"The **waitanyinvoice** RPC command waits until an invoice is paid, then returns a single entry as per **listinvoices**. It will not return for any invoices paid prior to or including the *lastpay_index*.",
|
|
"",
|
|
"This is usually called iteratively: once with no arguments, then repeatedly with the returned *pay_index* entry. This ensures that no paid invoice is missed. The *pay_index* is a monotonically-increasing number assigned to an invoice when it gets paid. The first valid *pay_index* is 1."
|
|
],
|
|
"request": {
|
|
"required": [],
|
|
"properties": {
|
|
"lastpay_index": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Ignores any invoices paid prior to or including this index. 0 is equivalent to not specifying and negative value is invalid."
|
|
]
|
|
},
|
|
"timeout": {
|
|
"type": "u64",
|
|
"description": [
|
|
"If specified, wait at most that number of seconds, which must be an integer. If the specified *timeout* is reached, this command will return with an error. You can specify this to 0 so that **waitanyinvoice** will return immediately with an error if no pending invoice is available yet. If unspecified, this command will wait indefinitely."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"label",
|
|
"payment_hash",
|
|
"status",
|
|
"created_index",
|
|
"expires_at"
|
|
],
|
|
"properties": {
|
|
"label": {
|
|
"type": "string",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"Description used in the invoice."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the *payment_preimage* which will prove payment."
|
|
]
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"paid",
|
|
"expired"
|
|
],
|
|
"description": [
|
|
"Whether it's paid or expired."
|
|
]
|
|
},
|
|
"expires_at": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of when it will become / became unpayable."
|
|
]
|
|
},
|
|
"amount_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount required to pay this invoice."
|
|
]
|
|
},
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT11 string (always present unless *bolt12* is)."
|
|
]
|
|
},
|
|
"bolt12": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT12 string (always present unless *bolt11* is)."
|
|
]
|
|
},
|
|
"created_index": {
|
|
"type": "u64",
|
|
"added": "v23.08",
|
|
"description": [
|
|
"1-based index indicating order this invoice was created in."
|
|
]
|
|
},
|
|
"updated_index": {
|
|
"type": "u64",
|
|
"added": "v23.08",
|
|
"description": [
|
|
"1-based index indicating order this invoice was changed (only present if it has changed since creation)."
|
|
]
|
|
}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"paid"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"pay_index",
|
|
"amount_received_msat",
|
|
"paid_at",
|
|
"payment_preimage"
|
|
],
|
|
"properties": {
|
|
"label": {},
|
|
"description": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"bolt11": {},
|
|
"bolt12": {},
|
|
"expires_at": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"pay_index": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Unique incrementing index for this payment."
|
|
]
|
|
},
|
|
"amount_received_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The amount actually received (could be slightly greater than *amount_msat*, since clients may overpay)."
|
|
]
|
|
},
|
|
"paid_at": {
|
|
"type": "u64",
|
|
"description": [
|
|
"UNIX timestamp of when it was paid."
|
|
]
|
|
},
|
|
"paid_outpoint": {
|
|
"type": "object",
|
|
"description": [
|
|
"Outpoint this invoice was paid with."
|
|
],
|
|
"added": "v23.11",
|
|
"additionalProperties": false,
|
|
"required": [
|
|
"txid",
|
|
"outnum"
|
|
],
|
|
"properties": {
|
|
"txid": {
|
|
"added": "v23.11",
|
|
"type": "txid",
|
|
"description": [
|
|
"ID of the transaction that paid the invoice."
|
|
]
|
|
},
|
|
"outnum": {
|
|
"added": "v23.11",
|
|
"type": "u32",
|
|
"description": [
|
|
"The 0-based output number of the transaction that paid the invoice."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"payment_preimage": {
|
|
"type": "secret",
|
|
"description": [
|
|
"Proof of payment."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"else": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"label": {},
|
|
"description": {},
|
|
"payment_hash": {},
|
|
"status": {},
|
|
"msatoshi": {},
|
|
"amount_msat": {},
|
|
"bolt11": {},
|
|
"bolt12": {},
|
|
"created_index": {},
|
|
"updated_index": {},
|
|
"expires_at": {}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"errors": [
|
|
"The following error codes may occur:",
|
|
"",
|
|
"- 904: The *timeout* was reached without an invoice being paid."
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-waitinvoice(7)",
|
|
"lightning-listinvoices(7)",
|
|
"lightning-delinvoice(7)",
|
|
"lightning-invoice(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
],
|
|
"examples": [
|
|
{
|
|
"request": {
|
|
"id": "example:waitanyinvoice#1",
|
|
"method": "waitanyinvoice",
|
|
"params": {}
|
|
},
|
|
"response": {
|
|
"label": "lbl balance l1 to l2",
|
|
"bolt11": "lnbcrt5m1pn2s39ksp53sknyy2mxxurt4y0wqgp730z0cnm0vz3zmzth8p79xsrtmg5llxspp5dp94v59nm6c99jf7lc07zmnhqw6kyujx3mkdav7643dczgtdedfqdpcv3jhxcmjd9c8g6t0dcs8xetwvss8xmmdv5s8xct5wvsxcvfqw3hjqmpjxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqqduqqqqgqqqqqqqqpqqqqqzsqqc9qxpqysgqdz9cftkxe6kcqfddyrvr7j57ulsfxxxkgkjyhr3k77n8v59mzs5rmuexz9lxusyhhehlemd9ujclgahln8e0n8y86stc7u8uys6mjqgqerm6q4",
|
|
"payment_hash": "684b5650b3deb052c93efe1fe16e7703b56272468eecdeb3daac5b81216dcb52",
|
|
"amount_msat": 500000000,
|
|
"status": "paid",
|
|
"pay_index": 1,
|
|
"amount_received_msat": 500000000,
|
|
"paid_at": 1722303671,
|
|
"payment_preimage": "bed4140e1db302720d7f9547dc9127d45b115080447cce7e23cfd00b60991831",
|
|
"description": "description send some sats l1 to l2",
|
|
"expires_at": 1722908470,
|
|
"created_index": 1,
|
|
"updated_index": 1
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:waitanyinvoice#2",
|
|
"method": "waitanyinvoice",
|
|
"params": {
|
|
"lastpay_index": 1,
|
|
"timeout": 0
|
|
}
|
|
},
|
|
"response": {
|
|
"label": "lbl_l23",
|
|
"bolt11": "lnbcrt1pn2s38zsp5lv49w44a8tvkwtkxfxwts8rnr864u59srp7sxuua3haahdhlhtrqpp5p928w8rmsg2hjeymedcn54vxhsz372qhcedgf003nmsknhx9594sdqcdserxgryv4ekxunfwp6xjmmwxqyjw5qcqp9rzjqdwjkyvjm7apxnssu4qgwhfkd67ghs6n6k48v6uqczgt88p6tky96qqq0vqqqqgqqyqqqqqpqqqqqzsqqc9qxpqysgqt5h8te9lkn0jpdkhkmlkzs80aw7mt5kdm6jxmvddkavt3vj0vakkmfcs0hsde8y8g8za46sch2lp4jxy56u8ve25sgpgcsya0vp92sgphzw570",
|
|
"payment_hash": "0954771c7b821579649bcb713a5586bc051f2817c65a84bdf19ee169dcc5a16b",
|
|
"status": "paid",
|
|
"pay_index": 2,
|
|
"amount_received_msat": 9900,
|
|
"paid_at": 1722303715,
|
|
"payment_preimage": "f3a3b40d63e62785f537aad60f93980914c5639872c7746299a6a1228abbc303",
|
|
"description": "l23 description",
|
|
"expires_at": 1722908514,
|
|
"created_index": 8,
|
|
"updated_index": 2
|
|
}
|
|
}
|
|
]
|
|
}
|