Simplicity copy guide
Blockchain programming language for high-assurance smart contracts; Bitcoin Script alternative.
- Recently rebranded (SimplicityHL; Simfony retired); slim package on purpose.
- "Powered by Simplicity" badge rejected (open source, no ROI); own marketing track instead.
- First Simplicity-powered product: Blockstream Lend (H2, legal-gated).
Golden rules
Get these right and most copy takes care of itself.
- Never "deterministic": the word is not in the paper; write "formally verifiable."
- SimplicityHL, one word; "Simfony" is retired.
- Never sole-credit Blockstream: name the researchers; Bitcoin protocol work is collaborative.
- Bitcoin steps are proposals: "Prove it on Liquid. Then bring it to Bitcoin." Never promise integration.
- Load quantum-content-rules.md before any SHRINCS, SHRIMPS, or signature-size claim; always pair component with system size.
Who you're writing for
Meet the reader before touching the rules.
Write for Bitcoin and Lightning devs, sidechain builders, and smart-contract researchers: assume they read code, explain why over what.
Attribute to named researchers, never sole-credit Blockstream for collaborative work; cite GitHub repos and commits as source of truth.
Route to @blksresearch: research content posts there; send the community to t.me/simplicity_community and Tuesday office hours.
Names
The product names and exactly how to write them.
Write Simplicity capitalized: the low-level, formally-verifiable smart contract language, never the high-level interface.
Write SimplicityHL: one word, caps S/H/L; never 'Simfony' (retired Jul 2025) or 'simplicity HL'.
Write BitMachine: one word, capital B and M, Simplicity's execution model.
Write simc lowercase (say 'sim-see'), the SimplicityHL compiler; hal-simplicity lowercase, hyphenated.
Write Simplex (smplx) capitalized, never lowercase; the early-stage dev framework for Simplicity contracts.
Write Simplicity Unchained for the oracle-based interpreter running Simplicity on chains without native support; in development.
Say this, not that
The usage dictionary. When in doubt, search it.
| Topic | Write | Never write | Why |
|---|---|---|---|
| combinator | combinator | function · opcode | one of Simplicity's nine primitive operators |
| jet | jet | built-in function | pre-compiled native implementation of a common expression |
| Merkle roots | Commitment / Identity / Annotated Merkle Root, spelled out on first use | bare acronyms on first use | |
| SHRIMPS | SHRIMPS, all caps; the multi-device extension (1,024 devices) | citing an eprint for it | load quantum-content-rules.md first |
| SHRINCS | SHRINCS, all caps, spelled out first use; eprint 2025/2203 (Kudinov, Nick) | writing sizes without quantum-content-rules.md loaded | load the rules file first |
| The high-level language | SimplicityHL, one word, caps S/H/L | simplicity HL | Rust-like, compiles to Simplicity |
| Completeness framing | finitiary completeness: any finite computation | apologizing for not-Turing-complete | the selling point |
| Verification claims | formally verifiable | deterministic | not in the paper; undefined terms for effect are banned |
| The old name | SimplicityHL | Simfony | retired July 2025 |
| Cost unit | milliWU; cost known before execution | "gas" | static analysis; no gas concept |
| PSET | Partially Signed Elements Transaction | Bitcoin's PSBT analog | |
| The compile target | Simplicity bytecode (the Rust-to-assembly analogy) | implying people write raw Simplicity | nobody writes raw Simplicity |
| Witness vs parameter | witness = runtime spend data · parameter = compile-time | swapping the two | witness::NAME · param::NAME |
Voice & tone
How the copy sounds, and where the register switches.
Write the most formal developer register: careful, precise language about safety guarantees, no hand-waving.
Sound like a maintainer writing release notes: assume the reader reads code, explain why over what.
Never use marketing language, simplify into inaccuracy, omit version numbers, or promise unshipped features.
Never use undefined terms for effect: don't call Simplicity 'deterministic'; write 'formally verifiable'.
Format terms and commands as inline code (jet::bip_0340_verify(), .simf, .wit); annotate versions inline; link GitHub.
Write file extensions lowercase with a dot: .simf (programs), .wit (witness data), .args (compile-time params).
Set headings Title Case (H1-H4); hold the technical, authoritative, precise register, no hype language.
Positioning
What to lead with, what to always pair, what never to claim.
These points are an amalgamation of what has been learned so far, from product docs, launches, and reviewer feedback. They are not definitive or authoritative positioning from anyone. Product marketing still needs to clearly define positioning for this product, which will happen in a follow-up.
Frame as a parallel replacement built on formal mathematical foundations, never an incremental Bitcoin Script upgrade.
Contrast with Solidity/EVM: no unbounded loops or global state; every program terminates; cost known pre-execution; UTXO-based.
Lead with formal verification and quantum resistance; thought leadership, zero branded demand. Load quantum-content-rules.md first.
Frame Bitcoin steps as proposals: 'Prove it on Liquid. Then bring it to Bitcoin.' Never promise testnet or mainnet integration.
Frame the 'last soft fork' thesis (Lewe) as an argument, not a deliverable; Poelstra: any finite computation runs in Simplicity.
Always pair component with system size: a 324-byte SHRINCS sig sits in a ~38 KB Simplicity tx. Load quantum-content-rules.md first.
Never claim sole credit: Blockstream Research works with external co-authors; frame Bitcoin protocol work as collaborative, not owned.
Claims
What a page or post may cite. Confirm, correct, or kill each row; an unconfirmed claim does not ship.
| Claim | As of | Status |
|---|---|---|
| Any finite computation can run in Simplicity (Poelstra) | current docs | approved |
| A 324-byte SHRINCS signature sits in a ~38 KB Simplicity transaction; always pair the two | eprint 2025/2203 | approved |
Open questions
Unresolved tensions for review. Don't resolve these in copy; flag them.
- No Simplicity boilerplate exists in boilerplates.md; a rebrand should author one.
- products-overview.md has no Simplicity entry despite coverage in product-brands.md and terminology.md.
- 'Simfony' is missing from the project CLAUDE.md retired-terms grep list, and old blog posts still use it with no redirect or update strategy.
- Typography conflict: product-brands.md says Carbon/Ubuntu for Simplicity graphics; corporate system mandates Rigid Square/Inter. No doc says which wins.
- Developer persona is the least documented internally: suggested content areas exist, guidelines unfilled.
- No lockup guidance: never written 'Blockstream Simplicity'; repos live under BlockstreamResearch. Make explicit in new guidelines.
Notepad
Scribble anything: loose thoughts, questions, things that don't fit a pin or a highlight. Saves automatically with the review feedback.