-
Notifications
You must be signed in to change notification settings - Fork 913
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
bkpr: add two custom notifications that we listen for
It might be nice to let the bookkeeper keep track of external accounts as well as the internal onchain wallet? To this end, we add some new custom notifications, which the bookkeeper will ingest and add to its ledger. Suggested-By: @chrisguida Changelog-Added: PLUGINS: `bookkeeper` now listens for two custom events: `utxo_deposit` and `utxo_spend`. This allows for 3rd party plugins to send onchain coin events to the `bookkeeper`. See the new plugins/bkpr/README.md for details on how these work!
- Loading branch information
1 parent
cd4298d
commit 0e99f2e
Showing
6 changed files
with
375 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| The bookkeeper keeps track of coins moving through your Lightning node. | ||
|
|
||
| See the doc/PLUGINS.md#coin_movement section on the message that CLN emits for us to process. | ||
|
|
||
| // FIXME: add more detailed documenation for how bookkeeper works. | ||
|
|
||
|
|
||
| ## 3rd Party Coin Movements | ||
| Bookeeper ingests 3rd party plugin notifications about on-chain movements that it should watch. | ||
|
|
||
| This allows for us to account for non-internal on-chain wallets in the single place, making `bookkeeper` your single source of truth for bitcoin for an organization or node-operator. | ||
|
|
||
| As a plugin writer, if you want to emit onchain events that the bookkeeper should track, you should emit an event with the following format: | ||
|
|
||
| ``` | ||
| { | ||
| "utxo_deposit": { | ||
| "account": "nifty's secret stash", | ||
| "transfer_from: null, | ||
| "outpoint": xxxx:x, | ||
| "amount_msat": "10000sat", | ||
| "coin_type": "bc", | ||
| "timestamp": xxxx, | ||
| "blockheight": xxx, | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ``` | ||
| { | ||
| "utxo_spend": { | ||
| "account": "nifty's secret stash", | ||
| "outpoint": xxxx:x, | ||
| "spending_txid": xxxx, | ||
| "amount_msat": "10000sat", | ||
| "coin_type": "bc", | ||
| "timestamp": xxxx, | ||
| "blockheight": xxx, | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ## Withdrawing money (sending to a external account) | ||
|
|
||
| Sending money to an external account is a bit unintuitive in in the UTXO model that we're using to track coin moves; technically a send to an external account is a "deposit" to 3rd party's UTXO. | ||
|
|
||
| To account for these, `bookkeeper` expects to receive a `utxo_deposit` event for the creation of an output to a 3rd party. It's assumed that you'll issue these at transaction creation time, and that they won't be final until we receive notice of spend of the inputs in the tx that created them. | ||
|
|
||
| To notify that money is being sent to a 3rd party output, here's the event we'd expect. | ||
|
|
||
| The two keys here are the following: | ||
|
|
||
| - The `account` is `external`. This is a special account in `bookkeeper` and used for tracking external deposits (aka sends) | ||
| - The `transfer_from` field is set to the name of the account that is sending out the money. | ||
|
|
||
|
|
||
| ``` | ||
| { | ||
| "utxo_deposit": { | ||
| "account": "external", | ||
| "transfer_from": "nifty's secret stash", | ||
| "outpoint": xxxx:x, | ||
| "amount_msat": "10000sat", | ||
| "coin_type": "bc", | ||
| "timestamp": xxxx, | ||
| "blockheight": xxx, | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ## List of todos | ||
|
|
||
| List of things to check/work on, as a todo list. | ||
|
|
||
| - Transfers btw a 3rd party wallet and the internal CLN wallet? These should be registered as internal transfers and not show up in `listincome` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,52 @@ | ||
| #!/usr/bin/env python3 | ||
| from pyln.client import Plugin | ||
|
|
||
|
|
||
| plugin = Plugin() | ||
|
|
||
|
|
||
| UTXO_DEPOSIT_TAG = "utxo_deposit" | ||
| UTXO_SPEND_TAG = "utxo_spend" | ||
|
|
||
|
|
||
| @plugin.method("sendspend") | ||
| def emit_spend(plugin, acct, outpoint, txid, amount, **kwargs): | ||
| """Emit a 'utxo_spend' movement | ||
| """ | ||
| utxo_spend = { | ||
| "account": acct, | ||
| "outpoint": outpoint, | ||
| "spending_txid": txid, | ||
| "amount_msat": amount, | ||
| "coin_type": "bcrt", | ||
| "timestamp": 1679955976, | ||
| "blockheight": 111, | ||
| } | ||
| plugin.notify(UTXO_SPEND_TAG, {UTXO_SPEND_TAG: utxo_spend}) | ||
|
|
||
|
|
||
| @plugin.method("senddeposit") | ||
| def emit_deposit(plugin, acct, is_withdraw, outpoint, amount, **kwargs): | ||
| """Emit a 'utxo_deposit' movement | ||
| """ | ||
| transfer_from = None | ||
|
|
||
| if is_withdraw: | ||
| acct = "external" | ||
| transfer_from = acct | ||
|
|
||
| utxo_deposit = { | ||
| "account": acct, | ||
| "transfer_from": transfer_from, | ||
| "outpoint": outpoint, | ||
| "amount_msat": amount, | ||
| "coin_type": "bcrt", | ||
| "timestamp": 1679955976, | ||
| "blockheight": 111, | ||
| } | ||
| plugin.notify(UTXO_DEPOSIT_TAG, {UTXO_DEPOSIT_TAG: utxo_deposit}) | ||
|
|
||
|
|
||
| plugin.add_notification_topic(UTXO_DEPOSIT_TAG) | ||
| plugin.add_notification_topic(UTXO_SPEND_TAG) | ||
| plugin.run() |
Oops, something went wrong.