Smaug

jekyll, github-pages  · 

Introducing Smaug

A CLN plugin to watch your bitcoin treasury with a meticulous eye

Smaug is a new CLN plugin that sends bkpr-compatible events to the bookkeeper(bkpr) plugin for external on-chain wallet movements. This allows bkpr to maintain a full picture of a merchant’s bitcoin inflows and outflows, vastly improving bitcoin accounting and financial analysis.

Background

Magic internet money

Since over a decade ago when I first got into bitcoin, I’ve been thinking about how to get merchants accepting bitcoin, because I think that bitcoin’s value is tied to its ability to be the best medium of exchange ever devised. Before the blocks filled up, and before chain analysis was a thing, the experience of using bitcoin was magical because it felt truly free, like something that no one could stop, or even track - not even governments. It was super easy to set up a node and simply start transacting, with no worries about whether someone might find out about what you were buying and object, or attempt to take a cut.

Bitcoin loses its magic

After the Silk Road got taken down in 2013, bitcoiners realized that bitcoin wasn’t as easy to use privately as they’d thought, and this took away some of the magic.

Then when the blocks filled up in 2015, bitcoiners increasingly realized that on-chain payments would never scale to a large enough userbase to challenge existing payment systems like Visa. As someone who had been trying to onboard in-person merchants like restaurants, I was already aware of the merchant’s painful UX of having to wait for a confirmation to securely settle with customers. Waiting for a confirmation or two was fine for online purchases, but it was absolutely nonviable for in-person contexts. Once the blocks filled up, the problem got even worse, and bitcoin’s magic faded even more.

Restoring the magic

Then, when the Lightning Network was announced around the same time, suddenly the way forward was clear: keep the blocks small to continue allowing anyone to sync a node, and upgrade bitcoin’s consensus rules to support Lightning, first through relative timelocks and then by fixing transaction malleability.

After Segwit activated (and an irritating “big block” minority finally forked off) in 2017, Lightning was ready to rock and roll. Development was slow at first, but bitcoiners knew it would be worth it, since Lightning would make bitcoin more magical than ever.

Fast forward to 2021, and Lightning was production-ready, but sort of a rough user experience. I joined Start9 Labs for a couple of years to try to make the experience better. It turned out that, not only would the Lightning Network need to be built (already a daunting task), but bitcoiners had to be taught to run their own always-on, remotely accessible servers. I took over maintenance of the CLN package for Start9, improving its usability and featureset to bring Lightning to the masses.

Fast forward to today, and Lightning is now smooth and user-friendly, with great full-node offerings (like Start9), but also great self-custodial LSP-assisted solutions like Phoenix and Albyhub. Lightning’s promise of making bitcoin more magical than ever was finally fulfilled!

Low merchant adoption

But merchant adoption is still low. How frustrating! Why would this be?

From discussing and thinking about this problem for years, I think the problem boils down to a few things:

1) Creating local circular economies of merchants and buyers who habitually use bitcoin 2) Making running a node cheaper and easier for merchants 3) Making accepting and holding bitcoin less risky for merchants

These three things can be summarized as follows: the cost/benefit analysis of accepting bitcoin, as a merchant, needs to be more favorable than accepting fiat, and it isn’t quite there yet.

So, even though Lightning works as smooth as butter, our work is still not done!

De-risking bitcoin for merchants

After leaving Start9 in early 2023, I started looking around for other ways to contribute to fixing the above problems. My friend Lisa Neigut (@niftynei), who I’d collaborated with to add dual funding and liquidity ads to the CLN Start9 package, suggested that I could write a plugin that reports on-chain activity for wallets outside of CLN to CLN’s accounting plugin, bookkeeper.

I’d already been looking to contribute to the accounting side of things, as I’d often heard merchants complain that bitcoin accounting is difficult, especially for tax purposes, and I’d noticed that running a Lightning node makes the problem even worse.

In addition to this, I realized that supporting small businesses is most likely bitcoin’s next killer app, given my knowledge of IBM’s and then Microsoft’s successes being almost entirely due to solving pain points for small businesses.

Even more fundamental than this, bitcoin could potentially usher in the next Renaissance, given how the last Renaissance was powered by gold and double-entry bookkeeping.

Bitcoin accounting promises to be orders of magnitude better than fiat accounting, given its open and permissionless nature. Determining your profits and losses, and paying your (minified) taxes, could be a breeze someday with the help of open protocols that collect all of your financial activity into one place, giving you a complete picture of all inflows and outflows. Fiat banks jealously guard your financial data, which makes getting an overview of all your accounts quite challenging.

So I decided to help de-risk bitcoin for merchants (problem number 3 from above), by improving accounting for Lightning merchants.

Smaug

Thus Smaug, an external on-chain wallet tracker for CLN, was born. Bitcoin-accepting businesses usually have a multisig as their treasury, and CLN’s built-in on-chain wallet does not make sense to use for this purpose, so most businesses use an external wallet. Smaug thus allows unifying all inflow and outflow data into one place.

OpenSats

After completing the original design, I applied for a grant from OpenSats to help make Smaug, (formerly watchdescriptor) a reality. Later in 2023 the application was accepted!

Design

Sounds simple, right?

This project turned out to be a lot more work than I expected! The biggest issue was wallet rescans.

Rescans

When I started building Smaug, I originally wanted it to be a pure CLN plugin with no direct dependency on bitcoind. To achieve this, I tried using BDK’s Esplora interface, but this turned out to be too flaky and unreliable to scan entire wallets. Both Blockstream and Mempool.space’s instances would severely rate-limit BDK’s requests, making Smaug unusable. I also realized that the privacy offered by such a solution was probably not sufficient for enterprises’ multisig treasuries (I used Blockstream’s esplora instance by default).

So I tried switching to a direct bitcoind connection, which BDK also had early support for. There was a draft PR demonstrating how to rescan a wallet using this interface. This solution was much better for privacy and reliability, but the rescans were still painfully slow (think: months). Eventually I decided to hack support into BDK (and some upstream Rust dependencies) for using the scanblocks RPC method, whose development I’d tracked since years before and had been released recently in Bitcoin Core v25.

Finally Smaug’s most important function worked!

Upstream changes

There were also a few small changes that needed to be made upstream in CLN for Smaug to do its thing. The first was a PR to add two new event types that the bookkeeper plugin would listen for. The other was support for these custom plugin notifications in the Rust CLN plugin framework.

Plugin-wise Smaug is actually quite simple; there is one RPC method (smaug, which I added a bunch of subcommands to using the excellent clap library), and one event subscription (block_added, so we can scan for txs as new blocks come in). There are also several options, all for connecting Smaug to bitcoind, and two event sender registrations, utxo_deposit and utxo_spend, the two new event types bookkeeper is expecting for on-chain wallet movement notifications.

(If you are wondering why your CLN node says the following when starting up, it’s because bookkeeper is listening for smaug notifications, but smaug is not running:

2025-04-17T02:51:25.414Z UNUSUAL plugin-bookkeeper: topic 'utxo_deposit' is not a known notification topic
2025-04-17T02:51:25.414Z UNUSUAL plugin-bookkeeper: topic 'utxo_spend' is not a known notification topic

)

Please let me know if you get a chance to try Smaug, I’d love to hear your feedback! I can be reached on Twitter or you can open an issue in the Smaug repo.

DevOps

The grant from OpenSats had been rather broad, in that Smaug was the core of my work, but the higher mission encapsulated by the grant was merchant adoption and dev education generally. As the project progressed these higher aspects ended up becoming more important than Smaug itself, as I struggled to find ways for users to run it in production, as well as ways for other devs to easily contribute.

I tried lots of things to help make Smaug more accessible, and I realized along the way that making custom code like this accessible to more users and devs is a problem across the bitcoin and lightning ecosystem, not just for Smaug.

Nix

I had originally intended to install Smaug on the CLN node of the dev education nonprofit Base58, but this turned out to be a lot more complicated than anticipated. I did end up packaging Smaug as a nix package so that users of the wonderful nix-bitcoin modules (like Base58) could easily slide Smaug into their setups.

Learning about Nix turned out to be useful for dev onboarding as well, as I was able to make a cool nix develop devShell that allows anyone to trivially get up and running with a batteries-included dev environment for Smaug.

Continuous integration and testing

My friend @fmhoeger eventually onboarded to the project and helped contribute a complete Python test suite. This suite was adapted in v0.1.1 to be compatible with the CI in the official CLN plugins repo, to which Smaug was eventually added.

Known production instances

Eventually I installed Smaug on a Raspiblitz node owned and operated by my local bitcoin community. Our community is not technically a merchant, but we have a small wallet for donations, and Smaug does a great job tracking this.

Future directions

Smaug has plenty of known (and likely unknown) outstanding issues. In order to iron these out, more people need to install it and use it for real-world operations. Right now the only output from Smaug is the series of bkpr- RPC methods that CLN has to issue accounting reports in JSON format. These can be imported into bitcoin accounting tools like Koinly, but more accounting UIs need to be built for Lightning in order for Smaug to truly reach its potential.

Takeaways

This project was a journey for me! I ended up pivoting a few times (special thanks to OpenSats for being amazing to work with) as I adjusted my approach. Most recently and most importantly, I realized that unified accounting tools like Smaug are probably more useful at a level of abstraction higher than the node itself.

As a CLN plugin, Smaug is accessible only to users running their own CLN nodes, and given plugins’ additional moving parts, the experience of installing and running a CLN plugin is really only ergonomic on raw Debian/Ubuntu or something like Raspiblitz (which is essentially Debian with a lot of utility scripts to make setup and maintenance easier). Specifically, plugins are not easy to use on systems that rely on containers like Start9 and Umbrel.

In addition to this, most Lightning businesses probably have (or want to have) something other than CLN that handles Lightning stuff (like LND, Phoenix/d, Albyhub etc), or even multiple Lightning wallets for different jobs. As a CLN plugin reporting directly to CLN, Smaug assumes that the merchant has only one Lightning node, or that CLN will be able to plug into all of the other pieces of the business that handle Lightning. While this would be possible to build, it’s a rather awkward design without a lot of additional development effort.

Accounting hub

Now that I’ve experimented with software like Albyhub, LNBits, and Phoenixd, which are super easy to set up and use and much easier to sell to merchants, I’ve concluded that accounting is probably best done at the “hub” level rather than the node level. Albyhub and LNBits still have no way of managing multiple connections node backends simultaneously (that I’m aware of), but Zeus and Alby Go do this, and now that NWC is becoming popular, it seems like it shouldn’t be too much of a lift to build something that connects to all a user’s backends using NWC. This includes on-chain wallet-watchers like Smaug, which could be adapted to connect to such a system, by simply rearchitecting it to use NWC and run as a standalone server rather than as a CLN plugin.

Then, once a prototype for such an accounting hub exists, NWC could be augmented to include more granular accounting data, such as that produced by CLN’s bookkeeper. That way we are working towards an open accounting standard that anyone can plug into, rather than just users of a particular Lightning implementation.

So, this is the direction I’m planning to start building in during the coming months.

Acknowledgements

Onward!