A portable, wallet-agnostic JSON format for describing the full lifecycle of a Simplicity-based smart contract on Bitcoin / Liquid (Elements).
This repository holds the specification and a set of worked examples. It is the format definition, not an implementation — a wallet or tool reads a manifest and uses it to build, sign, and broadcast the right transactions.
Simplicity covenants let you express rich spending conditions on Liquid, but a raw covenant program says nothing about how a wallet should drive it: which UTXOs to select, what each output should contain, which signatures and preimages to supply, what to validate before broadcasting, and how a contract moves from one state to the next.
A transaction manifest captures all of that in one declarative document. Given a manifest, any conforming wallet can walk a user through executing a contract action — selecting inputs, constructing outputs, populating witnesses, running validations, and broadcasting — without hard-coding knowledge of the specific protocol. The manifest is the shared contract between protocol authors and the wallets that execute their protocols.
A live contract instance is described by three companion files:
| File | Naming | Purpose |
|---|---|---|
| Manifest | txmanifest.json |
Protocol definition — static, shared across all deployments |
| Instance | *.instance.json |
One deployment: locked compile-time parameters + on-chain genesis anchor |
| State | *.state.json |
Live on-chain UTXO set for this instance (full snapshot) |
The manifest is the reusable definition; the instance and state files are specific to a single deployed contract and evolve as it is used.
- Classes — contract types and their typed fields (the compile-time parameters baked into a covenant at deploy time).
- Actions / methods — the operations that can be executed against a live
instance, each describing:
- Inputs consumed (with UTXO selection rules and witness requirements),
- Outputs produced (destinations, assets, and amount formulas),
- Witnesses — the signatures, preimages, and typed values needed to satisfy each covenant,
- Validations — business-logic checks run before a transaction is built,
each carrying an
error(code+message) surfaced when it fails.
- UTXO types — the covenant scripts (
.simfprograms) that outputs are locked to, and how class fields are wired onto each program's parameters. - Lifecycle — documentation of named states, transitions, and execution paths.
See Spec.md for the authoritative field reference, and WALLET.md for the execution lifecycle a wallet follows when running an action.
Spec.md Current specification (draft)
WALLET.md Wallet integration guide — the execution lifecycle
examples/
p2pk/ Hello-world: pay-to-public-key via a Simplicity checksig program
last_will/ Inheritance / dead-man's-switch style contract
lending/ Collateralised lending protocol (multiple covenants)
Each example pairs a txmanifest.json with the .simf covenant source(s) it
references (and, where relevant, a params.json).
The p2pk example is the smallest complete
manifest: a Pay action that locks funds into a Simplicity pay-to-public-key
output, and a Receive action that spends it back to a wallet using a BIP340
Schnorr signature. It is the best starting point for reading the format.
Draft. The format is still evolving. Content-addressed identifiers (for
compact, verifiable transmission, including via QR) are planned, and field names
may still change. Expect breaking changes before a 1.0 release.
An example wallet that consumes these files lives in a separate repository: txmanifest-wallet.
Licensed under the Apache License, Version 2.0.