Wrong-network payments
Why a BSV address and a BTC legacy address are indistinguishable, what that costs a user, and the four defences in the order they are worth building.
A pasted address can send money to another network, because a BSV address and a BTC legacy address look identical. We recommend handles first, the network named at the point of paste and on the review screen, and a test payment for a first-time address.
The two addresses share a format. Both are base58, both start with 1, and both pass each other's validation. Neither the user nor your code can tell them apart by looking, because there is nothing to look at.
Money sent to the wrong one is usually gone. It is not stolen. It sits on another chain, at an address whose keys the recipient may not hold, and recovering it needs the other party's cooperation and technical ability.
Why no amount of validation fixes this
A checksum proves the address is well formed. It cannot prove which network it belongs to, because the format carries no network field. An address that validates perfectly can still be for the wrong chain. This is the one error in this guide that correct software cannot catch.
Where it happens
- A user copies an address from an exchange withdrawal page with the wrong network selected.
- A payee pastes the address their other wallet gave them.
- An address is reused from an old email, a note or a printed invoice, and nobody recorded which chain it was for.
- A support agent pastes an address on behalf of somebody.
All four are copy-paste. None involves a user doing anything they would recognise as risky.
The four defences
In the order they are worth building. The first removes the risk; the other three reduce it.
1. Do not use addresses
A handle resolves through its own infrastructure, so it cannot be a handle for another chain. A saved contact is one you have already paid successfully, so it cannot have changed network since.
Do
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.
See Paying by handle.
2. Say the network, loudly, at the point of paste
Do
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
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
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.
3. Make the review screen say it
Do
Put the network on the confirmation, beside the recipient, in the same weight as the amount.
Do
Say plainly what cannot be undone, before the button: "Sent to the wrong network, this usually cannot be recovered."
4. Test with a small amount
Do
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.
Afterwards
Somebody will do it anyway. What the product does next decides whether they have a bad day or leave.
Do
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
Promise recovery you cannot deliver. If it needs the other party's cooperation, say that is what it needs.
Helping after a wrong-network payment
- OK: explain what happened, give the transaction reference and the output, and say what recovery would need.
- Grey area: offer to contact the recipient or the exchange on the user's behalf, with no promise about the outcome.
- Not OK: promise the money back, or call it a failed transaction so the user goes looking for a refund.
For exchanges and anyone with a withdrawal screen
This is the riskiest screen of all. The user chooses a network from a list, and a mis-click cannot be undone.
Do
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.
Open questions
- Does a warning on every pasted address still get read after the tenth paste, or does it become noise?
- Above what amount is a test payment worth the extra step? The page leaves the threshold to you because nobody has measured it.
- Does labelling a field "BSV address" help when the mistake was made earlier, on the screen the address was copied from?
- How far should a support team go in helping somebody recover a payment that only the other party can return?
Related
- Paying by handle: the first defence, in detail
- Sending: where these defences sit in a send flow, in the daily spending wallet
- Errors and failed payments: failures that do fail
- Legacy compatibility: paying and receiving with plain addresses
- Address: what an address is, and what it does not carry
Written from: BRC-29, BRC-169.
Checklist
The rules on this page, in a form you can work through.
13 rules