The BSV design guide

Start here

What BSV is, and how to design for it.

• Getting startedWhy BSV is different, the design principles, the visual language, and the software and hardware you design for.10 pages
• Designing BSV productsThe design process: knowing your users, the usage life cycle, personal finance, accessibility and common flows.8 pages

Patterns

What to design, by task: connecting, paying, charging, delegating, holding.

• Connecting a walletHow an app connects to a person's BSV wallet: what it can ask for, how little to ask for, and how the wallet knows who is asking.
• Permissions and allowancesWhat an app can do after it connects: the permission prompt, spending allowances, the wallet's permissions dashboard, revoking, and the capabilities that stay off by default.
• Signing inSigning somebody in with their wallet when there are no accounts or passwords: the first visit, returning visits, signing out, and asking for one fact from a Pass.
• Paying by handlePaying somebody by a readable name: how a handle becomes a payment, what to show before the confirm button, and the risk a readable name brings.
• Amounts and unitsHow to show BSV amounts: satoshis as the unit, which figure leads, what to do about the missing symbol, and the rules that stop a number being misread.
• Charging per useCharging a few satoshis many times: the patterns that work, the prompt problem, and how to show hundreds of payments without making somebody anxious.
• Wrong-network paymentsWhy a BSV address and a BTC legacy address are indistinguishable, what that costs a user, and the four defences in the order they are worth building.
• Errors and failed paymentsThe model for every failure in a BSV product: plain words first, whether money moved, what to do next, and the code underneath for support.
• Letting an agent spendSoftware spending on somebody's behalf: what to grant it, how to bound it, and the review screen a person needs when they were not the one who decided.
• Holding tokensWhat a token is on BSV, how one reaches a wallet, and the four things a product has to show before somebody can trust what they are holding.
• Spending conditionsRules written into money about when and how it can be spent: what BSV supports, how to explain a lock nobody can undo, and why the setup is part of the backup.
• Storing data on chainPutting data on the chain: what it is good for, what permanence means for a consent screen, and the four things to settle before you write anything.
• Web apps and native appsHow a website, a phone app and a desktop app each reach a person's BSV wallet, and what changes for the connect prompt, the no-wallet case and who the wallet can say is asking.

Reference designs

Worked examples you can take apart and borrow from.

• Daily spending walletA mobile wallet for everyday use: first use, connecting to apps, paying, receiving, contacts, activity, backup, security and settings.14 pages
• Savings walletA wallet for larger amounts that never connects to apps, with multi-key protection and deliberate top-ups.1 page
• Inheritance walletLong-term savings with a plan for passing funds on.6 pages
• Wallet patternsSeveral wallets at once, one shared between people, and one that grows.3 pages
• Pay-per-use readerA reading app that charges by the article: first visit, connecting, an allowance, the meter, receipts and refunds.3 pages
• Connected web appA ticketing site with no accounts: signing in with a wallet, proving an age with a Pass, buying, coming back and leaving.4 pages
• Agent with a budgetAn AI assistant that buys data for somebody: setting it up, its limits, approvals, the activity trail and stopping it.4 pages

Research

Running studies on BSV products: methods, personas and what has been published.

• Conducting researchWhere to start a study of a BSV product: the three constraints money adds, the questions worth asking, what to test, and how to keep participants' finances private.
• Recruiting participantsWho to recruit for a study of a BSV product, how to screen for them, how to pay them, and how to keep their financial details out of your notes.
• Interview guidesTwo discussion guides you can copy, one about a first wallet and one about paying inside an app, plus what not to ask and how to talk about money without asking for amounts.
• Usability test plansThree test plans you can run: connecting a wallet and granting a permission, paying per use inside an allowance, and recovering a wallet from its backup.
• What people call thingsFour methods for testing a product's words with the people who will read them, and a template for testing the guide's own vocabulary: handle, Pass, allowance, recovery words, connect and sats.
• User personasFive people to design against, what each needs from a BSV product, and where each one is lost.
• Writing up findingsA template for writing up a study so others can judge it, how to anonymise it, and how to contribute a finding to this guide by citing the rule it tests.
• Published researchPublished research on how people use wallets, with a note on which findings transfer to BSV and which do not.

Product and business

The decisions founders make: business models, pricing, measuring, growth and custody.

• Business modelsThe ways a BSV product can earn when a payment costs less than a penny: pay per use, metering, allowances, tipping, credit to try, unbundled subscriptions and models without advertising, with what each asks of the user.
• PricingSetting prices for a BSV product: price in local currency and settle in satoshis, show the price before the action, round honestly, change prices without surprises, and refund with a new payment.
• Measuring a productThe metrics that mean something for a BSV product, from a first payment as activation to recovery readiness and agent budgets, the vanity numbers to ignore, and how to measure without linking people's payments to who they are.
• Growth that paysGrowing a BSV product by paying people directly: referral payouts that arrive instantly, paying for contributions, credit to try, shareable handles and payment links, and the fraud every reward attracts.
• Custody as a product decisionWho holds the keys in your product: the user's own wallet, the product holding funds, or an arrangement in between, compared as onboarding, support, recovery and responsibility trade-offs.
• Talking about BSVHow much of the network a product should show, when to name it as Bitcoin SV or BSV, how to write a store listing and a landing page, and the copy that loses people.

How it works

The technical concepts behind BSV products, explained for designers.

Reference

Terms, sources and how to add to the guide.

• GlossaryBSV terms, from Action to UTXO.2 pages
• ResourcesBSV Academy, developer documentation, the BRC standards and design files.4 pages
• Case studiesWrite-ups of BSV products by the teams that built them: the five we most want, and how to contribute one.
• ContributeThe guide is open. How to suggest a change and add to it.7 pages