coin moves: update PLUGINS.md with details about coin_movements

Changelog-Added: Plugins: new notification type, `coin_movement`, which tracks all fund movements for a node

doc/PLUGINS.md

@@ -524,6 +524,95 @@ returns the result of sendpay in specified time or timeout, but
 `sendpay_failure` will always return the result anytime when sendpay
 fails if is was subscribed.
 
+
+### `coin_movement`
+
+A notification for topic `coin_movement` is sent to record the
+movement of coins.  It is only triggered by finalized ledger updates,
+i.e. only definitively resolved HTLCs or confirmed bitcoin transactions.
+
+```json
+{
+	"coin_movement": {
+		"version":1,
+		"node_id":"03a7103a2322b811f7369cbb27fb213d30bbc0b012082fed3cad7e4498da2dc56b",
+		"movement_idx":0,
+		"type":"chain_mvt",
+		"account_id":"wallet",
+		"txid":"0159693d8f3876b4def468b208712c630309381e9d106a9836fa0a9571a28722", // (`chain_mvt` type only, mandatory)
+		"utxo_txid":"0159693d8f3876b4def468b208712c630309381e9d106a9836fa0a9571a28722", // (`chain_mvt` type only, optional)
+		"vout":1, // (`chain_mvt` type only, optional)
+		"payment_hash": "xxx", // (either type, optional on `chain_mvt`)
+		"part_id": 0, // (`channel_mvt` type only, mandatory)
+		"credit":"2000000000msat",
+		"debit":"0msat",
+		"tag":"deposit",
+		"blockheight":102, // (`channel_mvt` type only. may be null)
+		"timestamp":1585948198,
+		"unit_of_account":"btc"
+	}
+}
+```
+
+`version` indicates which version of the coin movement data struct this
+notification adheres to.
+
+`node_id` specifies the node issuing the coin movement.
+
+`movement_idx` is an increment-only counter for coin moves emitted by this node.
+
+`type` marks the underlying mechanism which moved these coins. There are two
+'types' of `coin_movements`:
+  - `channel_mvt`s, which occur as a result of htlcs being resolved and,
+  - `chain_mvt`s, which occur as a result of bitcoin txs being mined.
+
+`account_id` is the name of this account. The node's wallet is named 'wallet',
+all channel funds' account are the channel id.
+
+`txid` is the transaction id of the bitcoin transaction that triggered this
+ledger event. `utxo_txid` and `vout` identify the bitcoin output which triggered
+this notification. (`chain_mvt` only) In most cases, the `utxo_txid` will be the
+same as the `txid`, except for `spend_track` notficiations.  Notifications tagged
+`chain_fees` and `journal_entry` do not have a `utxo_txid` as they're not
+represented in the utxo set.
+
+`payment_hash` is the hash of the preimage used to move this payment. Only
+present for HTLC mediated moves (both `chain_mvt` and `channel_mvt`)
+A `chain_mvt` will have a `payment_hash` iff it's recording an htlc that was
+fulfilled onchain.
+
+`part_id` is an identifier for parts of a multi-part payment. useful for
+aggregating payments for an invoice or to indicate why a payment hash appears
+multiple times. `channel_mvt` only
+
+`credit` and `debit` are millisatoshi denominated amounts of the fund movement. A
+'credit' is funds deposited into an account; a `debit` is funds withdrawn.
+
+
+`tag` is a movement descriptor. Current tags are as follows:
+ - `deposit`: funds deposited
+ - `withdrawal`: funds withdrawn
+ - `chain_fees`: funds paid for onchain fees. `chain_mvt` only
+ - `penalty`: funds paid or gained from a penalty tx. `chain_mvt` only
+ - `invoice`: funds paid to or recieved from an invoice. `channel_mvt` only
+ - `routed`: funds routed through this node. `channel_mvt` only
+ - `journal_entry`: a balance reconciliation event, typically triggered
+                    by a penalty tx onchain. `chain_mvt` only
+ - `onchain_htlc`: funds moved via an htlc onchain. `chain_mvt` only
+ - `pushed`: funds pushed to peer. `channel_mvt` only.
+ - `spend_track`:  informational notification about a wallet utxo spend. `chain_mvt` only.
+
+`blockheight` is the block the txid is included in. `chain_mvt` only. In the
+case that an output is considered dust, c-lightning does not track its return to
+our wallet. In those cases, the blockheight will be `null`, as they're recorded
+before confirmation.
+
+The `timestamp` is seconds since Unix epoch of the node's machine time
+at the time lightningd broadcasts the notification.
+
+`unit_of_account` is the 'currency' this coin movememnt is denominated in.
+
+
 ## Hooks
 
 Hooks allow a plugin to define custom behavior for `lightningd`