# Simplicity
> A typed, combinator-based, smart contract language for Bitcoin-like blockchains.
## Get Started
### Try it in your browser
This page compiles and runs SimplicityHL directly in your browser, using
the same compiler and Simplicity bit machine used on-chain. Nothing
you type here is sent to a server or to the blockchain. The compiler
is downloaded on the first Run; after that, each Run is immediate.
## Assertions
A SimplicityHL program doesn't return a value. It either holds or it doesn't. A
transaction spending a SimplicityHL-locked output is valid exactly when the program
holds.
```simplicityhl,run title="Assertions"
fn main() {
let (_, sum): (bool, u32) = jet::add_32(2, 2);
assert!(jet::eq_32(sum, 4));
}
```
Changing the last argument from `4` to `5` (or, indeed, changing any
of the integer values), and running again produces a program that still
compiles. But the program's logic no longer confirms the transaction;
on-chain, this is a rejected spend, not a runtime error.
## Arithmetic overflow
Addition that can overflow returns the overflow condition as an explicit value,
rather than wrapping silently or raising an error.
```simplicityhl,run title="Arithmetic overflow"
fn main() {
let (overflowed, sum): (bool, u32) = jet::add_32(4000000000, 1000000000);
let overflowed: bool = dbg!(overflowed);
let sum: u32 = dbg!(sum);
assert!(overflowed);
}
```
Running this prints `overflowed: true` and `sum: 705032704`, the wrapped result of
4000000000 + 1000000000. Changing the first argument to `2000000000` removes the
overflow: `overflowed` becomes `false`, and the final assertion, which requires it to be
`true`, fails. The addition still succeeds, but now the assertion fails.
## Transaction introspection
A SimplicityHL program runs in the context of a specific transaction input, and can
inspect that transaction directly: which input it is, how many inputs the transaction
has, and other properties. These tools can be used to build vaults and covenants, by
constraining the outputs of transaction itself to send assets back to the same program.
```simplicityhl,run title="Transaction introspection"
fn main() {
let index: u32 = dbg!(jet::current_index());
let inputs: u32 = dbg!(jet::num_inputs());
assert!(jet::lt_32(index, inputs));
}
```
This runs against a placeholder transaction with a single input, so it prints
`jet::current_index(): 0` and `jet::num_inputs(): 1`. Checked against a real
transaction, these jets return the transaction's actual values; the Quickstart linked
below does this against a live Liquid testnet transaction.
## Where to go next
- **Quickstart:** the [Quickstart tutorial](quickstart.md) compiles a similar contract, funds it, and spends it in a transaction on [Liquid](../glossary.md#liquid) testnet.
- **Use cases:** [applications built with Simplicity](../use-cases/index.md).
### Quickstart
# Simplicity Quickstart
Try a real smart contract transaction on [Liquid](../glossary.md#liquid) testnet with the `last_will.simf` contract.
You'll perform a [Liquid](../glossary.md#liquid) testnet transaction using the "last will" [covenant](../glossary.md#covenant). This allows an inheritor to claim funds after a delay if their benefactor goes silent, while the benefactor can postpone that indefinitely just by checking in.
??? note "Want to try it online with no download?"
You can also try an equivalent quickstart (and other Simplicity exercises and demos) online in your browser using the [Simplicity Codespace](https://github.com/codespaces/new/blockstream/simplicity-codespace).
## The contract
This [smart contract](../glossary.md#smart-contract), written in [SimplicityHL](../glossary.md#simplicityhl), is called `last_will.simf`. It implements a covenant with an inheritance-after-timeout pattern, using three keys and three spending paths:
* **Hot key**: the benefactor can "check in" at any time. Checking in re-creates the exact same contract at a new [UTXO](../glossary.md#utxo) (a [recursive covenant](../glossary.md#recursive-covenant)) and resets the inheritor's timelock. This is the key the benefactor is expected to use day-to-day.
* **Cold key**: the benefactor can also break out of the covenant entirely and move the funds anywhere, no matter what the timelock says. This key would typically be kept offline, since it's only needed in unusual circumstances. This quickstart doesn't exercise this path.
* **Inheritor key**: after a [timelock](../glossary.md#timelock) has elapsed, the inheritor can claim everything.
```mermaid
%%{init: {'flowchart': {'nodeSpacing': 150, 'rankSpacing': 100}}}%%
flowchart TD
F[Liquid testnet faucet] -- Funds --> C[Contract]
C -- "Hot key: check in (repeat any number of times)" --> C
C -- "Inheritor key: after timelock" --> H[Heir's wallet]
C -. "Cold key: any time" .-> O[Owner's own wallet]
```
The code (from the online SimplicityHL examples) looks like this:
```simplicityhl
fn checksig(pk: Pubkey, sig: Signature) {
let msg: u256 = jet::sig_all_hash();
jet::bip_0340_verify((pk, msg), sig);
}
fn enforce_relative_distance(min_distance: Distance) {
// Transaction version must be at least 2 for BIP68 relative locktime to apply.
assert!(jet::le_32(2, jet::version()));
// Fetch and parse the current input's own sequence number.
let actual_data: Either = unwrap(jet::parse_sequence(jet::current_sequence()));
let actual_distance: Distance = unwrap_left::(actual_data);
assert!(jet::le_16(min_distance, actual_distance));
}
// Enforce the covenant to repeat in the first output.
//
// Elements has explicit fee outputs, so enforce a fee output in the second output.
// Disallow further outputs.
fn recursive_covenant() {
assert!(jet::eq_32(jet::num_outputs(), 2));
let this_script_hash: u256 = jet::current_script_hash();
let output_script_hash: u256 = unwrap(jet::output_script_hash(0));
assert!(jet::eq_256(this_script_hash, output_script_hash));
assert!(unwrap(jet::output_is_fee(1)));
}
fn inherit_spend(inheritor_sig: Signature) {
let min_distance: Distance = param::MIN_DISTANCE_BLOCKS;
enforce_relative_distance(min_distance);
let inheritor_pk: Pubkey = param::INHERITOR_PUBLIC_KEY;
checksig(inheritor_pk, inheritor_sig);
}
fn cold_spend(cold_sig: Signature) {
let cold_pk: Pubkey = param::COLD_PUBLIC_KEY;
checksig(cold_pk, cold_sig);
}
fn refresh_spend(hot_sig: Signature) {
let hot_pk: Pubkey = param::HOT_PUBLIC_KEY;
checksig(hot_pk, hot_sig);
recursive_covenant();
}
enum Action {
Inherit(Signature),
ColdSpend(Signature),
HotSpend(Signature),
}
fn main() {
match witness::ACTION {
Action::Inherit(sig: Signature) => inherit_spend(sig),
Action::ColdSpend(sig: Signature) => cold_spend(sig),
Action::HotSpend(sig: Signature) => refresh_spend(sig),
}
}
```
You'll play the roles both of the benefactor and the inheritor, using two different [private keys](../glossary.md#private-key). In a real deployment, these keys would belong to different people. The benefactor would also have a "cold key", most likely kept offline.
Please choose your preferred language environment immediately below. You can also run any version [online, with no download](https://github.com/codespaces/new/blockstream/simplicity-codespace).
=== "Rust"
## Rust quickstart
Before beginning, please make sure you have Rust installed.
## Demo walkthrough
!!! tip "Need help?"
If you get stuck at any point in this tutorial, ask in the [Simplicity Community](https://community.simplicity-lang.org/) forum. Questions posted there are public, so the answer can help later readers too.
### 1. Clone the walkthrough git repository
```bash
git clone https://github.com/BlockstreamResearch/simplicity-demo
cd simplicity-demo/quickstart-cli
```
### 2. Create a random seed for the demo's keypairs
Run this command to create a random seed value. (This will be used to derive keypairs used in the demo.)
```bash
openssl rand -hex 32
```
Create an `.env.demo` file in the `quickstart-cli` directory, with a single line `SEED_HEX=` followed by your random seed value from the previous command.
Every `last-will` command below derives its keys from this one seed, so you don't need to manage three separate seeds to play all three roles yourself. In a real deployment, these would be three unrelated seeds held on different devices.
### 3. Compile the last-will contract
```bash
cargo run last-will compile-to-testnet-address -v
```
This derives all three keypairs from the seed, substitutes their public keys (and the default `--min-distance-blocks 3`) into `last_will.simf`, and compiles it. The output will look something like this:
```
# Deriving keypairs from seed.
# Compiling SimplicityHL program source_simf/last_will.simf.
SimplicityHL source code:
fn checksig(pk: Pubkey, sig: Signature) {
...
}
...
Parameter arguments (compile-time):
mod param {
const COLD_PUBLIC_KEY: u256 = 0x0804...;
const HOT_PUBLIC_KEY: u256 = 0x4f35...;
const INHERITOR_PUBLIC_KEY: u256 = 0x55f1...;
const MIN_DISTANCE_BLOCKS: u16 = 3;
}
# Deriving Liquid Testnet address.
---> Inheritor public key: 55f1cd1f0ebdd80e86080ab56c02fb3f65c540f880f4e5e48bc1800e74c13606
---> Cold public key: 08040427cb5728a184a886897f0faed50353919e24b0571de75c45ef799821be
---> Hot public key: 4f355bdcb7cc0af728ef3cceb9615d90684bb5b2ca5f859ab0f0b704075871aa
Contract's Liquid Testnet address: tex1p6df7ur00f9hc3k3y2g9ls6tl963sg59vm3pe9urytupxkhlpyrestuh6nm
```
(Without `-v`, you'll just see the address on the last line.) `MIN_DISTANCE_BLOCKS` defaults to 3 purely so this quickstart finishes in a few minutes, as Liquid Network blocks are created once per minute.
### 4. Fund the contract on Liquid testnet
```bash
cargo run last-will fund-from-faucet --address tex1p6df7ur00f9hc3k3y2g9ls6tl963sg59vm3pe9urytupxkhlpyrestuh6nm
```
**(Substitute the address from your own Step 3 output.)** This funds the contract with 100000 sats of tLBTC, and prints the funding transaction's ID; you'll need it for the next step. Wait for it to confirm (check the Explorer) before continuing, since a relative timelock's clock starts at the confirming block, not at broadcast time.
### 5. Check in with the hot key
This is the transaction the benefactor is expected to send periodically: it spends the current UTXO straight back to the *same contract address*, minus a fee, signed with the hot key. Producing this transaction is what resets the inheritor's timelock.
```bash
cargo run last-will prove-alive --utxo :0 --fee-sats 100 --broadcast
```
Replace `` with the transaction ID from Step 4. This derives all three keypairs again (needed to recompile the identical contract and re-derive its address), builds a transaction paying the contract's balance minus the fee back to itself, signs it with the hot key, builds the `Action::HotSpend` [witness](../glossary.md#witness), and (because `--broadcast` is set) submits it and prints the resulting txid.
??? "What's happening here?"
Leave off `--broadcast` and the command prints the finalized raw transaction hex instead of submitting it.
Wait for this transaction to confirm too, and note the block height it confirms at (visible on the Explorer): call it `HOT_CONFIRM_HEIGHT`. The inheritor's timelock is satisfied starting at block `HOT_CONFIRM_HEIGHT + 3` (or whatever `--min-distance-blocks` you used).
### 6. Try to inherit early (should fail)
With the benefactor apparently still active, the inheritor shouldn't be able to claim anything yet:
```bash
cargo run last-will spend-as-inheritor \
--utxo :0 \
--to-address tex1q9hgs7pj8etd92rw5qz3dymvujffxzylmj6a28h \
--fee-sats 100 \
--broadcast
```
Replace `` with the txid from Step 5. This derives the keys, builds a transaction spending the hot-spend UTXO to the given destination, declares a relative-locktime distance of `--min-distance-blocks` (3 by default) on the input, signs with the inheritor's key, and builds the `Action::Inherit` witness, all of which succeeds locally, since the contract's own check only compares against the *declared* distance. The broadcast, though, should fail with something like `non-BIP68-final`: the node independently checks how many blocks have *actually* passed since `` confirmed, and it's still close to zero.
This is the same split explained on the [Timelocks](../documentation/timelocks.md#timelock-enforcement-mechanisms) page: Simplicity checks "does this transaction's declared `sequence` satisfy my rule?"; blockchain consensus separately checks "has enough real time actually passed to accept this `sequence`?" Both conditions must be satisfied.
### 7. Wait, then inherit for real
Wait until the chain tip reaches `HOT_CONFIRM_HEIGHT + 3` (watch the Explorer, or poll it the way the [bash/CLI tab](#__tabbed_1_2) above does). At a block a minute on Liquid testnet, this should take about three minutes.
Then run the *identical* command from Step 6 again:
```bash
cargo run last-will spend-as-inheritor \
--utxo :0 \
--to-address tex1q9hgs7pj8etd92rw5qz3dymvujffxzylmj6a28h \
--fee-sats 100 \
--broadcast
```
This time it should succeed, printing a txid. You can view the completed transaction on the Explorer.
### Congratulations
You've walked a single contract through all three roles of a realistic covenant: funding it, proving activity to keep it alive, watching the network itself enforce a timelock the contract applied, and finally exercising the fallback path once that timelock had elapsed.
??? "See more technical details"
All four `last-will` subcommands support the `-v` option for verbose output, including the full compiled SimplicityHL source and parameter/witness values.
#### Next steps
* Once you're building something real rather than following a tutorial, [Simplex](https://github.com/BlockstreamResearch/smplx) handles project scaffolding, dependencies, and test suites for larger SimplicityHL projects.
* Read more about how relative and absolute timelocks work, and why they can only enforce *minimum* times, in [Timelocks](../documentation/timelocks.md).
* Read more about state and recursive covenants in [Covenants & State Management](../documentation/state.md).
* Try the same story in the [bash/CLI](#__tabbed_1_2) tab above.
* See more example contracts demonstrating other SimplicityHL language features.
=== "bash/CLI"
## bash/CLI quickstart
Before beginning, please make sure you have installed the toolchain applications (`simc` and `hal-simplicity`). You'll also need `curl` and `jq`.
??? note "Want to skip typing individual commands?"
A complete script that runs every step below automatically is available at last-will-demo.sh. Download it and run `bash last-will-demo.sh`. The walkthrough below explains what it's doing, step by step.
## Demo walkthrough
!!! tip "Need help?"
If you get stuck at any point in this tutorial, ask in the [Simplicity Community](https://community.simplicity-lang.org/) forum. Questions posted there are public, so the answer can help later readers too.
### 1. Save the contract
Save the contract above as `last_will.simf`.
### 2. Set up parameters
```bash
INTERNAL_KEY="50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0"
PRIVKEY_INHERITOR="0000000000000000000000000000000000000000000000000000000000000001"
PRIVKEY_COLD="0000000000000000000000000000000000000000000000000000000000000002"
PRIVKEY_HOT="0000000000000000000000000000000000000000000000000000000000000003"
INHERITOR_PUBLIC_KEY="0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798"
COLD_PUBLIC_KEY="0xc6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5"
HOT_PUBLIC_KEY="0xf9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9"
MIN_DISTANCE_BLOCKS=3
DESTINATION_ADDRESS=tex1q9hgs7pj8etd92rw5qz3dymvujffxzylmj6a28h
```
`INTERNAL_KEY` is the standard BIP-0341 unspendable [internal key](../glossary.md#internal-key), and the private keys are intentionally the small integers 1, 2, and 3. In a real contract these would be long random numbers, generated and held separately by each party. `DESTINATION_ADDRESS` is where the inheritor's claim will send funds; it defaults to a Liquid testnet faucet return address so nothing is wasted.
`MIN_DISTANCE_BLOCKS` is set to 3 purely so this quickstart finishes in a few minutes. [Liquid testnet blocks land once a minute](../documentation/timelocks.md#timelock-measurement-units), so you'll only have to wait three minutes in order to inherit the contract's funds. A longer, more realistic period can be achieved by raising this number, up to a point. `Distance` is capped at 65535, which at one block a minute is only about 45 days. A real deployment wanting something like a 180-day check-in period would need to use [a different timelock enforcement method](../documentation/timelocks.md#relative-timelock-in-simplicityhl) instead.
Now write out the `.args` file substituting these values into the contract's parameters:
```bash
cat > last_will.args << EOF
{
"INHERITOR_PUBLIC_KEY": "$INHERITOR_PUBLIC_KEY",
"COLD_PUBLIC_KEY": "$COLD_PUBLIC_KEY",
"HOT_PUBLIC_KEY": "$HOT_PUBLIC_KEY",
"MIN_DISTANCE_BLOCKS": "$MIN_DISTANCE_BLOCKS"
}
EOF
```
### 3. Compile and fund the contract
Check the result of compiling the contract with the parameters from the prior step:
```bash
simc -Z enums last_will.simf -a last_will.args
```
(This contract uses SimplicityHL's `enum` feature, which is still experimental. Compiling it requires passing `-Z enums` to `simc`.)
Now derive the contract's address and compute its [CMR](../glossary.md#cmr), which you'll need in later steps to attach the program to a [PSET](../glossary.md#pset):
```bash
COMPILED_PROGRAM=$(simc -Z enums last_will.simf -a last_will.args --json | jq -r .program)
CMR=$(hal-simplicity simplicity info "$COMPILED_PROGRAM" | jq -r .cmr)
CONTRACT_ADDRESS=$(hal-simplicity simplicity info "$COMPILED_PROGRAM" | jq -r .liquid_testnet_address_unconf)
```
Fund it from the Liquid testnet faucet, which provides free tLBTC assets for testing and experimentation:
```bash
FAUCET_TXID=$(curl "https://liquidtestnet.com/api/faucet?address=$CONTRACT_ADDRESS&action=lbtc" 2>/dev/null | jq -r .txid)
```
Wait for this transaction to confirm before continuing. You can check the Explorer, or `curl https://blockstream.info/liquidtestnet/api/tx/$FAUCET_TXID/status` until it reports `"confirmed": true`. This matters here specifically because a relative timelock's clock starts at the confirming block, not at broadcast time, so the steps below need this input to have actually landed in a block.
### 4. Check in with the hot key
This is the transaction the benefactor is expected to send periodically: it spends the current UTXO straight back to the *same contract address*, minus a [fee](../glossary.md#fee), signed with the hot key. Producing this transaction is what resets the inheritor's timelock. The covenant doesn't track a countdown anywhere; it just requires this specific action to keep happening, repeatedly creating a fresh copy of the same covenant.
First, fetch the details of the UTXO you're about to spend. The Explorer API reports its value in satoshis, but `hal-simplicity` expects an amount in LBTC, so the last three lines convert it:
```bash
curl https://liquid.network/liquidtestnet/api/tx/$FAUCET_TXID > input-tx.json
HEX=$(jq -r '.vout[0].scriptpubkey' < input-tx.json)
ASSET=$(jq -r '.vout[0].asset' < input-tx.json)
SATS=$(jq -r '.vout[0].value' < input-tx.json)
WHOLE=$(( SATS / 100000000 ))
REMAINDER=$(( SATS % 100000000 ))
VALUE=$(printf '%d.%08d' "$WHOLE" "$REMAINDER")
```
There are 100,000,000 satoshis in one LBTC. Dividing by this quantity gives the whole number of LBTC, with the remainder being the number of satoshis left over. `printf` joins the two with `%08d`, which pads the remainder to the eight decimal places an LBTC amount always carries, so 99900 satoshis becomes `0.00099900`. These calculations are performed in whole numbers, keeping the result exact down to the individual satoshi.
Build a [PSET](../glossary.md#pset) with two [outputs](../glossary.md#output): the refreshed contract, and an explicit fee. (The presence of these two outputs is what `recursive_covenant()` checks for above; the contract will reject anything else.)
```bash
PSET=$(hal-simplicity simplicity pset create \
'[ { "txid": "'"$FAUCET_TXID"'", "vout": 0 } ]' \
'[ { "'"$CONTRACT_ADDRESS"'": 0.00099900 }, { "fee": 0.00000100 } ]' \
| jq -r .pset)
PSET=$(hal-simplicity simplicity pset update-input "$PSET" 0 -i "$HEX:$ASSET:$VALUE" -c "$CMR" -p "$INTERNAL_KEY" | jq -r .pset)
```
Sign it with the hot key, and build the witness. `witness::ACTION` needs to carry the `Action::HotSpend` enum variant along with the signature:
```bash
HOT_SIGNATURE=$(hal-simplicity simplicity sighash "$PSET" 0 "$CMR" -x "$PRIVKEY_HOT" | jq -r .signature)
cat > last_will.wit << EOF
{
"ACTION": "Action::HotSpend(0x$HOT_SIGNATURE)"
}
EOF
```
Compile with the witness attached, finalize, extract, and broadcast:
```bash
PROGRAM=$(simc -Z enums last_will.simf -a last_will.args -w last_will.wit --json | jq -r .program)
WITNESS=$(simc -Z enums last_will.simf -a last_will.args -w last_will.wit --json | jq -r .witness)
PSET=$(hal-simplicity simplicity pset finalize "$PSET" 0 "$PROGRAM" "$WITNESS" | jq -r .pset)
RAW_TX=$(hal-simplicity simplicity pset extract "$PSET" | jq -r)
HOT_TXID=$(curl -X POST "https://blockstream.info/liquidtestnet/api/tx" -d "$RAW_TX" 2>/dev/null)
```
Wait for `HOT_TXID` to confirm before moving on: you'll need the [height](../glossary.md#height) it confirms at in a moment. Once the Explorer shows it as confirmed, fetch that height:
```bash
HOT_CONFIRM_HEIGHT=$(curl -sSL https://blockstream.info/liquidtestnet/api/tx/$HOT_TXID/status | jq -r .block_height)
```
### 5. Try to inherit early (should fail)
With the benefactor apparently still active, the inheritor shouldn't be able to claim anything yet. Let's confirm the contract actually enforces that, not just trust it.
Fetch the hot-spend output's details, the same way as before:
```bash
curl https://liquid.network/liquidtestnet/api/tx/$HOT_TXID > input-tx.json
HEX=$(jq -r '.vout[0].scriptpubkey' < input-tx.json)
ASSET=$(jq -r '.vout[0].asset' < input-tx.json)
SATS=$(jq -r '.vout[0].value' < input-tx.json)
WHOLE=$(( SATS / 100000000 ))
REMAINDER=$(( SATS % 100000000 ))
VALUE=$(printf '%d.%08d' "$WHOLE" "$REMAINDER")
```
This time, build the PSET with a [`sequence`](../documentation/timelocks.md#creating-appropriate-transactions) value declaring a relative distance of `MIN_DISTANCE_BLOCKS`:
```bash
PSET=$(hal-simplicity simplicity pset create \
'[ { "txid": "'"$HOT_TXID"'", "vout": 0, "sequence": '"$MIN_DISTANCE_BLOCKS"' } ]' \
'[ { "'"$DESTINATION_ADDRESS"'": 0.00099800 }, { "fee": 0.00000100 } ]' \
| jq -r .pset)
PSET=$(hal-simplicity simplicity pset update-input "$PSET" 0 -i "$HEX:$ASSET:$VALUE" -c "$CMR" -p "$INTERNAL_KEY" | jq -r .pset)
```
Sign with the inheritor's key this time, and build an `Action::Inherit` witness:
```bash
INHERITOR_SIGNATURE=$(hal-simplicity simplicity sighash "$PSET" 0 "$CMR" -x "$PRIVKEY_INHERITOR" | jq -r .signature)
cat > last_will.wit << EOF
{
"ACTION": "Action::Inherit(0x$INHERITOR_SIGNATURE)"
}
EOF
```
```bash
PROGRAM=$(simc -Z enums last_will.simf -a last_will.args -w last_will.wit --json | jq -r .program)
WITNESS=$(simc -Z enums last_will.simf -a last_will.args -w last_will.wit --json | jq -r .witness)
PSET=$(hal-simplicity simplicity pset finalize "$PSET" 0 "$PROGRAM" "$WITNESS" | jq -r .pset)
INHERIT_RAW_TX=$(hal-simplicity simplicity pset extract "$PSET" | jq -r)
```
Note that `finalize` and `extract` both **succeed**. That's expected: the contract's own check only compares against the `sequence` value you just declared, and 3 satisfies "at least 3". Now try broadcasting it anyway:
```bash
curl -X POST "https://blockstream.info/liquidtestnet/api/tx" -d "$INHERIT_RAW_TX"
```
This should be rejected with something like `non-BIP68-final`. The contract approved the transaction; the [node](../glossary.md#node) didn't, because it independently checks how many blocks have *actually* passed since `HOT_TXID` confirmed, and it's still close to zero. This is the same split explained on the [Timelocks](../documentation/timelocks.md#timelock-enforcement-mechanisms) page: Simplicity checks "does this transaction's declared `sequence` satisfy my rule?"; blockchain consensus separately checks "has enough real time actually passed to accept this `sequence`?" Both conditions must be satisfied.
Hold onto `INHERIT_RAW_TX`: you'll resend the exact same bytes in Step 7, unchanged.
### 6. Wait
```bash
TARGET_HEIGHT=$((HOT_CONFIRM_HEIGHT + MIN_DISTANCE_BLOCKS))
echo "Waiting for block $TARGET_HEIGHT..."
```
Poll the current chain tip until it reaches `TARGET_HEIGHT`:
```bash
curl -sSL https://blockstream.info/liquidtestnet/api/blocks/tip/height
```
At a block a minute, this should take about three minutes. Watch the Explorer if you'd rather not poll from the command line.
### 7. Inherit for real
Once the tip has reached `TARGET_HEIGHT`, resend the *identical* transaction from Step 5:
```bash
curl -X POST "https://blockstream.info/liquidtestnet/api/tx" -d "$INHERIT_RAW_TX"
```
This time it should be accepted, and you'll get back a txid. You can view the completed transaction on the Explorer.
### Congratulations
You've walked a single contract through all three roles of a realistic covenant: funding it, proving activity to keep it alive, watching the network itself enforce a timelock the contract applied, and finally exercising the fallback path once that timelock had elapsed.
#### Next steps
* Once you're building something real rather than following a tutorial, [Simplex](https://github.com/BlockstreamResearch/smplx) handles project scaffolding, dependencies, and test suites for larger SimplicityHL projects.
* Read more about how relative and absolute timelocks work, and why they can only enforce *minimum* times, in [Timelocks](../documentation/timelocks.md).
* Read more about state and recursive covenants in [Covenants & State Management](../documentation/state.md).
* Try the same story in the [Rust](#__tabbed_1_1) tab above.
* See more example contracts demonstrating other SimplicityHL language features.
### Build a complete application from web to wallet
# Build a complete Simplicity application, from contract to web to wallet
This tutorial connects every part of a [Simplicity](../glossary.md#simplicity) application: a
Simplicity [contract](../glossary.md#contract), tests that
run it on a local [regtest](../glossary.md#regtest) network, and a web page that compiles
the contract, reads [Liquid](../glossary.md#liquid) testnet, and has the user's keys sign
each [transaction](../glossary.md#transaction). You'll build each part and use them
together on Liquid testnet, signing first with keys the page holds and then with the
[Humid](../glossary.md#humid) browser wallet. You can adapt the same tools and code
patterns for an application of your own.
The example contract is an allowance: a beneficiary can withdraw up to a specified amount
at a time, with a minimum wait between withdrawals, and the benefactor who funded it can't
take the coins back.

The page you'll build, for claiming testnet coins locked by a Simplicity contract: one allowance instance can be claimed now, the other unlocks in one block.
## Architecture
At run time, the application has four components:
- **The contract,** `allowance.simf`, written in [SimplicityHL](../glossary.md#simplicityhl).
The page and Humid both compile it from source, with the allowance's terms filled in.
- **The web page,** a single HTML file that you serve locally. It holds the allowance's
terms, the amounts and the buttons. Its indexer lists the allowance's
[UTXOs](../glossary.md#utxo), which it reads from a public
[Esplora](../glossary.md#esplora) server over HTTP, and decides which action is valid
for each one.
- **The [LWK](../glossary.md#lwk) library,** compiled to WebAssembly and loaded by the
page. It compiles the contract and derives its [address](../glossary.md#address). When
the page does the signing, LWK also builds and signs each transaction: the funding with
the page's own wallet, and each withdrawal with the beneficiary key the page holds. The
page broadcasts each one through Esplora.
- **The Humid wallet,** a browser extension. The page calls it through the
`window.humid` object that Humid adds to the page, passing the contract source, a
[manifest](../glossary.md#manifest) that tells Humid how to build each transaction, and
the action to perform, with the values that action needs. Humid compiles the contract, builds the transaction, asks
the user to approve it, signs it and broadcasts it.
```mermaid
flowchart TD
source["allowance.simf"]
manifest["txmanifest.humid.json"]
subgraph page["The page: one HTML file"]
form["terms, amounts, buttons"]
index["indexer: list UTXOs, compare depth and balance"]
end
subgraph lib["lwk_wasm, loaded by the page"]
l["compiles the contract and derives the address builds and signs when the page does the signing"]
end
subgraph wallet["Humid extension"]
w["compiles the contract builds and signs asks the user broadcasts"]
end
chain[("Liquid testnet")]
source --> l
source --> w
manifest --> w
form -->|"terms + amounts"| l
form -->|"action + params"| w
l -->|"signed transaction via Esplora"| chain
w -->|"signed transaction"| chain
chain -->|"UTXOs, tip height via Esplora"| index
chain -->|"wallet balance via Esplora"| l
index -->|"which action is valid now"| form
```
---
## 1. Clone the example repository
The commands in this tutorial are for a Unix shell on Linux or macOS.
```bash
git clone https://github.com/BlockstreamResearch/simplicity-demo
cd simplicity-demo/allowance-web
```
`allowance-web` holds the contract, the page and two pages this tutorial links to:
[`EXPLANATION.md`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md), on how the application works, and
[`REFERENCE.md`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md), with error messages and the Humid wallet API.
Run every command in the rest of this tutorial from `allowance-web`. If you open another
terminal, `cd` to `allowance-web` in it first. A command block that changes to another
directory ends by changing back. If a command fails, look up its message in
[`REFERENCE.md`, "Errors and what causes them"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#errors-and-what-causes-them).
Open `contracts/allowance.simf` in your editor or viewer, and look through it to see what
SimplicityHL code looks like. Every later step builds on
this one contract, and you don't need to change it.
[`EXPLANATION.md`, "What the contract enforces"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md#what-the-contract-enforces)
walks through what each of its checks enforces.
## 2. Test that the contract enforces its terms on regtest
Check that you have Rust, installed with `rustup`:
```bash
rustup --version # any version; Rust's own installer provides rustup
rustc --version # 1.91 or newer; if older, run: rustup update stable
```
If `rustup` isn't found, [install Rust](https://rust-lang.org/tools/install/).
Install [Simplex](../glossary.md#simplex), which runs SimplicityHL integration tests
against a local [Elements](../glossary.md#elements) regtest
[node](../glossary.md#node) that it starts and supplies with test coins. Its installer,
`simplexup`, also installs the regtest tools the tests use. The tests are written for
Simplex 0.2.0, so install that release. Download the installer, read it if you want to,
then run it:
```bash
export SIMPLEX_DIR="$HOME/.simplex" # in a new terminal, run both exports again
mkdir -p "$SIMPLEX_DIR/bin"
curl -fsSL -o "$SIMPLEX_DIR/bin/simplexup" \
https://raw.githubusercontent.com/BlockstreamResearch/smplx/master/simplexup/simplexup
chmod +x "$SIMPLEX_DIR/bin/simplexup"
export PATH="$SIMPLEX_DIR/bin:$PATH"
simplexup --install 0.2.0
simplex --version # Simplex 0.2.0
```
If you already had a newer Simplex,
[`REFERENCE.md`, "Installing and running
Simplex"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#installing-and-running-simplex) explains how to switch back to it.
Then set up the project and run the tests:
```bash
simplex init allowance_example
cd allowance_example
rm tests/p2pk_test.rs simf/p2pk.simf # init's own sample
cargo add anyhow@1 smplx-std@=0.2.0 # the test needs these
cp ../examples/allowance-simplex/simf/allowance.simf ./simf/
cp ../examples/allowance-simplex/tests/allowance_test.rs ./tests/
simplex build && simplex test
cd ..
```
You should see both tests `PASS`:
```console
[...]
Starting 2 tests across 2 binaries
PASS [ 20.046s] simplex_allowance_example::allowance_test allowance_drains_over_successive_withdrawals__smplx_test
PASS [ 1.564s] simplex_allowance_example::allowance_test withdrawing_before_the_interval_is_rejected__smplx_test
────────────
Summary [ 21.611s] 2 tests run: 2 passed, 0 skipped
Exit Status: 0
```
If a test shows `FAIL`, check that `allowance_example/Cargo.toml` has
`smplx-std = "=0.2.0"` and that the two files copied into `allowance_example` are unchanged,
then see [Reporting problems](#reporting-problems).
The first test runs through a full lifecycle. The second attempts a
withdrawal before the [timelock](../glossary.md#timelock), which the node rejects
under [BIP68](../documentation/timelocks.md#timelock-enforcement-mechanisms).
[Next steps](#next-steps), at the end of this tutorial, suggests more tests you can write yourself.
## 3. Build the library the page uses to compile and sign
Check that LLVM `clang` has the `wasm32` target, which the LWK build needs:
```bash
clang -print-targets | grep -q wasm32 && echo present || echo MISSING
```
If you see `MISSING`, or `clang` isn't found, install LLVM and run the check again. On
Linux, install your distribution's `clang` and `llvm` packages.
??? warning "On macOS, use Homebrew's LLVM"
On macOS, install LLVM with `brew install llvm`, because the system `clang` doesn't support wasm.
Homebrew doesn't put this LLVM on your `PATH`, so run this in every terminal you use for
the rest of the tutorial:
```bash
export PATH="$(brew --prefix llvm)/bin:$PATH"
```
Then install `wasm-pack` and build LWK with its Simplicity feature, which LWK's published
builds leave out. The block checks out the LWK commit the page is written for, since
LWK's Simplicity API can change from one commit to the next. The `wasm-pack` build can
take some time, often without printing anything.
```bash
cargo install wasm-pack
git clone https://github.com/Blockstream/lwk
cd lwk
git checkout 6412ff6bfd823a0cd36d4d07d2f5aee01d6c9c01
cd lwk_wasm
wasm-pack build --release --target web --out-dir pkg-web -- --features simplicity
cd ../..
```
When the build finishes, `lwk/lwk_wasm/pkg-web/` contains `lwk_wasm.js` and
`lwk_wasm_bg.wasm`, the two files the page loads. Copy them:
```bash
mkdir -p examples/allowance-lwk/vendor
cp lwk/lwk_wasm/pkg-web/lwk_wasm.js lwk/lwk_wasm/pkg-web/lwk_wasm_bg.wasm \
examples/allowance-lwk/vendor/
```
## 4. Serve the page and fund its wallet
Open a second terminal in `allowance-web` and start a web server for the page:
```bash
python3 -m http.server 8099 --directory examples/allowance-lwk
```
You should see `Serving HTTP on … port 8099`. Leave it running until you finish the
tutorial, then stop it with Ctrl-C. If it prints `Address already in use`, run it again with another port
number and use that port below.
Open [http://localhost:8099/ :material-open-in-new:](http://localhost:8099/){target="_blank" title="Opens in a new tab"} in a Chromium-compatible browser, such as Chrome, because
the [Humid extension](#11-set-up-a-browser-wallet-to-sign-instead-of-the-page) that you'll use
later runs only in one. The page doesn't work if you open its HTML file directly. Keep the same port
throughout, because the page stores its wallet and key per origin.
You should see `Simplicity API: present` under "Library". If the build lacks the
feature, that section instead starts `Failed: This build is missing:`; redo the
[LWK build](#3-build-the-library-the-page-uses-to-compile-and-sign).
The page has its own single-signature wallet, separate from the
[beneficiary's key](#5-get-the-beneficiary-key-that-authorizes-withdrawals).
!!! warning "The page stores the mnemonic in plaintext"
The page keeps its mnemonic in `localStorage` in plaintext. Use it only for testnet
funds, and don't paste in a mnemonic from elsewhere.
On the **I'm the benefactor** tab, leave the mnemonic box blank, press **Open wallet**,
then **Request testnet funds**.
You should see a balance within about a minute. Press **Sync & show balance** to check
again. If it stays at zero, use the [Liquid testnet faucet](https://liquidtestnet.com/faucet) with the
address the page shows.
## 5. Get the beneficiary key that authorizes withdrawals
Open the **I'm the beneficiary** tab and press **Generate / show my key**. This shows the
BIP340 x-only [public key](../glossary.md#public-key) that the page generated for you
when it loaded. The page
[compiles it into the contract](#6-set-the-terms-and-compile-the-contract), and the contract accepts
a withdrawal only with a signature from the matching
[private key](../glossary.md#private-key).
You should see 64 hex characters.
In a real allowance, the beneficiary does this on a separate machine and sends the 64
characters to the benefactor. If you're testing on your own, the benefactor's
**Beneficiary's public key** field already holds this key. If you change that field,
press **Use my own key (single-wallet test)** on the **I'm the benefactor** tab to restore
it.
## 6. Set the terms and compile the contract
Open the **I'm the benefactor** tab and check the three values the page compiles into the contract:
- **Beneficiary's public key**, which holds the
[beneficiary's key](#5-get-the-beneficiary-key-that-authorizes-withdrawals).
- **Withdrawable per period**, which is `ALLOWANCE_AMOUNT` in sats. Keep it well above
500. The page uses a fixed [fee](../glossary.md#fee) of 500 sats for every withdrawal
and pays it out of the allowance, so the beneficiary can't withdraw an allowance of
500 sats or less.
- **Blocks between withdrawals**, which is `MIN_DISTANCE`. `3` means about three
minutes, convenient for a first run; `1440` is about a day.
Press **Compile & derive address**.
??? example "The code behind **Compile & derive address**"
```js
const args = new L.SimplicityArguments()
.addValue("BENEFICIARY_KEY", L.SimplicityTypedValue.fromU256Hex(params.benkey))
.addValue("ALLOWANCE_AMOUNT", L.SimplicityTypedValue.fromU64(params.allowance))
.addValue("MIN_DISTANCE", L.SimplicityTypedValue.fromU16(params.mindist));
const program = L.SimplicityProgram.load(source, args);
const address = program.createP2trAddress(
L.XOnlyPublicKey.fromString(NUMS_INTERNAL_KEY), network);
```
You should see the [CMR](../glossary.md#cmr) and a `tex1p…`
[covenant](../glossary.md#covenant) address. Changing
any of the terms gives a different allowance at a different address.
## 7. Fund the allowance
Set **Amount to lock** to a whole multiple of **Withdrawable per period**, such as `10000`
for an allowance of `5000`, so that the last withdrawal also takes a full allowance. The beneficiary can't withdraw a
final instance holding 500 sats or less. Then press **Fund**.
??? example "The code behind **Fund**"
```js
const pset = new L.TxBuilder(network)
.addExplicitRecipient(c.address, amount, policyAsset)
.finish(wollet);
const tx = wollet.finalize(signer.sign(pset)).extractTx();
```
**Broadcast for real** starts selected, so the page first shows what it will send: the amount,
the covenant address, the terms, the fee and the [output](../glossary.md#output) count.
Check them and press **Sign & broadcast**. To try it without sending anything, clear
**Broadcast for real** before you press **Fund**. The page then reports the txid it would
have sent.
You should see a broadcast txid. The transaction's output at the covenant address is the first
allowance instance.
??? example "Check the funding on chain"
Select the link under the txid to open the transaction in the block explorer. Among
its outputs, you should see the covenant address with the amount you locked. The
explorer shows amounts in test Liquid bitcoin (tLBTC), and 1 tLBTC is 100,000,000 sats.
The output's position can vary.
The explorer is Esplora's web interface, and it shows the same data that the page reads
as JSON from Esplora's API; see
[`REFERENCE.md`, "Chain access"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#chain-access).
## 8. Watch the allowance
Watching, [withdrawing](#9-withdraw) and [closing](#10-close-the-allowance) follow the
loop below; in this step, you watch the chain for live allowance instances. A partial withdrawal pays the beneficiary and recreates the covenant
with the remainder, so the timelock starts again from the block that confirmed the withdrawal.
```mermaid
flowchart TD
start(["your wallet, funded"]) -->|"Fund"| inst
inst["allowance instance: one UTXO at the covenant address"]
inst -->|"wait MIN_DISTANCE blocks"| ready["spendable"]
ready -->|"PartialWithdraw balance above ALLOWANCE_AMOUNT"| split
split["payout to the beneficiary, plus the remainder back to the same address"] --> inst
ready -->|"FullWithdraw balance at or below ALLOWANCE_AMOUNT"| done(["closed"])
```
Open the **I'm the beneficiary** tab and press **Refresh status**. The instance list and
the withdrawal controls are on that tab.
You should see one instance listed with a balance and either `PartialWithdraw` or
`FullWithdraw` as its action. Its "Timelock" column reads `unconfirmed (~1 min)` until the funding
transaction confirms, and then shows a timelock countdown. Each
UTXO at the covenant address is a separate allowance instance
with its own timelock.
??? example "Check the instances on chain"
Select the covenant address above the instance list to open its page in the explorer.
"Total unspent" should match the number of instances in the list, because each
unspent output at the address is an instance.
Select an entry in the "Instance" column to open its transaction. The explorer shows
how many blocks have confirmed it, such as `3 Confirmations`, and the instance becomes
spendable once that number reaches `MIN_DISTANCE`. The action follows the balance:
`FullWithdraw` when the instance holds `ALLOWANCE_AMOUNT` or less, otherwise
`PartialWithdraw`.
## 9. Withdraw
Wait until the button reads **Claim**. With a short `MIN_DISTANCE` such as `3`, the page
refreshes the list about once a minute; press **Refresh status** to check sooner.
Press **Use my wallet address** to fill **Pay withdrawals to** with your wallet's address.
Then press **Claim** and read the confirmation panel, which lists every output before the
page signs anything.
You should see these outputs:
| Output | `PartialWithdraw` | `FullWithdraw` |
| --- | --- | --- |
| 0 | the remainder, back to the covenant address | the payout to you |
| 1 | the payout to you | the fee |
| 2 | the fee | |
Press **Sign & broadcast**.
You should see a broadcast txid. After a `PartialWithdraw`, a new instance holding the
remainder appears within about a minute.
??? example "Check the payout on chain"
Select the link under the txid to open the transaction in the explorer. Among its
outputs, you should see the address in **Pay withdrawals to**. For a
`PartialWithdraw`, its amount is `ALLOWANCE_AMOUNT` minus the 500-sat fee. For a
`FullWithdraw`, it's the instance's whole balance minus the fee. The last output,
`Transaction fees`, is the fee: 0.000005 tLBTC.
If the claim fails with `non-BIP68-final`, not enough blocks have passed; wait and claim
again. If it fails with `insufficient fee, rejecting replacement`, an earlier attempt
already reached the mempool and probably succeeded. Before claiming again, select the
covenant address above the instance list and check whether its page in the explorer
already shows that withdrawal. For anything else, look up
the message in [`REFERENCE.md`, "Errors and what causes
them"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#errors-and-what-causes-them).
## 10. Close the allowance
Repeat the [withdrawal](#9-withdraw), leaving **Pay withdrawals to** as it is, until the
instance's action shows `FullWithdraw`, which takes everything remaining and ends the
covenant. Claim it the same way.
After each claim, the page refreshes the list. The button of the instance you just spent
shows `Spent`. The new instance holding the remainder appears as `Unconfirmed`, then
`Timelocked`, then **Claim** once its own timelock has passed.
Within about a minute of the `FullWithdraw`, you should see `No live instances at …` in place
of the list.
Once the `FullWithdraw` confirms, your payout address holds the locked amount, less the fee
for each withdrawal.
??? example "Check the close-out on chain"
Select the covenant address in `No live instances at …` to open its page in the explorer.
"Total unspent" should read `No outputs`: every instance is spent.
## 11. Set up a browser wallet to sign instead of the page
So far, the page has stored its keys in your browser's storage for the site and signed with
them itself. Humid is a browser-extension wallet that keeps its keys inside the extension,
behind a password, and signs only after you approve each transaction.
[`EXPLANATION.md`, "Who signs, and what that changes"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md#who-signs-and-what-that-changes)
compares the two. In this step, you install Humid and fund it with testnet coins. In the next
step, the page passes the contract to Humid, which builds and signs each transaction.
Download Humid 1.1.5, check the archive's SHA-256 hash, and unpack it:
```bash
curl -fsSLO https://github.com/BlockstreamResearch/humid/releases/download/1.1.5/humid-extension-1.1.5.zip
echo "25dcf36655e0e9eae501c85c395dfca4d8b5a607f13f848541d7b1b2246fb416 humid-extension-1.1.5.zip" \
| shasum -a 256 -c && unzip -q humid-extension-1.1.5.zip -d humid
```
You should see `humid-extension-1.1.5.zip: OK`. If it prints `FAILED` instead, the archive
isn't unpacked; delete it and run the block again. If it fails again, see
[Reporting problems](#reporting-problems).
Open `chrome://extensions`, turn on **Developer mode**, press **Load unpacked**, and
select the `humid` folder inside `allowance-web`.
You should see Humid listed and enabled. Then reload the allowance page, because the
browser adds the extension only to pages loaded after it.
Press the **Extensions** button (the puzzle-piece icon) in the top right of the browser
and select **Humid** to create a wallet. During setup, don't switch to another application
or click outside Humid's setup window, because the setup window closes.
1. Press **Create wallet**.
2. Note the 12 words the **Recovery phrase** panel shows (without leaving Humid's window,
for example on paper or another device), and press **I saved it**.
3. Enter the three words it asks for, and press **Continue**.
4. Enter a password of at least 8 characters twice and press **Create wallet**.
If the setup window closes partway through, open Humid and start over. It shows a new
recovery phrase, so note that one instead.
You should see Humid's account panel, with a network menu reading **LIQUID** at the top
left, a balance, and **Receive** and **Send** buttons.
!!! warning "Switch Humid to Liquid testnet"
Humid starts on Liquid mainnet. Open the **LIQUID** menu at the top left of the panel
and select **Liquid Testnet**.
Press **Receive**.
You should see a [confidential](../glossary.md#confidential) address starting `tlq1`,
the Liquid testnet form.
Fund Humid now, so its coins can confirm while you set up the page: use the
[Liquid testnet faucet](https://liquidtestnet.com/faucet) to send testnet coins to that
`tlq1…` address, not to the page's wallet.
In Humid's account panel, select the test Liquid bitcoin (tLBTC)
[asset](../glossary.md#asset) under "TOKENS" (Humid labels it `L-BTC`) to open its
activity list.
You should see the payment within about a minute, under `PENDING`, or under a date such as
`TODAY` once it has confirmed.
## 12. Run the same contract through the browser wallet
!!! warning "This creates a second, separate allowance"
Humid signs with its own key, so this allowance gets a new covenant address. In
Humid mode, the page can't claim an allowance compiled with the page's own key.
Select **Humid extension** under "Who signs". The page's own wallet and key sections
disappear, along with the results of your page-signed allowance. Then press **Check for Humid**.
You should see `Humid is available on this page.`
Press **Get my key from Humid**. The first call opens Humid's `Connect this dapp?` prompt;
press **Connect**. [`REFERENCE.md`, "Sessions and prompts"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#sessions-and-prompts)
explains when the connect prompt appears again.
??? example "The call behind **Get my key from Humid**"
```js
await invokeHumid("getWalletDescriptor", {
descriptorType: "publicWalletDescriptor",
descriptorFormat: [{ format: "bip380-split-branches" }],
});
// then derive the x-only key: see REFERENCE.md, "Deriving keys and addresses from the wallet"
```
You should see 64 hex characters under "Who signs", which differ from the
[page's beneficiary key](#5-get-the-beneficiary-key-that-authorizes-withdrawals). The page
also puts them in the **Beneficiary's public key** field on the **I'm the benefactor** tab.
Then fund the allowance through Humid:
1. [Compile the contract](#6-set-the-terms-and-compile-the-contract) again with this key.
2. Wait until the faucet payment to Humid is listed under a date rather than `PENDING` in
Humid's activity list. Humid spends only confirmed funds.
3. Set **Amount to lock** as you did to [fund the allowance](#7-fund-the-allowance), and
press **Fund**.
4. Approve Humid's `Perform a contract action?` window, which describes the transaction,
with **Sign and send**. By default, if you haven't used Humid for 15 minutes, it first asks for
your password in an `Unlock Humid` window.
??? example "The call behind **Fund** in Humid mode"
```js
await invokeHumid("processConfidentialTransaction", {
manifest, contractSources: { "./allowance.simf": source },
action: "Fund",
params: { BENEFICIARY_KEY, ALLOWANCE_AMOUNT, MIN_DISTANCE, amount_sat },
broadcast: true,
});
```
With **Broadcast for real** cleared, the page sends
`broadcast: false`. Humid's button then reads **Sign**, and Humid signs the
transaction without sending it.
[`REFERENCE.md`, "`processConfidentialTransaction`"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#processconfidentialtransaction)
documents the call.
You should see `Humid broadcast the funding transaction.` and a txid. Press **Refresh
status** on the **I'm the beneficiary** tab to see the new instance.
Then withdraw until the allowance closes. Humid sets the fee for each withdrawal and pays
the withdrawal to its own change address, so this mode doesn't show **Pay withdrawals to**.
On the **I'm the beneficiary** tab:
1. Wait `MIN_DISTANCE` blocks, until the instance's button reads **Claim**.
2. Leave **Dry run** cleared and press **Claim**.
3. Confirm the page's summary, which names the action, the instance it spends and its
balance.
4. Approve Humid's `Perform a contract action?` window with **Sign and send**, unlocking
Humid first if it asks.
5. Repeat from 1 with each new instance, until you've claimed the `FullWithdraw`.
You should see `PartialWithdraw broadcast by Humid.` or `FullWithdraw broadcast by Humid.`
with a txid for each withdrawal. Within about a minute of the `FullWithdraw`, the spent
instance leaves the instance list. If it was the only one, you should see
`No live instances at …`.
## Reporting problems
If a command fails with a message that isn't in [`REFERENCE.md`, "Errors and what causes
them"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#errors-and-what-causes-them), open an issue in the
[`simplicity-lang-org` repository](https://github.com/BlockstreamResearch/simplicity-lang-org/issues)
with the exact error text and the step you were on. If you're an AI agent running these
steps as a test, follow your own instructions instead.
## Next steps
Read [`EXPLANATION.md`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md) next. It covers what the contract enforces and how
the choice of signer affects the application. Before you adapt any of this for real funds, read
[`EXPLANATION.md`, "What a mainnet deployment
would require"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md#what-a-mainnet-deployment-would-require).
To adapt a component for your own contract:
- **The tests.**
[`examples/allowance-simplex/README.md`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/examples/allowance-simplex/README.md) has ten
more tests to write yourself. Most check that the contract rejects an invalid
withdrawal: one signed by someone other than the beneficiary, one that takes more
than the allowance, or one that tries to change the covenant's terms. Most of what they
need is in the two tests you
[ran on regtest](#2-test-that-the-contract-enforces-its-terms-on-regtest).
- **The manifest.** [`EXPLANATION.md`, "Writing a manifest for a different
contract"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md#writing-a-manifest-for-a-different-contract) shows how to
derive a manifest from a different contract's source, and
[`EXPLANATION.md`, "Checking a manifest you didn't
write"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/EXPLANATION.md#checking-a-manifest-you-didnt-write) covers reviewing one,
including one an AI assistant drafted.
- **The page.** [`examples/allowance-lwk/README.md`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/examples/allowance-lwk/README.md)
describes what the page does, step by step, and the constraints to keep when you change
its LWK calls.
- **The indexer.** `loadInstances()` in
[`examples/allowance-lwk/index.html`](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/examples/allowance-lwk/index.html) holds its core
logic: two Esplora calls, the depth arithmetic, and the balance comparison that picks the
action. [`REFERENCE.md`, "Chain access"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#chain-access) describes the calls.
To run an allowance between two people, each with a separate browser, see
[`examples/allowance-lwk/README.md`, "Running it as two separate
parties"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/examples/allowance-lwk/README.md#running-it-as-two-separate-parties).
For other clients for the same contract, including a command-line one that runs it without
a browser, see [`REFERENCE.md`, "Other clients for the same
contract"](https://github.com/BlockstreamResearch/simplicity-demo/blob/master/allowance-web/REFERENCE.md#other-clients-for-the-same-contract).
## Learn
### Execution Model
# On-chain Simplicity execution model
Simplicity is a special-purpose language. It works in the context of the Bitcoin transaction model on Bitcoin-like blockchains. This is sometimes also called the "[UTXO](../glossary.md#utxo) model". If you're already familiar with Bitcoin Script and the role it plays in the logic of Bitcoin transactions, you can think of Simplicity as a more expressive and more analyzable alternative to Bitcoin Script, useful for writing more complex conditions (such as recursive [covenants](../glossary.md#covenant) that can propagate conditions across multiple subsequent transactions).
This document will describe the context in which Simplicity programs run, and what they can and can't do as a result.
## The Simplicity and SimplicityHL environment
Developers generally write SimplicityHL, a higher-level language with a Rust-like syntax, which compiles to Simplicity. The SimplicityHL compiler translates SimplicityHL into Simplicity to run on Simplicity's abstract Bit Machine.
Simplicity programs are attached to UTXOs via [Taproot](../glossary.md#taproot) and define their spending conditions. However, the Simplicity program is only disclosed when redeeming (claiming) [assets](../glossary.md#asset). As part of the blockchain consensus process, all blockchain [nodes](../glossary.md#node) can confirm that it matches the commitment attached to the UTXO, and can run the program to confirm that it approves the proposed transaction.
## What Simplicity programs are used for
The basic task of every Simplicity program is to *consider a proposed blockchain transaction* and determine whether to *approve or disapprove* that transaction. More complex financial logic can be built out of one or more Simplicity programs working together to manage assets and their disposition across multiple related transactions. Together, the logic and rules governing a set of related blockchain transactions can be called a [smart contract](../glossary.md#smart-contract).
Designing a smart contract with Simplicity thus includes representing its logic as a series of on-chain transactions, and describing the rules that govern exactly when each transaction is permitted to occur.
## Where and how Simplicity programs run
Like Bitcoin Script scripts, Simplicity programs are *attached to [UTXO](../glossary.md#utxo)s* and define spending conditions for the UTXOs to which they are attached. A Simplicity program can, however, have more complex logic and functionality compared to a Bitcoin Script script.
The Simplicity program doesn't initiate or originate the transaction and doesn't decide anything about what the transaction should be (for instance, it doesn't calculate or choose destination addresses, although it can *constrain* them by rejecting transactions that specify inappropriate destinations).
In Bitcoin and related systems, anyone can propose any transaction at any time; the spending conditions associated with assets, such as those contained in the logic of a Simplicity program, form part of the rules that determine whether or not proposed transactions are valid and hence whether those transactions could eventually be recorded in a block and become part of the blockchain.
Whenever a [node](../glossary.md#node) examines a transaction involving UTXO controlled by a Simplicity program, the node will run that program to confirm that the program agrees to allow the transaction.
The information available to the program to use in making that decision consists of
* whatever details are hard-coded within the program (for example, trusted public key values),
* details of all the [input](../glossary.md#input)s and [output](../glossary.md#output)s of the proposed transaction, and
* [witness](../glossary.md#witness) data supplied by the creator of the transaction as input to the program.
Note that the program can directly check its own cryptographic identity by examining the input UTXO to which it was attached.
The [witness](../glossary.md#witness) supplied as part of the transaction by its creator represents inputs meant to provide additional context for the transaction. The form of the expected witness is determined in advance by the contract; a witness might include information such as
* choices among different options or contract features (for example, which of several possible actions the transaction is requesting to take)
* values of specific parameters (for example, an amount)
* asserted state from parties' prior interactions with the contract (see [State Management in SimplicityHL](state.md) for more details)
* digital signatures from parties approving the contract or confirming other relevant statements (for example, a party's signatures approving the exercise of some ability under the contract, or an oracle's signature asserting the truth of some off-chain fact such as a market price or whether a specific event has occurred)
The [Witnesses in SimplicityHL development](witness.md) document explains the concept in more detail; the [`.wit` file reference](witness-format.md) talks about the practical mechanics of creating one.
Because Simplicity is formally specified and fully deterministic, every node that examines that transaction will come to exactly the same conclusion about what the result of running the Simplicity program was, without ambiguity.
## How Simplicity programs are triggered or invoked
Simplicity programs are inherently reactive. Because they can't initiate transactions or other actions independently, they rely entirely on external client software to "drive" the contract state forward.
To interact with a Simplicity contract, end-user software (such as wallets or specialized apps) must be built specifically around that individual contract. The client software acts as the active engine for the contract's passive logic by:
* Generating transactions: Constructing and submitting on-chain transactions required to trigger specific contract functions.
* State tracking: Monitoring on-chain data to determine which actions are valid, and, if necessary, reminding the contract of the relevant state.
* User interface: Providing an interface to explain the current state to the user and allows the user to make choices (like a "refund" versus "spend" action) by translating those choices into transactions.
In this model, the client software proposes actions, while the Simplicity program judges and confirms whether those actions are actually permissible under the contract rules. Therefore, the client software must know enough about these rules and the contract state to propose transactions that will be accepted.
For development purposes, you can also run a Simplicity program locally with `hal-simplicity simplicity pset run` after building a [PSET](../glossary.md#pset) representing the overall transaction within which the program will run. This simulates the Simplicity logic that a node would follow, although nodes can also reject transactions for various other reasons, such as if the input UTXO has already been spent, if sufficient fees aren't paid with the transaction, or if spending conditions applicable to some other referenced UTXO aren't satisfied.
Below, this document presents several examples of applications of SimplicityHL and describe how the contracts they implement must be "driven" by some kind of end-user software generating and submitting appropriate transactions.
## Distinctive features of Simplicity and its environment
Simplicity is a deterministic functional programming environment. Simplicity programs [don't have access to any form of I/O or network access](https://delvingbitcoin.org/t/delving-simplicity-part-two-side-effects/2091). They can't display a user interface, read or write files, or call network APIs. In fact, they don't even have direct access to the data of the blockchains with which they are integrated. However, Simplicity does provide programs with the ability to *introspect* the currently-proposed transaction in order to find out details related to input and output asset types, amounts, and addresses. For example, a program can use [introspection](../glossary.md#introspection) to require that an asset is sent back to a copy of that same program; it does so by approving only transactions where an output with exactly the same program code receives the asset that was spent in the program's input.
Whenever a user proposes a transaction that would spend (consume as input) an existing UTXO to which a Simplicity program is attached, the proposed transaction makes a claim that the Simplicity program authorizes that UTXO to be spent in the indicated context. Nodes then check this claim by running the program. Most, though not all, programs will check cryptographic information derived from the attached witness data, such as whether one or more digital signatures included there are valid.
A Simplicity program can include several alternative paths reflecting different scenarios or outcomes, and different criteria for approving each one. A simple example is a timeout branch, where assets controlled by the program can be refunded to their original senders, but only after a certain amount of time has elapsed. This can serve as an alternative to the originally intended outcome in which a certain transaction is completed by transferring assets elsewhere. This prevents assets from being stuck inside the contract if some party fails to perform its role.
## Why not perform more complex computations in Simplicity?
Every Simplicity program is run (albeit in pruned form) by *every node* that validates a block containing a transaction spending assets controlled by the program. The computation to validate transactions is expensive; indeed, creators of transactions may be required to pay for it indirectly via fees.
Simplicity programs perform deterministic computations based on publicly-disclosed information. It is useful to have nodes perform computation to validate compliance with financial logic and contractual rules (that determine who is entitled to specific assets). However, computation that isn't necessary for these purposes doesn't need to be done on-chain and replicated by all validators.
For example, a loan might charge interest at a specified rate. In principle, a Simplicity program could compute how the loan balance will change over time based on different repayment schedules, but it doesn't *need* to make such hypothetical future projections in order to calculate the actual loan balance. It also wouldn't be able to output the results of these computations for anyone to see them. The same information can just as easily be computed by client-side software, and this is much more efficient. That computation can be done just once, on the device of the interested user.
In general, anything that doesn't have to happen on-chain should be handled outside of a Simplicity program. That includes any logic or computations that are relevant to user interface for the contract but not critical to its underlying financial logic and disposition of assets.
Many computationally-intensive tasks that must be performed on-chain, like cryptographic operations, can be outsourced to [jets](../glossary.md#jet), allowing the actual calculations to take place in native code.
## Examples
The functionality of three kinds of contracts is examined below in order to illustrate how Simplicity programs can make decisions in order to determine whether to approve proposed transactions.
These examples don't use introspection features, so they don't demonstrate Simplicity's ability to constrain outputs' destinations. Introspection would also provide an alternative way to implement the refund path in the `htlc` contract (constraining the refund payment to be sent to the address of the original sender of an asset, by asserting that an input address and output address match); this version instead hardcodes a key that can be used to authorize refunds, sent to any chosen address.
### p2ms
This program, `p2ms.simf`, is taken from the SimplicityHL examples collection. An [older version of the `bash` quickstart](https://github.com/BlockstreamResearch/simplicity-lang-org/blob/82e7f3e84218d6c3dd6dbbf5f772fcd5c192baab/docs/getting-started/bash-quickstart.md) guide provides a recipe for making a Liquid Testnet transaction using this program.
```simplicityhl
/*
* PAY TO MULTISIG
*
* The coins move if 2 of 3 people agree to move them. These people provide
* their signatures, of which exactly 2 are required.
*
* https://docs.ivylang.org/bitcoin/language/ExampleContracts.html#lockwithmultisig
*/
fn not(bit: bool) -> bool {
::into(jet::complement_1(::into(bit)))
}
fn checksig(pk: Pubkey, sig: Signature) {
let msg: u256 = jet::sig_all_hash();
jet::bip_0340_verify((pk, msg), sig);
}
fn checksig_add(counter: u8, pk: Pubkey, maybe_sig: Option) -> u8 {
match maybe_sig {
Some(sig: Signature) => {
checksig(pk, sig);
let (carry, new_counter): (bool, u8) = jet::increment_8(counter);
assert!(not(carry));
new_counter
}
None => counter,
}
}
fn check2of3multisig(pks: [Pubkey; 3], maybe_sigs: [Option; 3]) {
let [pk1, pk2, pk3]: [Pubkey; 3] = pks;
let [sig1, sig2, sig3]: [Option; 3] = maybe_sigs;
let counter1: u8 = checksig_add(0, pk1, sig1);
let counter2: u8 = checksig_add(counter1, pk2, sig2);
let counter3: u8 = checksig_add(counter2, pk3, sig3);
let threshold: u8 = 2;
assert!(jet::eq_8(counter3, threshold));
}
fn main() {
let pks: [Pubkey; 3] = [
0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798, // 1 * G
0xc6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5, // 2 * G
0xf9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9, // 3 * G
];
check2of3multisig(pks, witness::MAYBE_SIGS);
}
```
This program includes three hard-coded public keys. Its logic says that any proposed transaction will be approved if, and only if, exactly two digital signatures on the proposed transaction are provided and those signatures were correctly made by the private keys corresponding to any two of those three keys.
Since the signatures are made over the transaction data including the specific input(s) and output(s), it can be presumed that the holders of those keys agree with transferring specific assets controlled by the contract to those specific destinations.
Once an asset has been sent to this contract (that is, a UTXO identifies it as a spending condition), anyone can propose a transaction that would spend that asset. The contract examines the proposed transaction and decides whether it does or doesn't contain sufficient evidence (based on the presence or absence of valid signatures provided in the witness). It then approves or rejects the transaction on that basis.
??? "Expand for diagram"
```mermaid
flowchart TD
A((Claiming transaction)) -->|Witness| B[p2ms contract]
B --> C[Valid signature count is 0]
C --> D{Sig 1 provided and valid?}
D -->|Yes| E[Valid signature count increases by 1]
D -->|No| F[Valid signature count unchanged]
E --> G{Sig 2 provided and valid?}
F --> G
G -->|Yes| H[Valid signature count increases by 1]
G -->|No| I[Valid signature count unchanged]
H --> J{Sig 3 provided and valid?}
I --> J
J -->|Yes| K[Valid signature count increases by 1]
J -->|No| L[Valid signature count unchanged]
K --> M{Valid signature count equal to 2?}
L --> M
M -->|Yes| N((Approve transaction))
M -->|No| O((Reject transaction))
```
### htlc
This program, `htlc.simf`, is also taken from the SimplicityHL examples collection. It implements a hash-timelock contract, a mechanism often used in cryptocurrency swaps.
```simplicityhl
/*
* HTLC (Hash Time-Locked Contract)
*
* The recipient can spend the coins by providing the secret preimage of a hash.
* The sender can cancel the transfer after a fixed block height.
*
* HTLCs enable two-way payment channels and multi-hop payments,
* such as on the Lightning network.
*
* https://docs.ivylang.org/bitcoin/language/ExampleContracts.html#htlc
*/
fn sha2(string: u256) -> u256 {
let hasher: Ctx8 = jet::sha_256_ctx_8_init();
let hasher: Ctx8 = jet::sha_256_ctx_8_add_32(hasher, string);
jet::sha_256_ctx_8_finalize(hasher)
}
fn checksig(pk: Pubkey, sig: Signature) {
let msg: u256 = jet::sig_all_hash();
jet::bip_0340_verify((pk, msg), sig);
}
fn complete_spend(preimage: u256, recipient_sig: Signature) {
let hash: u256 = sha2(preimage);
let expected_hash: u256 = 0x66687aadf862bd776c8fc18b8e9f8e20089714856ee233b3902a591d0d5f2925; // sha2([0x00; 32])
assert!(jet::eq_256(hash, expected_hash));
let recipient_pk: Pubkey = 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798; // 1 * G
checksig(recipient_pk, recipient_sig);
}
fn cancel_spend(sender_sig: Signature) {
let timeout: Height = 1000;
jet::check_lock_height(timeout);
let sender_pk: Pubkey = 0xc6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5; // 2 * G
checksig(sender_pk, sender_sig)
}
fn main() {
match witness::COMPLETE_OR_CANCEL {
Left(preimage_sig: (u256, Signature)) => {
let (preimage, recipient_sig): (u256, Signature) = preimage_sig;
complete_spend(preimage, recipient_sig);
},
Right(sender_sig: Signature) => cancel_spend(sender_sig),
}
}
```
This program incorporates logic supporting two different outcomes, which are two different kinds of transactions that can potentially be approved in different circumstances. One path is called "complete" and represents a transaction that claims to complete the intended asset transfer. If the contract is satisfied (by someone revealing an appropriate hash preimage as "password") that this can occur, it will approve a transaction that effectuates this transfer. The authorized recipient must also provide a digital signature approving this transaction.
On the other hand, if the underlying asset being transferred is still controlled by the contract after a specified delay (here, of 1000 blocks since the receipt of the asset), the authenticated original sender can request a refund, and the contract will approve a transaction that effectuates the refund.
In each of these cases, the appropriate party must actively make a claim by submitting a transaction and substantiating it with a [witness](../glossary.md#witness) that proves all required conditions are met. Until the recipient explicitly creates and submits this claiming transaction, the assets remain controlled by the contract.
The contract doesn't store any kind of state to record whether one or the other paths has already previously been taken. The reason that one path excludes the other is simply that the underlying asset will already have been spent. In this case, the blockchain's transaction validity logic forbids double-spending the same [UTXO](../glossary.md#utxo). Another way of thinking of this is that, after the asset has been claimed from the contract by someone, the contract no longer controls the disposition of that asset, and therefore it is no longer interesting or relevant whether the contract would "agree" to some other transfer. In a certain sense, Simplicity contracts don't "know" what assets they control, but that information is readily available on the blockchain for inspection by software like wallet apps.
??? "Expand for diagram"
```mermaid
flowchart TD
A((Claiming transaction)) -->|Witness| B[htlc contract]
B -->Q{Which action?}
Q -->|Transfer| C{Hash preimage correct?}
Q -->|Refund| D{Time 1000 blocks after input transaction?}
C -->|Yes| E{Recipient signature valid?}
C -->|No| F((Reject transaction))
D -->|Yes| G{Sender signature valid?}
D -->|No| F((Reject transaction))
E -->|Yes| H((Approve transaction))
E -->|No| J((Reject transaction))
G -->|Yes| K((Approve transaction))
G -->|No| L((Reject transaction))
```
### Prediction market
This example discusses a prediction market contract but doesn't provide an example of SimplicityHL code for this contract.
A prediction market contract provides an example of how Simplicity contract updates are "driven" by some kind of end-user software such as a wallet or a contract-specific app, which must generate and submit appropriate transactions and witness data under appropriate circumstances.
A typical prediction market issues pairs of tokens called YES and NO with respect to a specific question. The market has functionality that tends to ensure that the YES and NO prices remain consistent with one another.
The implementing contract usually provides the following actions:
* Issue pair: lock $1 with the contract; receive new YES and NO tokens
* Redeem pair: burn existing YES and NO tokens; receive locked $1
* Claim YES: burn existing YES token, provide oracle statement asserting that question resolved YES; receive locked $1
* Claim NO: burn existing NO token, provide oracle statement asserting that question resolved NO; receive locked $1
Users can also directly trade YES and NO tokens with one another, allowing their prices to vary from the assumed "indifference" level of $0.50.
At least the final three actions will likely need to be provided by different code paths of the same program, because they all need to be able to release (authorize spending of) some $1 of locked value, and assets controlled by the prediction market ought to be fungible.
If the underlying question resolves as YES, the YES token will typically be worth one currency unit (such as $1), while the NO token won't be redeemable for any value. Conversely, if the underlying question resolves as NO, the NO token will be redeemable for $1 and the YES token won't be redeemable. When the question resolves (by the issuance of a signed [oracle](../glossary.md#oracle) statement indicating which side has won), each "winner" holding a token for the successful position on the question must individually proactively claim a reward by explicitly submitting a transaction that claims $1 from the contract in exchange for consuming a token. Therefore, all of the winners need to have, and use, software capable of formulating this claim transaction in order to receive any benefit from their successful bets in the market. In the absence of a specific claim transaction, the contract doesn't have any inherent notion of who the winners are or the fact that they have won or are entitled to anything. Some implementations may not even "remember" which side has won, and have to be reminded by resubmitting the oracle statement together with each successive claim.
??? "Expand for diagrams"
```mermaid
sequenceDiagram
participant wallet@{"alias": "User wallet"}
participant node@{"alias": "Node"}
participant impl@{"alias": "Node's Simplicity implementation"}
participant mempool@{"alias": "Mempool"}
wallet->>node: New tx spending assets from UTXO Y to address Z, witness W
node->>impl: Run program P with UTXO Y to address Z, witness W
impl->>node: Success
node->>mempool: This tx is valid, can relay it or include it in a block
node->>wallet: Your tx is valid
```
```mermaid
sequenceDiagram
participant wallet as User wallet
participant node as Node
participant impl as Node's Simplicity implementation
participant mempool as Mempool
wallet->>node: New tx spending assets from UTXO Y to address Z, witness W
node->>impl: Run program P with UTXO Y to address Z, witness W
impl->>node: Failure
node->>wallet: Your tx is invalid
```
### Covenants & State Management
# Covenants and state management
This document describes concepts and features for enforcing complex financial logic in a Simplicity [*covenant*](../glossary.md#covenant) that manages assets across a series of multiple transactions.
## Covenants
Some Simplicity contracts will be "finished" after a single transaction in which some party successfully claims the assets held by the contract. The [Hash Time-Locked Contract](https://github.com/BlockstreamResearch/SimplicityHL/blob/master/examples/htlc.simf) is an example where the contract is complete as soon as an authorized party claims its underlying value.
However, a key feature of Simplicity is the ability to implement more complex financial logic by [introspection](../glossary.md#introspection). Introspection allows a [smart contract](../glossary.md#smart-contract) to enforce policies and relationships that last beyond a single transaction. This is usually done by means of [covenants](../glossary.md#covenant), smart contracts that enforce that assets are sent *back to a copy of the same contract*. This allows a contract to "hold onto" assets across a series of transactions, possibly moving some portion of those assets in or out of the contract, or updating the contract's state over time.
```mermaid
flowchart LR
loop1[ ]:::inv
loop2[ ]:::inv
Z((User A)) -->|Asset deposit| A[Covenant]
Y((User B)) -->|Asset deposit| A
A --- loop1 -->|Some update action| A
A --- loop2 -->|Some other update action| A
A -->|Authorized withdrawal| B((Beneficiary))
A -->|Authorized refund| Y
classDef inv display:none,height:0,width:0;
```
In Simplicity, most complex and long-term financial relationships among multiple parties will be modeled as covenants.
A simple example is provided in [`last_will.simf`](https://github.com/BlockstreamResearch/SimplicityHL/blob/master/examples/last_will.simf).
???+ "Click to hide source code"
```simplicityhl
/*
* LAST WILL
*
* The inheritor can spend the coins if the owner doesn't move them for 25,920
* blocks (about 18 days on Liquid). The owner has to repeat the covenant when
* he moves the coins with his hot key. The owner can break out of the covenant
* with his cold key.
*
* Requires -Z enums to run this example.
*/
fn checksig(pk: Pubkey, sig: Signature) {
let msg: u256 = jet::sig_all_hash();
jet::bip_0340_verify((pk, msg), sig);
}
// Enforce the covenant to repeat in the first output.
//
// Elements has explicit fee outputs, so enforce a fee output in the second output.
// Disallow further outputs.
fn recursive_covenant() {
assert!(jet::eq_32(jet::num_outputs(), 2));
let this_script_hash: u256 = jet::current_script_hash();
let output_script_hash: u256 = unwrap(jet::output_script_hash(0));
assert!(jet::eq_256(this_script_hash, output_script_hash));
assert!(unwrap(jet::output_is_fee(1)));
}
pub fn enforce_relative_distance(min_distance: Distance) {
// Assert that the current input is spent in a transaction that can
// only appear a distance of at least min_distance blocks after the
// block containing the input UTXO.
// Panic otherwise.
// This is a replacement for the deprecated jet::check_lock_distance.
// Transaction version must be at least 2.
assert!(jet::le_32(2, jet::version()));
// Fetch and parse sequence
let actual_data: Either = unwrap(jet::parse_sequence(jet::current_sequence()));
let actual_distance: Distance = unwrap_left::(actual_data);
assert!(jet::le_16(min_distance, actual_distance));
}
fn inherit_spend(inheritor_sig: Signature) {
// On Bitcoin, this Distance would be 180 days; on Liquid, it is 18 days.
let timelock_distance: Distance = 25920;
enforce_relative_distance(timelock_distance);
let inheritor_pk: Pubkey = 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798; // 1 * G
checksig(inheritor_pk, inheritor_sig);
}
fn cold_spend(cold_sig: Signature) {
let cold_pk: Pubkey = 0xc6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5; // 2 * G
checksig(cold_pk, cold_sig);
}
fn refresh_spend(hot_sig: Signature) {
let hot_pk: Pubkey = 0xf9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9; // 3 * G
checksig(hot_pk, hot_sig);
recursive_covenant();
}
enum Action {
Inherit(Signature),
ColdSpend(Signature),
HotSpend(Signature),
}
fn main() {
match witness::ACTION {
Action::Inherit(sig: Signature) => inherit_spend(sig),
Action::ColdSpend(sig: Signature) => cold_spend(sig),
Action::HotSpend(sig: Signature) => refresh_spend(sig),
}
}
```
This contract allows an heir to claim an inheritance (held by the contract) after the creator has died. It also enforces a mandatory time delay in the claim process so that the heir can only claim the inheritance when the creator hasn't "refreshed" the contract within the past 18 days.
```mermaid
flowchart TD
Z((Creator's wallet)) -->|Asset deposit| A[Last will covenant]
A -->|Hot key signature Refresh covenant| A
A -->|Cold key signature Creator withdrawal| Z
A -->|Inheritor signature Inherit assets Only for assets held over 18 days| C((Inheritor's wallet))
```
The creator is expected to periodically refresh the contract by sending the contract's assets back to the same contract (via the **hot key**). Importantly, the "hot key" is restricted to authorizing this specific form of transaction: it can only authorize sending assets back to the same contract. (This restriction on the hot key's power, the fact that it can't *remove* assets from the covenant's control, is the part of this example that uses covenant logic.)
The creator's more secure **cold key** isn't needed routinely, but can be used to authorize arbitrary withdrawals if the contract creator no longer wishes to keep certain assets stored inside the contract.
The inheritor's **inheritor key** can authorize arbitrary withdrawals from the contract, but only of [UTXO](../glossary.md#utxo)s that have been held by the contract for at least 18 days. So, whenever the creator refreshes the covenant with a hot key transaction, this period begins anew.
The covenant logic in `last_will.simf` is enforced by ensuring that a specific [output](../glossary.md#output) has a script hash matching the script hash of the [input](../glossary.md#input) from which the Simplicity program is being run. This is determined using the relevant [jet](../glossary.md#jet)s.
## SimplicityHL state management
The `last_will.simf` example above is **stateless**: it doesn't require the contract to actively remember anything. UTXOs' age is represented on the blockchain itself, and the contract automatically blocks the inheritor from transferring fresh UTXOs.
The [execution environment of a Simplicity program](execution-model.md) is highly constrained; specifically, a Simplicity program can't perform any kind of input or output or network access, and can't even directly access the contents of earlier transactions on the blockchain.
Still, complex contracts will often need to enforce multiple related transactions and "remember" facts and details over time. For example, they may need to record the existence or size of a debt, or record whether a certain action has already been taken. How can they do so in Simplicity's transaction-based architecture, without being able to save or load anything corresponding to files or database entries?
The recommended mechanism uses **cryptographic commitments**. These incorporate the state reference into the on-chain address of a copy of the Simplicity program itself, which the program can confirm by [introspection](../glossary.md#introspection) when it is run.
Effectively, this method generates an address for a program in a way that inherently incorporates a cryptographic reference to specific state; when that program is run, it can confirm that the state it was given via a [witness](../glossary.md#witness) matches the state that it expects to have according to its own address. It can immediately reject any proposed transactions that attempt to delete or tamper with the state.
This approach provides a way for a contract to maintain state (the values of specific variables) between one transaction and another transaction, enforcing a guarantee that the later transaction has access to the correct values of those variables and that no one has modified them. The contract does so by enforcing that outputs, including address references to versions of the same contract, contain cryptographic references to that state ("save"). A version of the same or a related contract can then enforce in a later transaction that suggested state provided to that new transaction matches up correctly with those cryptographic references ("load").
## Wallet-side state storage and on-chain verification
This means that the actual state data isn't directly stored "inside of" the contract; the contract possesses a reliable way to *verify* state that is provided to it, but that state information is typically physically stored inside of a user's wallet software, and passed back to the contract whenever a new transaction involving the contract is constructed. Web developers may recognize this pattern as akin to digitally signed tokens (such as [JWT](https://www.jwt.io/introduction#what-is-json-web-token)) provided by clients to web applications. In the web application setting, the physical storage of the state information can be offloaded to the client, and a digital signature proves that the client didn't modify its contents. The "client" (the wallet or other software that is constructing future transactions) similarly has the responsibility to store and provide the state information back to the contract, under a form of cryptographic authentication preventing modification, although the exact cryptographic details are different from the JWT analogy.
In the Simplicity context, the cryptographic commitment to the state is actually used as part of the contract's on-chain address, so performing a state update will actually mean deriving an updated address for the same contract (or a specifically chosen successor contract), and committing a transaction that forwards assets from the contract's prior address to the updated address. Those forwarded assets' spending conditions are then controlled by the updated version of the contract, which is cryptographically bound to the updated version of the state information.
Whenever a [covenant](../glossary.md#covenant) performs a state update, it sends assets to a new copy of itself with a *different on-chain address* encoding a reference to the updated state data. A transaction can update state without moving any assets in or out of the contract, merely sending them to the new copy with the new address. Client software meant to interact with the contract must be programmed to observe that this has happened so that new transactions are always performed with the most current updated copy.
Although wallet software should generally store contract state in order to provide it back to the contract when performing subsequent transactions, this information could be recalculated if necessary by examining blockchain history, because all Simplicity program execution is deterministic and based on public information. Thus, state information isn't generally confidential; locally replaying the evolution of a contract will ordinarily reveal what the expected state for the next transaction should be. (An initial state commitment when a copy of a program receives assets for the first time could require witness values that haven't yet been publicly revealed anywhere, much as the code of the program may not have been publicly revealed. Storing state in a Merkle tree also optionally permits the state to be partially revealed as it is actually needed. For example, state of one branch of the program could be stored in one branch of the Merkle tree and state of another branch could be stored in another branch. The program could be designed so that the witness only reveals the part of the state that is actually used.)
## Basic state management mechanism
The modified address is calculated by storing a 256-bit state value in [Taproot](../glossary.md#taproot) alongside a commitment to the Simplicity program's code. Sample code to assert that input state is consistent with the program's address ("load"), and to assert that an output address is consistent with a commitment to a specific updated state value ("store") appears below. The `hal-simplicity simplicity pset update-input` command has also been updated with a `-s` flag that provides an input state value to the program; a copy should also be provided in the witness as `witness::STATE`.
The Rust version of this logic is found in [`state_management/bytes32_tr_storage`](https://github.com/BlockstreamResearch/simplicity-contracts/tree/main/crates/contracts/src/state_management/bytes32_tr_storage), including Rust code to build witnesses and transactions. This shows how a wallet can actually track and provide state back to the contract in a subsequent transaction.
Currently, this allows a program, if structured as a [covenant](../glossary.md#covenant), to pass itself state updates across subsequent transactions. The state information is always represented as a single uninterpreted `u256` integer value. This is conveniently the size of the output of a SHA256 hash, so a program can choose to interpret this value as a SHA256 hash of specified data items that are provided in a [witness](../glossary.md#witness), in a specific order. The program can then commit to specific values of these chosen data items between one transaction and the next. A more elegant approach would be interpreting this `u256` value as a reference to the root of a [Merkle tree](../glossary.md#merkle-tree).
A discussion and demonstration of this approach took place in [the December 23, 2025 Simplicity Office Hours session](https://youtu.be/ry2wQelP8Kc).
## Example with integer counter
This example contract, `third_time.simf`, uses the state management mechanism described in the prior section. It enforces the saying "the third time's the charm"; it requires a series of three distinct transactions in order to perform a withdrawal.
???+ "Click to hide source code"
```simplicityhl
/*
* "Third Time's The Charm" covenant demonstrating Simplicity state management
*
* This covenant requires three transactions in a row in order to release the
* locked coins. It counts how many of these transactions have been seen so
* far using the witness::STATE value.
*
* State management:
* Computes the "State Commitment" — the expected Script PubKey (address)
* for a specific state value.
*
* HOW IT WORKS:
* In Simplicity, state isn't stored in a dedicated database. Instead,
* it is verified via a "Commitment Scheme" inside the Taproot tree of the UTXO.
*
* This function reconstructs the Taproot structure to validate that the provided
* witness data (state_data) was indeed cryptographically embedded into the
* transaction output that is currently being spent.
*
* LOGIC FLOW:
* 1. Takes state_data (passed via witness at runtime).
* 2. Hashes it as a non-executable TapData leaf.
* 3. Combines it with the current program's CMR (tapleaf_hash).
* 4. Derives the tweaked_key (Internal Key + Merkle Root).
* 5. Returns the final SHA256 script hash (SegWit v1).
*
* USAGE:
* - For load(), we verify: CalculatedHash(witness::STATE) == input_script_hash.
* - For store(), we verify: CalculatedHash(updated_state) == output_script_hash.
* - This assertion proves that the UTXO is "locked" not just by the code,
* but specifically by THIS instance of the state data. So the on-chain address
* necessarily changes after each state-updating transaction in order to reflect
* a cryptographic commitment to the appropriate state data.
*
* Surrounding context tracks the state_data, interpreting its low 64 bits as
* a counter. The counter can be updated by an "update" transaction sending
* value back to the same contract. When the counter is equal to 2 or more,
* the "withdraw" transaction is permitted, sending some or all value
* to an arbitrary output address instead of back to the contract. Both the
* "update" and "withdraw" transactions must include a valid signature by
* the authorized key (here hardcoded in check_sig() for demonstration
* purposes).
*
* When initially funding the contract, use witness::STATE = 0.
*/
fn check_sig(sig: Signature) {
let authorized_key: Pubkey = 0x79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798; // 1 * G
let msg: u256 = jet::sig_all_hash();
jet::bip_0340_verify((authorized_key, msg), sig);
}
fn script_hash_for_input_script(state_data: u256) -> u256 {
// This is the bulk of our "compute state commitment" logic from above.
let tap_leaf: u256 = jet::tapleaf_hash();
let state_ctx1: Ctx8 = jet::tapdata_init();
let state_ctx2: Ctx8 = jet::sha_256_ctx_8_add_32(state_ctx1, state_data);
let state_leaf: u256 = jet::sha_256_ctx_8_finalize(state_ctx2);
let tap_node: u256 = jet::build_tapbranch(tap_leaf, state_leaf);
// Compute a taptweak using this.
let bip0341_key: u256 = 0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0;
let tweaked_key: u256 = jet::build_taptweak(bip0341_key, tap_node);
// Turn the taptweak into a script hash
let hash_ctx1: Ctx8 = jet::sha_256_ctx_8_init();
let hash_ctx2: Ctx8 = jet::sha_256_ctx_8_add_2(hash_ctx1, 0x5120); // Segwit v1, length 32
let hash_ctx3: Ctx8 = jet::sha_256_ctx_8_add_32(hash_ctx2, tweaked_key);
jet::sha_256_ctx_8_finalize(hash_ctx3)
}
fn load(state_data: u256) {
// Assert that the input is correct, i.e. "load".
assert!(jet::eq_256(
script_hash_for_input_script(state_data),
unwrap(jet::input_script_hash(jet::current_index()))
));
}
fn store(new_state: u256) {
assert!(jet::eq_256(
script_hash_for_input_script(new_state),
unwrap(jet::output_script_hash(jet::current_index()))
));
}
fn update(sig: Signature, state_data: u256) {
// In this case, if the signature is correct, we approve the transaction
// if the destination is the same contract but with a correct internal
// state update that increases the count by 1.
// Check that the signature is correct.
check_sig(sig);
let (state1, state2, state3, count): (u64, u64, u64, u64) = ::into(state_data);
let (carry, new_count): (bool, u64) = jet::increment_64(count);
// Check for overflow.
assert!(jet::eq_1(::into(carry), 0));
// Assert that the output is being sent to a correctly-updated copy of this
// specific program, i.e. "store".
let new_state: u256 = <(u64, u64, u64, u64)>::into((state1, state2, state3, new_count));
store(new_state);
// Assert that there are exactly two outputs in the currently-proposed
// transaction (corresponding to the new contract and the network fee
// payment). Without this logic, the updater could cause coins to leak out
// of the covenant by sending some of the input value to an uncontrolled
// output address that isn't a copy of this contract. (Even with this
// logic, the fee amount itself isn't constrained here, and the updater
// could choose to give away some or all of the stored value to miners in
// the form of an excessive fee.)
assert!(jet::eq_32(jet::num_outputs(), 2));
assert!(unwrap(jet::output_is_fee(1)));
}
fn withdraw(sig: Signature, state_data: u256) {
// In this case, if the signature is correct, and the count is already at
// least 2, we approve the transaction (allowing the destination(s) and
// amount(s) indicated by the proposer).
// Check that the signature is correct.
check_sig(sig);
// Assert that the count from the provided state is already at least 2.
let (_, _, _, count): (u64, u64, u64, u64) = ::into(state_data);
assert!(jet::le_64(2, count));
}
fn main() {
// Assert that the provided state_data is correct according to this
// program's cryptographic commitment.
let state_data: u256 = witness::STATE;
load(state_data);
match witness::UPDATE_OR_WITHDRAW {
Left(sig: Signature) => update(sig, state_data),
Right(sig2: Signature) => withdraw(sig2, state_data),
}
}
```
The use of `jet::le_64` means that one can update *at least* twice before a withdrawal. If this is replaced by `jet::eq_64`, the contract will enforce *exactly* two updates before a withdrawal.
As described earlier, each of the intermediate transactions will be sent to a **different on-chain address** representing a commitment to the same Simplicity covenant, but with different state. Thus, the `update` transactions in the diagram below each have corresponding distinct destination addresses.
```mermaid
flowchart TD
A((Faucet)) -->|Deposit| B[Contract count=0]
B -->|Update| C[Contract count=1]
C -->|Update| D[Contract count=2]
D -->|Withdraw| E((User wallet))
```
### Constraining state updates
Contracts must include logic to ensure that only authorized parties can perform transactions that cause state updates. The contract above does this with `check_sig()`, requiring that all transactions be signed by an authorized party.
The `update()` function in this example enforces further constraints on outputs, such as constraining the total number of outputs to exactly two. The first output must be an updated version of the same contract, while the second output must be a network fee payment. Without this constraint, the updater could add an additional output that leaks contract funds to an unrelated address.
A real financial application may need to include logic to enforce a variety of further constraints. For example:
* The contract may be designed to deal with a specified [asset](../glossary.md#asset), such as Liquid bitcoin (LBTC). Since [Liquid](../glossary.md#liquid) supports a variety of assets, the contract should inspect the assets being transferred to confirm that they're always of the expected kinds. In most contexts, payments shouldn't be allowed to be made with arbitrary assets.
* The contract may need to constrain fee amounts in order to prevent parties from intentionally donating the contract's assets to miners via excessive fees. The contract may also require a party performing an update to pay the network fee. In that case, it must allow that party to provide a fee input in the transaction that covers the transaction fee, and may also allow the party to receive change from the fee input.
## Next steps
For more about constraining output destinations in general, see "[Constraining Destinations](destinations.md)".
As noted above, a program can store multiple values by interpreting the commitment as a SHA256 hash, where the `load()` and `store()` routines verify that the hash value matches the hash calculated from all the relevant witness values. In this case, the contract developer will create a convention for exactly which values are hashed and in which order; that convention is then used whenever state is stored or loaded.
SimplicityHL will have library functions reflecting the `load` and `store` patterns to make it easier for developers to use these mechanisms without writing boilerplate referring to the lower-level details of the cryptographic state commitment. It will also offer a reference implementation of Merkle tree creation and verification to make it easier for developers to load and store multiple values in a standardized and elegant way.
### Constraining Destinations
# Constraining destinations
A contract that pays someone has to be able to say whom it will pay.
The most common pattern for authorizing a spend is to require a digital
signature by a specific key. The owner of that key is often presumed to
be allowed to send assets to any address.
Other patterns constrain the recipient address somehow. A
[covenant](../glossary.md#covenant) sends assets back to itself. A
withdrawal path may be allowed to reach only one hard-coded beneficiary.
A recovery path may pay a destination fixed when the contract was
written. Each of these is a constraint on where value is allowed to go.
Simplicity has no address type. The [jets](../glossary.md#jet) that
describe an [output](../glossary.md#output) return a single 32-byte
value, and a program constrains a destination address by comparing that
value against a hash it trusts.
## Require a payment to one destination
`jet::output_script_hash(i)` returns the SHA-256 hash of the scriptPubKey of output `i`, or
`None` if there is no such output. This hash can then be compared against an expected value:
```simplicityhl,run,tx txid="0440094a1c5d16ccae819750a19b5f2e926760de112c6f88d81361c0b48f57c2" title="Output 1 must pay a specific destination"
fn main() {
// SHA-256 of the destination's scriptPubKey, computed off-chain.
let expected: u256 = 0x3d510ce40240546ef06a28222fd212b28df743ac812bdbd2142958ceccbc47d3;
let actual: u256 = unwrap(jet::output_script_hash(1));
let actual: u256 = dbg!(actual);
assert!(jet::eq_256(expected, actual));
}
```
That runs against a real [Liquid](../glossary.md#liquid) testnet transaction, whose output 1
pays 875,121 satoshis of test Liquid bitcoin (tLBTC) to
`tex1p5ue6zd30fk23cvmpz5hj929ldld3nlvv5p5u58lnl7t8hzze8wgqjsnr3k`. Changing `expected` at all
will cause the hash of the destination address not to match, and the spend will fail.
The program doesn't learn anything else about that output. It doesn't know that the destination is a
[Taproot](../glossary.md#taproot) output, which key it pays, or which network it belongs to.
## Why the destination is a hash
An address is a human-facing encoding of exactly one scriptPubKey. It carries a network prefix,
a payload, a checksum, and on Liquid an optional blinding key. The blockchain doesn't natively
store or represent addresses. An output contains a scriptPubKey, and
a program is given a hash of that.
```mermaid
flowchart LR
A["Address tex1p5ue6zd… an encoding, for humans"]
B["scriptPubKey 5120a733a1… the bytes inside the output"]
C["SHA-256 digest 3d510ce4… all a Simplicity program can see"]
A -->|"decode"| B
B -->|"hash"| C
```
Only the third value is reachable from a program, and its type is `u256`: fixed width, and the
product of a one-way function. A program can therefore test a destination for equality, and
can't do anything else with it. It can't read out a public key, recover a script, discover which
kind of address was used, or learn how long the scriptPubKey was.
### What an output actually contains
An output carries an asset, an amount, a nonce, a scriptPubKey, and proofs for any blinded
amount or asset. It doesn't carry any program. For a Taproot destination the
scriptPubKey holds one tweaked key, and the script tree behind that key is chosen by whoever
eventually spends the output. It appears in that future transaction, and never appears at all
if the output is spent by key path or is never spent.
There is therefore no richer view of a destination available for a jet to return. Any detail
beyond the scriptPubKey has to be supplied by the party building the transaction.
A program can reconstruct the scriptPubKey of an output only when it already knows the program
behind it, which in practice almost always means a copy of itself. See
[a destination computed by the program](#a-destination-computed-by-the-program).
### Hashing a value that is already a hash
Some scriptPubKeys already contain a hash. A P2WPKH scriptPubKey is `0x0014` followed by
`HASH160` of a public key, and hashing it again can look circular.
The two hashes belong to different layers. The inner hash is part of the address payload:
Bitcoin hashes a key so that a lock can be short, and that hash is the destination's own
identity. The outer hash is Simplicity's view of the finished lock, turning a variable-length
script into one fixed-width value that a program can compare. Neither hash knows about the
other, and the outer one is applied to the serialized scriptPubKey bytes whatever those bytes
happen to be.
## Computing the hash off-chain
The 32 bytes a program compares against normally come from an address held by a person or a
wallet. Computing them takes two steps: decode the [address](../glossary.md#address) to its
scriptPubKey, then hash the scriptPubKey bytes with SHA-256.
Every method below must produce the following result for the address paid by output 1 of the
example transaction above. Use it as a test vector for any tool or code you adopt:
```text
address: tex1p5ue6zd30fk23cvmpz5hj929ldld3nlvv5p5u58lnl7t8hzze8wgqjsnr3k
scriptPubKey: 5120a733a1362f4d951c3361152f22a8bf6fdb19fd8ca069ca1ff3ff967b88593b90
scriptPubKey hash: 3d510ce40240546ef06a28222fd212b28df743ac812bdbd2142958ceccbc47d3
```
A tool that prints `d347bcccce582914d2db2b81ac43f78db212d22f22286af06e544002e40c513d` instead
has reversed the bytes. See [byte order](#byte-order).
=== "hal-simplicity"
[`hal-simplicity`](toolchain.md#hal-simplicity) decodes Liquid addresses, including
[confidential](../glossary.md#confidential) ones, and reports the scriptPubKey in the
`script_pub_key.hex` field. Pipe that field to a SHA-256 implementation:
```bash
ADDRESS=tex1p5ue6zd30fk23cvmpz5hj929ldld3nlvv5p5u58lnl7t8hzze8wgqjsnr3k
hal-simplicity address inspect "$ADDRESS" \
| jq -r .script_pub_key.hex \
| python3 -c 'import sys, hashlib; print(hashlib.sha256(bytes.fromhex(sys.stdin.read().strip())).hexdigest())'
```
`python3` does the hashing because the command-line SHA-256 tool isn't named the same
thing on every system: some provide `sha256sum`, others only `shasum -a 256`.
=== "JavaScript"
[`liquidjs-lib`](https://github.com/vulpemventures/liquidjs-lib) decodes Liquid
addresses, and Node.js's built-in `crypto` module computes SHA-256. Install the library
with `npm install liquidjs-lib`, then save this as `spk-hash.js`:
```javascript
const { address, networks } = require('liquidjs-lib');
const { createHash } = require('crypto');
// Use networks.liquid for a Liquid mainnet address.
const network = networks.testnet;
const scriptPubKey = address.toOutputScript(process.argv[2], network);
console.log(createHash('sha256').update(scriptPubKey).digest('hex'));
```
Run it with the address as its argument:
```bash
node spk-hash.js tex1p5ue6zd30fk23cvmpz5hj929ldld3nlvv5p5u58lnl7t8hzze8wgqjsnr3k
```
Published JavaScript for computing an Electrum `scripthash` follows the same steps and
adds `.reverse()` to the digest before converting it to hex. Leave that call out.
=== "Rust"
The [`elements`](https://crates.io/crates/elements) crate decodes addresses and
re-exports SHA-256. It is the route to prefer inside an application, because
[`rust-simplicity`](wallet.md#simplicityhl-rust-simplicity-and-simplex) already depends
on it, so it doesn't add anything to the build.
```rust
use std::str::FromStr;
use elements::hashes::{sha256, Hash};
use elements::Address;
fn main() {
let address =
Address::from_str("tex1p5ue6zd30fk23cvmpz5hj929ldld3nlvv5p5u58lnl7t8hzze8wgqjsnr3k")
.expect("valid Liquid address");
let hash = sha256::Hash::hash(address.script_pubkey().as_bytes());
println!("{hash}");
}
```
`sha256::Hash` displays its bytes in the order SHA-256 produces them. The double-SHA-256
types used for transaction and block IDs (`Txid`, `BlockHash`) display reversed, so
don't route the digest through one of those.
=== "Elements node"
`elements-cli validateaddress` reports the scriptPubKey in its `scriptPubKey` field:
```bash
elements-cli validateaddress "$ADDRESS" \
| jq -r .scriptPubKey \
| python3 -c 'import sys, hashlib; print(hashlib.sha256(bytes.fromhex(sys.stdin.read().strip())).hexdigest())'
```
The node accepts only addresses for the chain it is running. For an address from another
chain, `validateaddress` reports `"isvalid": false` with no `scriptPubKey` field, so `jq`
prints `null` and Python fails with
`ValueError: non-hexadecimal number found in fromhex() arg at position 0`.
### Checking a hash against the chain
Two checks compare a computed hash against data that doesn't come from your own code.
The [Esplora](https://github.com/Blockstream/esplora/blob/master/API.md) API indexes address
history by the same unreversed scriptPubKey hash. For an address that has received funds, a
correct hash returns that history:
```bash
curl -s https://blockstream.info/liquidtestnet/api/scripthash/3d510ce40240546ef06a28222fd212b28df743ac812bdbd2142958ceccbc47d3 \
| jq .chain_stats.tx_count
```
For Liquid mainnet, replace `liquidtestnet` with `liquid` in the URL. A nonzero count confirms
the hash. A count of zero means either that the hash is wrong (for example, reversed) or that
the address has never received funds, so this check can confirm a hash but can't rule one out.
The first runnable example on this page prints `actual` with `dbg!`: the value
`jet::output_script_hash` returns for output 1 of the transaction in its txid field. Changing
the txid, and the output index in the code, shows the value the jet returns for any output of
any Liquid testnet transaction.
### Byte order
!!! warning "The digest is used exactly as SHA-256 produces it"
These jets hash the relevant bytes and stop; **they don't reverse the result**.
This matters because the similar term "script hash" reaches many developers through the
Electrum server protocol, where a `scripthash` is the SHA-256 of a scriptPubKey
**byte-reversed**. The reversal follows Bitcoin's convention for displaying transaction
and block hashes. It isn't part of any consensus rule. The Esplora API also uses the name
`scripthash`, but doesn't reverse it, and its values match the jets.
Code written for Electrum servers produces a reversed value, which is the right *length*
but can never match the unreversed scriptPubKey hashes generated by Simplicity jets. Be
careful not to hard-code such reversed hashes in address whitelists in Simplicity
programs, as the resulting spending conditions will be unsatisfiable and assets may
get stuck.
The same scriptPubKey on testnet and mainnet:
Liquid testnet address: `tex1p2zffkaxp5py4fdutfdsrt6t6tcrc5ks09rkfd428hlhf4n5q8tqqn680xl`
*Correct* scriptPubKey hash: `cc2b404255f9225891b56c041d4908c373b49acf17abc0889b9644c9bc3b83ad`
*Incorrect* Electrum-style reversed hash: `ad833bbcc944969b88c0ab17cf9ab473c308491d046cb5915822f95542402bcc`
Liquid mainnet address: `ex1p2zffkaxp5py4fdutfdsrt6t6tcrc5ks09rkfd428hlhf4n5q8tqqjr4ghs`
*Correct* scriptPubKey hash: `cc2b404255f9225891b56c041d4908c373b49acf17abc0889b9644c9bc3b83ad`
*Incorrect* Electrum-style reversed hash: `ad833bbcc944969b88c0ab17cf9ab473c308491d046cb5915822f95542402bcc`
(The hashes for the testnet and mainnet addresses above are intentionally identical. A
network prefix is part of the address encoding, not of the scriptPubKey.)
## Whitelisting several destinations
A whitelist is the same comparison, repeated. Each permitted destination adds 32 bytes to the
program and one `jet::eq_256`:
```simplicityhl,run,tx txid="0440094a1c5d16ccae819750a19b5f2e926760de112c6f88d81361c0b48f57c2" title="A two-entry destination whitelist"
// Accept the destination if it matches the first permitted hash; otherwise try the
// second. Longer lists nest the same way.
fn is_whitelisted(script_hash: u256) -> bool {
let first: u256 = 0x15323a62a3948149ef617748d1acb45056f123740e9d44b43b23a4aecf0a542a;
let second: u256 = 0x3d510ce40240546ef06a28222fd212b28df743ac812bdbd2142958ceccbc47d3;
match jet::eq_256(first, script_hash) {
true => true,
false => jet::eq_256(second, script_hash),
}
}
fn main() {
assert!(is_whitelisted(unwrap(jet::output_script_hash(1))));
}
```
Both hashes above are real destinations in the example transaction: `first` is its output 0 and
`second` is its output 1. The program checks output 1, which is on the list, so it holds.
A destination that isn't on the list fails at run time, with no distinct error to catch. The
assertion isn't satisfied:
```simplicityhl,run,tx,expect=run-error txid="0440094a1c5d16ccae819750a19b5f2e926760de112c6f88d81361c0b48f57c2" title="A destination that isn't whitelisted"
fn main() {
// Only output 0's destination is permitted here.
let permitted: u256 = 0x15323a62a3948149ef617748d1acb45056f123740e9d44b43b23a4aecf0a542a;
// ...but output 1 is the one being checked.
assert!(jet::eq_256(permitted, unwrap(jet::output_script_hash(1))));
}
```
A long whitelist may be more efficiently represented as a [Merkle tree](../glossary.md#merkle-tree),
with the witness supplying a membership proof, so that program size stays constant. That
mechanism is similar to the one described under [state management](state.md#next-steps), but applied
to a list of destinations rather than to a contract's own state.
## Destinations the program doesn't know in advance
A hash compiled into the program can only name a destination that was known when the contract
was written. A destination chosen later has to be trusted for another reason: for example, because
a key approved it, an earlier transaction recorded it, or the program derived it.
When an output of the transaction being validated pays the destination, the program reads its
hash from `jet::output_script_hash`, and the witness doesn't need to supply it. The witness
supplies whatever makes that hash trustworthy, such as a signature, a Merkle path, or an output
index. Supplying the hash itself as witness data is necessary only when no output of the current
transaction pays the destination, which happens when a transaction records a destination for a
later transaction to pay.
### A destination approved by a key
A key hard-coded in the contract can approve destinations after the contract is deployed, so
the whitelist can grow without changing the contract. The program reads the destination's hash
from the transaction and checks the approver's signature over it:
```simplicityhl
fn main() {
let approver: Pubkey = param::APPROVER;
let contract_tag: u256 = param::CONTRACT_TAG;
// The signed message is SHA-256(contract_tag || scriptPubKey hash of output 1).
let destination: u256 = unwrap(jet::output_script_hash(1));
let ctx: Ctx8 = jet::sha_256_ctx_8_init();
let ctx: Ctx8 = jet::sha_256_ctx_8_add_32(ctx, contract_tag);
let ctx: Ctx8 = jet::sha_256_ctx_8_add_32(ctx, destination);
let message: u256 = jet::sha_256_ctx_8_finalize(ctx);
jet::bip_0340_verify((approver, message), witness::APPROVAL);
}
```
`APPROVER` and `CONTRACT_TAG` are [parameters](../glossary.md#parameter) fixed when the contract
is compiled. The approver signs the message off-chain and gives the signature to whoever builds
the spending transaction, which supplies it as `APPROVAL`.
The tag is a value unique to this contract. Without it, the signed message is the destination's
hash alone, and an approval for one contract is also valid for every other contract that trusts
the same key.
An approval covers the destination and nothing else about the transaction. Once it has
appeared in a spending transaction, anyone can reuse it to pay the same destination from this
contract again, and the approver can't withdraw it. That suits a destination meant to stay
approved, such as a cold-storage address. An approval that should expire or be used only once
needs further fields in the signed message, supplied in the witness and checked by the program,
or a record in the contract's state. As with any destination check, the program also has to
constrain the amount (see
[what a destination constraint doesn't do](#what-a-destination-constraint-doesnt-do)).
### A destination recorded by an earlier transaction
A contract can also fix a destination before the transaction that pays
it. One transaction records the destination's hash in the contract's
[state](state.md), and a later transaction enforces that payment is made
to that destination. The recording transaction can apply any rule for
accepting a destination: the key approval check above, a deposit and a
timelock, or any other condition the program can verify. The recording
transaction is also the case where the witness has to supply the hash,
because none of its outputs pays that destination: the contract pays
itself, with the new hash committed in its state.
A claimant records a destination, the contract's address changes to commit
to it, and from that point the contract pays that destination until
a later, equally guarded update replaces it. Contracts that release
value in exchange for revealed information need this property. Fixing
the destination before the information becomes public is what stops a
third party from copying the witness out of the mempool and redirecting
the payment (a form of "front-running" or "witness swiping").
When the later transaction pays out, the program can read the
destination's hash from `jet::output_script_hash` and use it to recompute
the state commitment, so the witness doesn't need to supply the hash
a second time.
!!! warning "An unauthenticated destination doesn't constrain anything"
If anyone can rewrite a contract's recorded destination at any time, whoever writes last
decides where the value goes. Recording a destination has to be guarded (by a key approval, a
deposit, a timelock, or some combination), just as any other state update is.
### A destination computed by the program
When the destination is *derived* rather than known, the program can build the scriptPubKey
bytes itself and hash them with the SHA-256 context jets. This is what a recursive covenant
does: it reconstructs the Taproot output that a copy of itself would have, so that it can
require the next output to be that copy.
The final step of that construction is the scriptPubKey template:
```simplicityhl
// Serialize a SegWit v1 output with a 32-byte program, `0x5120` followed by the key, and
// hash it. The result is comparable against jet::output_script_hash.
let ctx: Ctx8 = jet::sha_256_ctx_8_init();
let ctx: Ctx8 = jet::sha_256_ctx_8_add_2(ctx, 0x5120);
let ctx: Ctx8 = jet::sha_256_ctx_8_add_32(ctx, tweaked_key);
let expected: u256 = jet::sha_256_ctx_8_finalize(ctx);
```
The `tweaked_key` comes from the contract's own [CMR](../glossary.md#cmr) and state. The
[covenants and state management](state.md#basic-state-management-mechanism) page shows the whole
derivation, including where the hardcoded internal key comes from.
Building a scriptPubKey in-program means committing to one output template, and how expensive
that is depends on the available [jets](jets.md):
| Output type | scriptPubKey | Constructible in a program? |
| --- | --- | --- |
| P2TR | `0x5120` followed by a 32-byte output key | Yes, from a key the program computes |
| P2WSH | `0x0020` followed by `sha256(witnessScript)` | Yes, from a script the program hashes |
| P2WPKH, P2PKH, P2SH | contains a `HASH160` | Yes, but RIPEMD-160 has to be written out by hand |
The last row is unreasonably expensive for most applications, because there is no jet to
compute RIPEMD-160. The practical choice is to compute the hash off-chain and use one of the
other routes on this page: hard-code it, approve it with a key, or record it in state.
## What a destination constraint doesn't do
| The constraint doesn't | Because |
| --- | --- |
| force or forbid a confidential payment | A blinding key isn't part of a scriptPubKey, so a confidential Liquid address and its unconfidential form hash to the same value. This also means a destination check doesn't need any changes to work under [Confidential Transactions](../glossary.md#confidential) |
| pin the network | The same payload on testnet and mainnet produces the same scriptPubKey, and so the same hash. A hash can't be used to confirm that an address was a testnet one |
| hide the destination | The hash commits to a destination without publishing it, but anyone who already suspects a particular address can confirm it by hashing. It is a commitment, not a hiding commitment |
| say anything about other outputs | Constraining output 1 leaves every other output free. A contract that cares how much value leaves it must also constrain the output count, the fee output, and the [asset](../glossary.md#asset) and amount of each output it names |
| control who funds the contract | Anyone can pay to a contract's address. A program constrains the transaction that spends an output, never the transaction that created it |
Neglecting the fourth row is a common mistake. Pinning a destination while leaving the
amount unconstrained permits a transaction that pays the right party a single satoshi and sends
the rest somewhere else. See
[constraining state updates](state.md#constraining-state-updates) for the checks that belong
alongside a destination check.
## Terminology
"Script hash" names at least four different values in Bitcoin and Elements material, and only
one of them is what these jets return:
| Term as encountered | What it actually is |
| --- | --- |
| P2SH "script hash" | `HASH160` of a redeem script. `hal-simplicity address inspect` reports this in a field named `script_hash` |
| P2WSH "witness script hash" | SHA-256 of a witness script |
| Electrum protocol `scripthash` | SHA-256 of a scriptPubKey, byte-reversed |
| Esplora API `scripthash` | SHA-256 of a scriptPubKey, not reversed (the same value as the jet) |
| `jet::output_script_hash` | SHA-256 of a scriptPubKey, not reversed |
Because of that collision, prose on this site says **scriptPubKey hash** for the value these
jets return, which names the preimage instead of leaving "script" to be guessed. The jet names
themselves are fixed, so `jet::output_script_hash` and `jet::current_script_hash` keep their
spelling. The [jets reference](jets.md#transaction) defines each of them in terms of its
preimage for the same reason.
Esplora and the Electrum protocol both use the identifier `scripthash`, for the unreversed and
reversed digest respectively. This documentation avoids all forms of this term.
## Related pages
* **Covenants and state management:** [the same machinery applied to a contract's own address](state.md), and the mechanism for committing a destination between transactions.
* **Jets reference:** [`output_script_hash`, `input_script_hash`, `current_script_hash`, and the SHA-256 context jets](jets.md#transaction).
* **Toolchain reference:** [`hal-simplicity`](toolchain.md#hal-simplicity), including address inspection and the `-s` state commitment flag.
### Witnesses
# Witnesses in SimplicityHL development
This document describes *witnesses*, which are transaction-time input data for a Simplicity contract provided by the user proposing the transaction. A witness explains what the user wants the contract to do, and convinces the contract that this action is authorized.
When you interact with a Simplicity [contract](../glossary.md#contract) on the blockchain, you'll need to build and attach witness data for each [transaction](../glossary.md#transaction).
The [execution model](execution-model.md) for Simplicity [contract](../glossary.md#contract)s allows the user who is proposing a [transaction](../glossary.md#transaction) to provide input values to the contract. Each contract expects different inputs, but in general they help confirm that the proposed transaction is authorized according to the contract's rules. This is necessary because anyone can propose transactions to spend assets at any time, so a contract needs a clear way to distinguish which transactions are appropriate and which aren't.
One can think of a Simplicity program as a function that deterministically answers "yes" or "no" to each proposed transaction. The input data for this function will be the specific transaction details, together with some user-supplied inputs which are collectively known as a *witness*. The form of the expected witness is determined in advance by the Simplicity program, just as any function definition determines what kind of input that function expects.
The term "witness" here is adopted from its existing use in other kinds of Bitcoin transactions, and originally from a related meaning in computer science.
Among other things, a witness will usually contain digital signatures from some party or parties approving the proposed transaction. It might also include things like
* amounts (for example, how much of an asset is requested to be spent or transferred)
* oracle statements (confirming some fact about the outside world)
* values representing *choices* among several actions that can be taken at a certain moment (for example, whether a payment should proceed or be cancelled and refunded).
The witness is directly attached to the transaction and forms a part of it; if the transaction is confirmed, the witness data will be publicly visible on the blockchain as part of the confirmed transaction.
In an end-user application, witness data will typically be built by wallet or app software that understands how to interact with a certain contract on the user's behalf. During the contract development process, developers might build it manually.
Please note that this document is discussing "inputs" informally in the typical software development sense of [data provided to a function or program](https://en.wikipedia.org/wiki/Parameter_(computer_programming)), not the blockchain-specific sense of the specific [UTXO](../glossary.md#utxo)s consumed by a transaction (which will also be details relevant to many contracts' logic).
For the practical mechanics of building `.wit` files, compiling them with `simc`, and formatting every SimplicityHL type as a witness value, see the [`.wit` file reference](witness-format.md).
### Oracles
# Oracles in Simplicity
[Smart contracts](../glossary.md#smart-contract) in Simplicity, like other on-chain smart contracts, can only directly access or observe [transaction](../glossary.md#transaction) data.
However, contracts often refer to off-chain facts, such as a market price or whether an event has happened.
* What is the price of Bitcoin in dollars (on a specified exchange)?
* What is the price of wheat in Euros (on a specified market with specified delivery terms)?
* Who won the 2026 Super Bowl?
* Did the insured party suffer a covered loss during the term of an insurance contract? If so, how large was that loss?
These facts can be communicated to a contract with the help of an *oracle*, which is simply a trusted party that can make a digitally signed statement that the contract will accept.
Any entity that all of the parties interested in a contract can trust, and that's willing to make digital signatures in a prearranged form, can be an oracle.
The oracle needs to publish a public key and a well-defined format or structure that its statements will follow. These technical details are then encoded into any contract that will rely on that oracle.
When the oracle makes a statement, it communicates the signed statement publicly, or to a party that relies on it. That party then provides the relevant signed oracle statement and signature *in the [witness](../glossary.md#witness)* to a transaction involving a Simplicity contract.
The Simplicity contract receives the signed statement and signature via the witness and can verify their correctness and make a decision based on the content of the oracle statement.
## Examples of oracle statements
For example, an oracle for a yes-or-no event might say:
> We will hash one of the following `u8` values
> `0` representing NO
>
> `1` representing YES
>
> with SHA256 and we will then sign the result with BIP0340 with the key corresponding to public key `0x292cbaf344fc104ff2307cce72e84f13dbfeb6f603fe94938208c6150733b910`.
In this case the oracle could issue the signature `56c9b207945aca49302e26e0f68c7f28ce2801be1c8ed2eb0421d257ab6bf818be854a0a5d08a7346a6ec753c71aaf3c2ec346202ea061f32300f2da81493b40` (a BIP0340 signature of `SHA256(0x00)`) in case the underlying event turns out as NO.
Or a price oracle might say
> We will construct an oracle statement by hashing a `Height` (representing a [Liquid Network](../glossary.md/#liquid) [block height](../glossary.md#height) followed by a `u32` (representing a number of U.S. dollars that were paid on an exchange for 1 BTC in the most recent exchange transaction) with SHA256. We will sign this statement with the BIP0340 key corresponding to `0x292cbaf344fc104ff2307cce72e84f13dbfeb6f603fe94938208c6150733b910`.
The oracle may then publish the values `(height, price, signature)`, representing an instance of such an oracle statement. For example, it might publish
> (`3793375, 70664, 0x63decfbfb76f4b549d840d9c1fc95bf2bbe4d82209cf03d27fd4aef7e92d8d20f6844076588058baf70f34ee7e7a7ac2b44d0db2e1be7a792a474cc1d0544a6f`)
attesting to a price of $70664 observed at the time of Liquid block 3793375.
!!! Note
It's important for the oracle to clearly define the format of its statement, including the specific data types of the included values, in order to prevent any ambiguity about the oracle statement's meaning. For example, it must not be possible to reinterpret part of the block height as part of the price, or vice versa. This example avoids ambiguity by specifying that the height is a `Height` (32 bits) and that the price is a `u32` (32 bits). This makes it clear what each individual bit in the signed statement means.
Then a Simplicity witness using this statement might include
```json
{
"oracle_height": {
"value": "3793375",
"type": "Height"
},
"oracle_price": {
"value": "70664",
"type": "u32"
},
"oracle_signature": {
"value": "0x63decfbfb76f4b549d840d9c1fc95bf2bbe4d82209cf03d27fd4aef7e92d8d20f6844076588058baf70f34ee7e7a7ac2b44d0db2e1be7a792a474cc1d0544a6f",
"type": "Signature"
}
}
```
A SimplicityHL program that's run with this witness can verify it with
```simplicityhl
// Minimum required block height (= 2026-03-09).
// Block height is a 32-bit value.
assert!(jet::lt_32(3790000, witness::oracle_height));
// Hardcoded key of trusted signer
let oracle_pubkey: Pubkey = 0x292cbaf344fc104ff2307cce72e84f13dbfeb6f603fe94938208c6150733b910;
let ctx: Ctx8 = jet::sha_256_ctx_8_init();
let ctx1: Ctx8 = jet::sha_256_ctx_8_add_32(ctx, witness::oracle_height);
let ctx2: Ctx8 = jet::sha_256_ctx_8_add_32(ctx1, witness::oracle_price);
let overall_hash: u256 = jet::sha_256_ctx_8_finalize(ctx2);
jet::bip_0340_verify((oracle_pubkey, overall_hash), witness::oracle_signature);
```
Note that the program recomputes the SHA256 hash of the asserted data values, then checks that the provided oracle signature is a valid signature for that hash. If a party tried to submit a false or modified oracle statement, the oracle's signature wouldn't verify correctly.
The program can then use the validated `witness::oracle_price` value for other logic (for example, calculating a liquidation threshold or a pro-rated refund amount in the [Simplicity Lending Protocol](../use-cases/lending-protocol.md), or determining whether it exceeded a threshold for the conditions of a prediction contract).
A contract can also allow for multiple oracles by accepting any of several different public keys as trusted, providing a different verification path for each key.
## Prediction market example
Resolvr's [Deadcat project](https://github.com/Resolvr-io/deadcat/) includes an example of verifying oracle statements as part of a prediction market implementation. You can see the oracle statement verification logic itself in `verify_oracle_signature()` in [`prediction_market.simf`](https://github.com/Resolvr-io/deadcat/blob/master/src-tauri/crates/deadcat-sdk/contract/prediction_market.simf). A party claiming a redemption from the resolution of a prediction market position needs to provide a matching oracle statement to the contract.
## Oracles for business logic integration
In addition to financial applications like prediction markets and options contracts, oracles have applications for letting smart contracts "query" a company's databases or APIs. In this capacity, an internal oracle can bridge the gap between business systems and the blockchain by making signed statements about the results of API calls.
When a contract needs access to information kept in a database in order to make a decision, oracle mechanisms help work around [the fact that Simplicity contracts can't directly access off-chain data](execution-model.md).
For example, suppose you're creating an application which is only allowed to send withdrawals to explicitly pre-approved addresses. But the list of such addresses may live in a database, not on the blockchain. An internal oracle can help by
1. performing a database lookup,
2. combining the results with a current timestamp and,
3. digitally signing the results.
If a specific address is approved for withdrawals, that oracle statement confirms this fact in a format that can then be provided to the smart contract. If it's not, the oracle statement won't be issued and the transaction won't be completed.
Any kind of business may find this useful for adding back-end business logic to a smart contract application (in exchange for imposing dependencies on transactions). It may be especially relevant to regulated entities building regulated financial products and services, where the creators may want to apply additional off-chain criteria for approval of some on-chain actions.
??? Example
A user wants to withdraw assets from a smart contract to a user-specified address. The user has previously registered this address with a bank that created the contract and is using it to provide an on-chain service.
The user's software contacts the bank and requests an oracle statement to confirm that this transaction is allowed. The bank's systems perform a database lookup, find that the address is approved, and sign a timestamped oracle statement saying so. Now the user's software can provide this oracle statement to the smart contract, along with other user authorization information, to let the contract know that it's allowed to process the withdrawal.
If the address isn't found in the database, the bank's systems decline to issue the oracle statement, and instead let the user know what to do in order to get the address authorized to receive withdrawals.
For bidirectional communications between back-office business systems and a Simplicity smart contract, an indexing system can track on-chain transactions that affect smart contract state, and report the associated state updates to a traditional database.
## The oracle backend
At a technical level, issuing oracle statements for Simplicity contracts requires the following pieces:
* Generating a BIP0340 keypair
* An unambiguous format for structuring oracle statements
* Determining the underlying facts to which the oracle will attest
* Generating oracle statements based on the ascertained facts
* SHA256 hashing
* BIP0340 signing
* Publishing the oracle statements and associated signatures
SHA256 and BIP0340 should generally be used because they're most compatible with the rest of the ecosystem, and because Simplicity has built-in [jets](../glossary.md#jet) to help verify signatures made with them.
!!! warning
Operating a public oracle that smart contracts rely on is a serious responsibility, and may expose the operator to attacks meant to steal its keys or induce it to issue false statements. Oracle operators' security and business continuity best practices are beyond the scope of this document.
## Timeouts
If an oracle completely ceases to operate, it might be impossible to resolve contracts that rely on that oracle's statements. So, many forms of contract that rely on oracles can benefit from a timeout mechanism as a fail-safe. The smart contract can provide a timeout path so that, after a significant period of time has passed after the contract should have been resolved, unclaimed funds can be claimed as a refund by their original senders, or to some predesignated beneficiary.
With this precaution in place, if a relevant oracle statement is never produced, funds aren't locked inside the contract permanently.
### Timelocks
# Timelocks
Timelocks are a scripting feature of Bitcoin and inherited by [Elements](../glossary.md#elements). Timelocks can be used in Simplicity and SimplicityHL to enforce a rule that a [transaction](../glossary.md#transaction) may only happen after a specified amount of time has passed.
This is useful for *timeout* logic. Contracts will often have a timeout branch as a fallback mechanism. This timeout branch can allow parties to receive a refund of their assets if the [contract](../glossary.md#contract) isn't successfully completed. For example, an atomic swap contract has a timeout where the initiator can be refunded if the other party doesn't complete the swap in a specified period of time.
A [vault contract](../glossary.md#vault) can also use timelocks to require a series of transactions, with a specific time delay between them, in order to achieve a withdrawal.
## Timelock measurement units
Timelocks can be expressed in various ways. An *absolute* timelock gives an absolute time after which a transaction may occur ("starting next Monday"), while a *relative* timelock specifies how much later a transaction may occur after a prior transaction ("at least one week after this input was confirmed").
Time can be expressed in terms of *blocks* on the blockchain. A blockchain consists of an ever-growing series of blocks, which can be counted to obtain an ever-increasing timescale. In Simplicity, an absolute timelock measured in blocks is [called](../simplicityhl-reference/type_alias.md) a `Height`, while a relative timelock measured in blocks is called a `Distance`.
!!! note "Block creation intervals"
**[Liquid Network](../glossary.md#liquid) blocks are created once per minute.** This is different from Bitcoin, where a block is created (on average) once every ten minutes.
For example, [Liquid block 3800000](https://liquid.network/block/59d271b0df9808eb59e686be30bf0e3c3faf121a72dbd751e90df7bcaed90533) was created at 12:08:10 UTC on March 16, 2026.
Time can also be expressed in terms of *real time*. In Simplicity, an absolute timelock measured in real time is called a `Time`, while a relative timelock measured in real time is called a `Duration`.
!!! note "Absolute time scale"
In both Bitcoin and Liquid, **the *real time* scale for absolute timelock measurement is [*Unix time*](https://en.wikipedia.org/wiki/Unix_time)** (seconds since January 1, 1970).
For example, `Time` 1234567890 occurred on February 13, 2009, while `Time` 1800000000 will occur on January 15, 2027.
!!! note "Relative time scale"
In both Bitcoin and Liquid, **the units of *real time* for relative timelock measurement are *intervals of 512 seconds***.
Note that the unit of `Duration` is 512 seconds, while the increment of `Time` is 1 second.
For example, one day of real time is slightly less than 169 units of `Duration`.
### Summary
| Item | Absolute/Relative | Type name | Unit/scale |
| ----| --- | --- | --- |
| Blocks *(specified block height)* | Absolute | `Height` | Blockchain blocks |
| Blocks *(block count interval)* | Relative | `Distance` | Blockchain blocks |
| Real time *(specified time)* | Absolute | `Time` | Unix timestamp (seconds since 1970) |
| Real time *(interval)* | Relative | `Duration` | Units of 512 seconds |
You can pick any of these forms of timelock to use in any context in a Simplicity contract. Do not enforce more than one simultaneously, as it may be impossible to verify more than one form of timelock within a single transaction.
## Timelock enforcement mechanisms
When a [UTXO](../glossary.md#utxo) enforces a timelock, any transaction that attempts to spend resources from that UTXO must *assert* its compliance with the timelock. This is done by setting the `sequence` or `locktime` fields inside the transaction.
The timelock enforcement is a two-step process.
(1) The timelock-related [jets](../glossary.md#jet) in Simplicity can read the fields from the transaction and determine whether they obey the applicable timelock requirements.
(2) The blockchain consensus rules (applied by [nodes](../glossary.md#node) verifying transactions) will reject a transaction that asserts `sequence` or `locktime` fields that are still in the future compared to the current block.
Thus, Simplicity logic checks "is my timelock rule satisfied by this transaction's `sequence` or `locktime`?"; blockchain consensus checks "according to its `sequence` or `locktime`, is this transaction acceptable to include in the blockchain yet?".
??? "Detailed example"
Consider a SimplicityHL contract that, at some point, enforces a minimum relative `Distance` of 100 blocks. (A concrete version of the required code appears further below.)
If you want to build a transaction claiming assets from this contract, you will need to set the `sequence` field on each input to at least 100. Suppose there is only one input to your transaction. Then...
* If you don't set `sequence` at all, it will be assumed to be 0, and the timelock enforcement code further below will fail.
* If you set `sequence` to 50, the timelock enforcement code will fail because the `sequence` value is smaller than required.
* If you set `sequence` to 150, the timelock condition *succeeds*. However, if you *submit* this transaction to the Liquid Network blockchain less than 150 minutes after the input transaction, the [node](../glossary.md#node) to which you submitted it will reject it with a `non-BIP68-final` (meaning that it's still too early for the proposed transaction to be valid).
* If you set `sequence` to 150 and submit the transaction at least 150 blocks after the input transaction, the transaction should be valid and accepted on the blockchain (at least as far as the timelock condition is concerned!).
!!! note
Note that the timelock jets can't "look up" the real time in the outside world. Rather, they can look up *minimum* times that the transaction creator claimed the transaction would be submitted.
In lower-level libraries and documentation, these fields are also called `nSequence` and `nLockTime`.
## Absolute timelock in SimplicityHL
Enforcing an absolute timelock in SimplicityHL uses the jets `check_lock_height` (for absolute block height) or `check_lock_time` (for absolute Unix time).
`jet::check_lock_height(min_height: Height)`: Assert that the transaction's locktime is a block height greater than or equal to the provided value. Such a transaction can't be included on the blockchain prior to that block height.
`jet::check_lock_time(min_time: Time)`: Assert that the transaction's locktime is a Unix timestamp strictly greater than or equal to the provided value. Such a transaction can't be included on the blockchain prior to that timestamp.
## Relative timelock in SimplicityHL
A relative timelock is calculated based on the time when a particular UTXO was included in a block.
!!! warning "Deprecated jets"
The Simplicity jets that directly enforce relative timelocks have been deprecated due to an implementation error. However, a workaround is available. This document describes the workaround, not the deprecated jets.
This function enforces a relative distance timelock by calling a combination of related jets.
```simplicityhl
fn enforce_relative_distance(min_distance: Distance) {
// Assert that the current input is spent in a transaction that can
// only appear a distance of at least min_distance blocks after the input's
// UTXO. Panic otherwise.
// Transaction version must be at least 2.
assert!(jet::le_32(2, jet::version()));
// Fetch and parse sequence for current transaction
let parsed_seq: Option> = jet::parse_sequence(jet::current_sequence());
match parsed_seq {
// Failure condition
None => assert!(false),
// This is either a distance or a duration, but only a distance is
// acceptable here.
Some(actual_data: Either) => match actual_data {
// Is the actual distance greater than or equal to the specified min_distance?
Left(actual_distance: Distance) => assert!(jet::le_16(min_distance, actual_distance)),
// A duration isn't acceptable in this context.
Right(actual_duration: Duration) => assert!(false),
},
}
}
```
And this is the equivalent function to enforce a relative duration timelock.
```simplicityhl
fn enforce_relative_duration(min_duration: Duration) {
// Assert that the current input is spent in a transaction that can only
// appear a duration of at least min_duration units of 512 seconds after
// the input's UTXO. Panic otherwise.
// Transaction version must be at least 2.
assert!(jet::le_32(2, jet::version()));
// Fetch and parse sequence for current transaction
let parsed_seq: Option> = jet::parse_sequence(jet::current_sequence());
match parsed_seq {
// Failure condition
None => assert!(false),
// This is either a distance or a duration, but only a duration is
// acceptable here.
Some(actual_data: Either) => match actual_data {
// A distance isn't acceptable in this context.
Left(actual_distance: Distance) => assert!(false),
// Is the actual duration greater than or equal to the specified min_duration?
Right(actual_duration: Duration) => assert!(jet::le_16(min_duration, actual_duration)),
},
}
}
```
For real-time-based timelocks, Bitcoin and Elements use a rule called [Median Time Past](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) when determining the effective current time. This rule induces an extra delay (six minutes for Liquid Network, or about one hour for Bitcoin) for the validity of a transaction that using a real-time-based timelock.
## Creating appropriate transactions
Transactions that consume UTXOs with timelock conditions must be constructed appropriately to assert the appropriate timelock. The necessary properties can be set as follows:
| Kind | Type name | Transaction property |
| ---- | --- | --- |
| Absolute blocks | `Height` | `nSequence = 0xfffffffe` `nLockTime < 500000000` `nLockTime` equal to desired `Height` |
| Absolute time | `Time` | `nSequence = 0xfffffffe` `nLockTime >= 500000000` `nLockTime` equal to desired `Time` (Unix timestamp) |
| Relative blocks | `Distance` | `nSequence < 0x10000` `nSequence` equal to desired `Distance` (`0` ... `0xffff`) |
| Relative time | `Duration` | `nSequence = 0x00400000` + desired `Duration` (`0` ... `0xffff`) |
!!! note "More details"
The values in the table above are simple heuristics for common timelock assertions and don't include all scenarios and options.
For more details on timelock implementation and semantics, please see the Bitcoin timelock specifications in [BIP-65](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki), [BIP-68](https://github.com/bitcoin/bips/blob/master/bip-0068.mediawiki), and [BIP-112](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki).
As noted above, transaction-building tools and APIs may simply refer to the fields as `sequence` and `locktime`.
## No maximum time constraints
!!! warning "Timelocks enforce minimum transaction times, not maximum times"
In some smart contracts, one might be tempted to use timelock jets to require a transaction to happen *before* a certain time rather than *after*. However, this isn't supported. **Architecturally, timelocks in Simplicity contracts can only be usefully used to enforce minimum times, not maximum times, when transactions can occur.**
This section further discusses this limitation.
Because of the *monotonicity* property of Bitcoin and related blockchain systems, there is no way to directly express a requirement that a transaction occur *before* a certain block height and not after. These systems enforce a rule that a specific transaction that was valid at some point remains valid at all times in the future. Although you can write SimplicityHL code that asserts that a lock distance is *smaller than* rather than *larger than* a specific numerical value, the person creating the transaction can simply assert a small `sequence` value which will be accepted as valid by the blockchain consensus.
For example, if a contract was funded with a specific input at block height 5000, and the contract asserts that the relative `Distance` when spending that input should be *less than* 100, a transaction spending that input while asserting `sequence` equal to 50 will still be valid when committed at block height 10000, as the criteria 50<10000-5000 (required by the nodes enforcing blockchain consensus rules in the transaction sequence) and 50<100 (for the contract's own logic) are both true. Asserting the lock distance is small requires the use of a correspondingly small `sequence` value, but this does *not* imply that the resulting transaction is necessarily committed to the blockchain within a short time after the inputs it consumes.
### A workaround: state updates and preemption
Because permitted transactions can't automatically expire or become forbidden, Simplicity requires a different approach to enforce deadlines. Instead, you can achieve an *effective* maximum time for an action using a preemption pattern.
The core logic is simple: you can make it impossible to perform an action by removing the assets or state that it relies upon. This requires some party to proactively submit a transaction that performs the preempting action after some time limit has passed. It doesn't happen automatically.
A simple example is a timeout-and-refund mechanism. A contract can provide that, after a certain time period, assets may be transferred back to their original senders. Once a sender proactively claims such a refund, no further actions can be taken with the associated assets because the contract no longer holds them.
In general, a preempting transaction transfers the assets elsewhere, or it updates the [covenant's](../glossary.md#covenant) [state](state.md) to a new version that restricts previously allowed actions. A covenant can be written to permit an authorized party to perform a state update at a certain time which causes previously permitted actions to be forbidden. For example, an authorized update could perform an internal state change to declare a contract "closed" to new claims after a deadline.
An effective deadline is enforced provided that a party is incentivized to perform the required transfer or update action.
### Simplicity SDK (Simplex)
# Simplex
Simplex is a development framework and orchestration tool for [SimplicityHL](../glossary.md#simplicityhl) smart contracts. It assumes a Rust development environment, and helps you create applications and tools in Rust to interact with the underlying contract.
Simplex defines and runs realistic smart contract integration tests in Rust. It runs the tests against a local instance of [`elementsd`](../glossary.md#elementsd), which provides a customizable [Liquid Network](../glossary.md#liquid)-like environment for test transactions, so the tests don't broadcast any transactions on Liquid testnet.
A Simplex project's `Simplex.toml` file (automatically created by `simplex init`, as described below) configures the details of this test environment.
## Installing Simplex
You can get Simplex from the [smplx repository](https://github.com/BlockstreamResearch/smplx), or use the auto-install script:
```bash
curl -L https://smplx.simplicity-lang.org | bash
simplexup
```
When Simplex is installed with `simplexup`, you can rerun `simplexup` at any time to upgrade to the most recent release.
## Rust SDK
Simplex includes a [Rust SDK](https://docs.rs/smplx-sdk) with modules that compile SimplicityHL programs, build [witnesses](../glossary.md#witness) and [transactions](../glossary.md#transaction), and execute programs locally or in on-chain transactions. Applications and integration tests can use it to construct and spend contract transactions.
## Using Simplex
The `simplex` command-line tool creates projects, builds contracts, and runs tests, as described below.
### Creating a project
Run `simplex init` at the top-level directory of the project. This is ordinarily the same as the top-level directory of the associated Rust project (where the `Cargo.toml` file is found).
This step will add a complete starter project in place: `Cargo.toml` (already depending on `smplx-std`), `Simplex.toml`, `src/lib.rs` to let Rust code reference generated [artifacts](../glossary.md#artifacts), and starter contracts and tests.
Add or replace SimplicityHL source files in `simf/` as you go so Simplex can find them.
### Building artifacts
Run `simplex build` at the top-level directory of the project.
This process analyzes the SimplicityHL source code in `simf/` and creates corresponding Rust library files in `src/artifacts`, suitable for including from other Rust code. These library files define functions to build witnesses and blockchain transactions that spend from the individual SimplicityHL contract(s) within the Simplex project.
Whenever the SimplicityHL source code changes, re-run `simplex build` to regenerate the artifacts and keep them in sync with the contract's expectations.
???+ "SimplicityHL package dependencies"
If your contract's `.simf` files import a separate SimplicityHL package (via `use` of an external crate, not just a local module), list it under `[dependencies]` in `Simplex.toml` and run `simplex install` to fetch it before building.
### Creating tests
Create `.rs` files in `tests/` containing your integration tests. Each such file defines a series of named integration tests as Rust functions, each with a prototype like this:
```rust
#[simplex::test]
fn test_name(context: simplex::TestContext) -> anyhow::Result<()> {
// Test code goes here.
Ok(())
}
```
### Running tests
Run `simplex test` to execute your complete integration test suite against a local `elementsd`. Adding `-v` will display verbose output from the tests.
Pass one or more names to run only tests whose names match. Use `--target ` to run the tests in one file, where `` is the file name in `tests/` without `.rs`.
### Persistent regtest instance
`simplex test` normally spins up and tears down its own `elementsd`/Electrs pair for each test. Run `simplex regtest` in a separate terminal to instead start a standalone, long-lived node pair, then point `simplex test` at it via the `[test.rpc]`/`[test.esplora]` entries in `Simplex.toml`. This is useful when you want to inspect chain state between test runs instead of starting from scratch every time.
### Fuzz tests
Simplex (0.1.0+) can also run *fuzz tests*, which check a contract's logic and invariants against many randomly generated inputs instead of one hand-built transaction. Fuzz tests run entirely locally and don't start or contact `elementsd`. Simplex itself runs the contract internally in a Simplicity bit machine environment.
A fuzz test is marked `#[simplex::fuzz]`, receives a `TestContext`, and runs a fuzz engine for one contract, named by the program, arguments, and witness types that `simplex build` generated for it:
```rust
#[simplex::fuzz]
fn fuzz_test_name(context: simplex::TestContext) -> anyhow::Result<()> {
context
.engine::()
.run();
Ok(())
}
```
For each case, the engine generates values for the contract's arguments and witness, compiles the contract with those arguments, spends it in a test transaction, and executes it. By default, a case fails if execution fails. A custom check can instead expect a particular failure, such as a failed `assert!`, to test that the contract rejects invalid transactions. A custom check can also test any other property of the transaction, arguments, witness, and execution result.
The default strategy draws integer values from a mix of uniformly random values, boundary values (such as 0, 1, powers of two and one less than them, and the type's maximum), and integer literals that appear in the contract's source code, plus or minus one. It also sometimes copies one generated value into another field of the same case, so comparisons between fields are exercised. These choices make the fuzzer more likely to find the specific values at which a contract's behavior changes. A purely random strategy is also available.
Randomly generated values are almost never valid signatures, so a contract that checks a signature would reject nearly every case. A fuzz test can ask the test signer to replace a named witness value, such as `SIGNATURE`, with a valid signature over each generated transaction. [`examples/basic/tests/basic_fuzz.rs`](https://github.com/BlockstreamResearch/smplx/blob/master/examples/basic/tests/basic_fuzz.rs) shows this for a pay-to-public-key contract.
Run `simplex test --fuzz` to execute fuzz tests. Plain `simplex test` doesn't run them. The `[test.fuzz]` section of `Simplex.toml` sets the number of cases (`cases`), a fixed random seed (`seed`), and the network whose parameters the test transactions use (`network`). When a fuzz test finds a failing case, Simplex saves its seed and generated values in a `fuzz-failures/` directory, and later runs replay saved cases before generating new ones.
## Examples
[`BlockstreamResearch/smplx/examples`](https://github.com/BlockstreamResearch/smplx/tree/master/examples) contains sample Simplex projects demonstrating how to create integration and fuzz tests.
The current examples are:
* `examples/basic` (demonstrates a pay-to-public-key contract, called `p2pk.simf`, with both integration tests and fuzz tests)
Each has a `README.md` file describing the project and how to invoke its Simplex test suite.
You can also experiment with Simplex online in your browser using the [Simplicity Codespace](https://github.com/codespaces/new/blockstream/simplicity-codespace).
### Modules and Imports
# Introduction to modules and imports
As a SimplicityHL program grows, it's often useful to split it across multiple files, or to reuse functions that were already written for a different project. SimplicityHL has a lightweight system for this, based on two keywords: `pub` (to make something available to other files) and `use` (to bring something from another file into the one you're writing).
This system is loosely based on the module system in the Rust programming language, but is much simpler. This page introduces it from scratch and doesn't assume you've used Rust modules before. For the complete, formal syntax rules, see the [modules reference page](../simplicityhl-reference/modules.md).
!!! warning "This is an experimental feature"
Modules and imports are available since SimplicityHL 0.6.0, and are gated behind an unstable-features flag. To use any of the syntax described on this page, you need a compiler of at least that version, and you currently need to compile with `simc -Z imports program.simf` (equivalently, `--unstable-feature imports`). Omitting that option makes `use`, `mod`, `as`, and `crate::` all fail to compile.
## Making a symbol importable with `pub`
You don't have to do anything special to make a `.simf` file into a module; by default, every file is a module, but functions defined in one file aren't visible from another.
To let a function be imported into another file, put `pub` in front of its definition:
```simplicityhl
// shapes/polygons.simf
pub fn triangle_area(base: u32, height: u32) -> u32 {
let (_, doubled): (bool, u32) = jet::multiply_32(base, height);
let (half, _): (u32, bool) = jet::divide_32(doubled, 2);
half
}
```
Without `pub`, `triangle_area` could only be called from within `polygons.simf` itself.
## Importing a symbol with `use`
To use `triangle_area` from a different file, add a `use` line naming its full path, starting with `crate` and delimited with double colons:
```simplicityhl
// main.simf
use crate::shapes::polygons::triangle_area;
fn main() {
assert!(jet::eq_32(triangle_area(6, 4), 12));
}
```
Given a project laid out like this:
```
project/
├── main.simf
└── shapes/
└── polygons.simf
```
`crate` means "start from the root of my own project": by default, the folder containing the file you pass to `simc` (there's also a `--project-root` flag for less common layouts, covered in the reference page). Each `::`-separated segment after `crate` is then either:
* the name of a subdirectory to descend into, or
* the name of a `.simf` file (written without the `.simf` suffix): once a segment matches a file instead of a directory, that's the file being imported from,
with the very last segment naming the actual item being imported from that file. In the example above, `shapes` is a directory and `polygons` is the file `shapes/polygons.simf`.
## Grouping code with `mod`, without separate files
Sometimes you want to group related functions together without creating a whole new file for them. A `mod` block does that inside a single file. `mod` blocks can be nested.
```simplicityhl
mod math {
pub mod ops {
pub fn double(x: u32) -> u32 {
let (overflow, res): (bool, u32) = jet::add_32(x, x);
assert!(not(overflow));
res
}
}
}
mod business_logic {
use crate::math::ops::double;
pub fn calculate_fee(base_price: u32, tax: u32) -> u32 {
let (overflow, res): (bool, u32) = jet::add_32(double(base_price), tax);
assert!(not(overflow));
res
}
}
use crate::business_logic::calculate_fee;
fn main() {
assert!(jet::eq_32(calculate_fee(15, 5), 35));
}
```
This is a single file, `examples/modules.simf` in the SimplicityHL repository. Notice that `business_logic` still needs its own `use` line to access `math::ops`, even though both are defined in the same file. `pub` and `use` work the same way whether the code you're importing appears in the same file or a different one.
## Renaming an import with `as`
If an imported name would clash with something else, or you'd just prefer a different local name, add `as`:
```simplicityhl
use crate::shapes::polygons::triangle_area as tri_area;
```
The imported function will now be called `tri_area`.
## Importing several things at once
List multiple items from the same file in braces. Optionally, use an `as` wherever you like:
```simplicityhl
use crate::shapes::polygons::{triangle_area, square_area as sq_area};
```
There's no `*` wildcard to import "everything" from a file. Every name has to be listed explicitly.
## Re-exporting with `pub use`
Adding `pub` in front of a `use` line imports the item and makes it available for *other* files to import from *this* file, under its own name. This is handy for building a single file that gathers up functions from several lower-level files into one convenient place:
```simplicityhl
// lib/api.simf
pub use crate::shapes::polygons::triangle_area;
pub use crate::shapes::polygons::square_area;
```
Another file can then write `use crate::lib::api::triangle_area;` without needing to know that its implementation is actually stored in `shapes/polygons.simf`.
## Using code from another project
To reuse a library that lives in a separate directory entirely (not a subdirectory of your current project), tell `simc` about it with the `--dep` flag, giving it a local name (an *alias*) to import under:
```bash
simc -Z imports --dep shapes_lib=../shape_lib main.simf
```
This maps the name `shapes_lib` to the directory `../shape_lib` for the duration of this compile. Inside your code, you import from it exactly like a local module, just starting from the alias instead of `crate`:
```simplicityhl
use shapes_lib::polygons::triangle_area;
```
## Using the standard library with Simplex
SimplicityHL ships a standard library, [`simplicityhl-std`](https://github.com/BlockstreamResearch/simplicityhl-std), with functions like checked arithmetic and equality assertions; see the [standard library reference](stdlib.md) for the complete list. It can be imported the same way as any other external dependency.
Most current SimplicityHL projects, including the standard library's own development, are managed with [Simplex](simplex.md), which can fetch the standard library and register it as a dependency automatically with the special package name `std`:
```bash
simplex install std
```
This adds an entry to the project's `Simplex.toml`.
Simplex passes the equivalent of a `--dep std=...` argument to `simc` when it builds the project, so all standard library functions become available to import under `std::`:
```simplicityhl
use std::lib::u32::math::checked_add_32;
use std::lib::asserts::assert_eq_32;
fn main() {
assert_eq_32(unwrap(checked_add_32(1, 2)), 3);
}
```
## Using the standard library without Simplex
The same effect can be achieved manually by cloning the `BlockstreamResearch/simplicityhl-std` repository and registering it as a manual `--dep`. Point the alias at the repository's `simf` directory, since that's where the library's own `crate::` paths are rooted:
```bash
git clone --branch v0.1.0 https://github.com/BlockstreamResearch/simplicityhl-std.git
simc -Z imports --dep std=simplicityhl-std/simf myproject.simf
```
When the alias is created this way, the `use` lines in the SimplicityHL project source are identical to the Simplex case above.
## A quick summary of what's different from other languages
If you've used a language with a similar-looking import system before (including Rust), a few things about SimplicityHL's version are worth calling out because they're more restrictive:
* Functions are private unless marked `pub`: there's no way to import something that wasn't exported.
* Every local (non-dependency) path starts with `crate::`; there's no special way to refer to a parent module.
* There's no `*` wildcard import. Each imported name must be written out in full.
## Where to go next
* The [modules reference page](../simplicityhl-reference/modules.md) covers exact syntax details related to modules and imports.
* Read more about [Simplex](simplex.md) and its package and dependency management features.
### Ecosystem & Wallet Integration
# Development ecosystem and wallet integration
A Simplicity contract enforces financial logic through on-chain transactions, but it is only one piece of a complete financial application. By itself, a contract lacks a user interface or discovery mechanism. To make a Simplicity contract useful, other software, such as a dedicated native app, a web app, or a wallet taught to interact with the contract, needs to be provided.
These supporting applications need to handle integration tasks such as finding active instances of a contract on the blockchain and validating that they have the intended or desired functionality, determining the current contract state and the actions a user can take, creating transactions that send or claim assets or that update a contract's state, and representing this information in a meaningful way for an end user.
Because Simplicity and the blockchains that support it are open source, developers have the flexibility to create tools that facilitate these actions in a variety of development environments.
## Tooling (contract compilation and transaction generation)
### Command line
[Command-line tools for developing, testing, and exploration](toolchain.md) (`simc` and `hal-simplicity`) are available.
### SimplicityHL, rust-simplicity, and Simplex
The recommended development environment for building production applications that directly interact with Simplicity contracts is based on Rust. Three projects are most relevant to Rust developers.
* The [SimplicityHL](https://github.com/BlockstreamResearch/SimplicityHL) project includes a Rust library that lets you compile SimplicityHL to low-level Simplicity from inside a Rust program. The compilation logic is the same as in the `simc` compiler, but doesn't require a command-line invocation.
* The [`rust-simplicity`](https://github.com/BlockstreamResearch/rust-simplicity) library provides low-level functionality related to building witnesses and transactions. It can also derive on-chain addresses from a compiled Simplicity program.
* The [Simplex](simplex.md) orchestration tool can automatically generate code artifacts in Rust, compatible with `rust-simplicity`, that provide basic witness and transaction-building logic for a specified SimplicityHL program. It also provides other useful project management functionality such as dependency management and a test framework.
### LWK
The [Liquid Wallet Kit (LWK)](https://github.com/Blockstream/lwk/) provides higher-level functionality in Rust, with bindings also available for several other languages. Simplicity features are still being added in LWK as of April 2026, but are available as an alpha release behind the LWK compile-time feature `simplicity` (build with `cargo build --features simplicity`, `just build-bindings-lib-simplicity`, or `just python-build-bindings-simplicity`).
You can use LWK to build a complete wallet or blockchain app that interacts with Liquid Network, including interfacing with Simplicity contracts. LWK can also deal with storing digital assets' private keys directly in-app, and can generate addresses from a supplied seed. LWK's Simplicity support includes higher-level abstractions for transaction building for both commit and redeem transactions.
LWK can generate native apps or provide JavaScript bindings, with a WASM compile target, for building web apps.
A sample web app built in JavaScript using LWK's WASM target to generate Simplicity transactions is the [lending contract demo](https://demolending.distributedlab.com/). Its source code is available at [`BlockstreamResearch/simplicity-lending`](https://github.com/BlockstreamResearch/simplicity-lending).
## Tooling (blockchain indexing and discovery)
The main API for discovering and analyzing transactions on a blockchain, including to determine smart contract state, is [Esplora](https://github.com/Blockstream/esplora). You can use Blockstream's public Esplora instance or run your own Esplora service.
If you'd like to run your own Liquid Network node, you can do so with a local instance of [Elements](https://github.com/ElementsProject/elements). The local storage footprint of a Liquid node, as of April 2026, is about 50 gigabytes.
## About transaction-building for interacting with Simplicity contracts
Sending an [asset](../glossary.md#asset) to a Simplicity [smart contract](../glossary.md#smart-contract) requires calculating the appropriate on-chain address for the contract, possibly including a [state commitment](./state.md) representing the contract's new state. This is called a *commit* transaction.
Determining the appropriate address for a commit transaction may involve moderately complex logic, including [Taproot](../glossary.md#taproot) details (creating a P2TR address where the Simplicity program and state are committed in the Taptree). If the contract doesn't require updated state commitments, the address of a particular instance of a particular contract won't change from transaction to transaction, and so can be hard-coded or provided by an external tool. The overall form of the commit transaction simply looks like any other P2TR transaction; Simplicity-specific transaction-building logic may not be required.
Claiming an asset from a UTXO controlled by a Simplicity contract is called a *redeem* transaction. It requires building a complete transaction with witness data, control block, and possibly appropriate signatures. Simplicity-specific transaction-building logic is usually required for such a transaction.
A [covenant](../glossary.md#covenant) transaction, in which assets controlled by a contract are sent back to a version of that same contract, generally includes *both* redeem and commit halves in the same transaction.
If an application needs signatures from an existing wallet, a [PSET](../glossary.md#pset) representing a redeem transaction can be built by Simplicity-aware software, and external software can produce an appropriate signature over the proposed PSET transaction. These signatures can be inserted into the [witness](../glossary.md#witness) witness data.
## Wallet connection mechanisms
An official wallet connection recommendation is currently in development to connect external wallets with Simplicity clients.
Work on this mechanism is built on top of the Bitcoin ecosystem's existing [WalletConnect protocol](https://walletconnect.com/), including a facility for pairing an external wallet with a web application via WebSockets. This permits an existing wallet, with minimal changes, to provide signatures for transactions with Simplicity smart contracts.
In this model, the web application (which is developed with LWK targeting WASM) provides the main user interface for a given smart contract, including visualizing contract state and initiating actions with the contract, but users' digital assets can be held in an existent external application or device.
The interface is general in order to enable interoperability with any third-party wallet that supports the appropriate wallet connect extensions. However, if the wallet doesn't provide UI support for a specific contract, the web application must be trusted to accurately represent the meaning and effects of the contract state and requested signatures.
A proof of concept of some wallet connect mechanisms is available in the [lending contract demo](https://lending.dev.blockstream.com/). Lightly-customized versions of Blockstream Jade, the Blockstream App, and other wallet applications can pair with this demo and authorize lending contract transactions on Liquid testnet, in both lender and borrower roles.
### txmanifest
# txmanifest
`txmanifest` is a JSON-based file format for describing Simplicity [contracts](../glossary.md#contract). It provides a reusable, standardized way to *teach wallets* how to describe and interact with a Simplicity contract on-chain. This reduces the need to build custom UI and transaction logic for each contract/wallet pair.
When a wallet application imports a trusted [manifest](../glossary.md#manifest) file describing a contract, the wallet application learns how to recognize instances of the described contract on the blockchain, how to describe those details to a user, and how to build new transactions that perform actions in that contract instance.
For smart contract developers, `txmanifest` provides a way to describe a contract once and achieve interoperability with a whole ecosystem of wallets.
For wallet developers, `txmanifest` provides a way to add UI and transaction functionality once and achieve interoperability with a whole ecosystem of smart contracts.
## Online documentation
The `txmanifest` format is work-in-progress and hasn't yet been frozen as a released specification, but versions of it have been integrated with several Liquid wallets. Detailed documentation for the `txmanifest` format is available in the [*txmanifest book*](https://stringhandler.github.io/tx_manifest_book/).
## Reference implementation
The [`txmanifest-wallet`](https://github.com/stringhandler/txmanifest-wallet/) project provides a reference implementation of `txmanifest` as a developer-oriented wallet application with a textual user interface.
You can use `txmanifest-wallet` to debug and experiment with manifest files describing new or existing Simplicity contracts. An interactive online demonstration of this tool, with sample manifests and contracts, is available in the [txw codespace](https://github.com/codespaces/new/stringhandler/txw-codespace).
## Security considerations
The `txmanifest` format doesn't include a means to confirm or verify the correctness of descriptions.
Trusting an inaccurate or deceptive manifest file can result in wallets misinterpreting the meaning or effect of transactions, and misdescribing them to users. This could allow users' assets to be lost or stolen because the users approve transactions with undesired or unintended effects, including transferring assets to an attacker's control.
For example, a manifest file could falsely state that transferring currency to a certain address deposits it as collateral for a loan, which can purportedly be reclaimed by repaying the loan. In reality, the loan could have highly unfavorable terms that the wallet application fails to explain correctly, or the destination address could be some other form of contract that forfeits the user's deposit to an attacker with no further recourse.
Users and wallets must only import manifest files from appropriately trusted sources, and not automatically accept manifest files posted online or sent to them by strangers.
### Use Cases Overview
# Use Cases Overview
Simplicity can be used for a wide range of financial applications.
## Blockstream's reference implementations
Examples developed by Blockstream include
* [Simplicity DEX](simplicity-dex.md) for financial options
* [Simplicity Lending Protocol](lending-protocol.md) for collateralized lending ([implementation](https://github.com/BlockstreamResearch/simplicity-lending))
* [SHRINCS Simplicity verifier](https://github.com/BlockstreamResearch/shrincs-simplicity-verifier), for [Simplicity-based postquantum signature verification](https://blog.blockstream.com/blockstream-research-demonstrates-quantum-resistant-transaction-signing-on-liquid-using-simplicity-smart-contracts/) on Liquid (see also the [PQ Liquid Wallet](https://github.com/smeneguz/pq-liquid-wallet) hackathon project)
## Simplicity projects built by others
* [Resolvr](https://resolvr.io/) has created [Astrolabe](https://docs.simplicity-lang.org/news/2026/02/20/video-resolvr-astrolabe-demo/), a Simplicity-based reinsurance investment platform, and [Deadcat](https://github.com/Resolvr-io/deadcat), a Simplicity-based prediction market.
* [SideSwap](https://sideswap.io/) has [launched](https://sideswap.io/news/sideswap-press-release/) [Swaption](https://swaption.io/), a Simplicity-based noncustodial binary options marketplace.
* [StarkWare](https://starkware.co/) has used Simplicity to [implement a STARK verifier](https://starkware.co/blog/building-starks-in-simplicity/).
* [OceanSlim](https://github.com/0ceanslim) has created [anchor](https://github.com/0ceanSlim/anchor), a constant-product automated-market maker (AMM).
## Other examples and ideas
Check out the [SimplicityHL examples](https://github.com/BlockstreamResearch/SimplicityHL/tree/master/examples) for other introductory smart contract examples, including [vault](../glossary.md#vault) and [covenant](../glossary.md#covenant) mechanisms.
In addition to options, lending, insurance, and prediction markets, Simplicity is expected to support
* Cross-chain atomic swaps
* Crowdfunding contracts
* Bitcoin native smart contracts via Simplicity Unchained
* Vaults (multi-stage withdrawals)
### Simplicity DEX
# Simplicity DEX
The underlying code for this project is found in the [Simplicity DEX repository](https://github.com/Blockstream/simplicity-dex) (other relevant repository links appear below).
Despite the name, there is no exchange of Token A for Token B in the traditional sense at the core of the Simplicity DEX. It is a **structured product marketplace** that enables users to create and trade options contracts on-chain on the Liquid Network. Similar techniques can extend it to advertise and perform direct, immediate exchange of pairs of assets in a decentralized way without an intermediary; that functionality is planned for future development.
The current protocol facilitates *only* the exchange of "Grantor Tokens" plus a premium in USD for Liquid Bitcoin (LBTC) tokens. Support for other variations will be added in the future.
The existing code uses Nostr to publicize the existence of contracts and allow a party to locate a counterparty. This document focuses mainly on the financial logic of the contract rather than the technical mechanisms for representing the contract on Nostr and Liquid.
## Core definitions
**Call Option**: A financial contract that gives the holder the right, but not the obligation, to *buy* an underlying asset at a specified strike price before or at a specified expiration date.
**Put Option**: A financial contract that gives the holder the right, but not the obligation, to *sell* an underlying asset at a specified strike price before or at a specified expiration date.
> **Note**: The underlying [smart contract](../glossary.md#smart-contract) supports both Call and Put options, but the current CLI implementation only supports Call options.
**Grantor Token**: A tradable token received by the maker upon funding an options contract. The Grantor Token represents the right to claim assets at settlement - either the LBTC deposited during exercise (if the option is exercised) or the USDt collateral (if the option expires unexercised). In the current version of the protocol, the maker sells this token along with a premium in USD to a taker in exchange for LBTC.
## Implementation
The implemented protocol is a variation of a Call Option. The premium to the taker is paid during the exchange of LBTC and collateral tokens (i.e., Grantor Token).
### Participants
**Maker ("Option buyer")**: The party that creates the options contract. Upon creation, the maker:
* Deposits USDt collateral into the Collateral Covenant
* Receives both an **Option Token** and a **Grantor Token**
* Keeps the Option Token (gives the right to exercise)
* Pays a premium in USD to incentivize the taker to buy the Grantor Token for LBTC.
**Taker ("Option seller")**: The party that purchases the Grantor Token and receives the premium in USD. The taker:
* Pays LBTC to acquire the Grantor Token from the maker
* Holds the Grantor Token, which entitles them to claim assets at settlement
### Resources
The core contract of the Simplicity DEX is the Options contract:
The concept for this contract was proposed in the following whitepaper:
Link to the [Simplicity DEX repository](https://github.com/Blockstream/simplicity-dex).
## Financial Incentive
**Maker Profit Condition**: The maker profits when the value of the LBTC received (from selling the Grantor Token) exceeds the value of the USDt collateral deposited and the premium paid. This occurs when the LBTC price rises significantly above the strike price.
**Taker Profit Condition**: The taker profits when the premium they receive covers any potential losses, while still retaining a guaranteed claim on either LBTC (if the option is exercised) or the USDt collateral (if the option expires unexercised).
{ width="1457" height="888" }
!!! info "Option Offer Contract"
The [Option Offer contract](https://github.com/BlockstreamResearch/simplicity-contracts/blob/main/crates/contracts/src/finance/option_offer/source_simf/option_offer.simf) enables depositing two assets (collateral + premium) into a single covenant. A counterparty can then swap their settlement asset for both deposited assets in a single atomic transaction, with amounts enforced by configurable ratios (`collateral_per_contract` and `premium_per_collateral`).
## Detailed Step-by-Step Protocol Flow (Current implementation)
The maker selects locked-asset as USDt, and claim-asset as LBTC. The contract size is the collateral, e.g., 115,000 USDt. The strike price is $115,000 (LBTC/USDt). The term length is 30 days. The maker creates the "Options Creation" transaction which produces an Option Token Generator and a Grantor Token Generator held in a Generator Covenant.
The maker funds a single option using the "Option Funding" transaction, which requires depositing 115,000 USDt into the Collateral Covenant. The maker receives an Option Token and a Grantor Token from the Generator Covenant.
Note: at any time, the options contract can be canceled and the collateral retrieved by using both the Option Token and the Grantor Token together to unlock the collateral.
The maker deposits their newly minted Grantor Token along with premium (e.g., USDt) into the Option Offer contract. The taker pays LBTC (settlement asset) to the Option Offer contract and receives both the Grantor Token and the premium in a single atomic transaction. The maker keeps their Option Token.
**Case A: LBTC ends below $115,000.** Just prior to expiration, the maker uses their Option Token to exercise the Collateral Covenant. This requires depositing LBTC into a Settlement Covenant, which in turn unlocks the Collateral Covenant, whose 115,000 USDt funds the maker gets to keep. Afterwards, the taker can use their Grantor Token to retrieve the LBTC from the Settlement Covenant.
**Case B: LBTC ends above $115,000 or the maker lacks adequate LBTC funds.** The maker does nothing and their Option Token is useless. After the expiration date, the taker uses their Grantor Token to retrieve the 115,000 USDt from the Collateral Covenant.
### Key Design Properties
This contract design avoids the need for a price oracle, relying instead on the Option Token holder's (i.e., the maker's) natural incentives to choose the appropriate outcome. The taker is required to get the lesser-valued asset of the two, after the expiration date. The choices the maker can make can only improve the taker's outcome. The maker could incorrectly exercise or not exercise their option, which will cause the taker to end up with the more-valuable asset, or the maker could incorrectly exercise their option early, allowing the taker to get access to their funds prior to the expiration date, or both.
*It is the responsibility of the maker to optimize their handling of the options* in order to extract the most value for themselves. Any other outcome can only benefit the taker.
Avoiding the price oracle also automatically handles the case where the maker defaults: the taker gets the USDt collateral, regardless of the LBTC price.
The options design includes extra features beyond the basic specification. In particular, the Grantor and Option Tokens are real tradable assets, and both can be resold. This is particularly useful when the maker is in default (i.e., lacks sufficient funds to exercise the option) but the option is otherwise in-the-money: the maker can sell their Option Token to someone else who does have sufficient funds to exercise it.
The design also allows for more than one pair of Grantor/Option Tokens to be generated. For example, the maker can generate 10 token pairs along with 10 Collateral Covenant UTXOs, each holding one tenth of the total collateral. This enables partially filling the order. These sets of Option Tokens and Grantor Tokens are fungible and tradeable. Unfilled orders (i.e., when not all the Grantor Tokens are sold) can be used, along with the same number of Option Tokens, to cancel unused Collateral Covenants and recover the funds immediately.
```mermaid
sequenceDiagram
participant Maker
participant Options as Options Contract
participant OptionOffer as Option Offer Contract
participant Taker
Note over Maker,Taker: Phase 1 & 2: Creation and Funding
Maker->>Options: Create Options Contract
Options-->>Maker: Generator Covenant created
Maker->>Options: Deposit USDt collateral
Options-->>Maker: Option Token + Grantor Token
Note over Maker,Taker: Phase 3: Token Sale via Option Offer
Maker->>OptionOffer: Deposit Grantor Token + Premium (USDt)
Taker->>OptionOffer: Pay LBTC (settlement)
OptionOffer-->>Taker: Grantor Token + Premium
Maker->>OptionOffer: Withdraw settlement (LBTC)
OptionOffer-->>Maker: Repay full amount of settlement (LBTC)
Note over Maker,Taker: Phase 4a: Settlement (spot < strike)
alt LBTC price below strike
Maker->>Options: Exercise with Option Token + LBTC
Options-->>Maker: Release USDt collateral
Taker->>Options: Claim with Grantor Token
Options-->>Taker: Release LBTC from Settlement
end
Note over Maker,Taker: Phase 4b: Settlement (spot >= strike)
alt LBTC price above strike (or maker default)
Note over Maker: Option expires worthless
Taker->>Options: Claim with Grantor Token
Options-->>Taker: Release USDt collateral
end
```
## Appendix A: Excalidraw file
[profit-loss-diagram(2).excalidraw 28916](../assets/9e9ecabd-7792-4970-a69c-28847b5e9c99.excalidraw)
## Appendix B: Mapping to Traditional Options Positions
The Options contract is flexible enough to create all four standard options positions depending on two parameters: the collateral type and which token the maker sells.
However, the current contract configuration forces the premium to be of the collateral type, not in USD.
{ width="510" height="323" }
### The Two Determining Factors
**Collateral type determines Call vs Put:**
* **USDt collateral** → Call-like structure (the option is fundamentally about acquiring LBTC)
* **LBTC collateral** → Put-like structure (the option is fundamentally about acquiring USDt)
**Which token is sold determines who holds the Long vs Short position:**
* **Sell Grantor Token** (keep Option Token) → Maker holds the "long" position (has the right to exercise)
* **Sell Option Token** (keep Grantor Token) → Taker holds the "long" position (has the right to exercise)
### The Four Configurations
| Configuration | Collateral | Token Sold | Maker's Position | Taker's Position |
|----|----|----|----|----|
| 1 | USDt | Grantor | Long Call | Short Call |
| 2 | USDt | Option | Short Call | Long Call |
| 3 | LBTC | Grantor | Long Put | Short Put |
| 4 | LBTC | Option | Short Put | Long Put |
**Configuration 1 (USDt collateral, sell Grantor)** is the current implementation described in this document. The maker profits when LBTC rises significantly (Long Call profile), while the taker has limited upside but collects the premium spread (Short Call profile).
**Configuration 2 (USDt collateral, sell Option)** flips the positions. The taker, now holding the Option Token, has the right to exercise and profits when LBTC falls (Long Call on USDt, effectively). The maker keeps the Grantor Token and has the Short Call profile.
**Configuration 3 (LBTC collateral, sell Grantor)** creates a Put-like structure. The maker deposits LBTC as collateral. The Option Token holder can deposit USDt to claim the LBTC. The maker (holding Option Token) profits when LBTC falls (Long Put profile).
**Configuration 4 (LBTC collateral, sell Option)** is the inverse of Configuration 3. The taker holds the Option Token and has the Long Put position, profiting when LBTC falls. The maker has the Short Put profile.
### Practical Implications
This flexibility means market participants can use the same underlying contract to express different market views:
* **Bullish on LBTC**: Use Configuration 1 (maker) or Configuration 4 (taker)
* **Bearish on LBTC**: Use Configuration 3 (maker) or Configuration 2 (taker)
* **Neutral/yield-seeking**: Take the "short" side of any configuration to collect premium
The current CLI implementation supports Configuration 1, but the underlying smart contract is capable of supporting all four configurations.
### Lending Protocol
# Simplicity Lending Protocol on Liquid Network
[Simplicity](../glossary.md#simplicity) is a deterministic, statically analyzable smart contract language designed for Bitcoin-like systems, with predictable execution costs and a semantics that lends itself to high assurance reasoning and formal verification.
This article describes a Simplicity Lending Protocol implemented as Simplicity [smart contracts](../glossary.md#smart-contract) on the [Liquid Network](../glossary.md#liquid). The article focuses on the protocol design, financial logic, and contract decomposition. The Protocol implements on-chain borrowing at interest against collateral, with details agreed and accepted between two parties.
The Protocol can be used by any kind of entity, ranging from a financial institution to a private individual.
The Protocol handles accounting for a loan involving two different tokens, representing different [assets](../glossary.md#asset). For illustrative purposes, USDT is used as a loaned asset and LBTC as a collateral asset, but the protocol handles any pair of assets that are tokenized on Liquid.
The implementation plan consists of steps for the full Protocol implementation. It starts with verified lending primitives and increases the complexity and functionality of the Protocol over time.
The existing implementation can be found [on GitHub](https://github.com/BlockstreamResearch/simplicity-lending).
## Simplicity Lending Protocol Roadmap
### P2P Simplified Lending Contract
These are the parameters of the lending contract:
* **Borrower** - user with collateral asset A.
* **Lender** - user with loan asset B.
* **Collateral Amount** - pledged by Borrower collateral in asset A.
* **Loan Amount** - amount of asset B tokens borrowed by Borrower from Lender.
* **Lending Term** - moment in the future (UNIX time, block number, etc.) before which Borrower should repay the Loan Amount in asset B to the Lender.
* **Loan Amount** - the amount of the loan asset Borrower would like to borrow.
* **Collateral Amount** - locked by the Borrower, the collateral amount for the Loan Amount.
* **Liquidation** - if the Loan isn't repaid after the Lending Term, the Lender can claim the collateral.
* **Loan Fee** - fixed fee paid in loan asset B from Borrower to Lender for the Loan after the loan is originated. Can represent interest payment for a fixed-term loan.
* **Origination Fee** - fixed fee paid in collateral asset A from Borrower to Lender for the Loan for loan origination.
* **Protocol Fee (Reserve Factor)** - fee paid in loan asset B to the Protocol Address for the Loan after the loan repayment. The fee is calculated as a percentage of the Loan Fee.
```mermaid
flowchart TD
START((Start))
S_Proposed[State: Collateral Locked]
S_Active[State: Loan Active]
T_Cancelled([Terminated: Refunded])
T_Settled([Settled: Repaid])
T_Defaulted([Liquidated: Defaulted])
START -->|Borrower proposes terms Borrower pays collateral| S_Proposed
S_Proposed -->|Borrower cancels Collateral refunded to borrower| T_Cancelled
S_Proposed -->|Lender accepts Lender pays principal Borrower receives principal| S_Active
S_Active -->|Loan repaid Borrower repays principal Principal repaid to lender Collateral refunded to borrower| T_Settled
S_Active -->|Timeout reached Liquidation process invoked Collateral paid to lender or liquidator| T_Defaulted
style S_Proposed fill:#fff4dd,stroke:#d4a017,stroke-width:2px
style S_Active fill:#fff4dd,stroke:#d4a017,stroke-width:2px
style T_Cancelled fill:#eee,stroke:#999
style T_Settled fill:#d1fae5,stroke:#10b981
style T_Defaulted fill:#fee2e2,stroke:#ef4444
```
#### Loan Origination
##### Borrower to Lender
Borrower locks Collateral Amount and the Origination Fee in the offer transaction. The Borrower also states the following parameters in the transaction: the Loan Fee, Lending Term, Origination Fee, and the Loan Amount the Borrower would like to borrow.
After an offer is published with a transaction, any address can accept the offer as a Lender.
##### Lender to Borrower
If the Lender is satisfied with the loan conditions in the offer (Origination Fee, Loan Fee, Protocol Fee, Lending Term, Loan Amount, Collateral Amount), the Lender accepts the offer and sends the Loan Amount, receives a fixed Origination Fee in a transaction, and accepts the conditions of the loan, including Origination Fee, Loan Fee, Protocol Fee, Lending Term and Collateral Amount.
The Borrower receives the requested Loan Amount in the offer.
#### Loan Repayment
The Borrower should fully repay the loan plus the Loan Fee at any moment before the Lending Term. Loan Fee is divided into the Protocol Fee paid to the Protocol Address and the rest paid to the Lender. After the repayment, Borrower can claim back the full amount of the collateral asset.
#### Liquidation
If the Borrower didn't repay the full Loan Amount before the Lending Term, the Lender can claim the full collateral amount.
### P2P Lending Contract with Mock Price Oracle and Partial Loan Repayment
This contract variant is based upon the contract described in the prior section, with additional functionality and an additional Liquidation Loan-To-Value (LLTV) parameter.
Additional definitions:
* **Price Oracle** - source of constant verified price information of asset A in terms of asset B, signed by a trusted provider.
* **Third Party Liquidator** - any third party address that can fully repay the loan outstanding at the moment of liquidation and get the Collateral Amount.
* **Liquidation Protocol Fee** - fee paid to Protocol Address as a percentage (10%, for example) from the Collateral Amount at the liquidation event.
#### Loan Origination
##### Borrower to Lender
Borrower locks Collateral Amount and the Origination Fee in the transaction. The Borrower also states the transaction Loan Fee, Lending Term, Origination Fee, Loan Amount the Borrower would like to borrow, which should satisfy the following equation:
$$ \text{Loan Amount} < \text{LLTV} \times \text{Collateral Amount} \times \text{Price Oracle} $$
##### Lender to Borrower
If the Lender is satisfied with the loan conditions in the offer (Origination Fee, Loan Fee, Protocol Fee, Lending Term, Loan Amount, Collateral Amount, and LLTV), the Lender accepts the offer and sends a transaction with the Loan Amount in asset B and receives a fixed Origination Fee.
The Borrower receives the requested Loan Amount in the offer.
#### Loan Repayment
The Borrower should fully repay the Loan Amount plus Loan Fee at any moment before the expiration of the Lending Term. Loan Fee is divided into the Protocol Fee paid to the Protocol Address and the remainder paid to the Lender. After the repayment, Borrower can claim back the full amount of the collateral asset.
During the Lending Term, Borrower can choose a partial loan repayment to avoid a Liquidation event.
#### Liquidation
In case of a default on the loan (if the Borrower didn't repay the full Loan Amount plus the Loan Fee before the Lending Term), the Lender can claim the full collateral amount. (But see below for a partial liquidation alternative.)
Liquidation at any moment (before or after Lending Term) by a Third Party Liquidator is possible if the following equation is true:
$$ \text{Loan Amount Outstanding} > \text{LLTV} \times \text{Collateral Amount} \times \text{Price Oracle} $$
In this case, Third Party Liquidator receives the Collateral Amount minus the Liquidation Protocol Fee, which goes to the Protocol Address.
#### Partial Liquidation Invariant
The full collateral liquidation option allows the Lender, after the Lending Term, to liquidate the full amount of collateral even if the loan is significantly repaid. To mitigate this case and give the Borrower partial credit for partial repayment, a partial liquidation invariant is available. This alternative pays the Lender a pro-rated fraction of the collateral in exchange for the outstanding portion of the loan principal. The contract also sets a fixed Liquidation Penalty as an additional amount of collateral obtained by the Lender as a penalty for incomplete repayment. The rest of the collateral is sent back to the Borrower.
In this case, liquidation after the Lending Term can be initiated by the Lender or the Borrower. The collateral part received by the Borrower is calculated according to the following equation:
$$ \text{Borrower Collateral Payment} = \text{Collateral Amount} - \frac{\text{Loan Amount Outstanding}}{\text{Price Oracle}} - \text{Liquidation Penalty} $$
Liquidation Penalty is also subject to Liquidation Protocol Fee, which goes to the Protocol Address.
### P2P Lending Contract with Integrated Interest Rate
This contract variant is based upon the contract described in the prior section, but, instead of a fixed Loan Fee, a fixed Interest Rate is used.
Additional definitions:
* **Interest Rate** - fixed annual percentage rate (APR), which is a reward for the Lender from the Borrower as an incentive to provide the loan.
#### Loan Origination
##### Borrower to Lender
Borrower locks Collateral Amount and the Origination Fee in the transaction. The Borrower also states in the transaction the Interest Rate, Lending Term, Origination Fee, Loan Amount the Borrower would like to borrow, which should satisfy the following equation:
$$ \text{Loan Amount} < \text{LLTV} \times \text{Collateral Amount} \times \text{Price Oracle} $$
If the Lender is satisfied with the loan conditions in the offer (Origination Fee, Interest Rate, Protocol Fee, Lending Term, Loan Amount, Collateral Amount), the Lender accepts the offer and sends a transaction with the loan in asset B and receives a fixed Origination Fee.
##### Lender to Borrower
Lender sends the Loan Amount in a transaction and accepts the conditions of the loan, including Origination Fee, Interest Rate, Protocol Fee, Lending Term, Collateral Amount and LLTV.
The Borrower receives the requested Loan Amount in the offer.
#### Loan Repayment
The Borrower should fully repay the Loan Amount with the accrued Interest Rate at any moment before the Lending Term. Loan Fee is divided into the Protocol Fee paid to the Protocol Address and the rest paid to the Lender. After the repayment Borrower can claim back the full amount of the collateral asset.
During the Lending Term Borrower can choose a partial loan repayment to avoid a Liquidation event.
#### Liquidation
If the Borrower didn't repay the full Loan Amount plus the accrued Interest Rate before the Lending Term, the Lender can claim the full collateral amount.
Liquidation at any moment (before or after Lending Term) by the Third Party Liquidator is possible provided that the following equation is true:
$$ \text{Loan Amount Outstanding} + \text{Accrued Interest Rate} > \text{LLTV} \times \text{Collateral Amount} \times \text{Price Oracle} $$
Third Party Liquidator receives the Collateral Amount minus the Liquidation Protocol Fee, which goes to the Protocol Address.
#### Partial Liquidation Invariant
The full collateral liquidation option allows the Lender, after the Lending Term, to liquidate the full amount of collateral even if the loan is significantly repaid. To mitigate this case, a partial liquidation mechanism is available. The partial liquidation invariant sets the Liquidation Penalty as a fixed collateral asset amount obtained by the Lender on top of the recovered loan amount. The rest of the collateral is sent back to the Borrower.
In this case, liquidation after the Lending Term can be initiated by the Lender or the Borrower. The collateral part received by Borrower is calculated according to the following equation:
$$ \text{Borrower Collateral Payment} = \text{Collateral Amount} - \frac{\text{Loan Amount Outstanding}}{\text{Price Oracle}} - \text{Liquidation Penalty} $$
Liquidation Penalty is also subject to Liquidation Protocol Fee, which goes to the Protocol Address.
## First Lending Protocol Implementation
The first version of the Protocol is being finalized with a P2P Simplified Lending Contract solution, which will be deployed on the Liquid Network and allow lending USDT against LBTC for a fixed term.
The first lending protocol implementation is carried out by multiple [covenants](../glossary.md#covenant) that are constructed continuously by both Borrower and Lender in the following order:
### Creation of Utility Tokens
Both Lender's and Borrower's financial interests in the contract are represented by special "one-time" assets ([tokens](../glossary.md#token)) that enable the existence of secondary markets where these tokens can be sold/traded/exchanged.
To ensure the integrity of lending offer parameters across multiple covenants, specialized Parameter Tokens are utilized. These assets act as data carriers by encoding the protocol parameters directly within their amount fields.
**Important:** To ensure compatibility with Liquid/Elements consensus rules, the encoded value must not exceed the maximum allowed supply limit ([`MAX_MONEY`](https://github.com/ElementsProject/rust-elements/blob/f6ffc7800df14b81c0f5ae1c94368a78b99612b9/src/blind.rs#L471)). This effectively restricts the available data space within the token's amount field to 51 bits.
Two distinct tokens are required to store the current protocol state:
1. `FIRST_PARAMETERS_NFT`: Encodes the `PRINCIPAL_INTEREST_RATE`, `LOAN_DURATION`, `COLLATERAL_DECIMALS_MANTISSA`, and `PRINCIPAL_DECIMALS_MANTISSA`.
| Bits | Field name | Description |
| :---- | :---- | :---- |
| \[0..15\] | Interest Rate | 16-bit value for the loan interest (percentage) |
| \[16..42\] | Loan Expiration Time | 27-bit value for the loan expiration time in blocks (block height) |
| \[43..46\] | Collateral Decimals Mantissa | 4-bit exponent for collateral amount calculation |
| \[47..50\] | Principal Decimals Mantissa | 4-bit exponent for principal amount calculation |
2. `SECOND_PARAMETERS_NFT`: Encodes the `BASE_COLLATERAL_AMOUNT` and `BASE_PRINCIPAL_AMOUNT`.
| Bits | Field name | Description |
| :---- | :---- | :---- |
| \[0..24\] | Base Collateral Amount | 25-bit integer representing the collateral amount without decimals |
| \[25..49\] | Base Principal Amount | 25-bit integer representing the principal amount without decimals |
| \[50\] | Free Space | - |
Since the amount in a single [UTXO](../glossary.md#utxo) can't exceed $21,000,000 \times 10^8$, the number of bits required to encode the parameters can be reduced:
- Decimals mantissa (4 bits): This field occupies only 4 bits because assets with more than 8 decimals can't be created on Liquid.
- Base amount (25 bits): The base amount occupies 25 bits, allowing for a maximum value of 33,554,432. When combined with the decimals mantissa, it can represent any value from 0 up to the maximum possible supply.
- Interest Rate (16 bits): This field requires a minimum of 14 bits to express percentages using a scale where 10,000 equals 100%. Using 16 bits achieves a maximum interest rate of 655.36%.
- Loan expiration time in blocks: Setting this value to 27 bits allows the end block of the loan to be 134,217,728. This is currently ~248 years in the future with a 1-minute block rate.
### Lock Collateral
After calculating the Utility asset IDs, the "lock collateral" covenant can be constructed.
### Set up Lending
After the Borrower has constructed a "lock collateral" covenant, a Lender can then initiate the loan by sending the lending covenant transaction.
### Settle Lending
After the lending contract is set up, there are two ways it can be settled. Either the Borrower provides the principal with interest to the Lender and takes the collateral back, or the Lending Term expires, and the Lender liquidates the position, claiming the collateral.
## Indexing and Discovery Mechanism
The indexing mechanism is a critical component of the protocol's UX. To make the lending workflow functional, Lenders must be able to view all active loan offers from Borrowers. Simultaneously, Borrowers require real-time updates on the status of their offers to monitor repayment deadlines and obligations. The following indexing strategy is used to aggregate and display this data.
### Pre-lock Transaction Discovery and Verification
To monitor all active orders, an indexer scans the blockchain to identify transactions that initialize Pre-lock covenants. Once these transactions are identified, an indexer monitors the lifecycle of the resulting UTXOs to extract and update information regarding the loan terms.
An indexer recognizes Pre-lock initialization transactions by matching them against a specific transaction template:
- The transaction must contain a minimum of 5 inputs and 6 outputs.
- The transaction must include an `OP_RETURN` output containing a valid [BIP340](https://en.bitcoin.it/wiki/BIP_0340) public key.
- The first and second inputs must contain Parameter UTXOs, where the encoded amounts match the bit-packed lending protocol structure.
If a transaction meets the criteria above, the indexer performs a verification:
1. It attempts to compile the Pre-lock covenant using the parameters extracted from the transaction data.
2. It compares the resulting script hash ([CMR](../glossary.md#cmr)) with the script hash of output 0.
3. If the hashes match, the transaction is confirmed as a valid Pre-lock initialization.
### State Management
An indexer maintains a database of all existing offers. It continuously monitors the blockchain for spending transactions that target protocol-controlled outputs, allowing it to update the status of each loan (e.g., Active, Repaid, Cancelled, or Liquidated) in near real-time.
## Reference
### Introduction
# Introduction
SimplicityHL is a high-level language for writing Bitcoin smart contracts.
In other words, SimplicityHL is a language for expressing spending conditions of [UTXOs](../glossary.md#utxo) on the Bitcoin blockchain.
SimplicityHL looks and feels like [Rust](https://www.rust-lang.org/).
Developers write SimplicityHL, Bitcoin full nodes run Simplicity.
# Types and Values
- [Types and Values](./type.md)
- [Type Aliases](./type_alias.md)
- [Type Casting](./type_casting.md)
# Writing a Program
- [Let Statements](./let_statement.md)
- [Match Expression](./match_expression.md)
- [Functions](./function.md)
- [Programs](./program.md)
### Types and Values
# Types and Values
SimplicityHL mostly uses a subset of Rust's types.
It extends Rust in some ways to make it work better with Simplicity and with the blockchain.
## Boolean Type
| Type | Description | Values |
|--------|-----------------|-----------------|
| `bool` | Boolean | `false`, `true` |
Values of type `bool` are truth values, which are either `true` or `false`.
## Integer Types
| Type | Description | Values |
|--------|-----------------|--------------------------------------------------------|
| `u1` | 1-bit integer | `0`, `1` |
| `u2` | 2-bit integer | `0`, `1`, `2`, `3` |
| `u4` | 4-bit integer | `0`, `1`, …, `15` |
| `u8` | 8-bit integer | `0`, `1`, …, `255` |
| `u16` | 16-bit integer | `0`, `1`, …, `65535` |
| `u32` | 32-bit integer | `0`, `1`, …, `4294967295` |
| `u64` | 64-bit integer | `0`, `1`, …, `18446744073709551615` |
| `u128` | 128-bit integer | `0`, `1`, …, `340282366920938463463374607431768211455` |
| `u256` | 256-bit integer | `0`, `1`, …, 2256 - 1 |
Unsigned integers range from 1 bit to 256 bits.
[`u8`](https://doc.rust-lang.org/std/primitive.u8.html) to [`u128`](https://doc.rust-lang.org/std/primitive.u128.html) are also supported in Rust.
`u1`, `u2`, `u4` and `u256` are new to SimplicityHL.
Integer values can be written in decimal notation `123456`, binary notation `0b10101010` or hexadecimal notation `0xdeadbeef`. The number of bits or hex digits (for binary or hex notation) must correspond to the bit width of the type.
There are no signed integers.
The maximal `u256` value is `115792089237316195423570985008687907853269984665640564039457584007913129639935`.
## Tuple Types
| Type | Description | Values |
|--------------|-------------|---------------------------------------------------|
| `()` | 0-tuple | `()` |
| `(A)` | 1-tuple | `(a0,)`, `(a1,)`, … |
| `(A, B)` | 2-tuple | `(a0, b0)`, `(a1, b1)`, `(a2, b2)`, `(a3, b3)`, … |
| … | … | … |
| `(A, B, …)` | n-tuple | `(a0, b0, …)`, … |
[Tuples work just like in Rust](https://doc.rust-lang.org/std/primitive.tuple.html).
The empty tuple `()` contains no information.
It is also called the "unit".
It is mostly used as the return type of functions that don't return anything.
Singletons `(a0,)` must be written with an extra comma `,` to differentiate them from function calls.
Bigger tuples `(a0, b0, …)` work like in most other programming languages.
Each tuple type `(A1, A2, …, AN)` defines a sequence `A1`, `A2`, …, `AN` of types.
Values of that type must mirror the sequence of types:
A tuple value `(a1, a2, …, aN)` consists of a sequence `a1`, `a2`, …, `aN` of values, where `a1` is of type `A1`, `a2` is of type `A2`, and so on.
Tuples are always finite in length.
> Tuples are different from arrays:
> Each element of a tuple can have a different type.
> Each element of an array must have the same type.
## Array Types
| Type | Description | Values |
|----------|-------------|---------------------------------------------------|
| `[A; 0]` | 0-array | `[]` |
| `[A; 1]` | 1-array | `[a0]`, `[a1]`, … |
| `[A; 2]` | 2-array | `[a0, a1]`, `[a2, a3]`, `[a4, a5]`, `[a6, a7]`, … |
| … | … | … |
| `[A; N]` | n-array | `[a0, …, aN]`, … |
[Arrays work just like in Rust](https://doc.rust-lang.org/std/primitive.array.html).
The empty array `[]` is basically useless, but is included for completeness.
Arrays `[a0, …, aN]` work like in most other programming languages.
Each array type `[A; N]` defines an element type `A` and a length `N`.
An array value `[a0, …, aN]` of that type consists of `N` many elements `a0`, …, `aN` that are each of type `A`.
Arrays are always of finite length.
> Arrays are different from tuples:
> Each element of an array must have the same type.
> Each element of a tuple can have a different type.
## List Types
**SimplicityHL List types work differently from what you might expect from other languages. Please see their details and limitations below.** Notably, a List type must be declared with a length that is an exact power of two, and the List can never hold the full number of items indicated by its declared length.
| Type | Description | Values |
|---------------------------|---------------------|------------------------------------------------------|
| `List` | <2-list | `list![]`, `list![a1]` |
| `List` | <4-list | `list![]`, …, `list![a1, a2, a3]` |
| `List` | <8-list | `list![]`, …, `list![a1, …, a7]` |
| `List` | <16-list | `list![]`, …, `list![a1, …, a15]` |
| `List` | <32-list | `list![]`, …, `list![a1, …, a31]` |
| `List` | <64-list | `list![]`, …, `list![a1, …, a62]` |
| `List` | <128-list | `list![]`, …, `list![a1, …, a127]` |
| `List` | <256-list | `list![]`, …, `list![a1, …, a255]` |
| `List` | <512-list | `list![]`, …, `list![a1, …, a511]` |
| … | … | … |
| `List` | <2^N-list | `list![]`, …, `list![a1, …, a_{2^N - 1}]` |
Lists hold a variable number of elements of the same type.
This is similar to [Rust vectors](https://doc.rust-lang.org/std/vec/struct.Vec.html), but SimplicityHL doesn't have a heap.
In SimplicityHL, lists exist on the stack, which is why the maximum list length is bounded.
<2-lists hold fewer than 2 elements, so zero or one element.
<4-lists hold fewer than 4 elements, so zero to three elements.
<8-lists hold fewer than 8 elements, so zero to seven elements.
And so on.
For technical reasons, the list bound is always a power of two.
The bound 1 isn't supported, because it would only allow empty lists, which is useless.
> Lists are different from arrays:
> List values hold a variable number of elements.
> Array values hold a fixed number of elements.
On the blockchain, you pay for every byte that you use.
If you use an array, then you pay for every single element.
For example, values of type `[u8; 512]` cost roughly as much as 512 individual `u8` values.
However, if you use a list, then you only pay for the elements that you actually use.
For example, the type `List` allows for up to 511 elements.
If you only use three elements `list![1, 2, 3]`, then you pay for exactly three elements.
You **don't** pay for the remaining 508 unused elements.
## Option Types
| Type | Values |
|-------------|-----------------------------------|
| `Option` | `None`, `Some(a0)`, `Some(a1)`, … |
Options represent values that might not be present. [They work just like in Rust](https://doc.rust-lang.org/std/option/index.html).
An option type is generic over a type `A`.
The value `None` is empty.
The value `Some(a)` contains an inner value `a` of type `A`.
In Rust, we implement options as follows.
```simplicityhl
enum Option {
None,
Some(A),
}
```
## Either Types
| Type | Values |
|----------------|--------------------------------------------------------|
| `Either` | `Left(a0)`, `Left(a1)`, …, `Right(b0)`, `Right(b1)`, … |
Sum types represent values that are of some "left" type in some cases and that are of another "right" type in other cases.
[They work just like in the either crate](https://docs.rs/either/latest/either/enum.Either.html).
[The Result type from Rust is very similar, too](https://doc.rust-lang.org/std/result/index.html).
A sum type is generic over two types, `A` and `B`.
The value `Left(a)` contains an inner value `a` of type `A`.
The value `Right(b)` contains an inner value `b` of type `B`.
In Rust, we implement sum types as follows.
```simplicityhl
enum Either {
Left(A),
Right(B),
}
```
## Enum Types
Enum types are available since SimplicityHL 0.7.0 (compiling with `-Z enums`).
Enum types are declared with a stanza like
```simplicityhl
enum A {
B,
C,
D,
E,
}
```
This declaration allows the type `A` to take on any of four listed values, called `A::B`, `A::C`, `A::D`, and `A::E`. The declaration stanza belongs at the top level of the program, outside of any executable code block.
Enum type values can also wrap objects of other types, when this is appropriately declared in the initial enum declaration. The `Enum` instances then contain inner variables of the specified types.
```simplicityhl
enum A {
B,
C(T),
D,
E(U),
}
```
In this declaration, `A::C` wraps another object of type `T`, while `A::E` wraps another object of type `U`.
Enum types are intended for use in matching witness values with the `match` statement, so that one of a list of pre-specified actions or choices can be selected easily. By wrapping other values where needed, the additional values appropriate to a specific action or choice can also be provided in the witness.
| Type | Values (pursuant to declaration of a specific Enum) |
|----------------|--------------------------------------------------------|
| `EnumX` | `EnumX::A(T)`, `EnumX::B(U)`, `EnumX::C(V)` …, |
### Type Aliases
# Type Aliases
SimplicityHL currently doesn't support Rust-like `struct`s for organizing data.
```simplicityhl
struct User {
active: bool,
id: u256,
sign_in_count: u64,
}
```
SimplicityHL programmers have to handle long tuples of unlabeled data, which can get messy.
```simplicityhl
(bool, u256, u64)
```
To help with the situation, programmers can define custom type aliases.
Aliases define a new name for an existing type.
In contrast, `struct`s define an entirely new type, so aliases are different from `struct`s.
However, aliases still make the code more readable.
```simplicityhl
type User = (bool, u256, u64);
```
There is also a list of builtin type aliases.
These aliases can be used without defining them.
| Builtin Alias | Definition |
|------------------|-------------------------------|
| `Amount1` | `Either<(u1, u256), u64>` |
| `Asset1` | `Either<(u1, u256), u256>` |
| `Confidential1` | `(u1, u256)` |
| `Ctx8` | `(List, (u64, u256))` |
| `Distance` | `u16` |
| `Duration` | `u16` |
| `ExplicitAmount` | `u64` |
| `ExplicitAsset` | `u256` |
| `ExplicitNonce` | `u256` |
| `Fe` | `u256` |
| `Ge` | `(u256, u256)` |
| `Gej` | `((u256, u256), u256)` |
| `Height` | `u32` |
| `Lock` | `u32` |
| `Message` | `u256` |
| `Message64` | `[u8; 64]` |
| `Nonce` | `Either<(u1, u256), u256>` |
| `Outpoint` | `(u256, u32)` |
| `Point` | `(u1, u256)` |
| `Pubkey` | `u256` |
| `Scalar` | `u256` |
| `Signature` | `[u8; 64]` |
| `Time` | `u32` |
| `TokenAmount1` | `Either<(u1, u256), u64>` |
### Type Casting
# Casting
A SimplicityHL type can be cast into another SimplicityHL type if both types share the same structure.
The structure of a type has to do with how the type is implemented on the Simplicity "processor".
Below is a table of types that can be cast into each other.
| Type | Casts To (And Back) |
|----------------|------------------------------------|
| `bool` | `Either<(), ()>` |
| `Option` | `Either<(), A>` |
| `u1` | `bool` |
| `u2` | `(u1, u1)` |
| `u4` | `(u2, u2)` |
| `u8` | `(u4, u4)` |
| `u16` | `(u8, u8)` |
| `u32` | `(u16, u16)` |
| `u64` | `(u32, u32)` |
| `u128` | `(u64, u64)` |
| `u256` | `(u128, u128)` |
| `(A)` | `A` |
| `(A, B, C)` | `(A, (B, C))` |
| `(A, B, C, D)` | `((A, B), (C, D))` |
| … | … |
| `[A; 0]` | `()` |
| `[A; 1]` | `A` |
| `[A; 2]` | `(A, A)` |
| `[A; 3]` | `(A, (A, A))` |
| `[A; 4]` | `((A, A), (A, A))` |
| … | … |
| `List` | `Option` |
| `List` | `(Option<[A; 2]>, List)` |
| `List` | `(Option<[A; 4]>, List)` |
| `List` | `(Option<[A; 8]>, List)` |
| `List` | `(Option<[A; 16]>, List)` |
| `List` | `(Option<[A; 32]>, List)` |
| `List` | `(Option<[A; 64]>, List)` |
| `List` | `(Option<[A; 128]>, List)` |
| `List` | `(Option<[A; 256]>, List)` |
| … | … |
## Casting Rules
Type `A` can be cast into itself (reflexivity).
If type `A` can be cast into type `B`, then type `B` can be cast into type `A` (symmetry).
If type `A` can be cast into type `B` and type `B` can be cast into type `C`, then type `A` can be cast into type `C` (transitivity).
## Casting Expression
All casting in SimplicityHL happens explicitly through a casting expression.
```simplicityhl
::into(input)
```
The above expression casts the value `input` of type `Input` into some output type.
The input type of the cast is explicit while the output type is implicit.
In SimplicityHL, the output type of every expression is known.
```simplicityhl
let x: u32 = 1;
```
In the above example, the meaning of the expression `1` is clear because of the type `u32` of variable `x`.
Here, `1` means a string of 31 zeroes and 1 one.
_In other contexts, `1` could mean something different, like a string of 255 zeroes and 1 one._
The SimplicityHL compiler knows the type of the outermost expression, and it tries to infer the types of inner expressions based on that.
When it comes to casting expressions, the compiler has no idea about the input type of the cast.
The programmer needs to supply this information by annotating the cast with its input type.
```simplicityhl
let x: u32 = <(u16, u16)>::into((0, 1));
```
In the above example, the tuple `(0, 1)` of type `(u16, u16)` is cast into type `u32`.
Consult the table above to verify this is a valid cast.
### Let Statements
# Let Statement
Variables are defined in let statements, [just like in Rust](https://doc.rust-lang.org/std/keyword.let.html).
```simplicityhl
let x: u32 = 1;
```
The above let statement defines a variable called `x`.
The variable is of type `u32` and it is assigned the value `1`.
```simplicityhl
let x: u32 = f(1337);
```
Variables can be assigned to the output value of any expression, such as function calls.
## Explicit typing
In SimplicityHL, the type of a defined variable **always** has to be written.
This is different from Rust, which has better type inference.
## Immutability
SimplicityHL variables are **always** immutable.
There are no mutable variables.
## Redefinition and scoping
The same variable can be defined twice in the same scope.
The later definition overrides the earlier definition.
```simplicityhl
let x: u32 = 1;
let x: u32 = 2;
assert!(jet::eq_32(x, 2)); // x == 2
```
Normal scoping rules apply:
Variables from outer scopes are available inside inner scopes.
A variable defined in an inner scope shadows a variable of the same name from an outer scope.
```simplicityhl
let x: u32 = 1;
let y: u32 = 2;
let z: u32 = {
let x: u32 = 3;
assert!(jet::eq_32(y, 2)); // y == 2
x
};
assert!(jet::eq_32(z, 3)); // z == 3
```
## Pattern matching
There is limited pattern matching support inside let statements.
```simplicityhl
let (x, y, _): (u8, u16, u32) = (1, 2, 3);
let [x, _, z]: [u32; 3] = [1, 2, 3];
```
In the first line, the tuple `(1, 2, 3)` is deconstructed into the values `1`, `2` and `3`.
These values are assigned to the variable names `x`, `y` and `_`.
The variable name `_` is a special name that ignores its value.
In the end, two variables are created: `x: u32 = 1` and `y: u16 = 2`.
Similarly, arrays can be deconstructed element by element and assigned to a variable each.
### Match Expression
# Match Expression
A match expression conditionally executes code branches.
Which branch is executed depends on the input to the match expression.
```simplicityhl
let result: u32 = match f(42) {
Left(x: u32) => x,
Right(x: u16) => jet::left_pad_low_16_32(x),
};
```
In the above example, the output of the function call `f(42)` is matched.
`f` returns an output of type `Either`.
If `f(42)` returns a value that matches the pattern `Left(x: u32)`, then the first match arm is executed.
This arm simply returns the value `x`.
Alternatively, if `f(42)` returns a value that matches the pattern `Right(x: u16)`, then the second match arm is executed.
This arm extends the 16-bit number `x` to a 32-bit number by padding its left with zeroes.
Because of type constraints, the output of `f` must match one of these two patterns.
The whole match expression returns a value of type `u32`, from one of the two arms.
## Explicit typing
In SimplicityHL, the type of variables inside match arms must **always** be written.
This is different from Rust, which has better type inference.
## Pattern matching
There is limited support for pattern matching inside match expressions.
Boolean values can be matched.
The Boolean match expression is the replacement for an "if-then-else" in SimplicityHL.
```simplicityhl
let bit_flip: bool = match false {
false => true,
true => false,
};
```
Optional values can be matched.
The `Some` arm introduces a variable which must be explicitly typed.
```simplicityhl
let unwrap_or_default: u32 = match Some(42) {
None => 0,
Some(x: u32) => x,
};
```
Finally, `Either` values can be matched.
Again, variables that are introduced in match arms must be explicitly typed.
```simplicityhl
let map_either: u32 = match Left(1337) {
Left(x: u32) => f(x),
Right(y: u32) => f(y),
};
```
Since SimplicityHL 0.5.0, the match expression also supports further pattern matching, similar to Rust.
```simplicityhl
let unwrap_or_default: u32 = match Some((4, 2)) {
None => 0,
Some((y, z): (u16, u16)) => <(u16, u16)>::into((y, z)),
};
```
This is more concise than including code to perform the deconstruction inside the match arm.
For example, the code above is a more concise alternative to this version that subsequently deconstructes the tuple `x` of type `(u16, u16)` into two integers `y` and `z` of type `u16`.
```simplicityhl
let unwrap_or_default: u32 = match Some((4, 2)) {
None => 0,
Some(x: (u16, u16)) => {
let (y, z): (u16, u16) = x;
<(u16, u16)>::into((y, z))
}
};
```
The match arm can also contain match expressions for further deconstruction.
For example, the sum value `x` of type `Either` can be matched as either `Left(y: u32)` or `Right(z: u32)`.
```simplicityhl
let unwrap_or_default: u32 = match Some(Left(42)) {
None => 0,
Some(x: Either) => match x {
Left(y: u32) => y,
Right(z: u32) => z,
},
};
```
## Enum matching
Since SimplicityHL 0.7.0 (compiling with `-Z enums`), you can match on all values of an `enum` type.
This is useful for *actions* at the top level of a contract's `main()` function. Matching an `enum` lets a [witness](../glossary.md#witness) choose from among several predefined actions.
```simplicityhl
enum Action {
Inherit(Signature),
ColdSpend(Signature),
HotSpend(Signature),
}
// ...
match witness::ACTION {
Action::Inherit(sig: Signature) => inherit_spend(sig),
Action::ColdSpend(sig: Signature) => cold_spend(sig),
Action::HotSpend(sig: Signature) => refresh_spend(sig),
}
```
In this example, `witness::ACTION` is an object of type `Action` (with the explicit value either `Inherit(sig)`, `ColdSpend(sig)`, or `HotSpend(sig)`). The SimplicityHL program uses this value to learn which action the proposed transaction is attempting to take, and call the appropriate function to validate the conditions for that action.
## Only two branches per `match`
Differently from Rust, the `match` expression only allows two match arms (branches) per `match` (except for `enum` types).
For example, it is currently not possible to match `Left(Left(x: u8))`, `Left(Right(x: u8)`, `Right(Left(x: u8))`, and `Right(Right(x: u8))` as arms of a single `match` expression.
Matching these four possibilities instead requires two nested `match` expressions.
This limitation doesn't apply to the `enum` matching described above. A `match` on an `enum` type should contain exactly one branch for each declared value of that `enum` type, regardless of how many values the `enum` type can take on.
### Defining Functions
# Functions
Functions are defined and called [just like in Rust](https://doc.rust-lang.org/std/keyword.fn.html).
```simplicityhl
fn add(x: u32, y: u32) -> u32 {
let (carry, sum): (bool, u32) = jet::add_32(x, y);
match carry {
true => panic!(), // overflow
false => {}, // ok
};
sum
}
```
The above example defines a function called `add` that takes two parameters: variable `x` of type `u32` and variable `y` of type `u32`. The function returns a value of type `u32`.
The body of the function is a block expression `{ ... }` that is executed from top to bottom.
The function returns on the final line _(note the missing semicolon `;`)_.
In the above example, `x` and `y` are added via the `add_32` jet.
The function then checks if the carry is true, signaling an overflow, in which case it panics.
On the last line, the value of `sum` is returned.
The above function is called by writing its name `add` followed by a list of arguments `(40, 2)`.
Each parameter needs an argument, so the list of arguments is as long as the list of parameters.
Here, `x` is assigned the value `40` and `y` is assigned the value `2`.
```simplicityhl
let z: u32 = add(40, 2);
```
## No early returns
SimplicityHL has no support for an early return via a "return" keyword.
The only branching that is available is via [match expressions](./match_expression.md).
## No recursion
SimplicityHL has no support for recursive function calls.
A function can be called inside a function body if it has been defined before.
This means that a function can't call itself.
Loops, where `f` calls `g` and `g` calls `f`, are also impossible.
What _is_ possible are stratified function definitions, where level-0 functions depend on nothing, level-1 functions depend on level-0 functions, and so on.
```simplicityhl
fn level_0() -> u32 {
0
}
fn level_1() -> u32 {
let (_, next) = jet::increment_32(level_0());
next
}
fn level_2() -> u32 {
let (_, next) = jet::increment_32(level_1());
next
}
```
## Order matters
If function `g` calls function `f`, then `f` **must** be defined before `g`.
```simplicityhl
fn f() -> u32 {
42
}
fn g() -> u32 {
f()
}
```
## Main function
The `main` function is the entry point of each SimplicityHL program.
Running a program means running its `main` function.
Other functions are called from the `main` function.
```simplicityhl
fn main() {
// ...
}
```
The `main` function is a reserved name and must exist in every program.
SimplicityHL programs are always "binaries".
There is no support for "libraries".
## Jets
Jets are predefined and optimized functions for common use cases.
```simplicityhl
jet::add_32(40, 2)
```
Jets live inside the namespace `jet`, which is why they are prefixed with `jet::`.
They can be called without defining them manually.
It is usually more efficient to call a jet than to manually compute a value.
[The jet documentation](https://docs.rs/simfony-as-rust/latest/simfony_as_rust/jet/index.html) lists each jet and explains what it does.
### Modules and Imports Reference
# Modules and imports reference
An informal introduction to this feature is available in the [introduction to modules and imports](../documentation/modules.md).
The modules and imports feature is available experimentally since SimplicityHL 0.6.0 (compiling with `-Z imports`). Modules let you organize a program as multiple files and/or nested `mod` blocks, and let you import function and type definitions from elsewhere, whether from another file in your own project or from a separate project entirely. The syntax is a subset of that used by Rust.
The SimplicityHL modules mechanism also supports the [SimplicityHL standard library](../documentation/stdlib.md).
!!! warning "Unstable feature"
Everything on this page (`use`, `mod`, `as`, `pub`, and `crate::`) requires compiling with `simc -Z imports`, and this behavior is subject to change.
## Exporting with `pub`
The objects that can be exported and imported in SimplicityHL are functions and type aliases. SimplicityHL doesn't currently have any way to declare module-level constants, so these can't be exported or imported.
By default, every function and type alias is private to the file (or the `mod` block, see below) that declares it. To make a function, type alias, `mod` block, or `use` import visible to other files, put `pub` in front of its declaration. A `pub use` is a *re-export*; see [Re-exporting](#re-exporting-with-pub-use) below.
## Importing with `use`
Reference the item you want with a `use` declaration, giving its full path and ending in `;`.
### Local paths (`crate::`)
Local files (that is, files belonging to your own project rather than an external dependency) are addressed with the `crate::` prefix. Path resolution walks the remaining segments greedily: each segment that names an existing subdirectory is descended into, and the first segment that instead matches `.simf` (the name, without the `.simf` extension) marks the file being imported from. Any segments still remaining after that point name a chain of nested `mod` blocks inside that file, ending in the actual function or type being imported.
```simplicityhl
use crate::math::foo::bar;
```
Here, `math` is a subdirectory, `foo` is the file `math/foo.simf`, and `bar` is a `pub` item defined in that file: either directly, or, if the path had further segments, nested inside `pub mod` blocks within it.
By default, `crate::` is rooted at the directory containing the entry file you pass to `simc`. `simc --project-root ` (added in 0.7.2) can anchor it at a different directory instead, which allows the entry file to live in a subdirectory of the project.
There is no `super::` or other syntax for referring to a parent module relatively. Every local path is written in full, starting from `crate::`.
### Declaring modules inline with `mod`
Instead of (or alongside) splitting code into separate files, `mod name { ... }` groups items into a named namespace within a single file. `mod` blocks can be marked `pub` and nested to any depth:
```simplicityhl
mod math {
pub mod ops {
pub fn double(x: u32) -> u32 {
let (_, res): (bool, u32) = jet::add_32(x, x);
res
}
}
}
use crate::math::ops::double;
fn main() {
assert!(jet::eq_32(double(21), 42));
}
```
A `use` declaration is required to reach a sibling `mod` block's items even when both are defined in the same file. `pub`/`use` visibility rules don't distinguish between "same file" and "different file".
As a special case, `enum` declarations can't be placed inside any `mod` block, and (independently of modules) can only appear in the compiler's entry file, not in any other local file or in a dependency. (Enum identity is currently tied to the compiler's internal file-numbering, which isn't guaranteed stable once other files are involved; see [Enum Types](type.md#enum-types).)
### Aliasing with `as`
```simplicityhl
use crate::math::foo::bar as baz;
```
`bar` from `math/foo.simf` is available under the local name `baz` instead. Aliasing an import to `main` is an error, regardless of the imported item's original name.
### Importing multiple items at once
```simplicityhl
use crate::math::foo::{bar, baz as qux};
```
imports both `bar` and `baz` (renamed to `qux`) from the same file or `mod` block via a single declaration; aliasing with `as` works per item inside the list. There is no wildcard/glob form (the Rust-like form `use crate::math::foo::*;` isn't supported). Every imported name must be listed explicitly, either on its own or inside a `{ }` list.
### Re-exporting with `pub use`
Adding `pub` in front of a `use` declaration imports the item for use in the current file and also re-exports it, making it available for other files to import from this file/module, under its own path:
```simplicityhl
pub use crate::math::foo::bar;
```
Re-exports may be chained across any number of files. This is how the SimplicityHL standard library and multi-file "façade" libraries can expose a flat, curated set of names while splitting their actual implementations across multiple files.
## External library dependencies
To import from a `.simf` source tree other than the one containing your file, register it with the `simc` compiler's `--dep` flag:
```bash
simc -Z imports --dep NAME=PATH main.simf
```
This maps the prefix `NAME` to the directory `PATH` (relative or absolute) for that compile. A `use NAME::...` path is then resolved exactly like a `crate::...` path, but rooted at `PATH` instead of the project root:
```simplicityhl
use elsewhere::foo::bar;
```
When a program containing the code above is compiled with `simc -Z imports --dep elsewhere=../libs/elsewhere_dir main.simf`, the compiler looks for `bar` in `../libs/elsewhere_dir/foo.simf`. `--dep` can be repeated to register any number of dependencies, each under its own alias.
### Scoping a dependency with `CONTEXT:`
A `--dep` argument may optionally be prefixed with a context directory:
```bash
simc -Z imports --dep CONTEXT:NAME=PATH main.simf
```
This restricts the `NAME` alias so it only resolves for files located under `CONTEXT` (a path relative to, or equal to, the project root); files outside `CONTEXT` don't see `NAME` as a valid dependency at all. This lets different parts of a larger project map the same alias name to different targets, or limit which of your own files are allowed to see a given dependency. A plain `NAME=PATH` (no `CONTEXT:`) makes the alias available to every file in the project.
A file can't be imported both as a local (`crate::`) file and, through a `--dep` alias, as if it were external to the project. The compiler rejects this as an error.
### Programs
# Programs
A SimplicityHL program consists of a `main` [function](./function.md).
A program may also have [type aliases](./type_alias.md) or custom [function definitions](./function.md).
The `main` function comes last in the program, because everything it calls must be defined before it.
```simplicityhl
type Furlong = u32;
type Mile = u32;
fn to_miles(distance: Either) -> Mile {
match distance {
Left(furlongs: Furlong) => jet::divide_32(furlongs, 8),
Right(miles: Mile) => miles,
}
}
fn main() {
let eight_furlongs: Either = Left(8);
let one_mile: Either = Right(1);
assert!(jet::eq_32(1, to_miles(eight_furlongs)));
assert!(jet::eq_32(1, to_miles(one_mile)));
}
```
### Built-in Functions
# Built-in functions
[SimplicityHL](../glossary.md#simplicityhl) offers several built-in functions and macros. These are additional to the hundreds of [jets](../documentation/jets.md) provided by each Simplicity [integration](../glossary.md#integration).
|