Holding tokens
What a token is on BSV, how one reaches a wallet, and the four things a product has to show before somebody can trust what they are holding.
Holding tokens means showing somebody a thing they own that is not money: a ticket, a collectible, a credit. We recommend treating a token like a payment held in its own basket, and showing four things before anybody trades it: what it is, where it came from, whether it is the real one and what can be done with it.
A token is an output, owned the way a payment is owned and moved the way a payment is moved. That one fact decides most of the design. If you have drawn a wallet, you have most of the parts already.
A token is an output
Your wallet holds a specific output with a chain of history behind it. Nobody can change your balance by changing a contract. The only access an app has is the basket grant it asked for, and the user can revoke it.
What exists
Two families, and a product usually picks one.
1Sat Ordinals put the token on a single satoshi, with the content or the token data inscribed in the spending script (BRC-159, BRC-160). The family covers both one-of-a-kind items and fungible tokens. Its fungible form, BSV-21, is identified by a token ID rather than a ticker, so two issuers cannot collide (BRC-161, with validity proofs in BRC-176).
STAS, the other family, is stricter. More of the rules live in the script itself, which buys enforcement at the cost of flexibility.
Recommendation
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.
How a token reaches the wallet
Through the same connection the rest of your app uses. The wallet holds tokens in a basket: a named group of outputs kept apart from spending money (BRC-147 and BRC-163 define the profiles, BRC-165 the permissions).
That matters more than it sounds:
- A user's tokens cannot be spent as fees or swept into a payment by accident, because they are not in the spending pot.
- Your app asks for access to one basket, not to the wallet.
- The user can see what you were given and take it back.
See Permissions and allowances for designing the basket grant.
Don't
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.
The four things to show
What it is. A name and an image are the minimum, and neither is proof of anything. Both can be copied.
Where it came from. Every token has a chain of ownership back to its issue. This is the one thing a token can prove that a screenshot cannot. Show it.
Whether it is the real one. Two tokens can share a name and an image. The token ID distinguishes them, and the user will not read a token ID.
What can be done with it. Transferable, sellable, redeemable, or none of those. A user who cannot tell is one support ticket away.
Do
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
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
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.
Showing a token you cannot verify
- OK: show it with a plain "issuer not recognised" label and its provenance.
- Grey area: move it to a separate list of unrecognised tokens that the person has to open to see.
- Not OK: show it with the same name and image as a known token, and nothing to tell them apart.
Issuing
A product that mints tokens is asking a user to make something permanent.
Do
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
Treat the supply decision as final in the interface, because it is. A field labelled "Supply" with no warning is a trap.
Stablecoins
A stablecoin is a token whose issuer promises to redeem it at a fixed value. So the issuer matters more than the token: the user holds a promise, and the interface names whose promise it is.
Do
Name the issuer wherever the balance appears, not only at acquisition. "120 GBP, issued by Example Trust" is the honest form.
Don't
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.
What does not apply
| Pattern | Why it does not apply |
|---|---|
| Approve, then transfer | There is no allowance to grant a contract |
| Revoking a contract approval | There is no contract holding an approval. The app's basket grant is revoked in the wallet like any other |
| Gas settings for a mint | The fee is less than 1p and is not a decision |
| Bridges and wrapped versions | Tokens are native to the one chain |
See Glossary for the terms that do not apply here.
Open questions
- Which token family do the wallets your users already have support?
- Do people read a one-line provenance sentence, and how short can it get before it stops meaning anything?
- Who decides which issuers count as trusted for matching, and what should a wallet say about an issuer it has never seen?
- What should a wallet show for a token whose issuer, or the overlay service that tracks it, has stopped running?
- Does naming a stablecoin's issuer wherever the balance appears help people judge it, or become text they stop seeing?
Related
- Connected web app: a ticket bought and held as a token, on a whole site
- Permissions and allowances: designing the basket grant and revoking it
- Connecting a wallet: asking for one basket, not the wallet
- Transactions: outputs, and the chain of history behind a token
- Identity: issuers, and matching against ones people trust
- Storing data on chain: the other permanent thing a product writes
Written from: BRC-45, BRC-147, BRC-159, BRC-160, BRC-161, BRC-163, BRC-165, BRC-176, BRC-100.
Checklist
The rules on this page, in a form you can work through.
9 rules