Zap Accounting with CLN and ledger-cli
Double-entry accounting is a tried and true method for tracking the flow of money using a principle from physics: the conservation of energy. If we account for all the inflows and outflows of money, then we know that we can build an accurate picture of all of the money we’ve made and spent.
Bitcoin is particularly good at accounting in this sense, since transaction inflows and outflows are checked by code, with the latest state of the ledger stored in the UTXO set.
What about lightning? Every transaction is not stored on the blockchain, so we need same way to account for all the incoming and outgoing lightning transactions. Luckily for us, core-lightning (CLN) comes with a plugin that describes these transactions in detail!
For every transaction, CLN stores the amount credited and debited from your node: routed payments, invoices, etc. To access this, you just need to run the lightning-cli bkpr-listaccountevents command:
lightning-cli bkpr-listaccountevents | jq -cr '.events[] | [.type,.tag,.credit_msat,.debit_msat,.timestamp,.description] | @tsv' > events.txt
This will save a tab-separated file with some basic information about each credit and debit event on your node.
channel invoice 232000000 0 1662187126 Havana
channel invoice 2050000 0 1662242391 coinos voucher
channel invoice 0 1002203 1662463949 lightningpicturebot
channel invoice 300000 0 1663110636 [["text/plain","jb55's lightning address"],["text/identifier","jb55@sendsats.lol"]]
channel invoice 0 102626 1663483583 Mile high lightning club
Now here’s comes the cool part, we can take this data and build a ledger-cli file. ledger is a very powerful command-line accounting tool built on a plaintext transaction format. Using the tab-separated file we got from CLN, we can build a ledger file with a chart-of-accounts that we can use for detailed reporting. To do this, I wrote a script for converting bkpt reports to ledger:
http://git.jb55.com/cln-ledger
The ledger file looks like so:
2023-05-31 f10074c748917a2ecd8c5ffb5c3067114e2677fa6152d5b5fd89c0aec7fd81c5
expenses:zap:1971 1971000 msat
assets:cln -1971000 msat
2023-05-31 damus donations
income:lnurl:damus@sendsats.lol -111000 msat
assets:cln 111000 msat
2023-05-31 Zap
income:zap:event:f8dd1e7eafa18add4aa8ff78c63f17bdb2fab3ade44f8980f094bdf3fb72d512 -10000000 msat
assets:cln 10000000 msat
Each transaction has multiple postings which track the flow of money from one account to another. Once we have this file we can quickly build reports:
Balance report
Here’s the command for “account balance report since 2023-05 in CAD”
$ ledger -b 2023-05-01 -S amount -X CAD -f cln.ledger bal
CAD5290 assets:cln
CAD2202 expenses
CAD525 routed
CAD1677 unknown
CAD-7492 income
CAD-587 unknown
CAD-526 routed
CAD-1515 lnurl
CAD-614 jb55@sendsats.lol
CAD-1 tipjar
CAD-537 damus@sendsats.lol
CAD-364 gpt3@sendsats.lol
CAD-4012 merch
CAD-2571 tshirt
CAD-1441 hat
CAD-852 zap
CAD-847 event
CAD-66 30e763a1206774753da01ba4ce95852a37841e1a1777076ba82e068f6730b75d
CAD-60 f9cda1d7b6792e5320a52909dcd98d20e7f95003de7a813fa18aa8c43ea66710
CAD-49 5ae0087aa6245365a6d357befa9a59b587c01cf30bd8580cd4f79dc67fc30aef
CAD-43 a4d44469dd3db920257e0bca0b6ee063dfbf6622514a55e2d222f321744a2a0e
...
------------
0
As we can see it shows a breakdown of all the sats we’ve earned (in this case converted to fiat). We can have a higher-level summary using the depth argument:
$ ledger -M -S amount -X sat -f cln.ledger bal
sat14694904 assets:cln
sat6116712 expenses
sat1457926 routed
sat4658786 unknown
sat-20811616 income
sat-1630529 unknown
sat-1461610 routed
sat-4207647 lnurl
sat-11144666 merch
sat-2367164 zap
------------
0
As we can see we made 14 million sats this month, not bad! The number at the bottom balances to zero which means we’ve properly accounted for all income and expenses.
Daily Damus Donation Earnings
To support damus, some users have turned on a feature that sends zaps to support damus development. This simply sends a payment to the damus@sendsats.lol lightning address. Since we record these we can build a daily report of damus donations:
$ ledger -D -V -f cln.ledger reg damus
23-May-15 - 23-May-15 ..damus@sendsats.lol CAD-46 CAD-46
23-May-16 - 23-May-16 ..damus@sendsats.lol CAD-73 CAD-120
23-May-17 - 23-May-17 ..damus@sendsats.lol CAD-41 CAD-161
23-May-18 - 23-May-18 ..damus@sendsats.lol CAD-37 CAD-197
23-May-19 - 23-May-19 ..damus@sendsats.lol CAD-35 CAD-233
23-May-20 - 23-May-20 ..damus@sendsats.lol CAD-28 CAD-261
23-May-21 - 23-May-21 ..damus@sendsats.lol CAD-19 CAD-280
23-May-22 - 23-May-22 ..damus@sendsats.lol CAD-29 CAD-309
23-May-23 - 23-May-23 ..damus@sendsats.lol CAD-19 CAD-328
23-May-24 - 23-May-24 ..damus@sendsats.lol CAD-25 CAD-353
23-May-25 - 23-May-25 ..damus@sendsats.lol CAD-36 CAD-390
23-May-26 - 23-May-26 ..damus@sendsats.lol CAD-37 CAD-426
23-May-27 - 23-May-27 ..damus@sendsats.lol CAD-25 CAD-451
23-May-28 - 23-May-28 ..damus@sendsats.lol CAD-25 CAD-476
23-May-29 - 23-May-29 ..damus@sendsats.lol CAD-12 CAD-488
23-May-30 - 23-May-30 ..damus@sendsats.lol CAD-29 CAD-517
23-May-31 - 23-May-31 ..damus@sendsats.lol CAD-21 CAD-537
Not making bank or anything but this covered the relay server costs this month!
Hopefully ya’ll found this useful, feel free to fork the script and try it out!