FreeBSD Manual Pages
LIGHTNING-WAIT(7) LIGHTNING-WAIT(7) NAME lightning-wait -- Command to wait for creations, changes and deletions SYNOPSIS wait subsystem indexname nextvalue DESCRIPTION Command added in v23.08. The wait RPC command returns once the index given by indexname in sub- system 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!). • subsystem (string) (one of "invoices", "forwards", "sendpays"): The subsystem to get the next index value from. invoices: corresponding to listinvoices (added in v23.08). sendpays: corresponding to list- sendpays (added in v23.11). forwards: corresponding to listforwards (added in v23.11). • indexname (string) (one of "created", "updated", "deleted"): 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. • nextvalue (u64): The next value of the index. RELIABILITY Indices can go forward by more than one; in particlar, if multiple ob- jects were created and the one deleted, you could see this effect. Sim- ilarly, there are some places (e.g. invoice expiration) where we can update multiple entries at once. Indices only monotoncally increase. RETURN VALUE On success, an object is returned, containing: • subsystem (string) (one of "invoices", "forwards", "sendpays") • created (u64, optional): 1-based index indicating order entry was created. • updated (u64, optional): 1-based index indicating order entry was updated. • deleted (u64, optional): 1-based index indicating order entry was deleted. If subsystem is "invoices": - details (object, optional): - status (string, optional) (one of "unpaid", "paid", "expired"): Whether it's paid, unpaid or unpayable. - label (string, optional): Unique label supplied at invoice creation. - description (string, optional): De- scription used in the invoice. - bolt11 (string, optional): The BOLT11 string. - bolt12 (string, optional): The BOLT12 string. If subsystem is "forwards": - details (object, optional): - status (string, optional) (one of "offered", "settled", "failed", "lo- cal_failed"): Still ongoing, completed, failed locally, or failed after forwarding. - in_channel (short_channel_id, optional): Unique label supplied at invoice creation. - in_htlc_id (u64, optional): The unique HTLC id the sender gave this (not present if incoming channel was closed before upgrade to v22.11). - in_msat (msat, optional): The value of the incoming HTLC. - out_channel (short_channel_id, op- tional): The channel that the HTLC (trying to) forward to. If subsystem is "sendpays": - details (object, optional): - status (string, optional) (one of "pending", "failed", "complete"): Status of the payment. - partid (u64, optional): Part number (for multiple parts to a single payment). - groupid (u64, optional): Grouping key to dis- ambiguate multiple attempts to pay an invoice or the same payment_hash. - payment_hash (hash, optional): The hash of the payment_preimage which will prove payment. 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. AUTHOR Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. SEE ALSO lightning-listinvoices(7), lightning-listforwards(7), lightning-list- sendpays(7) RESOURCES Main web site: <https://github.com/ElementsProject/lightning> 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 re- member 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 in- voices 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 la- bel and status, allowing many callers to avoid the listinvoices call. EXAMPLES Example 1: Request: $ lightning-cli wait -k "subsystem"="invoices" "indexname"="created" "nextvalue"=0 { "id": "example:wait#1", "method": "wait", "params": { "subsystem": "invoices", "indexname": "created", "nextvalue": 0 } } Response: { "subsystem": "invoices", "created": 16 } Example 2: Request: $ lightning-cli wait -k "subsystem"="sendpays" "indexname"="created" "nextvalue"=18 { "id": "example:wait#2", "method": "wait", "params": { "subsystem": "sendpays", "indexname": "created", "nextvalue": 18 } } Response: { "subsystem": "sendpays", "created": 18, "details": { "status": "pending", "partid": 0, "groupid": 1, "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101" } } Example 3: Request: $ lightning-cli wait "sendpays" "updated" "18" { "id": "example:wait#3", "method": "wait", "params": [ "sendpays", "updated", 18 ] } Response: { "subsystem": "sendpays", "updated": 18, "details": { "status": "complete", "partid": 0, "groupid": 1, "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101" } } Core Lightning v25.02 LIGHTNING-WAIT(7)
NAME | SYNOPSIS | DESCRIPTION | RELIABILITY | RETURN VALUE | ERRORS | AUTHOR | SEE ALSO | RESOURCES | USAGE | EXAMPLES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-wait&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>