mirror of
https://github.com/ElementsProject/lightning.git
synced 2024-11-19 18:11:28 +01:00
a55c0d005d
Not singular (though we used to have a listinvoice, removed in v0.6.1). Reported-by: "Plant" via email Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
367 lines
11 KiB
JSON
367 lines
11 KiB
JSON
{
|
|
"$schema": "../rpc-schema-draft.json",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"added": "v23.08",
|
|
"rpc": "wait",
|
|
"title": "Command to wait for creations, changes and deletions",
|
|
"description": [
|
|
"The **wait** RPC command returns once the index given by *indexname* in *subsystem* reaches or exceeds *nextvalue*. All indexes start at 0, when no events have happened (**wait** with a *nextvalue* of 0 is a way of getting the current index, though naturally this is racy!)."
|
|
],
|
|
"request": {
|
|
"required": [
|
|
"subsystem",
|
|
"indexname",
|
|
"nextvalue"
|
|
],
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"description": [
|
|
"The subsystem to get the next index value from.",
|
|
" `invoices`: corresponding to `listinvoices` (added in *v23.08*).",
|
|
" `sendpays`: corresponding to `listsendpays` (added in *v23.11*).",
|
|
" `forwards`: corresponding to `listforwards` (added in *v23.11*)."
|
|
],
|
|
"enum": [
|
|
"invoices",
|
|
"forwards",
|
|
"sendpays"
|
|
]
|
|
},
|
|
"indexname": {
|
|
"type": "string",
|
|
"description": [
|
|
"The name of the index to get the next value for.",
|
|
" `created` is incremented by one for every new object.",
|
|
" `updated` is incremented by one every time an object is changed.",
|
|
" `deleted` is incremented by one every time an object is deleted."
|
|
],
|
|
"enum": [
|
|
"created",
|
|
"updated",
|
|
"deleted"
|
|
]
|
|
},
|
|
"nextvalue": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The next value of the index."
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"response": {
|
|
"required": [
|
|
"subsystem"
|
|
],
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"invoices",
|
|
"forwards",
|
|
"sendpays"
|
|
]
|
|
},
|
|
"created": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was created."
|
|
]
|
|
},
|
|
"updated": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was updated."
|
|
]
|
|
},
|
|
"deleted": {
|
|
"type": "u64",
|
|
"description": [
|
|
"1-based index indicating order entry was deleted."
|
|
]
|
|
},
|
|
"details": {}
|
|
},
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"invoices"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"unpaid",
|
|
"paid",
|
|
"expired"
|
|
],
|
|
"description": [
|
|
"Whether it's paid, unpaid or unpayable."
|
|
]
|
|
},
|
|
"label": {
|
|
"type": "string",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": [
|
|
"Description used in the invoice."
|
|
]
|
|
},
|
|
"bolt11": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT11 string."
|
|
]
|
|
},
|
|
"bolt12": {
|
|
"type": "string",
|
|
"description": [
|
|
"The BOLT12 string."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"forwards"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"offered",
|
|
"settled",
|
|
"failed",
|
|
"local_failed"
|
|
],
|
|
"description": [
|
|
"Still ongoing, completed, failed locally, or failed after forwarding."
|
|
]
|
|
},
|
|
"in_channel": {
|
|
"type": "short_channel_id",
|
|
"description": [
|
|
"Unique label supplied at invoice creation."
|
|
]
|
|
},
|
|
"in_htlc_id": {
|
|
"type": "u64",
|
|
"description": [
|
|
"The unique HTLC id the sender gave this (not present if incoming channel was closed before upgrade to v22.11)."
|
|
]
|
|
},
|
|
"in_msat": {
|
|
"type": "msat",
|
|
"description": [
|
|
"The value of the incoming HTLC."
|
|
]
|
|
},
|
|
"out_channel": {
|
|
"type": "short_channel_id",
|
|
"description": [
|
|
"The channel that the HTLC (trying to) forward to."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"if": {
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"subsystem": {
|
|
"type": "string",
|
|
"enum": [
|
|
"sendpays"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"then": {
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"subsystem": {},
|
|
"created": {},
|
|
"updated": {},
|
|
"deleted": {},
|
|
"details": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"failed",
|
|
"complete"
|
|
],
|
|
"description": [
|
|
"Status of the payment."
|
|
]
|
|
},
|
|
"partid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Part number (for multiple parts to a single payment)."
|
|
]
|
|
},
|
|
"groupid": {
|
|
"type": "u64",
|
|
"description": [
|
|
"Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash."
|
|
]
|
|
},
|
|
"payment_hash": {
|
|
"type": "hash",
|
|
"description": [
|
|
"The hash of the *payment_preimage* which will prove payment."
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"reliability": [
|
|
"Indices can go forward by more than one; in particlar, if multiple objects were created and the one deleted, you could see this effect. Similarly, there are some places (e.g. invoice expiration) where we can update multiple entries at once.",
|
|
"",
|
|
"Indices only monotoncally increase."
|
|
],
|
|
"usage": [
|
|
"The **wait** RPC is used to track changes in the system. Consider tracking invoices being paid or expiring. The simplest (and inefficient method) would be:",
|
|
"1. Call `listinvoices` to get the current state of all invoices, and remember the highest `updated_index`. Say it was 5.",
|
|
"2. Call `wait invoices updated 6`.",
|
|
"3. When it returns, call `listinvoices` again to see what changed.",
|
|
"",
|
|
"This is obviously inefficient, so there are two optimizations:",
|
|
"1. Call `listinvoices` with `index=updated` and `start=6` to only see invoices with `updated_index` greater than or equal to 6.",
|
|
"2. `wait` itself may also return some limited subset of fields from the list command (it can't do this in all cases); for `invoices` this is `label` and `status`, allowing many callers to avoid the `listinvoices` call."
|
|
],
|
|
"errors": [
|
|
"On error the returned object will contain `code` and `message` properties, with `code` being one of the following:",
|
|
"",
|
|
"- -32602: If the given parameters are wrong."
|
|
],
|
|
"json_example": [
|
|
{
|
|
"request": {
|
|
"id": "example:wait#1",
|
|
"method": "wait",
|
|
"params": {
|
|
"subsystem": "invoices",
|
|
"indexname": "created",
|
|
"nextvalue": 1
|
|
}
|
|
},
|
|
"response": {
|
|
"subsystem": "invoices",
|
|
"created": 1,
|
|
"details": {
|
|
"status": "unpaid",
|
|
"label": "invlabel",
|
|
"bolt11": "lnbcrt420p1pjmxtevsp5d8c6gnaj8lyjy2qly783vklda9dfaqeyzyc37agxxp8h3uguv8pqpp5w6lhwxhqnuew4hle5h7qwjm27zz784mvsrzhmayhscy5t2hy5c4qdqvd9h8ver9wd3sxqyjw5qcqp99qxpqysgq09gxhjhwu9u3z6dlt5ln5f4g8zl78wz4pgh0am3kz54m9lllhqckf4gmhmt2ftrclq5x62zkqmggc7y0ju0ghdfwjz8hyd8l5cqvemgpyyhm6w"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:wait#2",
|
|
"method": "wait",
|
|
"params": {
|
|
"subsystem": "invoices",
|
|
"indexname": "updated",
|
|
"nextvalue": 2
|
|
}
|
|
},
|
|
"response": {
|
|
"subsystem": "invoices",
|
|
"updated": 2,
|
|
"details": {
|
|
"status": "expired"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"request": {
|
|
"id": "example:wait#3",
|
|
"method": "wait",
|
|
"params": {
|
|
"subsystem": "sendpays",
|
|
"indexname": "updated",
|
|
"nextvalue": 2
|
|
}
|
|
},
|
|
"response": {
|
|
"subsystem": "sendpays",
|
|
"updated": 2,
|
|
"details": {
|
|
"status": "complete",
|
|
"partid": 0,
|
|
"groupid": 1,
|
|
"payment_hash": "220dcfcf43e1fab3ce30f70eb943c3ce962393f5a65ced52d749e324b443d19e"
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"author": [
|
|
"Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible."
|
|
],
|
|
"see_also": [
|
|
"lightning-listinvoices(7)",
|
|
"lightning-listforwards(7)",
|
|
"lightning-listsendpays(7)"
|
|
],
|
|
"resources": [
|
|
"Main web site: <https://github.com/ElementsProject/lightning>"
|
|
]
|
|
}
|