--- name: bsv-on-chain-data description: "Design or implement putting data on the BSV chain: choosing between a hash and the full content, the consent step for something permanent and public, overlay services for finding it again, large files, and timestamps. Use when asked to 'notarise a document', 'timestamp a file', 'write data on chain', 'store a hash', 'attach a receipt to a payment', 'upload a file to BSV', or anything about data rather than value on chain." --- > Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md). # Write data on the BSV chain with consent **Scope:** Data on chain: what it is good for, the consent step, hash versus content, overlays, large files and timestamps. **Does NOT cover:** - Tokens: see [bsv-tokens](../bsv-tokens/SKILL.md) - Building the transaction: see [bsv-actions](../bsv-actions/SKILL.md) **Cross-references:** [bsv-actions](../bsv-actions/SKILL.md), [bsv-tokens](../bsv-tokens/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md). Block space is not scarce on BSV, so data can live beside the payment rather than in a database that points at it. That turns a storage decision into a consent decision: what goes on chain cannot be edited, redacted or deleted by anybody, including you. A hash on a public chain is a cheap, independent witness, and it is the use case to reach for first. ## ALWAYS - Say "permanent and public" in the consent step, in those words, before anything is written. _([costs trust](https://www.bitcoinsv.design/guide/rule/f3791442cf/))_ - 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. _([costs trust](https://www.bitcoinsv.design/guide/rule/5ec4966080/))_ - Default to the hash. Publishing is the irreversible option and should be the deliberate one. _([costs trust](https://www.bitcoinsv.design/guide/rule/f21b5fcb40/))_ - Make sure the data can still be verified without your overlay. The point of putting it on chain was independence from you. _([costs trust](https://www.bitcoinsv.design/guide/rule/7162ccb4f6/))_ - Treat the overlay as a dependency the user should know exists, the way you would treat any other service. See Interoperability. _([rule](https://www.bitcoinsv.design/guide/rule/3b81bf9bb5/))_ - 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. _([rule](https://www.bitcoinsv.design/guide/rule/335014706c/))_ - Say "anchored in block 951,204" alongside the human date. The block is the fact; the date is the convenience. _([rule](https://www.bitcoinsv.design/guide/rule/fec32573be/))_ ## NEVER - 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. _([costs money](https://www.bitcoinsv.design/guide/rule/d18ac5c2f8/))_ - 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. _([costs trust](https://www.bitcoinsv.design/guide/rule/e608a8eef7/))_ - 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. _([rule](https://www.bitcoinsv.design/guide/rule/11cb102c91/))_ ## Patterns _Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._ ### 1. Decide: hash, or content? **When:** Before designing anything else. **How:** 1. A hash proves the content existed and has not changed, reveals nothing, and needs your server to show the document. Right for contracts, records and anything personal. 2. Full content proves the same and lets anyone read it, forever, without you. Right for public art, open records and published work. 3. Default to the hash. Publishing is the irreversible option and should be the deliberate one. 4. Settle four things first: who the audience is, hash or content, whose data it is and what they agreed to, and what the correction record will be when something is wrong. _Source: [Storing data on chain](https://www.bitcoinsv.design/guide/patterns/storing-data-on-chain/)_ ### 2. Ask for consent to something permanent **When:** Immediately before any write. **How:** 1. Say "permanent and public" in the consent step, in those words, before anything is written. 2. Show exactly what will be written. If it is a hash, say the document stays on your server and only a fingerprint goes out. 3. Never write anything identifying a person without an explicit, specific consent for that write. Agreeing to the terms is not consent to publish somebody's name forever. 4. Write it as an output of a `createAction` whose locking script is an unspendable data script (`OP_FALSE OP_RETURN` followed by the data) with 0 satoshis. _Source: [Storing data on chain](https://www.bitcoinsv.design/guide/patterns/storing-data-on-chain/)_ ### 3. Find it again, and show when **When:** Reading back what was written, or showing a timestamp. **How:** 1. The chain is not a database. An overlay service indexes the subset your app cares about (BRC-22); treat it as a dependency the user should know exists. 2. Make sure the data can still be verified without your overlay. Independence from you was the point. 3. Say "anchored in block 943,816" beside the human date. The block is the fact; the date is the convenience. 4. For large files, split across transactions (BRC-224), show progress honestly, and say what happens if it stops halfway. **Fallback:** The user wants it gone: you can stop displaying it, and say that is what you did. Never present that as deletion. _Source: [Storing data on chain](https://www.bitcoinsv.design/guide/patterns/storing-data-on-chain/)_ ## All the rules `references/rules.md`: 10 rules from 1 page, 6 of them costly, most costly first. Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json ## Implementation resources - **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk. - **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app. - **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number. --- _Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._