Technology primer
Enough of how BSV works to make good design decisions, in the order the pieces actually depend on each other.
You do not need to implement any of this. You do need enough of it to tell a good design decision from a plausible-sounding bad one, which is what this page is for. Most sections end with what it means for a screen.
The currency
One bitcoin divides into 100,000,000 satoshis. Satoshis are the real unit; "one bitcoin" is a convenient way of saying a hundred million of them.
On BSV fees are small enough that a payment of a few hundred satoshis is sensible, so the amounts your product shows will often be small numbers of satoshis.
For your screens: pick a unit and stay with it. Mixing "0.00000500 BSV" and "500 sats" in one interface asks users to do arithmetic to compare two things you wrote. See Amounts and units.
Transactions and outputs
There are no account balances. There are unspent outputs: discrete amounts, each locked to a condition, usually "whoever can sign with this key".
A transaction spends some outputs completely and creates new ones. Pay 300 satoshis from a 1,000 satoshi output and you get two new outputs: 300 to the recipient and about 700 back to yourself as change. A wallet's balance is the sum of the outputs it can spend.
For your screens: never show change as a separate payment in an activity list. One payment is one entry. See Coin selection.
Keys, and why there is no address to manage
A private key signs; the matching public key lets anyone verify the signature. An address is a short encoding of a public key.
Modern BSV wallets do not maintain lists of addresses. A wallet holds one master key and derives a fresh key for each payment from that key, the other party's public key, and a short string naming what the key is for (BRC-42). Both sides compute the same key from opposite directions; nobody else can.
For your screens: there is no address book of your own addresses, no "generate new address" button, and no address to show the user. Show the person or the app. See Payments.
The network and the ledger
Transactions are validated and ordered by miners, which on BSV are serious infrastructure rather than something a user runs. Valid transactions are gathered into blocks, and each block references the one before it, forming the blockchain.
Everything in it is public and permanent. Anyone can read any payment, now and in decades.
For your screens: anything written on chain cannot be unwritten. Encrypt anything personal before it goes there, and say so. See Wallet privacy.
Proof of work
To add a block, a miner must find a value that makes the block's hash meet a difficulty target. This takes real computation and real electricity, and finding it is rewarded with new coins and the fees in the block.
Rewriting history means redoing that work for every block since, against everyone else's ongoing work. The protection is economic: cheating costs more than it pays.
Blocks arrive about every ten minutes on average. On BSV the difficulty adjusts every block.
For your screens: "about ten minutes" is an average, not a promise. Never show a countdown to confirmation.
First seen, and why unconfirmed can be enough
The risk with an unconfirmed payment is a double spend: the payer sends the same coins twice and only one survives.
BSV miners follow a first-seen rule. The first valid version they see is the one they keep, and a conflicting later one is rejected. There is no replace-by-fee, so there is no mechanism for the payer to supersede what they already sent.
This is why BSV products can treat a payment as complete before it is mined, for ordinary amounts. It is a risk decision, scaled to the amount, not a guarantee. See Transactions.
For your screens: show "Paid" when the recipient accepts, and keep "Settling" for amounts large enough to justify waiting.
Verification without a node
Users do not run nodes. A wallet verifies a payment with block headers and a merkle proof: a short chain of hashes linking a transaction to the merkle root recorded in a header.
On BSV the proof usually arrives with the payment, packaged as BEEF along with the transaction's ancestors. The recipient can check the whole chain of spends back to a proven block without asking anyone.
For your screens: no node settings, no initial block download, no sync progress bar. See Nodes and verification.
Script, and what an output can require
The condition locking an output is a small program. It can require one signature, several, a secret, a time to have passed, or combinations. The Chronicle upgrade restored the remaining original opcodes, so the range is wide.
Two BSV specifics worth knowing before you design anything with them: there are no new pay-to-script-hash outputs, so a condition is visible from the moment it exists; and CHECKLOCKTIMEVERIFY and CHECKSEQUENCEVERIFY no longer act as checks, so a script that relies on them for a timelock enforces nothing. See Spending conditions.
What sits above the chain
Transactions stay on the base chain, because capacity grows and fees stay negligible. What sits above it is light: overlay services that track outputs relevant to one application or token type. They index; they do not hold the money.
For your screens: the wallet has no network state of its own to show: no connection to open, nothing to route, nothing to sync.
Hot and cold keys
A hot key is on a connected device: convenient, exposed. A cold key is kept offline: safer, slower to use.
Most people need both, which is the argument for separating an everyday wallet from savings. See Wallet setups and Private key management.
What this means for a screen
The primer is background, but a few of these facts change a design directly. The rule for when to say "Received" is on Why BSV is different.
Do
Verify with headers and a merkle proof rather than asking a server you trust. A wallet that can check its own money does not need to explain whose server it believes.
Do
Build time conditions with nLockTime and nSequence, and test that an early spend actually fails. CHECKLOCKTIMEVERIFY and CHECKSEQUENCEVERIFY run and enforce nothing here.
Don't
Design network states the wallet does not have: no connection setup, no routing errors, no sync progress bar. A BSV wallet hands payments to the recipient and verifies with headers, so none of these can occur.
Fee controls have nothing to act on either; see Transactions and outputs and Why BSV is different.
Where to read further
- The Bitcoin whitepaper (linked from the BSV wiki), which is nine pages and still the clearest description of the model
- The BSV wiki, for protocol detail
- The BRC standards, for the interfaces products are built on
- How it works, for the design consequences of all of it
Related
Written from: BSV wiki, Bitcoin whitepaper, BRC-9, BRC-42, BRC-62, BRC-100.
Checklist
The rules on this page, in a form you can work through.
3 rules