A look back at Unchained’s 2024 open source contributions

Self-sovereignty is a foundational building block to everything we build at Unchained. So, naturally, open source is a key part of our strategy. By providing tools that anyone can verify, build on, and use to interact with their funds, we feel better about the product. And our clients can have peace of mind that their funds remain accessible independent of Unchained. 

2024 has been a big year for Caravan, Unchained’s open source suite of tools. In addition to some nice new features for users, we’ve invested a lot into our DX (developer experience), modernized our codebase, and set the groundwork for more rapid development into the future. 

We’d like to take the opportunity as we round out the year to highlight some of the biggest changes Caravan has seen over the past ~12 months, including many big changes that casual observers might have missed. The updates can be categorized into roughly three buckets:

• Code organization: Monorepo and a rebrand
• Modernized tooling
• User-facing functionality (aka new features)

The common pattern here was a focus on improved DX. While true for any software project, it is especially true in open source that there is a flywheel effect where better DX can encourage more contributions and easier review. The knock on effect is of course more value delivered to users down the line. 

We also participated in the Summer of Bitcoin for the first time this year! This itself resulted in new code delivered that can be leveraged by other developers and will land in user-facing features in the not too distant future. 

Monorepo and a rebrand

One of the low key but most impactful changes for DX was a move to a monorepo, which involved moving our caravan coordinator (the UI) and our JS utility libraries, previously known as unchained-wallets and unchained-bitcoin, into a single GitHub repository. 

A monorepo is a single repository containing multiple distinct projects, with well-defined relationships.

monoreopo.tools

Colocating all of the code together meant a much more rapid iteration cycle when making changes to the libraries. Using a monorepo structure meant we could still keep the packages distinct and independently releasable. Make a change to the wallets library, have it automatically built in a local instance of the coordinator UI to test your changes without any npm link shenanigans, and have all changes atomically released and updated together. 

Leaning into the Caravan brand

Caravan has been around for many years now and has developed a reputation of its own, independent of Unchained. We think this is healthy, and having an open source project with a company backing it is familiar territory in the FOSS ecosystem. So, as part of this code migration, we decided to make this relationship official. All of our client-side open source code is hosted under the Caravan umbrella: the multisig wallet UI is now known internally as Caravan Coordinator with our flagship utility libraries now known as Caravan Wallets and Caravan Bitcoin.

Package Scoping

This was also an opportunity to bring in a much needed security improvement to protect users of our libraries from supply chain attacks by acquiring the @caravan scope on npm. Any packages developed and published by us will now be published under this scope helping protect from malicious imposter packages. So now, for example, if you want to use our keystore (aka signing device or “wallet”) utilities in your own project, rather than npm install unchained-wallets you would run npm install @caravan/wallets. 

Increased Modularity

Another DX improvement we were able to leverage with the monorepo pattern is to make our packages more modular, individual packages that solve specific bitcoin development issues. This makes the code easier to navigate, easier to contribute to, and can result in smaller bundle sizes. 

As part of this effort we’ve been focusing on a mix of modularizing existing tools from the legacy library, @caravan/bitcoin, and some new functionality. We plan on continuing to add to this library going forward, and slowly deprecate the legacy packages. 

@caravan/psbt

When we added ledger v2 support both at Unchained and in Caravan, we had to write the first open source implementation of version 2 of the PSBT standard. We pulled all of v2 support and most of the v0 support out of @caravan/bitcoin into its own package, continued to add functionality, and made typescript support more robust. 

@caravan/clients

Caravan coordinator lets you use multiple possible backends to interact with the bitcoin blockchain. @caravan/clients took this code out of the coordinator application into its own library, letting developers have a single interface for interacting with the bitcoind rpc, mempool.space, or blockstream.info backends. 

@caravan/bip32

This is a new package that provides utilities for interacting with bip32 derivation paths. It provides some tooling for analyzing, comparing, and now blinding extended public key paths. 

@caravan/descriptors

This one is a bit unique in that it does not reside in the monorepo because it is built with wasm, built from rust code on top of BDK, which has different build requirements. Rather than build our own miniscript parser and encoder, we thought it would be better to build on top of the standard libraries. This would give us future flexibility for more complex output descriptors and reduce the overall maintenance burden. So we worked with the BDK team to develop wasm bindings that convert a wallet config JSON to a descriptor string and back again. @caravan/descriptors takes these and adds TS wrappers so these tools can be used easily in any modern web or node application. 

Modern tooling

Another big behind the scenes change that you’re unlikely to have noticed if you’re not a developer is a more modern toolkit. The codebase that we have today is over 6 years old and a lot has changed in the JavaScript (and bitcoin) ecosystem. The refactor to a monorepo and the modularization described above gave us an opportunity to modernize major pieces of our tech stack. 

TypeScript and Modern React

All of our packages are now built with TypeScript. In order to allow for gradual migration, @caravan/bitcoin and @caravan/wallets have looser rules (like allowing any) with all new code expected to be written with more strict standards. Caravan coordinator still has a lot of old jsx and redux code, but we are continuing to migrate components to TypeScript and more modern React patterns such as hooks and functional components. 

Build System

Caravan no longer uses webpack to build production code bundles. Caravan coordinator is built with Vite, we are migrating our testing away from jest and to vitest, and the libraries are bundled with tsup, a lightweight, no-config necessary bundler powered by esbuild. Under the hood, the monorepo is powered by Turborepo, a build system optimized for scaling monorepos, particularly nice for quickly propagating changes during development and running tests across dependent projects. 

CI and Deployments

For automated versioning and releases, we moved away from semantic-release and commit-lint and towards changesets. The old way, while very nice in terms of consistency, had a relatively high learning curve for new developers with hard to parse error messages. Changesets is the system recommended by turborepo and so integrates well with the monorepo pattern, Additionally, by opting in to version bumps, it can easily walk a developer through which packages to bump and by how much and supports convenient GitHub automations to indicate to developers and reviewers if a changeset is needed. 

We also moved away from GitHub Pages for the hosted version of Caravan and to Vercel. As the maintainer of turborepo, it provides build speed and caching optimizations. It also requires much less configuration than GitHub Pages, is more reliable, and most importantly for OSS development, provides staging and development deployments for PRs which allows for easy testing of proposed changes. 

New features

With an improved DX and better, more modern tooling, we’ve been able to iterate with much higher velocity and with more internal and external contributors as well. Whether we are developing tools internally at Unchained or playing around with new ideas in Caravan, we can move quickly and bring the new features to users faster. Here are some of the highlights from our busiest year of new features since we released the wallet in 2020.

Descriptor Wallets

Functionally, while no different from the wallet types Caravan already supported, descriptors offer greater flexibility between different coordinators like Electrum, Sparrow, and even Bitcoin core’s own wallet without having to convert to and from our own json configuration. 

With the introduction of the @caravan/descriptors library built on top of BDK and native Wallet Policy in @caravan/wallets it was much easier to support wallet imports from descriptors and exporting an existing wallet as descriptors. 

Blinded Xpubs

Blinded Xpubs is a simple but powerful protocol that was first proposed by Michael Flaxman back in 2021. It allows you to engage in a collaborative custody arrangement with a third party without exposing your wallet history to that partner (until you need them to sign). Unfortunately, there hasn’t been much market adoption, with Sigbash being one of the only known production deployments. 

That is until we published @caravan/bip32 which includes utilities for creating blinded bip32 derivation paths from a source xpub. From there it was relatively easy to incorporate an implementation into the wallet generation UX of the Caravan coordinator. 

Spend To Taproot (S2TR)

This was long overdue but due to the age of the codebase and our reliance on an older version of bitcoinjs-lib (v5), upgrading PSBT parsing and serialization was far from trivial. In June of this year, we finally merged the 123 file diff pull request that brought S2TR support to caravan coordinator and any other code that upgrades to the latest versions of @caravan/wallets and @caravan/psbt.

BitBox Support

As previously mentioned, a major goal of improving the developer experience is to make it easier for external contributors to help improve the Caravan ecosystem. One of our biggest external contributions ever came this year with benma from the BitBox team who brought a brand new interaction to the @caravan/wallets library for anyone that wants to build BitBox support into their application, and in the same PR used the upgraded library in the Coordinator for anyone that wants to use BitBox in a segwit multisig wallet. 

Having the work in @caravan/wallets means any other JS project can benefit from this work, having it in a monorepo allowed for rapid development on both the library and the UI implementation, and the Vercel integration and deployments made the testing and review process much faster. 

Summer of Bitcoin

Summer of Bitcoin is a relatively new part of the bitcoin open source ecosystem. Every summer since 2021 they’ve paired high school and college students interested in learning more about bitcoin with open source projects in the space that they can contribute to. (see our posted project ideas here)

We ended up taking on three interns as part of the program, one design focused and two developer projects. 

Sodiq Arilewola worked on a reimagining of the Coordinator UI. While a full code rewrite is still a ways into the future, we are looking to incorporate some of his designs into the existing UI. Check out a full video walkthrough of his project. 

Harshil Jani built a library called @caravan/health. The primary goal of this project was to break down various properties of a bitcoin wallet, as well as on individual transactions, that could be used to analyze their “health”. We broke this down into two primary categories that could contribute to a wallet being healthy or unhealthy: Waste Metrics and Privacy Metrics. By building this as a standalone package in the monorepo, any developer could theoretically leverage these tools to build their own interfaces, dashboards, and other wallet tools. The exported functions take transaction history and individual transactions and return ratings for the range of supported metrics. 

Mrigesh Thakur also built a library, @caravan/fees. This package similarly could be used by any developer as well as within Caravan coordinator itself. @caravan/fees is meant for analyzing and generating fee bumping transactions. The package includes tools for generating CPFP as well as both acceleration and cancellation RBF transactions. All the utilities export base64 PSBTs which make them extremely portable. Simply analyze a pending transaction, decide the most appropriate fee bumping strategy, run it through the processor and use the resulting PSBT however you want.  

Mrigesh wrote about his work with fee management in caravan and built a very indepth Interactive Guide that shows how developers can use the suite of caravan libraries to build their own bitcoin wallet software. 

Caravan in 2025 and beyond

2024 was a big year for Unchained’s FOSS ecosystem. The Caravan coordinator, the world’s most popular stateless multisig bitcoin coordinator, may look largely the same as it did when it got its last major upgrade in 2020, but we were able to make major strides in tooling and developer experience this year while still delivering new features for users. 

With this foundation now in place we hope to continue our momentum. There’s still a lot more modularization we’d like to do continuing to move code out of @caravan/bitcoin in particular, with utilities for extended public keys and transactions being the top priority. We’ll also be continuing development of our PSBTv2 tooling, hoping to push version 2 PSBTs as the default standard. 

The Summer of Bitcoin projects also offer some very exciting areas of user facing features. A reskin of the coordinator application is high on the wishlist. Bringing the feature set introduced by @caravan/fees and @caravan/health directly to users via the UI is also a very high priority. Fee bumping support has been a long requested feature, and @caravan/fees gives us a lot of flexibility in how we can deliver this. With @caravan/health we can give users information about how to reduce fees long term with their wallet, how a transaction impacts the privacy of their wallet’s UTXO set and much more!

Of course, giving more developers the opportunity to contribute to the Caravan ecosystem and grow its capabilities has been a primary goal of our work this year. Whether you’re new to bitcoin development, working for a bitcoin company, or just looking to contribute to the FOSS ecosystem, there’s still lots more work to do! Feel free to reach out to the Unchained team if you have any questions about how to get started.