Design principles
Seven commitments this guide holds BSV products to, what each one costs, and the rules that follow from them.
These are the commitments a BSV product should be able to defend. They come partly from the technology and partly from what the ecosystem has learned by getting it wrong.
Every one of them has a cost. A principle stated without its cost is a slogan, so each section says what following it makes harder. Diverge where you have a reason, and say what the reason is.
Self-custody
This is the point of the whole exercise. Money held in a product that can be switched off is a database row with extra steps.
Do
Let the user hold their own keys, and make the path to doing so the default rather than an advanced option.
Do
Say plainly when something is custodial. A service holding keys on a user's behalf is a legitimate product; describing it as self-custody is not.
Don't
Build a product where the user's funds depend on your company continuing to exist. Every wallet should be recoverable without you. See Backups.
What it costs: there is nobody to call. No password reset, no chargeback, no support ticket that recovers lost money. Design the recovery path as carefully as the spending path, because it is the only one there is.
Security
The threats a product can do most about are ordinary ones: a lost phone with no backup, a convincing fake, a confirmation screen nobody read.
Do
Match the protection to the amount. A wallet holding coffee money and a wallet holding savings are different products, and pretending otherwise produces one that is wrong for both. See Wallet setups.
Do
Make the irreversible step unmistakable. A payment cannot be recalled, so the review screen is the last line of defence.
Do
Ask for as little as the product needs. The independent risk assessment of the wallet interface (BRC-151) warns how much a wallet can be asked for; the answer is to need less of it. See Connecting a wallet.
Don't
Train people to tap approve. A prompt that appears constantly, is pre-ticked, or reappears until accepted teaches exactly the habit that gets someone robbed.
What it costs: friction, in the places that deserve it. The discipline is spending that friction on the few moments that matter rather than sprinkling it everywhere.
Inclusion
The people who most need money that works without an account are rarely the people who enjoy reading about derivation schemes.
Do
Write for someone who has never heard of a UTXO and never needs to. Internal vocabulary belongs in advanced views and documentation.
Do
Meet WCAG 2.2 AA: contrast, touch targets, screen reader labels, and amounts that read aloud sensibly. See Accessibility.
Don't
Require an identity document, an email address or a phone number to hold money. Where a regulation requires it for a particular feature, gate that feature, not the wallet.
What it costs: you cannot explain your way out of a confusing design. Plain language exposes muddled thinking rather than hiding it.
Interoperability
BSV has an unusual advantage here: the Wallet Application Interface means an app built once works with any compatible wallet, and the user picks.
Do
Support the standards rather than a bespoke integration. Design your connect flow around "your wallet", not a brand.
Do
Give every wallet an export the user holds themselves, and a send to a plain address that works without your servers. See Legacy compatibility.
Don't
Invent a proprietary format for something a BRC already covers. A format only your product reads is a lock-in whether or not you meant it as one.
What it costs: you cannot retain users by trapping them, which means retaining them by being good.
Transparency
Tell people what will happen before it happens, including the parts that do not flatter the product.
Do
Show the total a payment takes from the user, who it goes to, and that it cannot be undone, before they commit.
Do
Say what your product can see and what it stores. A wallet that phones a service on every balance check should say which service and what it learns.
Do
Name the limits. "This backup covers your keys but not your payment records" is the sentence that stops somebody losing money later.
Don't
Describe a product as private, anonymous or instant without the qualifier that makes it true.
What it costs: some of your screens will say things you would rather they did not. That is the principle working.
Privacy
The chain is public and permanent. Privacy is decided before a transaction exists.
BSV's derivation gives a fresh key per payment, which removes the address-reuse leak. What is left is in your hands.
Do
Keep outputs from unrelated counterparties apart when selecting what to spend. Spending them together is the main remaining on-chain leak. See Coin selection.
Do
Before revealing key linkage for a counterparty, tell the user it exposes every payment between them and that counterparty, past and future. See Wallet privacy.
Don't
Collect what you do not need, and never attach a user's identity to routine payments for convenience.
Don't
Write personal data on chain in the clear. There is no delete.
What it costs: some features that would be easy with a central database are harder, and some are off the table.
Decentralisation
Users do not run nodes on BSV, so this principle is not about everyone validating everything. It is about your product not being a chokepoint.
Do
Let users choose or self-host the services your wallet depends on, and support more than one. See Nodes and verification.
Don't
Weld a product to one provider's endpoint. That is your product's lifespan as well as theirs.
What it costs: more work than hard-coding one API, and less control over the user's experience of it.
Using these
These are a checklist you can work through. Run it against a flow, not a product: "our wallet is secure" is not a claim anybody can check, while "our backup flow says what it does not cover" is.
Related
Written from: BRC-29, BRC-69, BRC-100, BRC-151.
Checklist
The rules on this page, in a form you can work through.
23 rules