.jpg)
Contents
The problem around wallet standards stems from a relatively simple root: Web3 builders and Bitcoin builders have historically been separate distinct groups. Bitcoin was Bitcoin, the most secure blockchain and notoriously hard to build on. As a result, it was slow to adapt to innovation.
If you wanted to build apps, you’d have had better luck in the past few years going to a different blockchain ecosystem altogether.
Web3 builders and Bitcoin builders have historically been separate distinct groups.
As a result, most Web3 wallet libraries fail to account for the unique traits of Bitcoin (the UTXO model, Bitcoin Script limitations, etc), and tools built specifically for Bitcoin lack the Web3 functionality that developers are looking for. In other words, there are currently two categories of wallet standards: those for Web3 and those for Bitcoin.
In the world of Web3 wallet standards, most are ecosystem-specific. For example, libraries like wagmi/ viem and web3.js are built primarily for the Ethereum ecosystem, and the Solana Wallet Adapter is built for Solana (duh). Most blockchain ecosystems are account-based models, and as a result, they usually lack basic support for UXTO-based systems like Bitcoin.
There are some exceptions of Web3 wallet libraries offering BTC support, like BTC Connect from the Particle Network and AppKit from Reown (formerly WalletConnect). However, they are limited in their support of meta-protocols (like Ordinals and Runes) and Bitcoin layers.
In the world of Bitcoin wallet standards, most wallet specs are narrowly focused on the Bitcoin L1 and Lightning (such as webBTC, webLN, bitcoin-connect) which means they don’t account for Bitcoin meta-protocols or for other Bitcoin layers. After the rise of metaprotocols,new Bitcoin wallet APIs entered the market (each of them slightly different from the next), which further exacerbated the problem of the lack of a flexible and widely-adopted Bitcoin wallet standard.
With so many options, it’s challenging for developers to know which specification to follow. Further, there isn’t a set of wallet standards that puts Bitcoin first, but also gives builders the flexibility and freedom to experiment with other innovations on Bitcoin.
Why not have the best of both worlds? That’s what we set out to achieve with WBIPs.
WBIPs: a New Bitcoin-Centric Wallet Standard
In early 2023, a group of devs and builders, including Hiro, Xverse, Leather, Asigna, and Bifrost Wallet came together to form WBIPs, a working group dedicated to establishing a better and more flexible set of specifications for Bitcoin wallets.
The guiding principle of WBIPs is to create a Bitcoin-centric wallet standard. By “Bitcoin-centric”, we mean a few things, so let’s break down this Bitcoin-centric philosophy. These are the core tenets of a bitcoin-centric wallet standard:
- Bitcoin is a first-class citizen. This standard should focus on the ability to use Bitcoin in the context of web applications and wallets.
- There is an emphasis on flexibility that enables people to use Bitcoin in whatever way they want whether that’s transacting on the BTC L1, interacting with metaprotocols like Ordinals and Runes, using apps and Bitcoin layers, or trying some yet-to-be-created protocol in the future.
- UTXO and account-based models are on equal footing. There will be no compromising the experience of one model for the gain of another.
The Priorities of WBIPs
WBIPs is open-source and maintained by a decentralized group of contributors instead of a single product or organization.
The approach of this decentralized working group is to take the best ideas from existing wallet standards instead of trying to reinvent the wheel. Let’s break down some of these ideas in greater detail.
Equal Footing for UTXO and Account-Based Models
At a high level, blockchains have two forms of record-keeping: UTXO and account-based models.
- UTXO model: This model tracks each individual coin. Each transaction generates a UTXO (an unspent transaction output) that is used in future transactions. In other words, a user’s total “balance” is the sum of the tokens associated with all of the UTXOs sent to a particular address. To send a transaction, a user consumes existing UTXOs and creates new UTXOs that are sent to the recipient.
- Account model: This model is simpler than the UTXO model and has a more traditional concept of “balance”, similar to what you would encounter at a bank. In this model, each address has a single “balance” figure for a given token that increases/decreases as transactions are sent to/from that account. This is what most Web3 ecosystems use.
Fundamentally, these forms of accounting are different, and giving equal prioritization to both in a single wallet standard is challenging.
The solution we arrived at was guided by working together with Bifrost Wallet. Given that account models offer a simpler and more familiar UX to users, we needed a concept of accounts for the UTXO model. To do so, we defined the term “account” in the UTXO model as the first address.
This address is used as the account identifier. Wallets know about which other “addresses” follow the same derivation path. They can group all of the addresses together in an “account” to achieve the easy UX of account-based models.
Using a Bitcoin wallet in a web app is tricky. Sometimes, apps should perform actions on behalf of the user, and they may need information on a user’s addresses in order to do so. But in the case of Bitcoin (or a cross-chain wallet), a user may have many addresses to choose from.
We want users to control what information web apps have access to (instead of default to sharing all of their addresses), but we also want great UX, such as avoiding forcing users to confirm each address in a separate popup.
To solve this issue, we introduced a new <code-rich-text>bip122_addressesChanged<code-rich-text> event, so websites can easily listen for addresses of the user. This new event structure lets the user decide what information and addresses to share, and the wallet can then push that information to an app rather than having the app pull each piece of information it needs in order to function (which then requires user confirmation).
This new event is especially useful cross-chain. For instance, a wallet could let a website know that a particular user has both a Bitcoin address and a Stacks address, unlocking use cases for web apps that bridge two or more chains.
Flexibility Across Bitcoin Layers and Metaprotocols
The next priority that we felt was important for this Bitcoin wallet standard was that the standard itself was flexible enough to both a) work across a variety of Bitcoin layers and metaprotocols and b) handle any future layers/metaprotocols that don’t currently exist today.
To maximize flexibility, we used JSON-RPC, a basic protocol for communicating that is the default in crypto. This protocol provides the rules/structure for requesting data/action from a wallet (or any other “backend”), and any request is just JSON being sent back and forth.
The exact content of a request can be anything and is flexible enough to be used for any future use cases. In our Bitcoin-centric standard, we define common terms and offer some suggestions to make it easier for any future requests/actions to be defined. For example, we offer some guidance on serializing integers that are too large for JavaScript to represent. This makes it easier for new actions to follow a consistent style, allowing for smoother integration by web-apps and wallets alike.
This interface can even be used for wallet-specific actions that will not find greater adoption. For example, a wallet could use a <code-rich-text>beta_x<code-rich-text> action to test a method before it rolls out completely.
Bringing WBIPs to Stacks
We plan to adopt this new Bitcoin-centric standard in the Stacks ecosystem, but we will have to make some big changes in Stacks.js in order to do so.
Today, developers use Stacks Connect (a Stacks.js library) to authenticate users and sign transactions and messages. However, Stacks Connect first launched in 2020 and has accumulated technical debt over time. For example, Stacks Connect was built to be secure for hosted wallets, which have since been phased out. This makes it cumbersome for devs to work with Connect and maintain the unnecessary code.
In order to adopt this standard, we will strip out the obsolete `auth` package and replace it with a simplified module that follows the WBIPs standard. Some wallets in the Stacks ecosystem are already providing some requests/actions in the new format. See an example from Leather and an example from Xverse.
A Better Bitcoin Experience for Devs and Users
Today, WBIPs is the wallet standard adopted by Leather, Xverse, and Asigna, and the standard was recently used for guiding the latest Reown standard (formerly WalletConnect).
Wallets can now implement Bitcoin methods via Reown, bringing Bitcoin to Reown’s wonderful UX experience. Alongside this work, we are also contributing to an updated standard for Stacks wallets, so keep an eye out for a new proposed spec for Stacks too.
Our goal is to unify wallet standards for Bitcoin and Bitcoin layers and make it easier for developers to build apps on Bitcoin and bring Bitcoin to their users via in-app experiences. Learn more about the work on the WBIPs site.
