Skip to content

Contracts: Simplicity

Live on testnet For developers Simplifies the whitepaper, section 1.3

Sequentia has no account-based virtual machine and does not want one. Contracts are written as spending conditions on outputs, in two languages inherited from Elements:

  • Tapscript with introspection: Bitcoin Script, plus opcodes that let a script read the transaction spending it.
  • Simplicity: a typed language for spending conditions, in which the cost of every program is bounded before it runs.

Either one can express a covenant: an output whose script constrains what the spending transaction must itself pay. Every financial application on the testnet is built from them.

Why not a virtual machine

In an unbounded execution environment, the cost of validating a transaction is discovered by running it. That is why such chains need gas, and why they still congest: when a contract becomes popular, automated trading saturates the chain and traders bid against each other to be confirmed first.

Simplicity is deliberately not Turing complete. A program is a fixed graph of combinators and built-in functions called jets (arithmetic, hashing, signature checks, reading the transaction). Its worst-case cost is computed statically over the whole program, and the block’s weight must pay for it. A contract can be as demanding as it likes and still cannot surprise a validator.

What covenants are used for

Application What the covenant enforces
SeqDEX resting orders An order can only be taken by a transaction paying the maker the price the order named
Pignus loans Collateral can only leave by repayment, liquidation at the agreed price, or the other exits fixed when the loan opened
Levo sales Tokens can only leave by being sold at the published price to the published treasury, or reclaimed after the close date
OpenDAMP regulated assets Every transfer of the asset must satisfy the issuer’s policy
Arca Each node of an ark’s tree pins what its children must be
Pool payouts A pool’s rewards can only be paid to its delegators, each their exact share
Supply caps and mint limiters An asset can only be reissued up to a cap, or at a limited rate

None of these needed a change to consensus. That is the practical meaning of programmability here.

How a Simplicity program sits on the chain

A program lives in a taproot leaf, beside ordinary tapscript leaves; the same tree can mix both. The leaf does not contain the program, only a 32-byte commitment to it. The program itself is revealed when the output is spent, pruned to the branches that spend actually takes.

Go deeperLeaf version, witness and budget
  • A Simplicity leaf has leaf version 0xbe; tapscript on Sequentia is 0xc4.
  • The leaf’s “script” is the program’s commitment Merkle root (CMR).
  • A spend carries: the witness values, the pruned program, the CMR, the control block, and optionally an annex.
  • Each spend has an execution budget tied to its weight. A program whose worst case could exceed the budget is refused.

On the live testnet Simplicity activated by miner signalling; on the mainnet parameters it is active from genesis. getdeploymentinfo reports the state.

Reference: simplicity.md in the node repository.

The toolchain

Repository What it is
sequentia-contracts Where contracts are compiled, linted, tested and recorded. Pins one compiler version, checks that its library matches the node’s, and holds the shared helpers and the contract templates.
smplx Sequentia’s copy of Simplex, the Simplicity development framework: a CLI, an SDK and a local chain for integration tests.
sequentia-oracle The format of signed price attestations, and the process that signs them.
sequentia-registry Beside assets, a registry of contract templates, each verified against its sources and compiler, and of oracle keys.

Why the compiler is pinned

A program’s commitment, and therefore its address, depends on the compiler that built it. Two versions of the compiler can turn the same source into two different addresses. So sequentia-contracts pins one compiler, and every project depends on that crate, not on the compiler directly:

[dependencies]
sequentia-contracts = { git = "https://github.com/ConcatenaLabs/sequentia-contracts" }
use sequentia_contracts::{compile, cmr_hex, simplicityhl::Arguments};
let program = compile(source, Arguments::default())?;
println!("{}", cmr_hex(&program));

A contract built this way behaves on the chain exactly as it did in its tests.

Templates

A template is a contract with its parameters left open, published with a descriptor and golden test vectors. Address derivation for a template’s instance is mirrored in Python, JavaScript and Go, with no compiler needed, so a wallet or a website can compute a contract’s address from its terms and check it.

The block explorer names a spend of a known template (an escrow, an order, a loan) after it.

Prices on-chain: the oracle

A loan liquidated below a strike, an option, a stable asset: each needs a price. Sequentia does not build a price feed into consensus. A contract instead checks an oracle’s signature over a price itself, against a key written into the contract.

The attestation is a fixed 142-byte message (the oracle’s key, the two assets, the price, its precision, a time and a beacon), signed with a BIP340 Schnorr signature that both Simplicity and tapscript can verify.

An oracle posts a bond. Anyone who finds two signed prices from the same oracle for the same pair and time can slash it.

What the node wallet does not do

The node validates Simplicity spends and does nothing else with them. Sequentia Core’s wallet cannot build or sign a Simplicity output. Programs are compiled and satisfied outside the node, and transactions spending them are assembled by the application and submitted raw. The browser wallets show contract spends and ask you to approve them.

Go deeperA trap worth knowing: only a block proves a rule

The mempool runs every Simplicity leaf as Simplicity, as a matter of relay policy, even on a chain where consensus does not enforce it. So a transaction being refused by the mempool says nothing about what consensus would accept.

When you test that a contract refuses something, prove it by forcing the transaction into a block, and read which of the two refusals you got. The harness in sequentia-contracts does this for every template.

Read further