# An app that connects to a wallet The three app reference designs, plus connecting, permissions, signing in, errors and the three charging patterns: one-off payments, micropayments and agent spending. Also covers what an app owes a user who wants to leave. The costly rules come first; the full list follows, grouped by page. Every line carries the address of the sentence it came from. 349 rules: 39 that can cost money, 86 that can cost trust, 224 standard. ## Start here - **DON'T** _(Costs money)_ Build a product where the user's funds depend on your company continuing to exist. Every wallet should be recoverable without you. See Backups. - **DO** _(Costs money)_ Make the irreversible step unmistakable. A payment cannot be recalled, so the review screen is the last line of defence. - **DO** _(Costs money)_ Show the total a payment takes from the user, who it goes to, and that it cannot be undone, before they commit. - **DO** _(Costs money)_ Name the limits. "This backup covers your keys but not your payment records" is the sentence that stops somebody losing money later. - **DON'T** _(Costs money)_ Let the everyday wallet draw from savings on its own, or let an agent raise its own budget. Both turn a bridge into a leak. - **DON'T** _(Costs money)_ Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree. - **DON'T** _(Costs money)_ Let an AI agent approve key linkage, share a Pass, or widen its own permissions. - **DON'T** _(Costs money)_ Show long decimal BSV amounts in a consumer interface. "0.00012500 BSV" asks the reader to count zeros, and they will get it wrong. - **DO** _(Costs money)_ Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. - **DO** _(Costs money)_ Put the network name next to the address field, always, not only on error. "BSV address" is three words and it is the whole defence. - **DO** _(Costs money)_ Warn on every pasted address rather than trying to detect a bad one. You cannot detect it, and a warning that only fires sometimes teaches people it means something specific. - **DON'T** _(Costs money)_ Use "bitcoin address" as the field label. That is the word that cannot distinguish the networks, on the screen where the distinction is the whole point. - **DO** _(Costs money)_ Put the network on the confirmation, beside the recipient, in the same weight as the amount. - **DO** _(Costs money)_ Say plainly what cannot be undone, before the button: "Sent to the wrong network, this usually cannot be recovered." - **DO** _(Costs money)_ Offer a test payment for a first-time address above a threshold you choose, and ask the user to check with the recipient that it arrived. It costs a fraction of a penny and it is the only defence that proves the address is right. - **DO** _(Costs money)_ Make the network selection impossible to leave at a default, and restate the chosen network on the confirmation. - **DON'T** _(Costs money)_ Offer "Try again" on a payment until you know the first attempt did not go out. - **DO** _(Costs money)_ Tell the user once when their wallet is retrying for them: "Your wallet will keep trying to send this. You don't need to pay again." - **DO** _(Costs money)_ Fund an agent by deliberate top-up, as a human action. A standing instruction to refill is the thing that turns a bounded loss into an unbounded one. - **DON'T** _(Costs money)_ Hand an agent the user's identity key or their Passes. It can have its own identity and act as itself; it should never be able to prove it is the person. - **DO** _(Costs money)_ Enforce limits outside the agent, in the wallet or the service holding its keys. A limit the agent checks itself is a limit an injected instruction can argue with. - **DO** _(Costs money)_ Treat the supply decision as final in the interface, because it is. A field labelled "Supply" with no warning is a trap. - **DON'T** _(Costs money)_ Write anything identifying a person without an explicit, specific consent for that write. "Agreed to the terms" is not consent to publish somebody's name forever. - **DO** _(Costs money)_ Name the article being bought on the wallet's payment sheet, so the reader can see that the thing she tapped is the thing she is paying for. - **DON'T** _(Costs money)_ Charge for an article the reader has already bought, whether she returns to it on the same day or a month later. - **DO** _(Costs money)_ Stop charging the moment the reader taps Stop, before any confirmation or animation, and say how much she spent today. - **DON'T** _(Costs money)_ Show Try again on an article while the wallet reports its payment as still being sent. - **DO** _(Costs money)_ Show on the review screen the same sats amount the wallet's prompt will show, and if the rate moves before Anna presses the button, update the figure on this screen first rather than letting the wallet show a different number. - **DON'T** _(Costs money)_ Add a booking fee or any other charge after the review screen. If the product charges one, it is part of the price shown here. - **DO** _(Costs money)_ Make a ticket valid at the door from the token alone, so it still works after Anna deletes her data or removes the site from her wallet. - **DO** _(Costs money)_ Show the amount and the payee from the payment Scout's wallet refused, and Scout's explanation separately, labelled as Scout's. If the explanation names a different amount, show both and say they disagree. - **DON'T** _(Costs money)_ Put "Always allow" or "Add to Scout's services" on the approval screen. Widening Scout's scope from a notification is how one odd request becomes a standing permission. - **DON'T** _(Costs money)_ Let the assistant approve its own request, or accept an approval from anywhere other than Anna's own device. - **DO** _(Costs money)_ Refuse a payment above the price shown on the limits screen, even when it is inside the per-payment limit, and send it to Anna like any other request outside scope. - **DO** _(Costs money)_ Cap paid retries to one service at a fixed number per task, show that number on the limits screen, and stop using the service when it is reached. Each retry is another payment, and a loop of small failures is how an agent spends its budget on nothing. - **DO** _(Costs money)_ Make pausing take effect in Scout's wallet, not in the assistant. Spending stops even if the assistant is still running or has not noticed. - **DO** _(Costs money)_ Offer only the wallet that funded Scout as the destination for what is left. A payee chosen at the end of a delegation is a payee nobody vetted. - **DO** _(Costs money)_ Show the network on every receive screen that shows a plain address, and warn on send when an address is pasted rather than picked. - **DO** _(Costs money)_ When an import of recovery words finds nothing, check the other derivation path before telling the user the wallet is empty. - **DON'T** _(Costs trust)_ 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. - **DO** _(Costs trust)_ Give every wallet an export the user holds themselves, and a send to a plain address that works without your servers. See Legacy compatibility. - **DO** _(Costs trust)_ 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** _(Costs trust)_ Put a savings total and a quick-pay action on the same screen. The total makes the payment feel smaller than it is. - **DO** _(Costs trust)_ Let the weight of a confirmation follow its consequence: whether it can be undone, how large the amount is against what the wallet holds, whether the recipient is new, and whether it grants something that keeps working after today. - **DON'T** _(Costs trust)_ Use one confirmation style for everything. People learn the shape of "confirm" within a week and stop reading what is inside it. - **DO** _(Costs trust)_ Give every failure on the send and connect flows a message that says whether money moved: "Nothing left your wallet" or "The payment went through". - **DO** _(Costs trust)_ Export the wallet backup in the wallet data format (BRC-38 and BRC-39), to a file the user holds. If your format is your own, say so plainly and publish it. - **DO** _(Costs trust)_ Make a wallet's permission prompt readable in full by a screen reader: who is asking, what for, and for how long. A grant the person could not hear is not consent. - **DO** _(Costs trust)_ Request each permission when the user first uses the feature that needs it. - **DON'T** _(Costs trust)_ Bundle every permission into one approval screen during onboarding. - **DON'T** _(Costs trust)_ Preselect broad permissions, describe a permission as less than it is, or show a refused prompt again until the user gives in. All three teach people to tap Allow without reading. - **DO** _(Costs trust)_ Show the app's name from its manifest beside its verified domain in every prompt, and the domain alone when the app has no manifest. - **DON'T** _(Costs trust)_ Cancel a wallet request because the user has not answered yet. A timeout turns a user who was reading into an error. - **DO** _(Costs trust)_ Cap an allowance per payment, per hour and per day as well as per month, where the wallet supports it, and show every cap in the same prompt. - **DO** _(Costs trust)_ Ask the user again when an amount is unusually high, the recipient is new, the payment pattern changes, an allowance that has ended would start again, or the app asks for a new protocol, basket, Pass field, the identity key or key linkage. - **DO** _(Costs trust)_ Make a revoke take effect at once, and say what stops working: "The Satoshi Vision can no longer charge you. It will ask again when you next open an article." - **DO** _(Costs trust)_ Ask for key linkage fresh each time, name who receives it and what they learn, and keep a local record of what was revealed to whom. - **DON'T** _(Costs trust)_ Ask for an email address or a password as part of signing in. If you need an email for receipts, ask for it afterwards, as its own optional step. - **DO** _(Costs trust)_ Sign users in with a key derived for your app. If your database leaks, the leaked keys can't be matched to the same person's activity elsewhere. - **DON'T** _(Costs trust)_ Use the root identity key as the account ID for a social network, game, shop or payment service. One breach then becomes a cross-app tracking event. - **DON'T** _(Costs trust)_ Request the wallet's root identity key without a reason you can state in the prompt. Approving a sign-in or a payment must never include it. - **DO** _(Costs trust)_ Say on sign-out that the app is still connected in the wallet, and where to disconnect it: "Signed out. Pixel Arcade is still listed in your wallet. Remove it there to stop it asking." - **DON'T** _(Costs trust)_ Call sign-out "Disconnect wallet". It does not touch the wallet's permissions, and the user will think it did. - **DO** _(Costs trust)_ Use Bitcoin SV or BSV on screen: "Send BSV", "Your BSV balance", "Bitcoin SV address". Use one of the two consistently within a screen. - **DON'T** _(Costs trust)_ Write "bitcoin" alone on a screen where somebody is about to move money. Used precisely it is an umbrella covering several chains, so it is the one word that cannot tell a user which network they are on. See Bitcoin. - **DO** _(Costs trust)_ Say when a converted figure is an estimate, and roughly how fresh the rate is. A price that silently drifts is worse than one labelled approximate. - **DO** _(Costs trust)_ Keep one bitcoin unit per screen. Mixing "0.0001 BSV" and "10,000 sats" in one view asks the user to do arithmetic to compare two things you wrote. - **DON'T** _(Costs trust)_ Abbreviate amounts in a financial context. "12.5k sats" saves four characters and introduces a rounding question. - **DON'T** _(Costs trust)_ Shorten a number with an ellipsis, ever. Reformat it or let it wrap. - **DO** _(Costs trust)_ Show the running total against the allowance wherever the spending is happening, not only in a settings screen. - **DO** _(Costs trust)_ Put a stop control next to that total. One action, no confirmation, effective immediately. - **DON'T** _(Costs trust)_ Renew an allowance that has ended without asking the user again. A limit that starts again each month within a live grant is normal, provided the reset date is shown beside what is left. - **DO** _(Costs trust)_ Make stopping obvious and instantaneous, and confirm that it stopped. "Stopped. You spent 340 sats." closes the loop. - **DO** _(Costs trust)_ Offer a ceiling before starting, not only an allowance. "Stop at 5,000 sats" is a different and more reassuring promise. - **DO** _(Costs trust)_ Fail towards not charging. A user who got something free will forgive you; one charged twice will not. - **DO** _(Costs trust)_ Say what happened in plain words: which network it went to, that the money is not lost from the chain but is out of reach from here, and what recovery would require. - **DON'T** _(Costs trust)_ Promise recovery you cannot deliver. If it needs the other party's cooperation, say that is what it needs. - **DO** _(Costs trust)_ Say whether money moved in every message that follows a payment attempt, including when the answer is that nothing left the wallet. - **DO** _(Costs trust)_ Require a human for anything outside the scope: a new payee, a larger amount, a wider permission. Send the person a notification for it, rather than adding it to a list they have to check. - **DO** _(Costs trust)_ Record what each payment was for at the moment it happens. Intent cannot be reconstructed afterwards. - **DO** _(Costs trust)_ Surface the unusual rather than the complete. A payee it has never paid, or a payment larger than its usual, belongs at the top; the routine belongs in a total. - **DON'T** _(Costs trust)_ Report agent spending only in a log. A log is for after somebody already suspects something. - **DO** _(Costs trust)_ Put one control that stops everything, visible wherever the agent is, with no confirmation step. Confirmations are for actions you might regret, and stopping is not one of them. - **DO** _(Costs trust)_ Name the agent and its purpose wherever its spending appears. "Example Assistant, buying search results" is a thing a person can consent to; "automated payments" is not. - **DON'T** _(Costs trust)_ Ask for broad wallet access in order to read a token balance. Ask for the basket. An app that wants everything in order to show one number is the reason permission screens get ignored. - **DO** _(Costs trust)_ Show provenance as a short human sentence before a trade or a transfer: "Issued by Example Studio, 3 owners since, unbroken." The full chain belongs behind that line, not in front of it. - **DO** _(Costs trust)_ Resolve the real-or-fake question for the user rather than printing an ID and hoping. Match against issuers they already trust, and say plainly when you cannot. - **DON'T** _(Costs trust)_ Show a token's picture at the size of a decision without the provenance beside it. The picture is the part that is trivial to fake. - **DO** _(Costs trust)_ Say what is being written on chain, that it cannot be edited later, and what it costs. The cost is a fraction of a penny, which is worth saying out loud because people expect otherwise. - **DO** _(Costs trust)_ Name the issuer wherever the balance appears, not only at acquisition. "120 GBP, issued by Example Trust" is the honest form. - **DON'T** _(Costs trust)_ Draw a stablecoin balance in the same type as a BSV balance with no distinction. One is a bearer asset and the other is a claim on a company. - **DO** _(Costs trust)_ Say "permanent and public" in the consent step, in those words, before anything is written. - **DO** _(Costs trust)_ Show exactly what will be written. If it is a hash, say that the document stays on your server and only a fingerprint goes out. - **DON'T** _(Costs trust)_ Offer a delete button for on-chain data. You can stop displaying it. That is not the same thing and the difference is the whole point. - **DO** _(Costs trust)_ Default to the hash. Publishing is the irreversible option and should be the deliberate one. - **DO** _(Costs trust)_ Make sure the data can still be verified without your overlay. The point of putting it on chain was independence from you. - **DO** _(Costs trust)_ Name the price, in satoshis and local currency, on the same panel as the connect button. The reader should know what the first tap costs before the wallet opens. - **DO** _(Costs trust)_ Ask for a key made for this site only at connection, and nothing else: no identity key, no Pass, no spending grant. - **DO** _(Costs trust)_ Give the allowance an end date in the request itself, and show that date on the wallet's sheet. When it ends, ask again and show what the last one was spent on. - **DO** _(Costs trust)_ Say on the stopped state that the allowance still exists in the wallet, and where to remove it. - **DON'T** _(Costs trust)_ Describe a refund in the app as a payment being reversed or cancelled. Say "We've sent you 20 sats back". - **DO** _(Costs trust)_ After a revocation, keep every article the reader already paid for readable once she connects the same wallet again, with no new payment. - **DO** _(Costs trust)_ Ask only for the sign-in key at this step. Payment, the age check and the ticket basket each wait for the screen where Anna first needs them. - **DON'T** _(Costs trust)_ Ask for a name or email straight after sign-in to make the header friendlier. "Your account" is enough until Anna chooses to add something. - **DON'T** _(Costs trust)_ Offer to "find" Anna's account when a different wallet connects. The site cannot tell it is her, and guessing from anything else would link identities she kept apart. - **DO** _(Costs trust)_ List on the site, before the wallet prompt opens, the one thing the site will receive and the things it will not, in the same words the wallet is about to use. - **DON'T** _(Costs trust)_ Ask for a date of birth and work out the age on the site. The site then holds a fact it never needed, and the wallet's field-level choice is wasted. - **DO** _(Costs trust)_ Ask for the same single field, "over 18", at every age-restricted checkout, and never widen a later request because an earlier one was granted. - **DON'T** _(Costs trust)_ Ask for a spending allowance "to make the next purchase faster". A site people pay a few times a year should ask each time. - **DON'T** _(Costs trust)_ Put a "Disconnect" button on the site that only clears the session. Anna would believe the site lost its access when the wallet still lists it. - **DO** _(Costs trust)_ Store the result of an age check, the gig and the date, and never the Pass or any field beyond the one asked for, and say so on the site's data page. - **DON'T** _(Costs trust)_ Keep anything about Anna that this page does not list. If the site starts storing something new, the page changes the same day. - **DON'T** _(Costs trust)_ Offer to connect Scout to Bitcoin SV Wallet with a spending permission as a quicker alternative. Two routes to the same task make the safer one look like the slow one. - **DON'T** _(Costs trust)_ Ask Anna to switch on a low-balance refill during funding. Topping up is a separate decision each time, made when she can see what the last budget bought. - **DO** _(Costs trust)_ Say plainly when a service kept the money: "Example Data was paid 15 sats and sent nothing back." Whether money moved is the first thing the errors pattern asks every failure to answer. - **DO** _(Costs trust)_ Record Scout's reason with each payment at the moment it is made, and keep it unchangeable. A reason written afterwards is a story, not a record. - **DON'T** _(Costs trust)_ Present Scout's note in the same style as the amount and payee. The amount and payee come from the payment; the note comes from the agent, and the screen should show the difference. - **DON'T** _(Costs trust)_ Offer "Get a refund" or "Dispute" on an agent payment. Scout cannot reverse a payment, and a button that implies it can will be pressed and will fail. - **DO** _(Costs trust)_ Show the exact time spending stopped, and whether a payment was already on its way at that moment: "The last payment, 20 sats to The Satoshi Vision at 14:32, went through before you paused." - **DON'T** _(Costs trust)_ Let Scout's stop message argue for resuming. "I was nearly there" turns a safety control into a negotiation with the thing being stopped. - **DO** _(Costs trust)_ Say on the revoke screen that the money left in Scout's wallet stays there until Anna sends it back, and show the amount. - **DO** _(Costs trust)_ Always show the user what they're paying for, and the running total against their allowance. Small, frequent payments add up, and users should never be surprised by them. - **DON'T** _(Costs trust)_ Trust a single service's word that a payment is confirmed. The merkle proof is the evidence; verify it against headers rather than displaying whatever the API returned. - **DO** _(Costs trust)_ Move funds out of a seed-only wallet by sending them, not by importing its words. - **DO** _(Costs trust)_ Every consumer wallet should still be able to send to a plain address. It's the user's guaranteed exit if anything else in the stack fails. Label it clearly, for example Send to external wallet, and make sure it works without any vendor service. ## Every rule, by page ### Design principles https://www.bitcoinsv.design/guide/getting-started/principles/ - **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** _(Costs money)_ Build a product where the user's funds depend on your company continuing to exist. Every wallet should be recoverable without you. See Backups. - **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** _(Costs money)_ 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. - **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** _(Costs trust)_ 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. - **DO** Support the standards rather than a bespoke integration. Design your connect flow around "your wallet", not a brand. - **DO** _(Costs trust)_ 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. - **DO** _(Costs money)_ 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** _(Costs money)_ 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. - **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** _(Costs trust)_ 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. - **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. ### Visual language https://www.bitcoinsv.design/guide/getting-started/visual-language/ - **DO** Use the BSV mark, the upright B on gold, wherever a BSV product needs the symbol as a mark. - **DON'T** Use the orange disc or a tilted B to stand for BSV. Both say a different network to anyone who knows the difference. - **DO** Use the Unicode character ₿, not the logo, when you need the bitcoin symbol in text. It scales, reflows and can be read by a screen reader. For amounts and labels, use sats and BSV; see Amounts and units. - **DON'T** Use the golden disc logo inside a sentence. It is a mark, not a letterform, and at text size it is a smudge. - **DON'T** Put memes in a product. They read as a private joke to people inside and as unseriousness to people outside, and the second group is who you are trying to reach. - **DO** Draw the thing that is happening. A payment is a person handing something to a person. - **DO** Pick a point on the scale deliberately and hold it across the product. Drifting between the two is what produces an app that is baffling to newcomers and patronising to everyone else. - **DON'T** Use a lightning bolt to mean speed in a BSV product. Show the thing itself: a payment confirmed while the customer is still at the till. - **DON'T** Put advocacy in a product. Say what yours does and let it be judged on that. - **DO** Reach for the gold metaphor on a savings surface and leave it off an everyday one. A payment app that looks like a vault tells people their coffee money is an investment. ### Spending, saving and delegating https://www.bitcoinsv.design/guide/designing-products/spending-saving-delegating/ - **DO** Decide which state of mind each screen is for, and design that screen for it alone. - **DON'T** _(Costs trust)_ Put a savings total and a quick-pay action on the same screen. The total makes the payment feel smaller than it is. - **DO** Build each state of mind on its own wallet, so the separation holds even when the interface does not. A layout can be redesigned; a key the everyday wallet never had cannot leak from it. - **DO** Make every move between states of mind a visible step the person takes, with its own confirmation. - **DON'T** _(Costs money)_ Let the everyday wallet draw from savings on its own, or let an agent raise its own budget. Both turn a bridge into a leak. - **DO** Pick the primary state of mind for the product, and say so. A payments app is for spending, with saving as an optional layer reached by a bridge. A savings product is for saving, with a quick top-up as its one shortcut. A product that will not choose ends up with the savings total next to the pay button. ### Getting to know your users https://www.bitcoinsv.design/guide/designing-products/getting-to-know-your-users/ - **DO** Lead with the concrete benefit for the person in front of you. "Keep the 45p the card company takes on a £5 sale" beats any sentence containing the word sovereignty. - **DO** Count the ideas a person has to hold to finish their first task, not just the steps. Each new idea is a place they can stop. - **DON'T** Treat speed as comprehension. Removing friction removes the reason to stop; it does not answer "what did I just do?" - **DO** _(Costs trust)_ Let the weight of a confirmation follow its consequence: whether it can be undone, how large the amount is against what the wallet holds, whether the recipient is new, and whether it grants something that keeps working after today. - **DON'T** _(Costs trust)_ Use one confirmation style for everything. People learn the shape of "confirm" within a week and stop reading what is inside it. - **DO** Decide which of the three you are for, and say so. A product aimed at all three serves none well. - **DON'T** Assume somebody who has used another chain understands this one. They will look for a fee picker, wait for confirmations, and assume their recovery words work here. See Legacy compatibility. - **DO** Test recovery before you polish onboarding: confirm a new user can restore their wallet on a second device before refining the first-run screens. ### Common user flows https://www.bitcoinsv.design/guide/designing-products/common-user-flows/ - **DON'T** Lead a store listing with self-custody or decentralisation. They are reasons to stay, not reasons to install. - **DO** Use the device's own biometric with a passcode fallback, and require authentication for payments above a threshold the user can see. - **DO** Make the wallet's own activity the place to find out whether something worked. See Activity. - **DO** Offer a view-only mode for people who should see a balance but not spend it. - **DO** _(Costs trust)_ Give every failure on the send and connect flows a message that says whether money moved: "Nothing left your wallet" or "The payment went through". ### Usage life cycle https://www.bitcoinsv.design/guide/designing-products/usage-life-cycle/ - **DON'T** Keep showing onboarding hints to somebody on their hundredth payment. - **DO** Teach each of the four at the moment it first applies: ownership when money first arrives, irreversibility on the first review screen, the backup when the balance is worth protecting, the network name wherever somebody pastes an address. - **DON'T** Teach what the product can take care of for them, such as fees or key schemes. Every concept taught before it is needed is a reason to stop. - **DO** Make the first thing a new user does end with them holding real money: received from a person, or spent on something they wanted anyway. - **DON'T** Build a practice wallet or a simulated payment in place of a real first receive. It teaches the user that the real thing is somewhere else. - **DO** Design for the person doing the introducing: a handle they can share, a payment request they can send, and a first payment that says who it came from. See Contacts. - **DO** Get a new user from opening the app to holding money in one sitting, without leaving the app except to ask somebody to pay them. - **DO** Give every setup step a way back. A mistake during setup should cost a tap, not the wallet. - **DO** Ask the person, after a test, to explain to a friend what they just did. What they cannot explain did not land. - **DO** Measure where people stop, step by step, and work on the worst step first. A whole-funnel number tells you there is a problem and not where it is. - **DO** Design the "frightening moment" explicitly. A payment that looks stuck, an unexpected balance, an app asking for something alarming. One clear explanation at that moment can keep somebody who would otherwise leave. - **DO** We suggest two causes to check first: being asked to choose a key scheme, and having nowhere to get any BSV. The first is yours to fix. See First use. ### Interoperability https://www.bitcoinsv.design/guide/designing-products/interoperability/ - **DO** Talk to the wallet through the connection standard rather than bundling one. The user keeps their keys where they already are, and your app works with wallets that did not exist when you shipped. - **DON'T** Build a wallet inside your app because it is quicker. You inherit key custody, recovery and support, and the user now has one more set of keys to lose. - **DO** Accept a pasted or scanned value without asking the user which kind it is. Detect it and say what you found. - **DO** Support the peer-to-peer payment flow, where the payee's software supplies the output script and gets the transaction and its proof directly. It is the privacy-preserving default and it is how handles work. - **DO** _(Costs trust)_ Export the wallet backup in the wallet data format (BRC-38 and BRC-39), to a file the user holds. If your format is your own, say so plainly and publish it. - **DO** Support restoring a backup written by other software, and report honestly what came across and what did not. - **DON'T** Keep the only copy of a user's proofs on your server. That is custody by another name, whoever holds the keys. - **DO** Verify Passes rather than issuing your own account. A person who has already proved who they are to somebody you trust should not have to do it again. - **DO** Ask for the single field you need. A Pass can be shown selectively, and asking for all of it when you need one line is a design choice, not a protocol limit. - **DO** Offer a plain export of contacts and labels, in a documented format, without a support request. - **DO** Encode a handle rather than an address where you can. It is shorter, it survives being printed once, and it does not tie a person to one key forever. - **DO** Support animated codes for anything that does not fit in one frame, such as a transaction with its proof going to an offline signer. - **DO** Use upper case for codes made only of digits, capitals and $%+-./:. Those encode in a smaller, faster-scanning mode. Handles and addresses do not qualify. - **DON'T** Use a transaction format that leaves out the input proofs. The receiver then has to ask a third party whether the transaction is real. - **DO** Follow the fountain-coded air-gap transport (BRC-141) rather than a private encoding, so a user's existing signer works with your software. - **DO** Exchange public keys and pending transactions in documented formats, and let a cosigner review and sign in whatever wallet they already use. - **DO** List your dependencies somewhere a curious user can find them, and let the technical ones be changed. - **DO** Let a user point at their own header source and their own broadcaster. Most will never touch the setting, and the option costs little. ### Accessibility https://www.bitcoinsv.design/guide/designing-products/accessibility/ - **DON'T** Ship a control labelled "button". A QR code built as an unlabelled image is not selectable at all, so it does not exist for a screen reader user. - **DO** Name the thing and its effect: "QR code, double tap to copy the payment handle". - **DO** _(Costs trust)_ Make a wallet's permission prompt readable in full by a screen reader: who is asking, what for, and for how long. A grant the person could not hear is not consent. - **DO** Put the recipient before the amount in the reading order of a review screen. It is the field most worth hearing first. - **DO** Give every scan a typed or pasted equivalent. A user who cannot aim a camera still needs to pay. - **DO** Pair colour with a word or a symbol, always. Sent and received, plus and minus, not just red and green. - **DON'T** Put a countdown on a confirmation. Nothing here expires, so a timer is a difficulty you added. If a rate quote goes stale, refresh it rather than timing the person out. - **DO** Make sure an amount reads aloud correctly. "12,500 sats" should be spoken as a number and a unit, which means it has to be text with a real unit beside it. - **DO** Use fixed-width digits (tabular-nums), so a changing balance does not shift the layout under a magnified viewport. - **DO** Offer at least one route that does not need handwriting: an encrypted file the user stores themselves, split shares held by people they trust, or a signing device. - **DO** Let the words be read aloud in private, and let the confirmation step be completed with a screen reader. A test that only works by sight makes recovery impossible later. - **DO** Write at a reading age of about twelve. Short sentences, common words, one idea each. - **DO** Say what happened and what it means for the money. "The payment did not go through. Nothing left your wallet." beats an error code every time. - **DO** Run the send and recovery flows with the screen reader on and the screen off. It takes an afternoon and finds problems an automated audit misses. - **DO** Include people with disabilities in research, paid, rather than simulating them. ### Connecting a wallet https://www.bitcoinsv.design/guide/patterns/connecting-a-wallet/ - **DO** Write the connect flow around "your wallet". Name a specific wallet only when helping somebody install one. - **DO** _(Costs trust)_ Request each permission when the user first uses the feature that needs it. - **DON'T** _(Costs trust)_ Bundle every permission into one approval screen during onboarding. - **DO** Warn the user and ask for approval again when an app's domain or certificate changes unexpectedly. - **DO** Publish an exposure statement for your app: the wallet methods you call, the protocols and baskets you use, whether you request the identity key or Passes, what wallet data you keep, and whether agents can act through your app. - **DO** If you build a wallet, publish one for the wallet too: what is allowed automatically, how apps are kept apart, where data is stored, what a full backup contains, and whether users can move funds without your service. ### Permissions and allowances https://www.bitcoinsv.design/guide/patterns/permissions-and-allowances/ - **DON'T** _(Costs trust)_ Preselect broad permissions, describe a permission as less than it is, or show a refused prompt again until the user gives in. All three teach people to tap Allow without reading. - **DO** _(Costs trust)_ Show the app's name from its manifest beside its verified domain in every prompt, and the domain alone when the app has no manifest. - **DO** Write the description for each permission your app declares as what the user gets from it: "To save your reading position", not "Protocol access". - **DO** Let the user approve some items in a grouped prompt and decline others, and let the app carry on with what was approved. - **DON'T** _(Costs money)_ Show an amount taken from the app's description text. Show the amount from the request itself, and warn if the two disagree. - **DO** Show a waiting state in the app that tells the user their wallet is asking them something, and keep it until the wallet answers. - **DON'T** _(Costs trust)_ Cancel a wallet request because the user has not answered yet. A timeout turns a user who was reading into an error. - **DO** Set an allowance to expire by default, and make a lasting allowance an explicit choice the user picks. - **DO** _(Costs trust)_ Cap an allowance per payment, per hour and per day as well as per month, where the wallet supports it, and show every cap in the same prompt. - **DO** _(Costs trust)_ Ask the user again when an amount is unusually high, the recipient is new, the payment pattern changes, an allowance that has ended would start again, or the app asks for a new protocol, basket, Pass field, the identity key or key linkage. - **DO** Show the date a monthly allowance starts again beside what is left of it: "1,200 of 5,000 sats left, resets 1 December". - **DO** After a refusal, say in one sentence what the app cannot do without the permission, and keep everything else working. - **DO** Ask again only when the user next uses the feature that needs the permission, not on the next screen. - **DO** _(Costs trust)_ Make a revoke take effect at once, and say what stops working: "The Satoshi Vision can no longer charge you. It will ask again when you next open an article." - **DO** _(Costs trust)_ Ask for key linkage fresh each time, name who receives it and what they learn, and keep a local record of what was revealed to whom. - **DON'T** _(Costs money)_ Let an AI agent approve key linkage, share a Pass, or widen its own permissions. ### Signing in https://www.bitcoinsv.design/guide/patterns/signing-in/ - **DO** Use one button for a first visit and a return visit. There is no separate sign-up, because there is no account to create. - **DON'T** _(Costs trust)_ Ask for an email address or a password as part of signing in. If you need an email for receipts, ask for it afterwards, as its own optional step. - **DO** _(Costs trust)_ Sign users in with a key derived for your app. If your database leaks, the leaked keys can't be matched to the same person's activity elsewhere. - **DON'T** _(Costs trust)_ Use the root identity key as the account ID for a social network, game, shop or payment service. One breach then becomes a cross-app tracking event. - **DON'T** _(Costs trust)_ Request the wallet's root identity key without a reason you can state in the prompt. Approving a sign-in or a payment must never include it. - **DO** Recognise a returning user without a wallet prompt where the wallet already holds your app's permission. - **DON'T** Show a public key as the user's name. Use the name they gave you, or a plain label such as "Your account". - **DO** Tell people before their first sign-in that the account belongs to their wallet: "Restore this wallet and your account comes back with it. A different wallet is a new account." - **DO** _(Costs trust)_ Say on sign-out that the app is still connected in the wallet, and where to disconnect it: "Signed out. Pixel Arcade is still listed in your wallet. Remove it there to stop it asking." - **DON'T** _(Costs trust)_ Call sign-out "Disconnect wallet". It does not touch the wallet's permissions, and the user will think it did. - **DO** Ask for the narrowest field that answers the question: "over 18", not a date of birth. - **DO** Say which Pass issuers you accept, and offer another way to qualify where the law allows. - **DON'T** Make a Pass a condition of signing in when only one feature needs it. Ask at that feature. - **DO** After the first sign-in, say in one line what your app received and what it cannot see: "Pixel Arcade can recognise you next time. It can't see your balance or your other apps." ### Amounts and units https://www.bitcoinsv.design/guide/patterns/amounts-and-units/ - **DO** Default to satoshis, not BSV, for the bitcoin figure. Everyday amounts are hundreds or thousands of satoshis, and the decimal form is unreadable at that scale. - **DO** Write "sats" or "satoshis" in words, and group digits in threes: 12,500 sats. - **DON'T** _(Costs money)_ Show long decimal BSV amounts in a consumer interface. "0.00012500 BSV" asks the reader to count zeros, and they will get it wrong. - **DON'T** Adopt a satoshi glyph. None renders reliably, none is in common fonts, and your users have not seen any of them. - **DO** _(Costs trust)_ Use Bitcoin SV or BSV on screen: "Send BSV", "Your BSV balance", "Bitcoin SV address". Use one of the two consistently within a screen. - **DO** Prefer "Bitcoin SV" where there is room and the reader may be new to it, "BSV" where space is tight or the term repeats in a list. - **DON'T** _(Costs trust)_ Write "bitcoin" alone on a screen where somebody is about to move money. Used precisely it is an umbrella covering several chains, so it is the one word that cannot tell a user which network they are on. See Bitcoin. - **DO** Lead with local currency for anything a person chooses to buy, with the satoshi amount beside it: "£12.00 (24,000 sats)". - **DO** Lead with satoshis for figures software decides or enforces, such as allowance limits, what is left of an allowance and agent budgets, with local currency beside them. - **DO** Let the two be swapped in one tap, and remember the choice. - **DO** _(Costs trust)_ Say when a converted figure is an estimate, and roughly how fresh the rate is. A price that silently drifts is worse than one labelled approximate. - **DO** Use tabular figures (tabular-nums in CSS) everywhere a figure appears, so digits line up in a column and a changing balance does not shift the layout. - **DO** Format for the reader's locale. 1,200 and 1.200 and 1 200 are the same number to three different people and three different numbers to one of them. - **DO** _(Costs trust)_ Keep one bitcoin unit per screen. Mixing "0.0001 BSV" and "10,000 sats" in one view asks the user to do arithmetic to compare two things you wrote. - **DON'T** _(Costs trust)_ Abbreviate amounts in a financial context. "12.5k sats" saves four characters and introduces a rounding question. - **DON'T** _(Costs trust)_ Shorten a number with an ellipsis, ever. Reformat it or let it wrap. - **DO** Leave the fee off the review screen and put it in the transaction details. If it is shown, show it in local currency: "Fee: less than 1p". - **DO** Show the individual amount where it happens and the aggregate where the user is deciding something. "About 1p (20 sats)" on the article, "940 sats (about 47p) today" in the allowance summary. - **DO** Round aggregates to a sensible precision in local currency. "About 24p today" is more useful than "£0.2384". - **DO** Make sure an amount reads correctly aloud. A screen reader should say "twelve thousand five hundred satoshis", which means the unit needs to be text rather than an image or an unlabelled glyph. - **DO** Never rely on colour alone to show direction. Pair the colour with a sign or a word. ### Charging per use https://www.bitcoinsv.design/guide/patterns/charging-per-use/ - **DO** _(Costs trust)_ Show the running total against the allowance wherever the spending is happening, not only in a settings screen. - **DO** _(Costs trust)_ Put a stop control next to that total. One action, no confirmation, effective immediately. - **DON'T** _(Costs trust)_ Renew an allowance that has ended without asking the user again. A limit that starts again each month within a live grant is normal, provided the reset date is shown beside what is left. - **DO** Put the cost on the thing: "about 1p (20 sats)" on the article link, "5 sats per request" on the endpoint. - **DO** Lead with local currency for anything a person chooses to buy, and with satoshis for anything software decides, with the other figure beside it. "About 1p" means something to a reader; "20 sats" means something to a developer. - **DON'T** Round a per-use price up to something tidy because the real number looks odd. The real number is the product's best argument. - **DO** Group by what the user was doing, not by transaction. "The Satoshi Vision, 14 articles, about 14p (280 sats)" is one row they understand. - **DO** Let that row open into the individual payments, for the person who wants them and the accountant who needs them. - **DO** Lead with the period total. "About 24p today" answers the question they actually have. - **DON'T** Show a notification per payment. The first one is informative, the fortieth is why the feature gets switched off. - **DO** Show the rate and the elapsed cost together, and update at a pace a person can read. A figure changing ten times a second is not information. - **DO** _(Costs trust)_ Make stopping obvious and instantaneous, and confirm that it stopped. "Stopped. You spent 340 sats." closes the loop. - **DO** _(Costs trust)_ Offer a ceiling before starting, not only an allowance. "Stop at 5,000 sats" is a different and more reassuring promise. - **DO** Decide what happens when one payment in a hundred fails: retry, skip, or stop. Then tell the user which, once, rather than reporting each one. - **DO** _(Costs trust)_ Fail towards not charging. A user who got something free will forgive you; one charged twice will not. ### Wrong-network payments https://www.bitcoinsv.design/guide/patterns/wrong-network-payments/ - **DO** _(Costs money)_ Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. - **DO** _(Costs money)_ Put the network name next to the address field, always, not only on error. "BSV address" is three words and it is the whole defence. - **DO** _(Costs money)_ Warn on every pasted address rather than trying to detect a bad one. You cannot detect it, and a warning that only fires sometimes teaches people it means something specific. - **DON'T** _(Costs money)_ Use "bitcoin address" as the field label. That is the word that cannot distinguish the networks, on the screen where the distinction is the whole point. - **DO** _(Costs money)_ Put the network on the confirmation, beside the recipient, in the same weight as the amount. - **DO** _(Costs money)_ Say plainly what cannot be undone, before the button: "Sent to the wrong network, this usually cannot be recovered." - **DO** _(Costs money)_ Offer a test payment for a first-time address above a threshold you choose, and ask the user to check with the recipient that it arrived. It costs a fraction of a penny and it is the only defence that proves the address is right. - **DO** _(Costs trust)_ Say what happened in plain words: which network it went to, that the money is not lost from the chain but is out of reach from here, and what recovery would require. - **DO** Give them the transaction reference and the output, so somebody technical can help. - **DON'T** Say "transaction failed". It did not fail. It succeeded somewhere else, and telling somebody it failed sends them looking for a refund that is not coming. - **DON'T** _(Costs trust)_ Promise recovery you cannot deliver. If it needs the other party's cooperation, say that is what it needs. - **DO** _(Costs money)_ Make the network selection impossible to leave at a default, and restate the chosen network on the confirmation. - **DO** Treat a first withdrawal to a new address as a different flow from a repeat one. ### Errors and failed payments https://www.bitcoinsv.design/guide/patterns/errors-and-failed-payments/ - **DO** _(Costs trust)_ Say whether money moved in every message that follows a payment attempt, including when the answer is that nothing left the wallet. - **DO** End every error with one thing the user can do, as a button where there is one. - **DO** Put the error code and technical detail in an expandable details area with a copy button, so support can ask for it. - **DO** Keep what the user entered. Return them to where they were with the amount, recipient and note still filled in. - **DON'T** Write "Something went wrong" on its own. If you truly do not know what happened, say what you do know and whether money moved. - **DO** Explain a failure in the app when it is about the app's task, such as an article not unlocking, and in the wallet when it is about the user's money or permissions. - **DON'T** _(Costs money)_ Offer "Try again" on a payment until you know the first attempt did not go out. - **DO** _(Costs money)_ Tell the user once when their wallet is retrying for them: "Your wallet will keep trying to send this. You don't need to pay again." - **DON'T** Show a refusal or an unanswered wallet prompt in an error style. Both are the user's choice, and red tells them they did something wrong. ### Letting an agent spend https://www.bitcoinsv.design/guide/patterns/letting-an-agent-spend/ - **DO** _(Costs money)_ Fund an agent by deliberate top-up, as a human action. A standing instruction to refill is the thing that turns a bounded loss into an unbounded one. - **DON'T** _(Costs money)_ Hand an agent the user's identity key or their Passes. It can have its own identity and act as itself; it should never be able to prove it is the person. - **DO** Show all four on one screen, as current values rather than settings. "412 of 5,000 sats, 18 payments today, 3 services, 22 days left" is a status, and a settings form is not. - **DO** _(Costs money)_ Enforce limits outside the agent, in the wallet or the service holding its keys. A limit the agent checks itself is a limit an injected instruction can argue with. - **DO** _(Costs trust)_ Require a human for anything outside the scope: a new payee, a larger amount, a wider permission. Send the person a notification for it, rather than adding it to a list they have to check. - **DO** Group by purpose, not by payment. "Research assistant: 6 sources, 240 sats" is reviewable; forty rows are not. - **DO** _(Costs trust)_ Record what each payment was for at the moment it happens. Intent cannot be reconstructed afterwards. - **DO** _(Costs trust)_ Surface the unusual rather than the complete. A payee it has never paid, or a payment larger than its usual, belongs at the top; the routine belongs in a total. - **DON'T** _(Costs trust)_ Report agent spending only in a log. A log is for after somebody already suspects something. - **DO** _(Costs trust)_ Put one control that stops everything, visible wherever the agent is, with no confirmation step. Confirmations are for actions you might regret, and stopping is not one of them. - **DO** Say what stopping means: no further payments, work in progress abandoned, funds stay where they are. A user who is not sure what the button does will not press it. - **DO** _(Costs trust)_ Name the agent and its purpose wherever its spending appears. "Example Assistant, buying search results" is a thing a person can consent to; "automated payments" is not. - **DO** Report on a human schedule. A daily summary a person reads beats a real-time feed nobody watches. ### Holding tokens https://www.bitcoinsv.design/guide/patterns/holding-tokens/ - **DON'T** _(Costs trust)_ Ask for broad wallet access in order to read a token balance. Ask for the basket. An app that wants everything in order to show one number is the reason permission screens get ignored. - **DO** _(Costs trust)_ Show provenance as a short human sentence before a trade or a transfer: "Issued by Example Studio, 3 owners since, unbroken." The full chain belongs behind that line, not in front of it. - **DO** _(Costs trust)_ Resolve the real-or-fake question for the user rather than printing an ID and hoping. Match against issuers they already trust, and say plainly when you cannot. - **DON'T** _(Costs trust)_ Show a token's picture at the size of a decision without the provenance beside it. The picture is the part that is trivial to fake. - **DO** _(Costs trust)_ Say what is being written on chain, that it cannot be edited later, and what it costs. The cost is a fraction of a penny, which is worth saying out loud because people expect otherwise. - **DO** _(Costs money)_ Treat the supply decision as final in the interface, because it is. A field labelled "Supply" with no warning is a trap. - **DO** _(Costs trust)_ Name the issuer wherever the balance appears, not only at acquisition. "120 GBP, issued by Example Trust" is the honest form. - **DON'T** _(Costs trust)_ Draw a stablecoin balance in the same type as a BSV balance with no distinction. One is a bearer asset and the other is a claim on a company. - **DO** Choose by what you need enforced on chain rather than by what is popular. A loyalty point and a regulated instrument are not the same design problem, and the stricter family exists for the second. ### Storing data on chain https://www.bitcoinsv.design/guide/patterns/storing-data-on-chain/ - **DO** _(Costs trust)_ Say "permanent and public" in the consent step, in those words, before anything is written. - **DO** _(Costs trust)_ Show exactly what will be written. If it is a hash, say that the document stays on your server and only a fingerprint goes out. - **DON'T** _(Costs money)_ Write anything identifying a person without an explicit, specific consent for that write. "Agreed to the terms" is not consent to publish somebody's name forever. - **DON'T** _(Costs trust)_ Offer a delete button for on-chain data. You can stop displaying it. That is not the same thing and the difference is the whole point. - **DO** _(Costs trust)_ Default to the hash. Publishing is the irreversible option and should be the deliberate one. - **DO** Treat the overlay as a dependency the user should know exists, the way you would treat any other service. See Interoperability. - **DO** _(Costs trust)_ Make sure the data can still be verified without your overlay. The point of putting it on chain was independence from you. - **DO** Show progress honestly for anything large, and say what happens if it stops halfway. A partially written file is a real state, not a theoretical one. - **DON'T** Put a large file on chain because you can. Cost is not the constraint; permanence is, and so is the user's understanding of it. - **DO** Say "anchored in block 951,204" alongside the human date. The block is the fact; the date is the convenience. ### Pay-per-use reader https://www.bitcoinsv.design/guide/pay-per-use-reader/ - **DO** Read each screen's reasoning before borrowing it. The prices and limits fit a news site charging about 1p an article and will be wrong for a product charging a hundred times that. ### First visit and connecting https://www.bitcoinsv.design/guide/pay-per-use-reader/first-visit/ - **DO** Mark free articles as plainly as paid ones on the front page, so the absence of a price is never mistaken for a missing label. - **DON'T** Put a connect prompt, a sign-in button or a wallet logo on the front page. Nothing there costs money, so nothing there needs a wallet. - **DO** Show enough of a paid article before the price for the reader to judge it: at least the headline, the standfirst and the opening paragraphs. - **DO** _(Costs trust)_ Name the price, in satoshis and local currency, on the same panel as the connect button. The reader should know what the first tap costs before the wallet opens. - **DO** _(Costs trust)_ Ask for a key made for this site only at connection, and nothing else: no identity key, no Pass, no spending grant. - **DON'T** Treat "Not now" as an error. Keep the reader on the article they chose, with the free paragraphs still showing. - **DO** _(Costs money)_ Name the article being bought on the wallet's payment sheet, so the reader can see that the thing she tapped is the thing she is paying for. - **DO** Open the rest of the article in place the moment the wallet reports the payment accepted, at the paragraph where the free part ended. - **DON'T** Show the allowance offer before the reader has finished her first paid article, or on any free article. - **DO** Treat "No thanks" as final for the visit. The reader goes on paying per article with a wallet prompt each time, and the card does not return until her next visit. - **DO** _(Costs trust)_ Give the allowance an end date in the request itself, and show that date on the wallet's sheet. When it ends, ask again and show what the last one was spent on. ### Reading and the meter https://www.bitcoinsv.design/guide/pay-per-use-reader/reading/ - **DO** Show what the article just cost and what is left of today's allowance on the article itself, above the headline, every time the allowance pays for one. - **DO** Mark articles the reader has already bought as read, without a price, so she never wonders whether opening one again will charge her. - **DON'T** _(Costs money)_ Charge for an article the reader has already bought, whether she returns to it on the same day or a month later. - **DO** List what today's spending bought by article title, with the total first in local currency and the remaining allowance beneath it. - **DO** _(Costs money)_ Stop charging the moment the reader taps Stop, before any confirmation or animation, and say how much she spent today. - **DO** _(Costs trust)_ Say on the stopped state that the allowance still exists in the wallet, and where to remove it. - **DO** Explain a used-up allowance on the article the reader was trying to open, with the free paragraphs still showing, and offer a one-time payment for that article. - **DON'T** Raise the limit for the reader, or suggest a larger figure as the default. A new limit is a new request that she types or chooses. - **DON'T** _(Costs money)_ Show Try again on an article while the wallet reports its payment as still being sent. ### Receipts, refunds and leaving https://www.bitcoinsv.design/guide/pay-per-use-reader/receipts-and-leaving/ - **DO** Describe each payment request with the article's title, short enough to read in one line of a wallet's activity list. - **DO** Let the reader reach every article she has paid for from its receipt, so a receipt doubles as her reading history. - **DO** Put a way to report a faulty article next to each receipt line, not on a separate support page. - **DO** Name the article in the refund's note, so the incoming payment in the reader's wallet explains itself without a visit to the app. - **DON'T** _(Costs trust)_ Describe a refund in the app as a payment being reversed or cancelled. Say "We've sent you 20 sats back". - **DO** Show the price-change notice to every reader with an active allowance before the new price applies, with the date it takes effect. - **DO** _(Costs trust)_ After a revocation, keep every article the reader already paid for readable once she connects the same wallet again, with no new payment. - **DON'T** Ask for the allowance again in the same panel that tells the reader she is no longer connected. Reconnecting and granting an allowance are two decisions, made at two moments. ### Connected web app https://www.bitcoinsv.design/guide/connected-web-app/ - **DO** Write down, before drawing any screen, the three things a ticketing site needs from the wallet (a key for this site, one Pass field for age-restricted gigs, one basket for tickets) and treat any request beyond them as a design change that needs a reason. - **DON'T** Add an account system "for later" alongside the wallet sign-in. Two ways to be the same person on one site is how people end up with two half-accounts and a support ticket. - **DO** Publish the site's exposure statement where the sign-in button is, as a link, so somebody like Ilse can read what the site asks for before she connects. See Disclose what you use. ### Signing in https://www.bitcoinsv.design/guide/connected-web-app/signing-in/ - **DO** Let people browse every gig, date and price without connecting. Connecting is for buying and for seeing tickets already bought, not for looking. - **DON'T** Name a wallet brand on the site's connect button or its explanation. The site works with any compatible wallet, and naming one tells everyone else they are in the wrong place. - **DO** _(Costs trust)_ Ask only for the sign-in key at this step. Payment, the age check and the ticket basket each wait for the screen where Anna first needs them. - **DON'T** Treat "Not now" at this prompt as a failure. Put the Connect wallet button back, keep the gig page as it was, and say nothing louder than the button. - **DO** Show the "what we can and can't see" line once, after the first sign-in only, on the page Anna was already on rather than a separate welcome screen. - **DON'T** _(Costs trust)_ Ask for a name or email straight after sign-in to make the header friendlier. "Your account" is enough until Anna chooses to add something. - **DO** Try a silent sign-in on load when the site has seen this browser before, and fall back to the Connect wallet button only if the wallet does not answer without a prompt. - **DO** Under the connect button, say in one line that the account follows the wallet, not the device: "Use the same wallet on any device to see your tickets. A different wallet starts a new account." - **DON'T** _(Costs trust)_ Offer to "find" Anna's account when a different wallet connects. The site cannot tell it is her, and guessing from anything else would link identities she kept apart. ### Proving an age https://www.bitcoinsv.design/guide/connected-web-app/proving-an-age/ - **DO** Show the age step only for gigs that have an age limit, and name the venue's rule as the reason: "The Corner Room is over 18 only", not "Verification required". - **DO** _(Costs trust)_ List on the site, before the wallet prompt opens, the one thing the site will receive and the things it will not, in the same words the wallet is about to use. - **DON'T** _(Costs trust)_ Ask for a date of birth and work out the age on the site. The site then holds a fact it never needed, and the wallet's field-level choice is wasted. - **DO** Request the field with Example Tickets named as the verifier, and if the venue itself will receive the answer, name the venue in the request too, so the wallet's "Sent to" line is true. - **DO** _(Costs trust)_ Ask for the same single field, "over 18", at every age-restricted checkout, and never widen a later request because an earlier one was granted. - **DO** Name the issuers the site accepts, and who chose them, on the screen that tells somebody they have no suitable Pass. - **DO** Offer a way to buy that does not depend on a Pass where the venue allows one, so missing a Pass costs Anna a step at the door rather than the ticket. - **DON'T** Send Anna to an issuer and empty her basket behind her. Keep the gig and the ticket she chose waiting for when she comes back. - **DO** Word a refusal as Anna's decision and its one consequence for this gig, and leave every other part of the site, including other gigs, working as before. - **DON'T** Reopen the wallet's Pass prompt automatically after a refusal, or on the next page load. The next request waits for Anna to press Ask my wallet again. ### Buying a ticket https://www.bitcoinsv.design/guide/connected-web-app/buying-a-ticket/ - **DO** _(Costs money)_ Show on the review screen the same sats amount the wallet's prompt will show, and if the rate moves before Anna presses the button, update the figure on this screen first rather than letting the wallet show a different number. - **DO** Name who receives the money and who the ticket is for in one line. Anna is paying the ticket site, for a venue, and both names belong on the screen. - **DO** Say on the review screen what Anna can do with the ticket afterwards, give it away or not, refund it or not, before she pays rather than in the terms. - **DON'T** _(Costs money)_ Add a booking fee or any other charge after the review screen. If the product charges one, it is part of the price shown here. - **DO** Ask for the tickets basket in the first purchase's prompt, as a separate item Anna can decline, and never at sign-in. - **DON'T** _(Costs trust)_ Ask for a spending allowance "to make the next purchase faster". A site people pay a few times a year should ask each time. - **DO** Tell Anna where the ticket is, in her wallet, on the confirmation, so she does not wait for an email that is not coming. - **DO** Write the gig name, venue, date and what the holder may do with the ticket into the token when it is issued, so any wallet can show it without asking the site. - **DON'T** Let a picture of the ticket be enough to get in. The picture is the part anybody can copy; the door has to check that the person in front of it holds the ticket now. ### Coming back and leaving https://www.bitcoinsv.design/guide/connected-web-app/coming-back-and-leaving/ - **DO** Label the site's own control Sign out, and put the one-line pointer to the wallet directly beneath it, so the two actions are read together. - **DON'T** _(Costs trust)_ Put a "Disconnect" button on the site that only clears the session. Anna would believe the site lost its access when the wallet still lists it. - **DO** Say on sign-out that it applies to this device only, and that the ticket is unaffected, in one line on the page she lands on. - **DON'T** Sign Anna straight back in on the next page load after she pressed Sign out. Wait until she presses Connect wallet again on this device. - **DO** Treat a sign-in that suddenly prompts again as a returning user whose wallet was cleared or who removed the site, and show the ordinary connect flow without asking why. - **DO** _(Costs trust)_ Store the result of an age check, the gig and the date, and never the Pass or any field beyond the one asked for, and say so on the site's data page. - **DO** _(Costs money)_ Make a ticket valid at the door from the token alone, so it still works after Anna deletes her data or removes the site from her wallet. - **DON'T** _(Costs trust)_ Keep anything about Anna that this page does not list. If the site starts storing something new, the page changes the same day. ### Agent with a budget https://www.bitcoinsv.design/guide/agent-with-a-budget/ - **DO** Take the split between the assistant and the wallet that holds its keys before you take any screen. Every rule in this section assumes the limits sit in the wallet and not in the assistant's instructions. - **DON'T** Copy the example numbers as defaults. The budget, rate and expiry here suit one research task, and your product's tasks will need their own. ### Setting it up https://www.bitcoinsv.design/guide/agent-with-a-budget/setting-it-up/ - **DO** Say on Scout's first screen, in one line, that the worst case is the amount Anna sends it. "Scout can't spend more than you give it" is the reassurance the whole design rests on. - **DON'T** _(Costs trust)_ Offer to connect Scout to Bitcoin SV Wallet with a spending permission as a quicker alternative. Two routes to the same task make the safer one look like the slow one. - **DO** Show the services row as named services with their prices, never as a field where Anna types an address or a domain. - **DO** Translate the budget into what it buys for this task: "10,000 sats is about 2,000 data requests, or 500 articles." The number only means something beside its use. - **DON'T** Offer "no end date" as an option on this screen. A delegation with no end is the one nobody comes back to review. - **DO** Request exactly the budget Anna set. If she changes the amount in Bitcoin SV Wallet, show the new figure as Scout's budget on the next screen rather than holding on to the old one. - **DON'T** _(Costs trust)_ Ask Anna to switch on a low-balance refill during funding. Topping up is a separate decision each time, made when she can see what the last budget bought. - **DO** List on the review what will come to Anna for approval: "a new service", "anything over 100 sats", "going over 3,000 sats in a day". The approvals are part of the deal, not a surprise later. - **DO** Name on the review the one device where approvals will arrive, and accept approvals only there. - **DO** Say when and where the daily summary will arrive, and let Anna change the time on this screen. - **DO** Disable Start Scout until the top-up has arrived, and say so beside the button: "Waiting for 10,000 sats from Bitcoin SV Wallet". - **DON'T** Move the status strip into a settings page once setup is done. Anna checks on Scout from where its work is, and that is where the total and the pause belong. ### While it works https://www.bitcoinsv.design/guide/agent-with-a-budget/while-it-works/ - **DO** Show each purchase in the task view beside the step of the task it served, so "4 articles" reads as part of the research rather than a separate bill. - **DON'T** Notify Anna's phone for payments inside the limits. She is not watching on purpose, and a buzz per article would teach her to silence Scout entirely. - **DO** _(Costs money)_ Show the amount and the payee from the payment Scout's wallet refused, and Scout's explanation separately, labelled as Scout's. If the explanation names a different amount, show both and say they disagree. - **DO** Name every limit the request breaks: "New service" and "Over 100 sats a payment". Anna is deciding whether the limits were wrong or the request is. - **DON'T** _(Costs money)_ Put "Always allow" or "Add to Scout's services" on the approval screen. Widening Scout's scope from a notification is how one odd request becomes a standing permission. - **DON'T** _(Costs money)_ Let the assistant approve its own request, or accept an approval from anywhere other than Anna's own device. - **DO** Show what the budget bought on the same screen that says it is spent. Anna decides whether to top up by judging the last budget, not by looking at a zero. - **DO** Offer to finish the task with what Scout has already bought, as an equal choice beside topping up. - **DO** _(Costs money)_ Refuse a payment above the price shown on the limits screen, even when it is inside the per-payment limit, and send it to Anna like any other request outside scope. - **DO** _(Costs trust)_ Say plainly when a service kept the money: "Example Data was paid 15 sats and sent nothing back." Whether money moved is the first thing the errors pattern asks every failure to answer. - **DO** _(Costs money)_ Cap paid retries to one service at a fixed number per task, show that number on the limits screen, and stop using the service when it is reached. Each retry is another payment, and a loop of small failures is how an agent spends its budget on nothing. ### Reviewing what it did https://www.bitcoinsv.design/guide/agent-with-a-budget/reviewing-what-it-did/ - **DO** Put refused payments, approvals Anna gave, and any service that kept money without delivering at the top of the daily summary, above the total. - **DO** Say "Nothing unusual today" when that is true. A summary that only ever lists problems leaves Anna unsure whether a quiet one means no problems or a missing section. - **DON'T** Send a summary on a day Scout spent nothing and nothing changed. A daily message with no news is the fastest way to have the useful ones ignored. - **DO** Mark every payment in the trail with the task it served. A payment that belongs to no task is itself something to flag. - **DO** Show refused payments in the trail beside the ones that went through, marked "Refused, nothing sent". What Scout tried to buy is part of what it did. - **DO** _(Costs trust)_ Record Scout's reason with each payment at the moment it is made, and keep it unchangeable. A reason written afterwards is a story, not a record. - **DON'T** _(Costs trust)_ Present Scout's note in the same style as the amount and payee. The amount and payee come from the payment; the note comes from the agent, and the screen should show the difference. - **DO** Put Pause Scout on any payment Anna has flagged, so she can stop it from the place she noticed the problem. - **DON'T** _(Costs trust)_ Offer "Get a refund" or "Dispute" on an agent payment. Scout cannot reverse a payment, and a button that implies it can will be pressed and will fail. ### Stopping it https://www.bitcoinsv.design/guide/agent-with-a-budget/stopping-it/ - **DO** _(Costs trust)_ Show the exact time spending stopped, and whether a payment was already on its way at that moment: "The last payment, 20 sats to The Satoshi Vision at 14:32, went through before you paused." - **DO** _(Costs money)_ Make pausing take effect in Scout's wallet, not in the assistant. Spending stops even if the assistant is still running or has not noticed. - **DON'T** Ask "Are you sure?" before pausing. Pausing costs nothing and can be undone; a question in front of it only slows down the person who is worried. - **DO** Say how far the task got and what was already bought, so Anna can decide between resuming, finishing with what there is, and ending. - **DO** Say what happened to any approval that was waiting: still waiting while paused, cancelled when revoked. - **DON'T** _(Costs trust)_ Let Scout's stop message argue for resuming. "I was nearly there" turns a safety control into a negotiation with the thing being stopped. - **DO** _(Costs trust)_ Say on the revoke screen that the money left in Scout's wallet stays there until Anna sends it back, and show the amount. - **DON'T** Bundle revoking with deleting Scout's activity. Anna may end the job precisely because she wants to look at what happened. - **DO** _(Costs money)_ Offer only the wallet that funded Scout as the destination for what is left. A payee chosen at the end of a delegation is a payee nobody vetted. - **DO** Close the job with the three numbers Anna will want to reconcile: what she sent, what Scout spent, and what came back. ### Payments https://www.bitcoinsv.design/guide/how-it-works/payments/ - **DO** Show "Paid" or "Received" as soon as the recipient's wallet replies "accepted". Do not wait for the payment to be mined. - **DO** Don't show derived payment addresses in the main interface. Show the person, handle or app the payment relates to. Keep raw transaction details in an advanced view. - **DO** _(Costs trust)_ Always show the user what they're paying for, and the running total against their allowance. Small, frequent payments add up, and users should never be surprised by them. ### Nodes and verification https://www.bitcoinsv.design/guide/how-it-works/nodes/ - **DO** Let a wallet point at a different service provider, and ideally more than one at a time. A wallet welded to one company's endpoint has that company's lifespan. - **DON'T** _(Costs trust)_ Trust a single service's word that a payment is confirmed. The merkle proof is the evidence; verify it against headers rather than displaying whatever the API returned. - **DO** Put the services a wallet uses in an advanced settings screen, with what each one is for in one line. Users who care should be able to see and change them. - **DON'T** Put verification in front of ordinary users. Nobody should have to understand merkle proofs to be paid. - **DO** Keep headers synced quietly in the background and never make it a user-facing task. If headers are stale, say what that means for the user ("can't confirm payments from the last 3 days") rather than showing a sync percentage they can do nothing about. ### Legacy compatibility https://www.bitcoinsv.design/guide/how-it-works/legacy-compatibility/ - **DO** _(Costs money)_ Show the network on every receive screen that shows a plain address, and warn on send when an address is pasted rather than picked. - **DO** _(Costs money)_ When an import of recovery words finds nothing, check the other derivation path before telling the user the wallet is empty. - **DO** _(Costs trust)_ Move funds out of a seed-only wallet by sending them, not by importing its words. - **DO** Pick the payment method automatically, in this order: peer-to-peer, then address-only Paymail, then a plain address. - **DON'T** Ask the user to choose a payment protocol. - **DO** _(Costs trust)_ Every consumer wallet should still be able to send to a plain address. It's the user's guaranteed exit if anything else in the stack fails. Label it clearly, for example Send to external wallet, and make sure it works without any vendor service.