mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 22:31:48 +01:00
04884ca664
Merge information from `*.request.json` & `*.schema.json`. Also consolidate remaining details from `*.md` files and create a single file in schemas folder.
280 lines
8.4 KiB
JSON
280 lines
8.4 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 **listinvoice**. 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",
|
|
"description",
|
|
"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."
|
|
],
|
|
"example_json_request": [
|
|
{
|
|
"id": "example:waitanyinvoice#1",
|
|
"method": "waitanyinvoice",
|
|
"params": {
|
|
"lastpay_index": null,
|
|
"timeout": null
|
|
}
|
|
},
|
|
{
|
|
"id": "example:waitanyinvoice#2",
|
|
"method": "waitanyinvoice",
|
|
"params": {
|
|
"lastpay_index": 3,
|
|
"timeout": 0
|
|
}
|
|
}
|
|
],
|
|
"example_json_response": [
|
|
{
|
|
"label": "inv1",
|
|
"bolt11": "lnbcrt10n1pjmxtsxsp56sn02x8lccjfsvunnhz5858zuyxztug9luy226w4qsmfm4r8pkcspp5gw5r0dw99yf3zqxrg24l8g9m9hun9cu06ldg4rga8s9t9kv8z45sdq8d9h8vvgxqyjw5qcqp99qxpqysgqv537uh2sx8ch640mf4t43t8qjtpg3z7gukgm07tlyq986m7nvsnxkapg37z4vsxtl4thfqzc64anqr83geygkc2xaftxgr97dltqfjqpe3mhja",
|
|
"payment_hash": "43a837b5c529131100c342abf3a0bb2df932e38fd7da8a8d1d3c0ab2d9871569",
|
|
"amount_msat": 1000,
|
|
"status": "paid",
|
|
"pay_index": 1,
|
|
"amount_received_msat": 1000,
|
|
"paid_at": 1706241546,
|
|
"payment_preimage": "a0c668998de14b975f33e1060b3efd7efc0bde784ac266ab667a1b2fddab3cd1",
|
|
"description": [
|
|
"Inv1."
|
|
],
|
|
"expires_at": 1706846342,
|
|
"created_index": 1,
|
|
"updated_index": 1
|
|
},
|
|
{
|
|
"label": "inv4",
|
|
"bolt11": "lnbcrt10n1pja0tkmsp57j4z9zwvdsyh57unh3da7aac5z20clfnrwy5nqm6wujaelduw23qpp580mdrwakz9xewc2vhvpucset9gjkgdvyhw7h9frcy2d6p2lwdw2qdq8d9h8vdqxqyjw5qcqp99qxpqysgqtgyzhtxs3p2dyk8wk9q028033303702d2hml4frmu38qe79mrkgzgxvyjmq2q4nhjgcuz3uhmlda3jnhf9w6mj8mj97pkgnda9l5kdcqsdgewf",
|
|
"payment_hash": "3bf6d1bbb6114d97614cbb03cc432b2a25643584bbbd72a478229ba0abee6b94",
|
|
"amount_msat": 1000,
|
|
"status": "paid",
|
|
"pay_index": 4,
|
|
"amount_received_msat": 1000,
|
|
"paid_at": 1708633825,
|
|
"payment_preimage": "77336a342dde76050c7ee7fc18599e407dfc1edad3c784ba68e9603004365b94",
|
|
"description": "inv4",
|
|
"expires_at": 1709238619,
|
|
"created_index": 4,
|
|
"updated_index": 4
|
|
}
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-waitinvoice(7)",
|
|
"lightning-listinvoice(7)",
|
|
"lightning-delinvoice(7)",
|
|
"lightning-invoice(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
]
|
|
}
|