Storing data on chain
Putting data on the chain: what it is good for, what permanence means for a consent screen, and the four things to settle before you write anything.
Data can be written into a transaction, beside a payment, where it stays permanently and publicly. Designing that is mostly designing consent: show what will be written, say it cannot be removed, and default to writing a hash.
What it is actually good for
Proving something existed. A hash written on chain proves a document existed before that block and has not changed since. The document itself never has to leave your server (BRC-220 covers notarisation).
Proving an order of events. Two records anchored in different blocks are provably in that order, without anybody's clock being trusted.
Carrying the receipt with the payment. An invoice, a licence or a delivery note, attached to the transaction that paid for it, so neither can be produced without the other.
Provenance. The history behind a token or a file, readable by anyone, with no index to go out of date (BRC-145).
The thing that has no equivalent
A hash on a public chain is an independent witness that costs a fraction of a penny. No counterparty, no notary, no subscription, and it keeps working if your company stops existing. That is the use case to reach for first.
Permanence is the whole design problem
What goes on chain cannot be edited, redacted or deleted: not by you, not by the user, not by a court order against your company.
That is the feature. It is also what a user will not understand from a button that says "Save to chain".
Do
Say "permanent and public" in the consent step, in those words, before anything is written.
Do
Show exactly what will be written. If it is a hash, say that the document stays on your server and only a fingerprint goes out.
Don't
Write anything identifying a person without an explicit, specific consent for that write. "Agreed to the terms" is not consent to publish somebody's name forever.
Don't
Offer a delete button for on-chain data. You can stop displaying it. That is not the same thing and the difference is the whole point.
Writing something about a person to the chain
- OK: a hash of something that cannot be guessed, with consent given for that specific write.
- Grey area: content the person wrote themselves, published with consent that says permanent and public in those words.
- Not OK: a name or personal details, published on the strength of a general agreement to the terms.
See Wallet privacy.
Hash it, or publish it?
This question decides the rest of the design.
| Hash only | Full content | |
|---|---|---|
| Proves | The content existed and has not changed | The same, plus anyone can read it |
| Reveals | Nothing, unless the content is short enough to guess | Everything, forever |
| Needs your server | Yes, to show the document | No |
| Right for | Contracts, records, anything personal | Public art, open records, published work |
Do
Default to the hash. Publishing is the irreversible option and should be the deliberate one.
Finding it again
Data on chain is not a database. There is no query, and a product does not scan the chain.
An overlay service indexes the part of the chain your application cares about and answers questions about it (BRC-22, BRC-136). A product that reads its data back needs one, its own or somebody else's.
Do
Treat the overlay as a dependency the user should know exists, the way you would treat any other service. See Interoperability.
Do
Make sure the data can still be verified without your overlay. The point of putting it on chain was independence from you.
Big files
Large content is split across transactions and reassembled. There are formats for carrying media this way (BRC-224).
Do
Show progress honestly for anything large, and say what happens if it stops halfway. A partially written file is a real state, not a theoretical one.
Don't
Put a large file on chain because you can. Cost is not the constraint; permanence is, and so is the user's understanding of it.
Timestamps
A block gives a time nobody controls. It is approximate, within an hour or so, and the guarantee is the order, not the clock reading (BRC-168).
Do
Say "anchored in block 951,204" alongside the human date. The block is the fact; the date is the convenience.
What to settle before you write anything
- Who is the audience? Nobody, your users, or the public forever.
- Hash or content? Default to hash.
- Whose data is it? If it is a person's, what exactly did they agree to?
- What happens when it is wrong? There is no edit. Plan the correction record now, because you will need one.
Open questions
- Do people understand "permanent and public" from those words alone, or only once they have seen what it means?
- Is a hash of personal data really safe to publish when the content is guessable? A birth date or a short answer can be confirmed by hashing the likely values.
- A hash only proves something while somebody still holds the original. Who keeps it, and for how long?
- What does a correction record look like to somebody who finds the original first?
- How does a person check the data once the overlay that indexed it has stopped running?
Related
- Wallet privacy: what a public chain reveals about a person
- Transactions: where the data sits in a transaction
- Holding tokens: provenance, read back from the chain
- Interoperability: overlays as dependencies
- Nodes and verification: checking data without your own overlay
Written from: BRC-145, BRC-168, BRC-220, BRC-224, BRC-22, BRC-136.
Checklist
The rules on this page, in a form you can work through.
10 rules