From 44f747b29a10c573fde3abfab6b52884f0f393bd Mon Sep 17 00:00:00 2001 From: lisa neigut Date: Fri, 3 Apr 2020 17:37:00 -0500 Subject: [PATCH] coin moves: update PLUGINS.md with details about `coin_movement`s Changelog-Added: Plugins: new notification type, `coin_movement`, which tracks all fund movements for a node --- doc/PLUGINS.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/doc/PLUGINS.md b/doc/PLUGINS.md index f3494d96f..0d764814c 100644 --- a/doc/PLUGINS.md +++ b/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`