Browse Source

doc: update channel_state_changed notification

ppa-prep
Michael Schmoock 4 years ago
committed by neil saitug
parent
commit
86137852d2
  1. 30
      doc/PLUGINS.md
  2. 10
      doc/lightning-listpeers.7
  3. 5
      doc/lightning-listpeers.7.md

30
doc/PLUGINS.md

@ -325,8 +325,8 @@ into a block.
### `channel_state_changed` ### `channel_state_changed`
A notification for topic `channel_state_changed` is sent every time a channel A notification for topic `channel_state_changed` is sent every time a channel
changes its state. The notification includes the peer and channel ids as well changes its state. The notification includes the `peer_id` and `channel_id`, the
as the old and the new channel states. old and new channel states, the type of `cause` and a `message`.
```json ```json
{ {
@ -335,11 +335,35 @@ as the old and the new channel states.
"channel_id": "a2d0851832f0e30a0cf778a826d72f077ca86b69f72677e0267f23f63a0599b4", "channel_id": "a2d0851832f0e30a0cf778a826d72f077ca86b69f72677e0267f23f63a0599b4",
"short_channel_id" : "561820x1020x1", "short_channel_id" : "561820x1020x1",
"old_state": "CHANNELD_NORMAL", "old_state": "CHANNELD_NORMAL",
"new_state": "CHANNELD_SHUTTING_DOWN" "new_state": "CHANNELD_SHUTTING_DOWN",
"cause" : "remote",
"message" : "Peer closes channel"
} }
} }
``` ```
A `cause` can have the following values:
- "unknown" Anything other than the reasons below. Should not happen.
- "local" Unconscious internal reasons, e.g. dev fail of a channel.
- "user" The operator or a plugin opened or closed a channel by intention.
- "remote" The remote closed or funded a channel with us by intention.
- "protocol" We need to close a channel because of bad signatures and such.
- "onchain" A channel was closed onchain, while we were offline.
Most state changes are caused subsequentially for a prior state change, e.g.
"CLOSINGD_COMPLETE" is followed by "FUNDING_SPEND_SEEN". Because of this, the
`cause` reflects the last known reason in terms of local or remote user
interaction, protocol reasons, etc. More specifically, a `new_state`
"FUNDING_SPEND_SEEN" will likely _not_ have "onchain" as a `cause` but some
value such as "REMOTE" or "LOCAL" depending on who initiated the closing of a
channel.
Note: If the channel is not closed or being closed yet, the `cause` will reflect
which side "remote" or "local" opened the channel.
Note: If the cause is "onchain" this was very likely a conscious decision of the
remote peer, but we have been offline.
### `connect` ### `connect`
A notification for topic `connect` is sent every time a new connection A notification for topic `connect` is sent every time a new connection

10
doc/lightning-listpeers.7

@ -114,6 +114,14 @@ The channel will eventually be removed from this array\.
.RE .RE
.IP \[bu]
\fIstate_changes\fR: An array of objects describing prior state change events\.
.IP \[bu]
\fIopener\fR: A string \fB"local"\fR or \fB"remote\fR" describing which side opened this
channel\.
.IP \[bu]
\fIcloser\fR: A string \fB"local"\fR or \fB"remote\fR" describing which side
closed this channel or \fBnull\fR if the channel is not (being) closed yet\.
.IP \[bu] .IP \[bu]
\fIstatus\fR: An array of strings containing the most important log messages \fIstatus\fR: An array of strings containing the most important log messages
relevant to this channel\. relevant to this channel\.
@ -319,4 +327,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Lightning
RFC site (BOLT #9): RFC site (BOLT #9):
\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md\fR \fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md\fR
\" SHA256STAMP:c1ed65bd0e15a1056e3785cf8162ae11d4817fef3c1c12a85c46bab82ab32d0e \" SHA256STAMP:8f6fbdc92e59d5efb2e9e8fa113651badb8aacddaea29d81798ecb598fbaad01

5
doc/lightning-listpeers.7.md

@ -84,6 +84,11 @@ The objects in the *channels* array will have at least these fields:
peer, or a theft attempt). peer, or a theft attempt).
* `"CLOSED"`: The channel closure has been confirmed deeply. * `"CLOSED"`: The channel closure has been confirmed deeply.
The channel will eventually be removed from this array. The channel will eventually be removed from this array.
* *state_changes*: An array of objects describing prior state change events.
* *opener*: A string `"local"` or `"remote`" describing which side opened this
channel.
* *closer*: A string `"local"` or `"remote`" describing which side
closed this channel or `null` if the channel is not (being) closed yet.
* *status*: An array of strings containing the most important log messages * *status*: An array of strings containing the most important log messages
relevant to this channel. relevant to this channel.
Also known as the "billboard". Also known as the "billboard".

Loading…
Cancel
Save