Simplicity on Liquid: Getting Started

The easiest way to deploy Simplicity smart contracts on Liquid testnet using the Web IDE. (Guide Not directly affiliated with Blockstream or Simplicity-Lang)

Developer Documentation -SimplicityHL Rust Docs -SimplicityHL Repo -SimplicityHL Code Examples

---

Table of Contents

1. Simplicity Introduction
2. Using the Simplicity Web IDE
3. Advanced: Command Line Guide
4. Next Steps

---

Simplicity Introduction

What is Simplicity?

Simplicity is a low-level, formally verifiable programming language designed specifically for blockchain smart contracts. Unlike traditional smart contract languages, Simplicity prioritizes:

• Formal Verification: Programs can be mathematically proven to be correct
• Static Analysis: Resource usage (CPU, memory) is known before execution
• Security: Minimal attack surface with clear, auditable semantics
• Efficiency: Optimized for blockchain validation

How Simplicity Fits into Liquid and Bitcoin

Current Status:

• Liquid Network: Simplicity is currently active on Liquid testnet and will soon be available on Liquid mainnet
• Bitcoin: Simplicity is compatible with Bitcoin but requires a soft fork activation (future)

Architecture:

• Simplicity programs are deployed as Taproot script paths (P2TR)
• Programs execute in a bit machine (not stack-based)
• Uses jets (optimized opcodes) for common operations like signature verification
• Compatible with BIP-340 Schnorr signatures and BIP-341 Taproot

SimplicityHL is the high-level language that compiles to Simplicity, similar to how Rust compiles to assembly language.

How Simplicity Works

1. Write: Developer writes a contract in SimplicityHL (.simf file)
2. Compile: SimplicityHL compiler (simc) converts it to Simplicity bytecode
   • Implementation: SimplicityHL/src/compile.rs - translates SimplicityHL AST to Simplicity combinators
3. Commit: The program's CMR (Commitment Merkle Root) is computed
   • Implementation: rust-simplicity/src/merkle/cmr.rs - Merkle root that commits to program structure
4. Address: A P2TR address is derived from the CMR
5. Fund: Bitcoin/Liquid is sent to the address
6. Spend: To spend, you provide:
   • The Simplicity program
   • Witness data (signatures, hash preimages, etc.)
   • The transaction spends the UTXO if the program evaluates to true

Execution Model:

Transaction → Simplicity VM → Program + Witness → Evaluate → Accept/Reject

The program has access to transaction data (sighash) through jets like jet::sig_all_hash().

Technical Details:

• Jets: Optimized native implementations of common operations. For example, jet::bip_0340_verify is implemented in rust-simplicity/simplicity-sys/depend/simplicity/jets-secp256k1.c (C) with Rust bindings
• Sighash: Computed in rust-simplicity/src/policy/sighash.rs using ElementsEnv::c_tx_env().sighash_all()
• Transaction Environment: Elements-specific environment built in rust-simplicity/simplicity-sys/depend/simplicity/elements/txEnv.c

---

Using the Simplicity Web IDE

This is the easiest way to get started with Simplicity on testnet! No installation required, works in your browser.

https://ide.simplicity-lang.org

Advantages:

• No installation required (browser-based)
• Automatic sighash computation
• Built-in key management
• Visual transaction builder
• Automatic witness encoding
• Direct broadcast to testnet
• Real-time error checking

Constants:

• Testnet Blockhash: a771da8e52ee6ad581ed1e9a99825e5b3b7992225534eaa2ae23244fe26ab1c1
• Internal Key: 0xf5919fa64ce45f8306849072b26c1bfdd2937e6b81774796ff372bd1eb5362d2

Source: https://github.com/BlockstreamResearch/simplicity-webide

---

Step-by-Step Guide

Step 1: Write Your Contract

Open https://ide.simplicity-lang.org in your browser. You'll see a default P2PK contract.

You can customize it or use example contracts like:

Simple contract

fn main() {
    ()
}

---

Step 2: Generate Address

Click the "Address" button. The address is copied to your clipboard.

Keep the Web IDE tab open!

---

Step 3: Fund the Address

1. Go to https://liquidtestnet.com/faucet
2. Paste your address
3. Click "Send assets"
4. Copy the transaction ID

---

Step 4: Look Up Funding Transaction

1. Go to https://blockstream.info/liquidtestnet
2. Paste the transaction ID
3. Wait for confirmation (~1 minute)
4. Note the vout and value (usually vout=1, value=100000)

---

Step 5: Enter UTXO Data

Go back to the Web IDE, scroll to "Transaction" section:

1. Txid: Paste funding transaction ID
2. Vout: Enter output index (e.g., 1)
3. Value: Enter amount (e.g., 100000)

Leave other fields as defaults.

---

Step 6: Generate Signature (if needed)

For contracts with signatures (like P2PK):

1. Click "Sig 0" button
2. Signature is copied to clipboard
3. Paste into your witness section

Update your code:

mod witness {
    const SIGNATURE: Signature = 0xf74b3ca574647f8595624b129324afa2...;
}

---

Step 7: Build Transaction

Click the "Transaction" button. The complete transaction hex is copied to clipboard.

---

Step 8: Broadcast

1. Go to https://blockstream.info/liquidtestnet/tx/push
2. Paste transaction hex
3. Click "Broadcast transaction"

Success! View your transaction on the explorer.

---

Advanced: Command Line Guide

For advanced users who want command-line control and access to the hal-simplicity, see:

CLI_GUIDE.md - Complete command-line deployment guide (Work in Progress)

---

Next Steps

a) Examples on GitHub

Explore more advanced contract examples:

SimplicityHL Examples Repository:

https://github.com/BlockstreamResearch/SimplicityHL/tree/master/examples

Example Contracts:

• p2pk.simf - Pay to public key (code)
• p2pkh.simf - Pay to public key hash (code)
• p2ms.simf - Pay to multisig (code)
• htlc.simf - Hash Time-Locked Contract (code)
• hodl_vault.simf - Time-locked vault (code)
• ctv.simf - CheckTemplateVerify covenant (code)
• escrow_with_delay.simf - Escrow with timeout (code)
• last_will.simf - Inheritance contract (code)
• sighash_all_anyonecanpay.simf - Custom sighash modes (code)
• non_interactive_fee_bump.simf - Fee bumping without cooperation (code)

Study the Code: Each example includes corresponding .wit (witness) files showing how to provide the required witness data. The examples demonstrate practical patterns you can adapt for your own contracts.

Simplicity Web IDE:

https://ide.simplicity-lang.org

• Visual contract development
• Built-in sighash computation
• Transaction builder
• Live on-chain deployment

b) What Can You Build?

Important: Simplicity is a stateless contracting system. Each contract execution is independent and doesn't maintain persistent state between transactions. This is by design for security and formal verification.

Despite being stateless, Simplicity enables powerful and interesting use cases:

Realistic Use Cases Today

1. Advanced Payment Conditions

• Multisignature: M-of-N signature requirements
• Timelocks: Absolute or relative time/height locks
• Hash Time-Locked Contracts (HTLCs): Lightning Network-style contracts
• Covenant Restrictions: Control where funds can be sent

2. Vaults and Security

• Delayed Withdrawals: Require waiting period for large withdrawals
• Emergency Recovery: Backup keys that activate after timelock
• Decaying Security: Multisig that reduces signatures needed over time

3. Inheritance and Estate Planning

• Time-Locked Inheritance: Funds unlock to heirs after inactivity period
• Multi-Beneficiary Distribution: Split funds between multiple heirs
• Conditional Release: Release funds based on multiple criteria

4. Atomic Swaps

• Cross-Asset Swaps: Trustless swaps between different assets on Liquid
• Cross-Chain Swaps: Atomic swaps with other UTXO chains
• Hash-Locked Contracts: Trustless exchange using hash preimages

5. Oracle Integration

• Signature Verification: Verify signed data from trusted oracles
• Price-Based Conditions: Execute only if price is within bounds
• Time-Stamped Data: Verify oracle data with timestamps

6. Covenant Applications

• Spending Restrictions: Limit where and how funds can move
• Output Templates: Enforce specific output patterns (similar to CTV)
• Fee Bumping: Non-interactive transaction fee increases

Advanced Possibilities

STARK Proof Verification: With OP_STARKVERIFY integration, Simplicity contracts can verify zero-knowledge proofs, enabling verification of off-chain computation and potentially bridging to other systems.

Payment Channels: Custom payment channel logic with more flexible conditions than standard Lightning.

Complex Multisig: Signature requirements that change based on amount, destination, or time.

The Potential

While stateless, Simplicity's formal verification capabilities and expressive power enable creating highly secure, auditable smart contracts for specific use cases. As the ecosystem develops, we expect to see interesting combinations of Simplicity contracts with off-chain computation and layer 2 systems.

c) How to Contribute

Report Issues

• GitHub Issues: Report bugs or request features
  • SimplicityHL: https://github.com/BlockstreamResearch/SimplicityHL/issues
  • hal-simplicity: https://github.com/apoelstra/hal/issues

Contribute Code

1. Fork a core repository Blockstream Research

Write Documentation

• Improve existing docs
• Write tutorials and guides
• Create example contracts
• Translate documentation

Join the Community

• Twitter: Follow @SimplicityLang for updates and discussions
• Telegram: Join the Simplicity Telegram group to connect with developers

Improve Tooling

• Better error messages
• Debugging tools
• Testing frameworks

---

License

This guide is released under CC0-1.0 (Public Domain).