diff --git a/contrib/plugins/funds/LICENSE b/contrib/plugins/funds/LICENSE new file mode 100644 index 000000000000..4734a6c8a40c --- /dev/null +++ b/contrib/plugins/funds/LICENSE @@ -0,0 +1,21 @@ +Note: The code of this plugin is covered by the following (BSD-MIT) license: + + Copyright Rene Pickhardt 2018-2019. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/contrib/plugins/funds/README.md b/contrib/plugins/funds/README.md new file mode 100644 index 000000000000..8565caf4f182 --- /dev/null +++ b/contrib/plugins/funds/README.md @@ -0,0 +1,33 @@ +# Funds overview plugin + +This plugin extends the c-lightning command line API with the `funds` command. +Users can get a quick overview of their total funds, the offchain funds in +channels and the onchain funds in unspent transaction outputs. + +run the plugin with: + +``` +lightningd --plugin=/path/to/lightning/contrib/plugins/funds/funds.py +``` + +Once the plugin is active you can run `lightning-cli help funds` +to learn about the command line API. + +The easiest call will be `lightning-cli funds` without any additional arguments. + +## About the plugin +This plugin was created and is maintained by Rene Pickhardt. It shall serve as +an educational resource on his Youtube channel at: + +https://www.youtube.com/user/RenePickhardt + +The plugin is licensed like the rest of c-lightning with BSD-MIT license +and comes without any warrenty (see LICENSE file) + +If you like my work feel free to support me on patreon: +https://www.patreon.com/renepickhardt + +or leave me a tip on my donation page (comming from the donation plugin): +https://ln.rene-pickhardt.de/ + +The work was partially sponsored by http://fulmo.org/ \ No newline at end of file diff --git a/contrib/plugins/funds/funds.py b/contrib/plugins/funds/funds.py new file mode 100755 index 000000000000..502a1e536c78 --- /dev/null +++ b/contrib/plugins/funds/funds.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python3 +""" This plugin gives you a nicer overview of the funds that you own. + +Instead of calling listfunds and adding all outputs and channels +this plugin does that for you. + +Activate the plugin with: +`lightningd --plugin=PATH/TO/LIGHTNING/contrib/plugins/funds/funds.py` + +Call the plugin with: +`lightning-cli funds` + +The standard unit to depict the funds is set to satoshis. +The unit can be changed by and arguments after `lightning-cli funds` +for each call. It is also possible to change the standard unit when +starting lightningd just pass `--funds_display_unit={unit}` where +unit can be s for satoshi, b for bits, m for milliBitcoin and B for BTC. + + +Author: Rene Pickhardt (https://ln.rene-pickhardt.de) +Development of the plugin was sponsored by fulmo.org +""" + +import json + +from lightning.lightning import LightningRpc +from lightning.plugin import Plugin +from os.path import join + +rpc_interface = None +plugin = Plugin(autopatch=True) + +unit_aliases = { + "bitcoin": "BTC", + "btc": "BTC", + "satoshi": "sat", + "satoshis": "sat", + "bit": "bit", + "bits": "bit", + "milli": "mBTC", + "mbtc": "mBTC", + "millibtc": "mBTC", + "B": "BTC", + "s": "sat", + "m": "mBTC", + "b": "bit", +} + +unit_divisor = { + "sat": 1, + "bit": 100, + "mBTC": 100*1000, + "BTC": 100*1000*1000, +} + + +@plugin.method("funds") +def funds(unit=None, plugin=None): + """Lists the total funds the lightning node owns off- and onchain in {unit}. + + {unit} can take the following values: + s, satoshi, satoshis to depict satoshis + b, bit, bits to depict bits + m, milli, btc to depict milliBitcoin + B, bitcoin, btc to depict Bitcoins + + When not using Satoshis (default) the comma values are rounded off.""" + + plugin.log("call with unit: {}".format(unit), level="debug") + if unit is None: + unit = plugin.get_option("funds_display_unit") + + if unit != "B": + unit = unit_aliases.get(unit.lower(), "sat") + else: + unit = "BTC" + + div = unit_divisor.get(unit, 1) + + funds = rpc_interface.listfunds() + + onchain_value = sum([int(x["value"]) for x in funds["outputs"]]) + offchain_value = sum([int(x["channel_sat"]) for x in funds["channels"]]) + + total_funds = onchain_value + offchain_value + + return { + 'total_'+unit: total_funds//div, + 'onchain_'+unit: onchain_value//div, + 'offchain_'+unit: offchain_value//div, + } + + +@plugin.method("init") +def init(options, configuration, plugin): + global rpc_interface + plugin.log("start initialization of the funds plugin", level="debug") + basedir = configuration['lightning-dir'] + rpc_filename = configuration['rpc-file'] + path = join(basedir, rpc_filename) + plugin.log("rpc interface located at {}".format(path)) + rpc_interface = LightningRpc(path) + plugin.log("Funds Plugin successfully initialezed") + plugin.log("standard unit is set to {}".format( + plugin.get_option("funds_display_unit")), level="debug") + + +# set the standard display unit to satoshis +plugin.add_option('funds_display_unit', 's', + 'pass the unit which should be used by default for the simple funds overview plugin') +plugin.run()