LIGHTNING-WAIT(7)

🌈 LIGHTNING-WAIT(7) 🌈

okay bestie, this is the lightning-wait manual page — aka the wait command, and it is literally giving "sit tight until the index catches up" energy. 🎀

---

💖 NAME 💖

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 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! 🙈).

• subsystem (string) (one of "invoices", "forwards", "sendpays", "htlcs", "chainmoves", "channelmoves", "networkevents"): 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).
  • htlcs: corresponding to listhtlcs (added in v25.05).
  • chainmoves: corresponding to listchainmoves (added in v25.09).
  • channelmoves: corresponding to listchannelmoves (added in v25.09).
  • networkevents: corresponding to listnetworkevents (added in v25.12).
• 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 particular, if multiple objects were created and the one deleted, you could see this effect (a channel closing will delete all the htlcs, for example). You can also see if it changes happen more rapidly than you can call wait again.

Indices only monotoncally increase. 🦋

👑 RETURN VALUE 👑

On success, an object is returned, containing:

• subsystem (string) (one of "invoices", "forwards", "sendpays", "htlcs", "chainmoves", "channelmoves", "networkevents")
• 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) deprecated in v25.05, removed after v26.06:
  • 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): Description used in the invoice.
  • bolt11 (string, optional): The BOLT11 string.
  • bolt12 (string, optional): The BOLT12 string.
• invoices (object, optional) (added v25.05):
  • status (string, optional) (one of "unpaid", "paid", "expired"): Whether it's paid, unpaid or unpayable. (added v25.05)
  • label (string, optional): Unique label supplied at invoice creation. (added v25.05)
  • description (string, optional): Description used in the invoice. (added v25.05)
  • bolt11 (string, optional): The BOLT11 string. (added v25.05)
  • bolt12 (string, optional): The BOLT12 string. (added v25.05)

🌸 If subsystem is "forwards" 🌸

• details (object, optional) deprecated in v25.05, removed after v26.06:
  • status (string, optional) (one of "offered", "settled", "failed", "local_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, optional): The channel that the HTLC (trying to) forward to.
• forwards (object, optional) (added v25.05):
  • status (string, optional) (one of "offered", "settled", "failed", "local_failed"): Still ongoing, completed, failed locally, or failed after forwarding. (added v25.05)
  • in_channel (short_channel_id, optional): Unique label supplied at invoice creation. (added v25.05)
  • 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). (added v25.05)
  • in_msat (msat, optional): The value of the incoming HTLC. (added v25.05)
  • out_channel (short_channel_id, optional): The channel that the HTLC (trying to) forward to. (added v25.05)

🫶 If subsystem is "sendpays" 🫶

• details (object, optional) deprecated in v25.05, removed after v26.06:
  • 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 disambiguate 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.
• sendpays (object, optional) (added v25.05):
  • status (string, optional) (one of "pending", "failed", "complete"): Status of the payment. (added v25.05)
  • partid (u64, optional): Part number (for multiple parts to a single payment). (added v25.05)
  • groupid (u64, optional): Grouping key to disambiguate multiple attempts to pay an invoice or the same payment_hash. (added v25.05)
  • payment_hash (hash, optional): The hash of the payment_preimage which will prove payment. (added v25.05)

🧚 If subsystem is "htlcs" 🧚

• htlcs (object, optional) (added v25.05):
  • state (string, optional) (one of "SENT_ADD_HTLC", "SENT_ADD_COMMIT", "RCVD_ADD_REVOCATION", "RCVD_ADD_ACK_COMMIT", "SENT_ADD_ACK_REVOCATION", "RCVD_REMOVE_HTLC", "RCVD_REMOVE_COMMIT", "SENT_REMOVE_REVOCATION", "SENT_REMOVE_ACK_COMMIT", "RCVD_REMOVE_ACK_REVOCATION", "RCVD_ADD_HTLC", "RCVD_ADD_COMMIT", "SENT_ADD_REVOCATION", "SENT_ADD_ACK_COMMIT", "RCVD_ADD_ACK_REVOCATION", "SENT_REMOVE_HTLC", "SENT_REMOVE_COMMIT", "RCVD_REMOVE_REVOCATION", "RCVD_REMOVE_ACK_COMMIT", "SENT_REMOVE_ACK_REVOCATION"): The first 10 states are for out, the next 10 are for in. (added v25.05)
  • htlc_id (u64, optional): The id field which uniquely identifies this HTLC for this channel and direction. (added v25.05)
  • short_channel_id (short_channel_id, optional): The channel that contains/contained the HTLC. (added v25.05)
  • cltv_expiry (u32, optional): The block number where this HTLC expires/expired. (added v25.05)
  • amount_msat (msat, optional): The value of the HTLC. (added v25.05)
  • direction (string, optional) (one of "out", "in"): Out if we offered this to the peer, in if they offered it. (added v25.05)
  • payment_hash (hash, optional): Payment hash sought by HTLC. (added v25.05)

⭐ If subsystem is "chainmoves" ⭐

• chainmoves (object, optional) (added v25.09):
  • account (string): The account (e.g. channel id) associated with this movement. (added v25.09)
  • credit_msat (msat): The amount incoming (added v25.09)
  • debit_msat (msat): The amount outgoing (added v25.09)

🌈 If subsystem is "channelmoves" 🌈

• channelmoves (object, optional) (added v25.09):
  • account (string): The account (e.g. channel id) associated with this movement. (added v25.09)
  • credit_msat (msat): The amount incoming (added v25.09)
  • debit_msat (msat): The amount outgoing (added v25.09)

🔥 If subsystem is "networkevents" 🔥

• networkevents (object, optional) (added v25.12):
  • created_index (u64, optional): The created_index of the record added/deleted (added v25.12)
  • type (string, optional) (one of "connect", "connect_fail", "ping", "disconnect"): The kind of network event (added v25.12)
  • peer_id (pubkey, optional): The peer this network event was with (added v25.12)

💀 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-listsendpays(7), lightning-listhtlcs(7), lightning-listchainmoves(7), lightning-listchannelmoves(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 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.

✨ EXAMPLES ✨

okay bestie, this is the part where it all clicks 💡 — three whole examples, and honestly they're giving tutorial energy in the best way. Let's walk through them together 🫶

---

🌸 Example 1: the "just tell me when something happens" classic

So first up, you're asking about the invoices subsystem and its created index, starting from 0. Request:

$ lightning-cli wait -k "subsystem"="invoices" "indexname"="created" "nextvalue"=0

and the actual JSON-RPC request that goes over the wire looks like this:

{
  "id": "example:wait#1",
  "method": "wait",
  "params": {
    "subsystem": "invoices",
    "indexname": "created",
    "nextvalue": 0
  }
}

Then the response comes back, no cap:

{
  "subsystem": "invoices",
  "created": 16
}

see how it handed you back the subsystem plus the index name created with its new value 16? that's the whole vibe ✨ it just tells you the next thing that happened. iconic.

---

🦋 Example 2: waiting on sendpays, and getting details

Now we're on sendpays and the created index, this time starting from 18:

$ lightning-cli wait -k "subsystem"="sendpays" "indexname"="created" "nextvalue"=18

which becomes this request:

{
  "id": "example:wait#2",
  "method": "wait",
  "params": {
    "subsystem": "sendpays",
    "indexname": "created",
    "nextvalue": 18
  }
}

and the response:

{
  "subsystem": "sendpays",
  "created": 18,
  "details": {
    "status": "pending",
    "partid": 0,
    "groupid": 1,
    "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101"
  },
  "sendpays": {
    "status": "pending",
    "partid": 0,
    "groupid": 1,
    "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101"
  }
}

look at that — you get the value 18, plus a details object and a sendpays object, both carrying status ("pending" here), partid 0, groupid 1, and the payment_hash 💅 same info, two spots, that's just how it's served up.

---

🎀 Example 3: positional params, same energy

Last one, and look at you going positional this time — no -k keys, just straight values in order:

$ lightning-cli wait "sendpays" "updated" "18"

request:

{
  "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"
  },
  "sendpays": {
    "status": "complete",
    "partid": 0,
    "groupid": 1,
    "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101"
  }
}

same shape as before, except this time it's the updated index doing the work and the status is "complete" instead of "pending" 🏁 — so you can literally watch the state move. obsessed. 🔥

---

💀 friendly reminder before you run off and build something on this: go back and reread the RELIABILITY and ERRORS sections from earlier in the page, because this command is exactly the kind of thing where knowing what happens when stuff goes sideways matters. don't skip it, bestie. 🙈

---

and that's a wrap on LIGHTNING-WAIT(7) 🎉 this whole thing came to you from Core Lightning v26.06.9 — that's the source/version stamped on the footer of the page, which also carries the page name LIGHTNING-WAIT(7) at the end. go forth and wait on indexes like the main character you are. periodt 💖✨