diff --git a/doc/PLUGINS.md b/doc/PLUGINS.md
index c40e9d6a7bcc..63dd9d1a4661 100644
--- a/doc/PLUGINS.md
+++ b/doc/PLUGINS.md
@@ -325,8 +325,8 @@ into a block.
 ### `channel_state_changed`
 
 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
-as the old and the new channel states.
+changes its state. The notification includes the `peer_id` and `channel_id`, the
+old and new channel states, the type of `cause` and a `message`.
 
 ```json
 {
@@ -335,11 +335,31 @@ as the old and the new channel states.
         "channel_id": "a2d0851832f0e30a0cf778a826d72f077ca86b69f72677e0267f23f63a0599b4",
         "short_channel_id" : "561820x1020x1",
         "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.
+ - "LOCAL"     Known internal reasons, e.g. a failed HTLC.
+ - "USER"      The operator or a plugin opened or closed a channel by 'hand'.
+ - "REMOTE"    The remote bilaterally closed or funded a channel with us.
+ - "ONCHAIN"   Something happened onchain that forces us to change the state.
+
+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.
+
+If the channel is not closed or being closed yet, the `cause` will reflect which
+side "REMOTE" or "LOCAL" opened the channel.
+
 ### `connect`
 
 A notification for topic `connect` is sent every time a new connection
diff --git a/doc/lightning-listpeers.7 b/doc/lightning-listpeers.7
index bf76c354ec86..1d7736c284a3 100644
--- a/doc/lightning-listpeers.7
+++ b/doc/lightning-listpeers.7
@@ -114,6 +114,8 @@ The channel will eventually be removed from this array\.
 
 .RE
 
+.IP \[bu]
+\fIstate_changes\fR: An array of objects describing prior state change events\.
 .IP \[bu]
 \fIstatus\fR: An array of strings containing the most important log messages
 relevant to this channel\.
@@ -285,7 +287,7 @@ channel in order to enforce the timeout onchain\.
 successfully claim this HTLC\.
 .IP \[bu]
 \fIstate\fR: A string describing whether the HTLC has been communicated to
-or from the peer, whether it has been signed in a new commitment, whether 
+or from the peer, whether it has been signed in a new commitment, whether
 the previous commitment (that does not contain it) has been revoked, as
 well as when the HTLC is fulfilled or failed offchain\.
 .IP \[bu]
@@ -319,4 +321,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:c1ed65bd0e15a1056e3785cf8162ae11d4817fef3c1c12a85c46bab82ab32d0e
+\" SHA256STAMP:26c4df63ed0c5ec78db34e0a65023cbb7dfa7089a5134381bd6131f65dc04435
diff --git a/doc/lightning-listpeers.7.md b/doc/lightning-listpeers.7.md
index e25b5e7a4016..6e1119045797 100644
--- a/doc/lightning-listpeers.7.md
+++ b/doc/lightning-listpeers.7.md
@@ -84,6 +84,7 @@ The objects in the *channels* array will have at least these fields:
     peer, or a theft attempt).
   * `"CLOSED"`: The channel closure has been confirmed deeply.
     The channel will eventually be removed from this array.
+* *state_changes*: An array of objects describing prior state change events.
 * *status*: An array of strings containing the most important log messages
   relevant to this channel.
   Also known as the "billboard".
@@ -211,7 +212,7 @@ Objects in the *htlcs* array will contain these fields:
 * *payment\_hash*: The payment hash, whose preimage must be revealed to
   successfully claim this HTLC.
 * *state*: A string describing whether the HTLC has been communicated to
-  or from the peer, whether it has been signed in a new commitment, whether 
+  or from the peer, whether it has been signed in a new commitment, whether
   the previous commitment (that does not contain it) has been revoked, as
   well as when the HTLC is fulfilled or failed offchain.
 * *local\_trimmed*: A boolean, existing and `true` if the HTLC is not