"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.",
"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."
