Address
What a BSV address is, why users should rarely see one, and the rules for showing one when they must.
Paint texture by Geordanna Cordero on Unsplash
An address is a short identifier that money can be paid to. On BSV it is machine plumbing, and most users should never meet one.
The short version
There is one address format in practice. Users share a handle instead. An address appears on screen only when there is nothing else to show.
One format
BSV uses the original format: a base58 string of 26 to 35 characters, beginning with 1, case sensitive.
Example: 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
An address that starts with anything other than 1 is not one a BSV wallet should create. One starting with 3 is a script address; none have been created since 2020.
Sharing one identifier without reusing an on-chain address is what handles and the peer-to-peer payment flow do: the identifier stays the same, and every payment goes to a fresh output.
Why users should not see one
A handle looks like anna@example.com. It can be read aloud, written on a sign, and typed from memory, and behind it the payer's wallet and the payee's wallet agree a fresh output for every payment.
Do
Make the handle the thing a user shares. Put the address behind a "Show address" control for the cases that need one.
Don't
Lead a receive screen with an address. It is the least usable identifier you have and it is almost never the one the payer needs.
An address is still the right answer in three cases: paying software that only understands addresses, printing something that must work without a server, and moving funds out of an old wallet.
Change
The address a wallet sends change to is its own, and is never shown. See Activity.
Don't
Show change as a transaction, a second recipient, or a separate line in a balance. It is the most common way to make a wallet look wrong when it is right.
Showing one properly
Formatting makes an address comparable character by character.
Payments are final, so an address review screen exists to let somebody check the address.
Do
Use a monospace face whose characters are clearly distinguishable, such as Source Code Pro or Fira Mono. Base58 excludes 0, O, I and l for this reason, so do not fight it with an ambiguous font.
Do
Group it into chunks of four characters, and offer a large, expanded view. People compare in chunks and cannot compare a 34-character run.
Don't
Shorten an address with an ellipsis where somebody is checking it. Middle elision is acceptable in a list row, never on a confirmation.
Validation
Confirmation that an address is valid can be quiet.
An invalid one should be loud, and sending should be impossible.
The format carries a checksum, so a typed or mistyped address can be rejected before any money moves.
Do
Validate as it is entered, and disable sending until it passes.
What validation cannot do
A valid address is not the intended address. A checksum catches typos, not a swapped clipboard or a wrong contact. That is why the recipient, not the address, belongs at the top of a review screen.
It also cannot tell which network an address belongs to. Some other networks use the same format, and money sent to one of them is usually gone. See Wrong-network payments.
Commonly misunderstood: an address starting with 1 is a BSV address
A BTC legacy address also starts with 1, uses the same base58 format and passes the same checksum. Validation accepts it, and nothing on screen tells the two apart. Name the network beside the address field, and prefer a handle.
Reuse
Where reuse is possible, explain the cost and let the user decide.
Paying twice to the same address links the two payments permanently, to anyone looking. The chain is public and nothing is ever deleted.
Do
Derive a fresh output for every payment. The peer-to-peer flow does this without the user knowing, which is the right amount of knowing.
Do
Where a user deliberately publishes a fixed address, such as a donation page, say what it costs them in a sentence rather than preventing it.
See Wallet privacy.
Related
Written from: BRC-29, BRC-42, BRC-169.
Checklist
The rules on this page, in a form you can work through.
9 rules