Overview
What a BSV wallet actually holds, why one master key is not one address, and the four ways products control who can sign.
A private key is what makes money move. Whoever holds one can spend what it controls, and nobody can reverse that. Everything on this page follows from those two sentences.
Most of the difficulty in wallet design is not cryptography. It is that losing a key and leaking a key are both catastrophic, and the things that prevent one tend to cause the other. A key written on paper cannot be hacked and can be burned. A key backed up to five places is hard to lose and easy to steal. Every scheme below is a position on that trade-off. Your job is to pick the one that matches what your users will actually do.
What a BSV wallet holds
A modern BSV wallet does not hold a list of keys. It holds one master private key, and derives every other key it needs from that one, on demand.
Derivation uses the key derivation scheme (BRC-42). A child key comes from three things:
- the holder's master key
- the other party's public key
- an invoice number, a short string naming what the key is for.
The two parties reach the same child key from opposite sides, because the shared secret between their master keys is the same in both directions. Nobody else can compute it.
The invoice number has a defined shape (BRC-43): <security level>-<protocol>-<key id>. So a key is always for something, and the wallet can reason about what an app is asking for rather than handing over an opaque key.
Why this matters to a designer
There is no "wallet address" to show the user and no key list to manage. Keys are created as they are needed and most are used once. Any screen that asks a user to pick, name or copy a key is a screen this model does not need, and it can usually be removed.
Three kinds of counterparty
The counterparty in a derivation is one of three things, and the difference is visible in what a key can do:
| Counterparty | Who can derive the public key | Used for |
|---|---|---|
| A specific key | Only the two parties | Payments and messages between two people |
| Self | Only the user | The user's own data, notes, encrypted records |
| Anyone | Anybody who knows the user's identity key | Things meant to be publicly verifiable |
Anyone is the one that needs care. With anyone, the information that turns the master key into a child key is public. So anyone who obtains one such child private key can work back to the master identity key.
Do
Have apps sign through the Wallet Application Interface, which uses a key derived for that purpose and never hands the app a private key.
Don't
Let the master identity key sign payments or messages directly, and never expose a child private key derived against anyone.
The master key comes from entropy
A wallet starts with 32 bytes of randomness. How that becomes something a user can keep is the part they will see.
- Recovery words (BRC-75). Twelve to twenty-four words in the BIP-39 format, hashed into a single master key. The words look like any other recovery phrase and use the same wordlist, but they do not produce the same keys as a BIP-39 and BIP-32 wallet, because the BSV scheme skips BIP-32 and BIP-44 entirely. See Legacy compatibility.
- Backup shares (BRC-140). The secret split into m pieces, any n of which rebuild it: for example five shares, any three of which rebuild it. Fewer than n reveal nothing at all.
- Both at once (BRC-157). The same entropy encoded as words and split into shares, so either route restores the same wallet. Each one grants full control, so each needs the care the recovery words would get on their own.
Words and shares are alternatives
Words and shares are alternatives, not layers. Holding both does not make a wallet safer. It makes two complete copies of the secret, in two places that can each be stolen.
The four schemes
These four are about who can sign. Each still needs a backup, manual or automatic; see Manual backup and Automatic cloud backup. Every product picks one, or offers a path between them.
Single key on one device
One master key, held by the wallet on a phone or computer, protected by the device's secure storage and the user's passcode or biometric.
Fits: everyday spending, first wallets, anything where the balance is small enough to lose. Fails at: a lost device with no backup, and malware with device access.
Multi-key
Several keys, a set number of which must sign. The keys sit on different devices, or with different people.
Fits: savings, shared money, business accounts, inheritance. Fails at: everyday speed. Every payment needs more than one action. See Multi-key.
External signer
The key lives on a device that never goes online. Transactions are carried to it and signatures carried back.
Fits: larger holdings, people who already own a signing device. Fails at: convenience, and anyone who will not keep track of a second object. See External signers.
Shared or delegated keys
A service holds a key alongside the user's, or holds it outright. This includes custodial wallets and co-signing services.
Fits: onboarding, recovery assistance, business controls. Fails at: self-custody, which it is not.
Don't
Describe a shared or custodial key as self-custody.
Choosing one
The right scheme is a function of the amount, the user and the cost of being wrong.
Do
Start people on the simplest scheme that suits the amount they hold, and offer a clear upgrade when the balance grows past it. See Wallet setups.
Do
Name what each scheme protects against, in the user's terms: a lost phone, a stolen phone, a dishonest person, a forgotten password.
Don't
Offer a choice of key scheme during onboarding. A person setting up their first wallet has no basis to answer, and the question is a good way to lose them before they hold anything.
Don't
Describe a scheme as "secure" without saying against what. Every scheme here is secure against something and useless against something else.
Related
- Backups: keys are only half of a complete backup
- Multi-key
- External signers
- Wallet setups: which wallet should hold what
Written from: BRC-42, BRC-43, BRC-75, BRC-100, BRC-140, BRC-157, ts-stack docs.
Checklist
The rules on this page, in a form you can work through.
7 rules