diff --git a/doc/lightning-listpeers.7 b/doc/lightning-listpeers.7 index 04ace1236..03d142e8c 100644 --- a/doc/lightning-listpeers.7 +++ b/doc/lightning-listpeers.7 @@ -41,6 +41,302 @@ node will no longer appear in the command output\. .SH RETURN VALUE +On success, an object containing \fBpeers\fR is returned\. It is an array of objects, where each object contains: + +.RS +.IP \[bu] +\fBid\fR (pubkey): the public key of the peer +.IP \[bu] +\fBconnected\fR (boolean): True if the peer is currently connected +.IP \[bu] + +\fBchannels\fR (array of objects): + +.RS +.IP \[bu] +\fBstate\fR (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBopener\fR (string): Who initiated the channel (one of "local", "remote") +.IP \[bu] +\fBfeatures\fR (array of strings): +.RS +.IP \[bu] +BOLT #9 features which apply to this channel (one of "option_static_remotekey", "option_anchor_outputs") + +.RE + +.IP \[bu] +\fBscratch_txid\fR (txid, optional): The txid we would use if we went onchain now +.IP \[bu] +\fBfeerate\fR (object, optional): Feerates for the current tx: +.RS +.IP \[bu] +\fBperkw\fR (u32): Feerate per 1000 weight (i\.e kSipa) +.IP \[bu] +\fBperkb\fR (u32): Feerate per 1000 virtual bytes + +.RE + +.IP \[bu] +\fBowner\fR (string, optional): The current subdaemon controlling this connection +.IP \[bu] +\fBshort_channel_id\fR (short_channel_id, optional): The short_channel_id (once locked in) +.IP \[bu] +\fBchannel_id\fR (hex, optional): The full channel_id (always 64 characters) +.IP \[bu] +\fBfunding_txid\fR (txid, optional): ID of the funding transaction +.IP \[bu] +\fBinflight\fR (array of objects, optional): Current candidate funding transactions (only for dual-funding): +.RS +.IP \[bu] +\fBfunding_txid\fR (txid): ID of the funding transaction +.IP \[bu] +\fBfunding_outnum\fR (u32): The 0-based output number of the funding transaction which opens the channel +.IP \[bu] +\fBfeerate\fR (string): The feerate for this funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBtotal_funding_msat\fR (msat): total amount in the channel +.IP \[bu] +\fBour_funding_msat\fR (msat): amount we have in the channel +.IP \[bu] +\fBscratch_txid\fR (txid): The commitment transaction txid we would use if we went onchain now + +.RE + +.IP \[bu] +\fBclose_to\fR (hex, optional): scriptPubkey which we have to close to if we mutual close +.IP \[bu] +\fBprivate\fR (boolean, optional): if False, we will not announce this channel +.IP \[bu] +\fBcloser\fR (string, optional): Who initiated the channel close (\fBnull\fR is deprecated!) (one of "local", "remote", \fInull\fR) +.IP \[bu] +\fBfunding\fR (object, optional): +.RS +.IP \[bu] +\fBlocal_msat\fR (msat): Amount of channel we funded +.IP \[bu] +\fBremote_msat\fR (msat): Amount of channel they funded + +.RE + +.IP \[bu] +\fBto_us_msat\fR (msat, optional): how much of channel is owed to us +.IP \[bu] +\fBmin_to_us_msat\fR (msat, optional): least amount owed to us ever +.IP \[bu] +\fBmax_to_us_msat\fR (msat, optional): most amount owed to us ever +.IP \[bu] +\fBtotal_msat\fR (msat, optional): total amount in the channel +.IP \[bu] +\fBfee_base_msat\fR (msat, optional): amount we charge to use the channel +.IP \[bu] +\fBfee_proportional_millionths\fR (u32, optional): amount we charge to use the channel in parts-per-million +.IP \[bu] +\fBdust_limit_msat\fR (msat, optional): minimum amount for an output on the channel transactions +.IP \[bu] +\fBmax_total_htlc_in_msat\fR (msat, optional): max amount accept in a single payment +.IP \[bu] +\fBtheir_reserve_msat\fR (msat, optional): minimum we insist they keep in channel +.IP \[bu] +\fBour_reserve_msat\fR (msat, optional): minimum they insist we keep in channel +.IP \[bu] +\fBspendable_msat\fR (msat, optional): total we could send through channel +.IP \[bu] +\fBreceivable_msat\fR (msat, optional): total peer could send through channel +.IP \[bu] +\fBminimum_htlc_in_msat\fR (msat, optional): the minimum amount HTLC we accept +.IP \[bu] +\fBtheir_to_self_delay\fR (u32, optional): the number of blocks before they can take their funds if they unilateral close +.IP \[bu] +\fBour_to_self_delay\fR (u32, optional): the number of blocks before we can take our funds if we unilateral close +.IP \[bu] +\fBmax_accepted_htlcs\fR (u32, optional): Maximum number of incoming HTLC we will accept at once +.IP \[bu] +\fBstate_changes\fR (array of objects, optional): Prior state changes: +.RS +.IP \[bu] +\fBtimestamp\fR (string): UTC timestamp of form YYYY-mm-ddTHH:MM:SS\.%03dZ +.IP \[bu] +\fBold_state\fR (string): Previous state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBnew_state\fR (string): New state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") +.IP \[bu] +\fBcause\fR (string): What caused the change (one of "unknown", "local", "user", "remote", "protocol", "onchain") +.IP \[bu] +\fBmessage\fR (string): Human-readable explanation + +.RE + +.IP \[bu] +\fBstatus\fR (array of strings, optional): +.RS +.IP \[bu] +Billboard log of significant changes + +.RE + +.IP \[bu] +\fBin_payments_offered\fR (u64, optional): Number of incoming payment attempts +.IP \[bu] +\fBin_offered_msat\fR (msat, optional): Total amount of incoming payment attempts +.IP \[bu] +\fBin_payments_fulfilled\fR (u64, optional): Number of successful incoming payment attempts +.IP \[bu] +\fBin_fulfilled_msat\fR (msat, optional): Total amount of successful incoming payment attempts +.IP \[bu] +\fBout_payments_offered\fR (u64, optional): Number of outgoing payment attempts +.IP \[bu] +\fBout_offered_msat\fR (msat, optional): Total amount of outgoing payment attempts +.IP \[bu] +\fBout_payments_fulfilled\fR (u64, optional): Number of successful outgoing payment attempts +.IP \[bu] +\fBout_fulfilled_msat\fR (msat, optional): Total amount of successful outgoing payment attempts +.IP \[bu] + +\fBhtlcs\fR (array of objects, optional): current HTLCs in this channel: + +.RS +.IP \[bu] +\fBdirection\fR (string): Whether it came from peer, or is going to peer (one of "in", "out") +.IP \[bu] +\fBid\fR (u64): Unique ID for this htlc on this channel in this direction +.IP \[bu] +\fBamount_msat\fR (msat): Amount send/received for this HTLC +.IP \[bu] +\fBexpiry\fR (u32): Block this HTLC expires at +.IP \[bu] +\fBpayment_hash\fR (hex): the hash of the payment_preimage which will prove payment (always 64 characters) +.IP \[bu] +\fBlocal_trimmed\fR (boolean, optional): if this is too small to enforce onchain (always \fItrue\fR) +.IP \[bu] +\fBstatus\fR (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin) + +.RE + +If \fBdirection\fR is "out": + +.RS +.IP \[bu] +\fBstate\fR (string): Status of the HTLC (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") + +.RE + +If \fBdirection\fR is "in": + +.RS +.IP \[bu] +\fBstate\fR (string): Status of the HTLC (one of "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") + +.RE + + +.RE + +If \fBclose_to\fR is present: + +.RS +.IP \[bu] +\fBclose_to_addr\fR (string, optional): The bitcoin address we will close to + +.RE + +If \fBscratch_txid\fR is present: + +.RS +.IP \[bu] +\fBlast_tx_fee_msat\fR (msat): fee attached to this the current tx + +.RE + +If \fBshort_channel_id\fR is present: + +.RS +.IP \[bu] +\fBdirection\fR (u32): 0 if we're the lesser node_id, 1 if we're the greater + +.RE + +If \fBinflight\fR is present: + +.RS +.IP \[bu] +\fBinitial_feerate\fR (string): The feerate for the initial funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBlast_feerate\fR (string): The feerate for the latest funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBnext_feerate\fR (string): The minimum feerate for the next funding transaction in per-1000-weight, with "kpw" appended +.IP \[bu] +\fBnext_feestep\fR (u32, optional): The number of fee steps so far, plus one + +.RE + +.IP \[bu] + +\fBlog\fR (array of objects, optional): if \fIlevel\fR is specified, logs for this peer: + +.RS +.IP \[bu] +\fBtype\fR (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") + +.RE + +If \fBtype\fR is "SKIPPED": + +.RS +.IP \[bu] +\fBnum_skipped\fR (u32): number of deleted/omitted entries + +.RE + +If \fBtype\fR is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + +.RS +.IP \[bu] +\fBtime\fR (string): UNIX timestamp with 9 decimal places +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The actual log message +.IP \[bu] +\fBnode_id\fR (pubkey): The peer this is associated with + +.RE + +If \fBtype\fR is "IO_IN" or "IO_OUT": + +.RS +.IP \[bu] +\fBtime\fR (string): UNIX timestamp with 9 decimal places +.IP \[bu] +\fBsource\fR (string): The particular logbook this was found in +.IP \[bu] +\fBlog\fR (string): The actual log message +.IP \[bu] +\fBnode_id\fR (pubkey): The peer this is associated with +.IP \[bu] +\fBdata\fR (hex): The IO which occurred + +.RE + + +.RE + +If \fBconnected\fR is \fItrue\fR: + +.RS +.IP \[bu] +\fBnetaddr\fR (array of strings): A single entry array: +.RS +.IP \[bu] +address, e\.g\. 1\.2\.3\.4:1234 + +.RE + +.IP \[bu] +\fBfeatures\fR (hex): bitmap of BOLT #9 features from peer's INIT message + +.RE + On success, an object with a "peers" key is returned containing a list of 0 or more objects\. @@ -342,4 +638,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Lightning RFC site (BOLT #9): \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md\fR -\" SHA256STAMP:1163bde5a9f836ba7bd142559cd3bab893ab3159a99041a88ac8b31556b67905 +\" SHA256STAMP:840f7597143789d88d7e3ef1c3e8a1e50dbee44b4b471f0608433fd60077248e diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md index e97f534a1..281141a00 100644 --- a/doc/lightning-listpeers.7.md +++ b/doc/lightning-listpeers.7.md @@ -38,6 +38,122 @@ node will no longer appear in the command output. RETURN VALUE ------------ +[comment]: # (GENERATE-FROM-SCHEMA-START) +On success, an object containing **peers** is returned. It is an array of objects, where each object contains: +- **id** (pubkey): the public key of the peer +- **connected** (boolean): True if the peer is currently connected +- **channels** (array of objects): + - **state** (string): the channel state, in particular "CHANNELD_NORMAL" means the channel can be used normally (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **opener** (string): Who initiated the channel (one of "local", "remote") + - **features** (array of strings): + - BOLT #9 features which apply to this channel (one of "option_static_remotekey", "option_anchor_outputs") + - **scratch_txid** (txid, optional): The txid we would use if we went onchain now + - **feerate** (object, optional): Feerates for the current tx: + - **perkw** (u32): Feerate per 1000 weight (i.e kSipa) + - **perkb** (u32): Feerate per 1000 virtual bytes + - **owner** (string, optional): The current subdaemon controlling this connection + - **short_channel_id** (short_channel_id, optional): The short_channel_id (once locked in) + - **channel_id** (hex, optional): The full channel_id (always 64 characters) + - **funding_txid** (txid, optional): ID of the funding transaction + - **inflight** (array of objects, optional): Current candidate funding transactions (only for dual-funding): + - **funding_txid** (txid): ID of the funding transaction + - **funding_outnum** (u32): The 0-based output number of the funding transaction which opens the channel + - **feerate** (string): The feerate for this funding transaction in per-1000-weight, with "kpw" appended + - **total_funding_msat** (msat): total amount in the channel + - **our_funding_msat** (msat): amount we have in the channel + - **scratch_txid** (txid): The commitment transaction txid we would use if we went onchain now + - **close_to** (hex, optional): scriptPubkey which we have to close to if we mutual close + - **private** (boolean, optional): if False, we will not announce this channel + - **closer** (string, optional): Who initiated the channel close (`null` is deprecated!) (one of "local", "remote", *null*) + - **funding** (object, optional): + - **local_msat** (msat): Amount of channel we funded + - **remote_msat** (msat): Amount of channel they funded + - **to_us_msat** (msat, optional): how much of channel is owed to us + - **min_to_us_msat** (msat, optional): least amount owed to us ever + - **max_to_us_msat** (msat, optional): most amount owed to us ever + - **total_msat** (msat, optional): total amount in the channel + - **fee_base_msat** (msat, optional): amount we charge to use the channel + - **fee_proportional_millionths** (u32, optional): amount we charge to use the channel in parts-per-million + - **dust_limit_msat** (msat, optional): minimum amount for an output on the channel transactions + - **max_total_htlc_in_msat** (msat, optional): max amount accept in a single payment + - **their_reserve_msat** (msat, optional): minimum we insist they keep in channel + - **our_reserve_msat** (msat, optional): minimum they insist we keep in channel + - **spendable_msat** (msat, optional): total we could send through channel + - **receivable_msat** (msat, optional): total peer could send through channel + - **minimum_htlc_in_msat** (msat, optional): the minimum amount HTLC we accept + - **their_to_self_delay** (u32, optional): the number of blocks before they can take their funds if they unilateral close + - **our_to_self_delay** (u32, optional): the number of blocks before we can take our funds if we unilateral close + - **max_accepted_htlcs** (u32, optional): Maximum number of incoming HTLC we will accept at once + - **state_changes** (array of objects, optional): Prior state changes: + - **timestamp** (string): UTC timestamp of form YYYY-mm-ddTHH:MM:SS.%03dZ + - **old_state** (string): Previous state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **new_state** (string): New state (one of "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN") + - **cause** (string): What caused the change (one of "unknown", "local", "user", "remote", "protocol", "onchain") + - **message** (string): Human-readable explanation + - **status** (array of strings, optional): + - Billboard log of significant changes + - **in_payments_offered** (u64, optional): Number of incoming payment attempts + - **in_offered_msat** (msat, optional): Total amount of incoming payment attempts + - **in_payments_fulfilled** (u64, optional): Number of successful incoming payment attempts + - **in_fulfilled_msat** (msat, optional): Total amount of successful incoming payment attempts + - **out_payments_offered** (u64, optional): Number of outgoing payment attempts + - **out_offered_msat** (msat, optional): Total amount of outgoing payment attempts + - **out_payments_fulfilled** (u64, optional): Number of successful outgoing payment attempts + - **out_fulfilled_msat** (msat, optional): Total amount of successful outgoing payment attempts + - **htlcs** (array of objects, optional): current HTLCs in this channel: + - **direction** (string): Whether it came from peer, or is going to peer (one of "in", "out") + - **id** (u64): Unique ID for this htlc on this channel in this direction + - **amount_msat** (msat): Amount send/received for this HTLC + - **expiry** (u32): Block this HTLC expires at + - **payment_hash** (hex): the hash of the payment_preimage which will prove payment (always 64 characters) + - **local_trimmed** (boolean, optional): if this is too small to enforce onchain (always *true*) + - **status** (string, optional): set if this HTLC is currently waiting on a hook (and shows what plugin) + + If **direction** is "out": + - **state** (string): Status of the HTLC (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") + + If **direction** is "in": + - **state** (string): Status of the HTLC (one of "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") + + If **close_to** is present: + - **close_to_addr** (string, optional): The bitcoin address we will close to + + If **scratch_txid** is present: + - **last_tx_fee_msat** (msat): fee attached to this the current tx + + If **short_channel_id** is present: + - **direction** (u32): 0 if we're the lesser node_id, 1 if we're the greater + + If **inflight** is present: + - **initial_feerate** (string): The feerate for the initial funding transaction in per-1000-weight, with "kpw" appended + - **last_feerate** (string): The feerate for the latest funding transaction in per-1000-weight, with "kpw" appended + - **next_feerate** (string): The minimum feerate for the next funding transaction in per-1000-weight, with "kpw" appended + - **next_feestep** (u32, optional): The number of fee steps so far, plus one +- **log** (array of objects, optional): if *level* is specified, logs for this peer: + - **type** (string) (one of "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT") + + If **type** is "SKIPPED": + - **num_skipped** (u32): number of deleted/omitted entries + + If **type** is "BROKEN", "UNUSUAL", "INFO" or "DEBUG": + - **time** (string): UNIX timestamp with 9 decimal places + - **source** (string): The particular logbook this was found in + - **log** (string): The actual log message + - **node_id** (pubkey): The peer this is associated with + + If **type** is "IO_IN" or "IO_OUT": + - **time** (string): UNIX timestamp with 9 decimal places + - **source** (string): The particular logbook this was found in + - **log** (string): The actual log message + - **node_id** (pubkey): The peer this is associated with + - **data** (hex): The IO which occurred + +If **connected** is *true*: + - **netaddr** (array of strings): A single entry array: + - address, e.g. 1.2.3.4:1234 + - **features** (hex): bitmap of BOLT #9 features from peer's INIT message +[comment]: # (GENERATE-FROM-SCHEMA-END) + On success, an object with a "peers" key is returned containing a list of 0 or more objects. @@ -256,3 +372,4 @@ Main web site: Lightning RFC site (BOLT \#9): +[comment]: # ( SHA256STAMP:61071f726dbf0ac566607035239841ec19695688d4a1fd9f94f3c22ade6548d0) diff --git a/doc/schemas/listpeers.schema.json b/doc/schemas/listpeers.schema.json new file mode 100644 index 000000000..e992bf98d --- /dev/null +++ b/doc/schemas/listpeers.schema.json @@ -0,0 +1,936 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": [ "peers" ], + "properties": { + "peers": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "id", "connected", "channels" ], + "properties": { + "id": { + "type": "pubkey", + "description": "the public key of the peer" + }, + "connected": { + "type": "boolean", + "description": "True if the peer is currently connected" + }, + "log": { + "type": "array", + "description": "if *level* is specified, logs for this peer", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "type" ], + "properties": { + "type": { + "type": "string", + "enum": [ "SKIPPED", "BROKEN", "UNUSUAL", "INFO", "DEBUG", "IO_IN", "IO_OUT" ] + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "enum": [ "SKIPPED" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "num_skipped" ], + "properties": { + "type": { }, + "num_skipped": { + "type": "u32", + "description": "number of deleted/omitted entries" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "enum": [ "BROKEN", "UNUSUAL", "INFO", "DEBUG" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "time", "source", "log", "node_id" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The actual log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + } + } + } + }, + { + "if": { + "properties": { + "type": { + "enum": [ "IO_IN", "IO_OUT" ] + } + } + }, + "then": { + "type": "object", + "additionalProperties": false, + "required": [ "time", "source", "log", "node_id", "data" ], + "properties": { + "type": { }, + "time": { + "type": "string", + "description": "UNIX timestamp with 9 decimal places" + }, + "source": { + "type": "string", + "description": "The particular logbook this was found in" + }, + "log": { + "type": "string", + "description": "The actual log message" + }, + "node_id": { + "type": "pubkey", + "description": "The peer this is associated with" + }, + "data": { + "type": "hex", + "description": "The IO which occurred" + } + } + } + } + ] + } + }, + "channels": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "state", "opener", "features" ], + "properties": { + "state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "the channel state, in particular \"CHANNELD_NORMAL\" means the channel can be used normally" + }, + "scratch_txid": { + "type": "txid", + "description": "The txid we would use if we went onchain now" + }, + "feerate": { + "type": "object", + "description": "Feerates for the current tx", + "additionalProperties": false, + "required": [ "perkw", "perkb" ], + "properties": { + "perkw": { + "type": "u32", + "description": "Feerate per 1000 weight (i.e kSipa)" + }, + "perkb": { + "type": "u32", + "description": "Feerate per 1000 virtual bytes" + } + } + }, + "owner": { + "type": "string", + "description": "The current subdaemon controlling this connection" + }, + "short_channel_id": { + "type": "short_channel_id", + "description": "The short_channel_id (once locked in)" + }, + "channel_id": { + "type": "hex", + "description": "The full channel_id", + "minLength": 64, + "maxLength": 64 + }, + "funding_txid": { + "type": "txid", + "description": "ID of the funding transaction" + }, + "inflight": { + "type": "array", + "description": "Current candidate funding transactions (only for dual-funding)", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "funding_txid", "funding_outnum", "feerate", "total_funding_msat", "our_funding_msat", "scratch_txid" ], + "properties": { + "funding_txid": { + "type": "txid", + "description": "ID of the funding transaction" + }, + "funding_outnum": { + "type": "u32", + "description": "The 0-based output number of the funding transaction which opens the channel" + }, + "feerate": { + "type": "string", + "description": "The feerate for this funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "total_funding_msat": { + "type": "msat", + "description": "total amount in the channel" + }, + "our_funding_msat": { + "type": "msat", + "description": "amount we have in the channel" + }, + "scratch_txid": { + "type": "txid", + "description": "The commitment transaction txid we would use if we went onchain now" + } + } + } + }, + "close_to": { + "type": "hex", + "description": "scriptPubkey which we have to close to if we mutual close" + }, + "private": { + "type": "boolean", + "description": "if False, we will not announce this channel" + }, + "opener": { + "type": "string", + "enum": [ "local", "remote" ], + "description": "Who initiated the channel" + }, + "closer": { + "FIXME": "deprecated_apis turns off null!", + "type": [ "string", "null" ], + "enum": [ "local", "remote", null ], + "description": "Who initiated the channel close (`null` is deprecated!)" + }, + "features": { + "type": "array", + "items": { + "type": "string", + "enum": [ "option_static_remotekey", "option_anchor_outputs" ], + "description": "BOLT #9 features which apply to this channel" + } + }, + "funding": { + "type": "object", + "additionalProperties": false, + "required": [ "local_msat", "remote_msat" ], + "properties": { + "local_msat": { + "type": "msat", + "description": "Amount of channel we funded" + }, + "remote_msat": { + "type": "msat", + "description": "Amount of channel they funded" + } + } + }, + "funding_allocation_msat": { + "deprecated": true + }, + "funding_msat": { + "deprecated": true + }, + "to_us_msat": { + "type": "msat", + "description": "how much of channel is owed to us" + }, + "min_to_us_msat": { + "type": "msat", + "description": "least amount owed to us ever" + }, + "max_to_us_msat": { + "type": "msat", + "description": "most amount owed to us ever" + }, + "total_msat": { + "type": "msat", + "description": "total amount in the channel" + }, + "fee_base_msat": { + "type": "msat", + "description": "amount we charge to use the channel" + }, + "fee_proportional_millionths": { + "type": "u32", + "description": "amount we charge to use the channel in parts-per-million" + }, + "dust_limit_msat": { + "type": "msat", + "description": "minimum amount for an output on the channel transactions" + }, + "max_total_htlc_in_msat": { + "type": "msat", + "description": "max amount accept in a single payment" + }, + "their_reserve_msat": { + "type": "msat", + "description": "minimum we insist they keep in channel" + }, + "our_reserve_msat": { + "type": "msat", + "description": "minimum they insist we keep in channel" + }, + "spendable_msat": { + "type": "msat", + "description": "total we could send through channel" + }, + "receivable_msat": { + "type": "msat", + "description": "total peer could send through channel" + }, + "minimum_htlc_in_msat": { + "type": "msat", + "description": "the minimum amount HTLC we accept" + }, + "their_to_self_delay": { + "type": "u32", + "description": "the number of blocks before they can take their funds if they unilateral close" + }, + "our_to_self_delay": { + "type": "u32", + "description": "the number of blocks before we can take our funds if we unilateral close" + }, + "max_accepted_htlcs": { + "type": "u32", + "description": "Maximum number of incoming HTLC we will accept at once" + }, + "msatoshi_to_us": { + "deprecated": true + }, + "msatoshi_to_us_min": { + "deprecated": true + }, + "msatoshi_to_us_max": { + "deprecated": true + }, + "msatoshi_total": { + "deprecated": true + }, + "dust_limit_satoshis": { + "deprecated": true + }, + "max_htlc_value_in_flight_msat": { + "deprecated": true + }, + "our_channel_reserve_satoshis": { + "deprecated": true + }, + "their_channel_reserve_satoshis": { + "deprecated": true + }, + "spendable_msatoshi": { + "deprecated": true + }, + "receivable_msatoshi": { + "deprecated": true + }, + "htlc_minimum_msat": { + "deprecated": true + }, + "state_changes": { + "type": "array", + "description": "Prior state changes", + "items": { + "type": "object", + "additionalProperties": false, + "required": [ "timestamp", "old_state", "new_state", "cause", "message" ], + "properties": { + "timestamp": { + "type": "string", + "description": "UTC timestamp of form YYYY-mm-ddTHH:MM:SS.%03dZ" + }, + "old_state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "Previous state" + }, + "new_state": { + "type": "string", + "enum": [ "OPENINGD", "CHANNELD_AWAITING_LOCKIN", "CHANNELD_NORMAL", "CHANNELD_SHUTTING_DOWN", "CLOSINGD_SIGEXCHANGE", "CLOSINGD_COMPLETE", "AWAITING_UNILATERAL", "FUNDING_SPEND_SEEN", "ONCHAIN", "DUALOPEND_OPEN_INIT", "DUALOPEND_AWAITING_LOCKIN" ], + "description": "New state" + }, + "cause": { + "type": "string", + "enum": [ "unknown", "local", "user", "remote", "protocol", "onchain" ], + "description": "What caused the change" + }, + "message": { + "type": "string", + "description": "Human-readable explanation" + } + } + } + }, + "status": { + "type": "array", + "items": { + "type": "string", + "description": "Billboard log of significant changes" + } + }, + "in_payments_offered": { + "type": "u64", + "description": "Number of incoming payment attempts" + }, + "in_offered_msat": { + "type": "msat", + "description": "Total amount of incoming payment attempts" + }, + "in_msatoshi_offered": { + "deprecated": true + }, + "in_payments_fulfilled": { + "type": "u64", + "description": "Number of successful incoming payment attempts" + }, + "in_fulfilled_msat": { + "type": "msat", + "description": "Total amount of successful incoming payment attempts" + }, + "in_msatoshi_fulfilled": { + "deprecated": true + }, + "out_payments_offered": { + "type": "u64", + "description": "Number of outgoing payment attempts" + }, + "out_offered_msat": { + "type": "msat", + "description": "Total amount of outgoing payment attempts" + }, + "out_msatoshi_offered": { + "deprecated": true + }, + "out_payments_fulfilled": { + "type": "u64", + "description": "Number of successful outgoing payment attempts" + }, + "out_fulfilled_msat": { + "type": "msat", + "description": "Total amount of successful outgoing payment attempts" + }, + "out_msatoshi_fulfilled": { + "deprecated": true + }, + "htlcs": { + "type": "array", + "description": "current HTLCs in this channel", + "items": { + "type": "object", + "additionalProperties": true, + "required": [ "direction", "id", "amount_msat", "expiry", "payment_hash", "state" ], + "properties": { + "direction": { + "type": "string", + "enum": [ "in", "out" ], + "description": "Whether it came from peer, or is going to peer" + }, + "id": { + "type": "u64", + "description": "Unique ID for this htlc on this channel in this direction" + }, + "amount_msat": { + "type": "msat", + "description": "Amount send/received for this HTLC" + }, + "msatoshi": { + "deprecated": true + }, + "expiry": { + "type": "u32", + "description": "Block this HTLC expires at" + }, + "payment_hash": { + "type": "hex", + "description": "the hash of the payment_preimage which will prove payment", + "maxLength": 64, + "minLength": 64 + }, + "local_trimmed": { + "type": "boolean", + "enum": [ true ], + "description": "if this is too small to enforce onchain" + }, + "status": { + "type": "string", + "description": "set if this HTLC is currently waiting on a hook (and shows what plugin)" + } + }, + "allOf": [ + { + "if": { + "properties": { + "direction": { + "enum": [ "out" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "state" ], + "properties": { + "direction": { }, + "id": { }, + "amount_msat": { }, + "msatoshi": { }, + "expiry": { }, + "payment_hash": { }, + "local_trimmed": { }, + "status": { }, + "state": { + "type": "string", + "enum": [ "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" ], + "description": "Status of the HTLC" + } + } + } + }, + { + "if": { + "properties": { + "direction": { + "enum": [ "in" ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "state" ], + "properties": { + "direction": { }, + "id": { }, + "amount_msat": { }, + "msatoshi": { }, + "expiry": { }, + "payment_hash": { }, + "local_trimmed": { }, + "status": { }, + "state": { + "type": "string", + "enum": [ "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" ], + "description": "Status of the HTLC" + } + } + } + } + ] + } + } + }, + "allOf": [ + { + "if": { + "required": [ "close_to" ] + }, + "then": { + "additionalProperties": false, + "required": [ ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "direction": { }, + "close_to_addr": { + "type": "string", + "description": "The bitcoin address we will close to" + } + } + } + }, + { + "if": { + "required": [ "scratch_txid" ] + }, + "then": { + "additionalProperties": false, + "required": [ "last_tx_fee_msat" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "close_to_addr": { }, + "initial_feerate": { }, + "last_feerate": { }, + "next_feerate": { }, + "next_feestep": { }, + "direction": { }, + "last_tx_fee": { + "deprecated": true + }, + "last_tx_fee_msat": { + "type": "msat", + "description": "fee attached to this the current tx" + } + } + } + }, + { + "if": { + "required": [ "short_channel_id" ] + }, + "then": { + "additionalProperties": false, + "required": [ "direction" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "close_to_addr": { }, + "initial_feerate": { }, + "last_feerate": { }, + "next_feerate": { }, + "next_feestep": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "direction": { + "type": "u32", + "description": "0 if we're the lesser node_id, 1 if we're the greater" + } + } + } + }, + { + "if": { + "required": [ "inflight" ] + }, + "then": { + "additionalProperties": false, + "required": [ "initial_feerate", "last_feerate", "next_feerate", "next_fee_step" ], + "properties": { + "state": { }, + "scratch_txid": { }, + "feerate": { }, + "owner": { }, + "short_channel_id": { }, + "channel_id": { }, + "funding_txid": { }, + "inflight": { }, + "close_to": { }, + "private": { }, + "opener": { }, + "closer": { }, + "features": { }, + "funding": { }, + "funding_allocation_msat": { }, + "funding_msat": { }, + "to_us_msat": { }, + "min_to_us_msat": { }, + "max_to_us_msat": { }, + "total_msat": { }, + "fee_base_msat": { }, + "fee_proportional_millionths": { }, + "dust_limit_msat": { }, + "max_total_htlc_in_msat": { }, + "their_reserve_msat": { }, + "our_reserve_msat": { }, + "spendable_msat": { }, + "receivable_msat": { }, + "minimum_htlc_in_msat": { }, + "spendable_msatoshi": { }, + "receivable_msatoshi": { }, + "their_to_self_delay": { }, + "our_to_self_delay": { }, + "max_accepted_htlcs": { }, + "msatoshi_to_us": { }, + "msatoshi_to_us_min": { }, + "msatoshi_to_us_max": { }, + "msatoshi_total": { }, + "dust_limit_satoshis": { }, + "max_htlc_value_in_flight_msat": { }, + "our_channel_reserve_satoshis": { }, + "their_channel_reserve_satoshis": { }, + "spendable_satoshis": { }, + "receivable_satoshis": { }, + "htlc_minimum_msat": { }, + "state_changes": { }, + "status": { }, + "in_payments_offered": { }, + "in_offered_msat": { }, + "in_msatoshi_offered": { }, + "in_payments_fulfilled": { }, + "in_fulfilled_msat": { }, + "in_msatoshi_fulfilled": { }, + "out_payments_offered": { }, + "out_offered_msat": { }, + "out_msatoshi_offered": { }, + "out_payments_fulfilled": { }, + "out_fulfilled_msat": { }, + "out_msatoshi_fulfilled": { }, + "htlcs": { }, + "inflight": { }, + "last_tx_fee": { }, + "close_to_addr": { }, + "direction": { }, + "last_tx_fee": { }, + "last_tx_fee_msat": { }, + "initial_feerate": { + "type": "string", + "description": "The feerate for the initial funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "last_feerate": { + "type": "string", + "description": "The feerate for the latest funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "next_feerate": { + "type": "string", + "description": "The minimum feerate for the next funding transaction in per-1000-weight, with \"kpw\" appended" + }, + "next_feestep": { + "type": "u32", + "description": "The number of fee steps so far, plus one" + } + } + } + } + ] + } + } + }, + "allOf": [ + { + "if": { + "additionalProperties": true, + "properties": { + "connected": { + "enum": [ true ] + } + } + }, + "then": { + "additionalProperties": false, + "required": [ "netaddr", "features" ], + "properties": { + "id": { }, + "channels": { }, + "connected": { }, + "htlcs": { }, + "log": { }, + "last_tx_fee": { }, + "netaddr": { + "type": "array", + "minItems": 1, + "maxItems": 1, + "description": "A single entry array", + "items": { + "type": "string", + "description": "address, e.g. 1.2.3.4:1234" + } + }, + "features": { + "type": "hex", + "description": "bitmap of BOLT #9 features from peer's INIT message" } + } + } + } + ] + } + } + } +}