[plugin] Plugin that depicts the off- and onchain funds in a nicer overview

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.

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/

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()