home | help 
LIGHTNING-WAIT(7)					       LIGHTNING-WAIT(7)

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: cor-
	responding 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  cre-
	ated.
     *	updated  (u64,	optional):  1-based index indicating order entry was up-
	dated.
     *	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.  - descrip-
     tion (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 la-
     bel supplied at invoice creation. (added v25.05) - description (string, op-
     tional): 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 "of-
     fered", "settled", "failed",  "local_failed"):  Still  ongoing,  completed,
     failed  locally,  or  failed  after  forwarding.  - in_channel (short_chan-
     nel_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_chan-
     nel_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 up-
     grade  to	v22.11). (added v25.05) - in_msat (msat, optional): The value of
     the incoming HTLC. (added	v25.05)  -  out_channel  (short_channel_id,  op-
     tional): 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  "pend-
     ing",  "failed",  "complete"):  Status  of the payment.  - partid (u64, op-
     tional): 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) -  pay-
     ment_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_REVO-
     CATION"):	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-listsend-
     pays(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 in-
     voices 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
     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"
       },
       "sendpays": {
	 "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"
       },
       "sendpays": {
	 "status": "complete",
	 "partid": 0,
	 "groupid": 1,
	 "payment_hash": "paymenthashwtspct20101010101010101010101010101010101010101010101"
       }
     }

Core Lightning v26.06.1 				       LIGHTNING-WAIT(7)
home | help