App Blueprintbtcapps.org

Sheet S-02 · Principles

Ten principles for designing Bitcoin apps

Bitcoin apps differ from ordinary fintech in four ways: payments are irreversible, keys can sit with the user, the ledger is public, and finality arrives slowly. These ten entries turn those four facts into design decisions you can apply on Monday.

Filter by concern

Showing all 10 principles.

Detail01

Name the key holder, every time

At every moment, the interface should make it obvious who can move the funds: the user, you, or both together.

Whoever controls the keys controls the coins. A screen that blurs this, by calling a custodial balance "your bitcoin" without saying who holds the keys, or by hiding a co-signer behind friendly wording, creates expectations that collapse at the worst moment: a lockout, an outage, a shutdown. Honest labelling is cheaper than a support queue and far cheaper than a lost user's trust.

In practice

  • Use one fixed phrase per model, such as "You hold the keys" or "We hold the keys for you", on the first screen and beside the balance.
  • Say what happens if the service shuts down: can people still reach their funds?
  • Keep marketing copy and interface copy consistent with each other.

Watch for

Words like "secured", "protected" or "insured" used without saying by whom, against what, and within which limits.

TrustUXChecklist:U-01U-10
Detail02

Treat irreversibility as a design material

A confirmed payment cannot be undone by your app, so build the pause, the preview and the plain-language warning into the flow itself.

Card networks taught people to expect disputes and chargebacks. A Bitcoin transaction has no such backstop: once it is buried under enough blocks, only the recipient can send the money back. That is a feature for merchants and a hazard for newcomers. Good design slows down the dangerous moment without punishing the routine one.

In practice

  • Make the confirmation screen show the full address, amount, fee and total.
  • Add friction in proportion to risk: a first payment to a new address, or an amount that is a large share of the balance.
  • Offer a small practice payment before the first real one.

Watch for

Dark patterns that rush people: countdown timers, auto-advance, or a Send button that is the loudest thing on every screen.

UXSecurityChecklist:U-11U-04S-04
Detail03

Show time honestly

Never show a payment as complete before the network agrees, and explain what "pending" means and what the user can do meanwhile.

Blocks are targeted about every ten minutes on average, but any single wait can be much shorter or much longer. A broadcast transaction is not the same as one included in a block, and one confirmation is not the same as six. Interfaces that flatten all this into one green "Success" toast teach the wrong model and leave merchants exposed to payments that later vanish.

In practice

  • Name the states: sent, in a block, and settled by your own stated policy.
  • Give a plain reason for waiting instead of an endless spinner.
  • For merchants, define how many confirmations each order size needs, and show it on screen.

Watch for

Time estimates presented as promises. Say "usually", and show what you actually know.

UXTrustChecklist:U-03U-09
Detail04

Make recovery a feature you rehearse

A backup nobody has tested is a hope. Creating, verifying and restoring a backup should be part of the product.

In self-custody the backup is the account. If the only copy is lost, nobody, including you, can help. The failure rarely looks like broken cryptography. It looks like a screenshot synced to the wrong place, a note thrown away during a move, or a restore flow that was never tried. For custodial services the equivalent is account recovery, which must resist social engineering as hard as it helps real owners.

In practice

  • Show the backup once and ask for a short verification before continuing.
  • Provide a "test my backup" path that restores into a clean profile.
  • State in one sentence what the backup contains and what it does not, such as labels or channel state.

Watch for

Backups that quietly sync to cloud services the user never chose.

SecurityUXChecklist:U-06U-12
Detail05

Private by default, disclosure by choice

Assume every request leaks something, and tell people what leaks, and to whom, before they opt in.

Bitcoin's ledger is public. Anyone who can link addresses to a person can follow their payments. Apps add more leaks: look-ups sent to a third-party server reveal which addresses a user cares about, analytics reveal behaviour, and notification providers see timing. Privacy cannot be bolted on later, because data already shared cannot be recalled. It is a first-sprint decision.

In practice

  • Generate a fresh receiving address for each payment by default.
  • List every external service the app talks to on one settings page, and let experienced users point it at their own node.
  • Keep analytics off by default and never include addresses or amounts.

Watch for

Words like "anonymous" or "untraceable". Describe what a feature does and does not hide, not an absolute.

PrivacyTrustChecklist:U-13S-07
Detail06

Show exactly what will be signed

The screen the user approves must match the bytes that get signed: amount, destination, fee and change.

Signing is the point of no return. Malware, tampered pages and clipboard hijackers all try to swap a destination between the moment someone pastes it and the moment they confirm. The defence is a confirmation step that decodes the real transaction, shows the full address in readable chunks and, where a hardware signer exists, repeats the check on its own screen.

In practice

  • Render the confirmation from the transaction being signed, not from the form state that produced it.
  • Show addresses in groups, emphasise the first and last characters, and warn if the clipboard changes after pasting.
  • Be consistent about units, and spell out sats versus BTC wherever there is doubt.

Watch for

Addresses shortened with an ellipsis on the confirmation screen. That is where the swap hides.

SecurityUXChecklist:S-05S-06U-04
Detail07

Give fees a story and a default

Fees are the price of block space. Offer a sensible default and describe the choices in terms of time and cost.

Miners include transactions that pay well enough for the space available, and the going rate moves with demand. Users who cannot see why a fee is what it is feel cheated, and users who set it too low simply wait. The honest design explains the trade-off in one line, starts at a reasonable setting, and gives the impatient a way to pay more later.

In practice

  • Present a short scale from slower and cheaper to faster and dearer, with the amount in bitcoin units and any local-currency figure labelled as an estimate.
  • Support bumping or replacing a stuck payment where the protocol allows it.
  • Never change the fee silently between confirmation and signing.

Watch for

Fee constants baked into a release. Rates move, so read them from a source you can name.

UXChecklist:U-05U-02
Detail08

Shrink the blast radius of every secret

Keep keys in as few places as possible, for as little time as possible, reachable by as few components as possible.

Every extra copy, log line or integration is another place a secret can escape. Treat key material with the care you would give anything hazardous: create it in a controlled spot, store it in the strongest container the platform offers, and process it in a narrow, well-tested module. Separate duties so that no single compromised component, person or credential can move everything.

In practice

  • Use the platform's hardware-backed secure storage where it exists.
  • Keep signing code in an isolated module with a tiny interface and no third-party analytics.
  • Scrub secrets from logs, crash reports, clipboards and screenshots, and limit how long they stay in memory.

Watch for

Debug logging left on in release builds, and support tools that can see far more than the job needs.

SecurityChecklist:S-01S-02S-03
Detail09

Fail loudly, recover quietly

When something goes wrong, say what happened, whether the funds are safe, and what to do next, in that order.

Money apps create anxiety by default. A raw error code or a spinner that never ends makes people guess, and guessing near money is dangerous: they retry, reinstall, or ask strangers for help. Error states are where trust is earned. They also include quiet failures, such as a data source that is down, a stale balance, or a broadcast the network rejected.

In practice

  • Write each error in three lines: what happened, what is still safe, what to try.
  • When offline, show last-known data with a timestamp rather than a blank screen.
  • Make retries safe so that tapping twice never sends twice.

Watch for

Messages that blame the user, or that say "contact support" without offering a safe way to do so.

UXSecurityChecklist:U-08U-09S-11
Detail10

Use the standards, do not invent cryptography

Prefer widely reviewed standards and libraries to novel schemes, and invent only where you can afford independent review.

Bitcoin's tooling has had many years of public scrutiny: address formats with checksums, standard key derivation, output descriptors, partially signed transaction formats and test networks. Following them gives users portability, because they can leave your app with their funds and recover with other software. Home-grown schemes lock people in and hide bugs until someone loses money.

In practice

  • Use established libraries for key derivation, signing and address handling, and do not write your own primitives.
  • Document exactly which standards and versions you follow, so users can recover without you.
  • Commission independent review before real money is involved, and publish what was reviewed.

Watch for

"Proprietary" backup formats and clever shortcuts that nobody outside the team has examined.

SecurityTrustChecklist:S-01S-08S-14

From principles to a plan

Principles are only useful if they change what you build. Run the wizard to see which ones bite hardest for your combination of app type, custody model and audience, then use the checklist to confirm each one is reflected in the product.

Draft a blueprint Open the checklist

Guidance only. These principles are design advice drawn from long-standing practice. They are not a standard, not a certification and not a guarantee that any app is safe.