Manifest field reference

Every field the manifest format defines, generated from schema/txmanifest.schema.json — the schema the reference wallet emits from the types it parses with, so this page cannot drift from the engine. See schema/README.md for the exact revision it was taken from.

A field not listed here is a parse error, not an ignored key. Two exceptions apply everywhere and are not repeated per type: $comment (documentation a tool must ignore) and $schema (an editor hint), both legal on any object at any depth.

For what the type strings mean — u64, pubkey, liquid.asset_id — see Field types.

Manifest (root)

actions — map of string → Action

Standalone actions that require no template instance (e.g. Prepare).

chain — string

No description in the schema.

contract_templates — map of string → ContractTemplate

Contract template definitions. Each template has typed fields and actions. An action carrying a create_instance block is a constructor for its template.

description — string

No description in the schema.

manifest_version — string, required

Version of the manifest format this file is written against, as specified by ELIP-205 — not the version of any tool that reads it. Checked against FORMAT_VERSION at parse time; see check_format_version for the compatibility rule.

protocol — string, required

No description in the schema.

simplicity_hl — SimplicityHl

SimplicityHL toolchain settings for this manifest's .simf programs.

utxo_types — map of string → UtxoType

No description in the schema.

Action

allow_change — AllowChange

Whether the engine may append a change output this action did not declare.

Every output a transaction carries must be written in the manifest. The network fee is the single exception, because it has no manifest spelling. A change output is not an exception: its address and amount are chosen by the engine, so silently adding one moves value to a destination the manifest never named, in an amount nobody wrote down. That is how an oversized collateral input once turned 88,735 satoshis into a miner's fee without a word of warning.

So the default is AllowChange::None: a surplus in any asset — including L-BTC — is an error, and the action must size its inputs to what it spends. Relax it only where the surplus genuinely cannot be predicted:

• "none" (default) — no change may be added; any surplus is an error.

• "lbtc_only" — the engine may return an L-BTC surplus to the wallet. Use this for ordinary funding actions, where the fee is only known after the size is. A surplus in any other asset is still an error.

• "any" — the engine may return a surplus in any asset.

This governs undeclared change. An output with "destination": "change" is declared, and permits change for its own asset regardless of this setting.

create_instance — InstanceCreate

Constructor-only: defines the new instance written to the instance file.

description — string

No description in the schema.

inputs — array of Input

No description in the schema.

intent — string

One-line statement of what this action does, shown as the first clear-signing screen. Supports {ref} and {ref:symbol} interpolation against the execution context (see preview::interpolate); asset-typed refs must carry :symbol so a wallet can substitute a friendly name (enforced by validate::check_ui).

Named for the intent field in Ethereum's ERC-7730 clear-signing metadata, which plays the same role. Author-supplied, so only as trustworthy as the manifest's own signature chain — never a substitute for what a hardware device verifies. It IS covered by the registry hash (see crate::canonical).

on_post_broadcast — HookBlock

Method-level hook: runs after broadcast (captures txids, asset IDs).

on_pre_broadcast — HookBlock

Method-level hook: runs after inputs are resolved, before PSET is built.

outputs — array of Output

No description in the schema.

params — map of string → ParamDef

Runtime action parameters (Spec §5). Prompted, or set by hooks.

AllowChange

Which assets an action lets the engine return a surplus in, via a change output the manifest did not declare. See Action::allow_change.

Spelled as an enum rather than a boolean because the useful middle case — "return leftover L-BTC, but never move a protocol asset I did not account for" — is the one most funding actions want, and a boolean cannot say it.

• "none" No undeclared change. A surplus in any asset fails the build.

• "lbtc_only" Only the policy asset (L-BTC) may be returned.

• "any" Any asset may be returned.

BlindingFactors

The blinding factors of one confidential output or input.

A wallet normally draws both factors at random, which is right when nothing but the receiver ever reads them. It is wrong when a covenant reads them: a program that checks its own outputs' commitments (deadcat_v3 requires each recreated reissuance token to advance both factors by exactly one) can only be satisfied by factors the spender chose deliberately. Elements' blind_last offers no way to say which, so the engine runs its own blinding pass whenever this field appears.

Each factor is a 32-byte scalar written as a small decimal ("1"), a 0x-prefixed hex string of up to 64 chars, or a reference (params.X, instance.X) resolving to either — which is how a factor an operator reads off an explorer or a side file reaches the build.

On an output it pins what the builder would otherwise choose. Omitting one leaves it random; omitting both makes the field a no-op. One confidential output must keep a free value_bf: the transaction's blinding factors have to sum to zero and the builder solves the last free one to make that true, so pinning every one of them leaves the transaction unbalanceable. In practice that free output is the change.

On a covenant input it is not a choice but a statement of fact — the factors the UTXO being spent was created with. They are what lets the engine rebuild the confidential prevout the sighash and the introspection jets need, and (for a reissuance) the assetBlindingNonce Elements demands. Both halves are required, and a wrong value is caught before signing: the rebuilt commitments simply will not be the ones on chain.

The factors are public to anyone who reads them here, so this trades the output's confidentiality for reissuability: it hides nothing, it only keeps the commitment well-formed. Elements has no explicit reissuance token (confidential_validation.cpp rebuilds the spent token's generator from the blinding nonce and byte-compares it), so a token that must stay reissuable must stay blinded, with a factor its next spender can reproduce.

asset_bf — any

Asset blinding factor (abf). Also the value Elements requires as the assetBlindingNonce of any later reissuance spending this output.

value_bf — any

Value blinding factor (vbf).

ComputeSpec

How a value is computed: either a plain expression string or a structured spec.

Used in two places, deliberately the same shape: create_instance.fields values and ParamDef::compute.

Hand-deserialized rather than #[serde(untagged)], for the same reason as UiSpec: untagged collapses every inner failure into data did not match any variant of untagged enum ComputeSpec, which hides the one thing the author needs to know. Dispatching on the JSON shape lets ParamCompute's error — naming the offending key or the unknown type — reach the surface.

• string Simple expression: "$params.COLLATERAL_ASSET_ID", "instance.DEBT - 1".

• object Structured compute — tapleaf, simf_fn, or an explicit expr.

ContractTemplate

A contract template: typed field declarations and named methods.

actions — map of string → Action

Actions callable on an instance of this template. Structurally identical to the top-level actions — the only difference is that these run against an instance, so their formulas may reference instance.*. An action carrying a create_instance block constructs a new instance of this template.

description — string

No description in the schema.

fields — map of string → FieldDef

Field declarations — names and types only. Values are set by constructors.

FieldDef

A field declaration inside a contract template. Just a name and type; no compute here.

default — string

No description in the schema.

description — string

No description in the schema.

type — string, required

No description in the schema.

HookBlock

A hook: a flat map of setter targets to the values they take.

One type serves every hook position — an action's on_pre_broadcast / on_post_broadcast and an input's on_resolved — because they only ever differed in when they run, never in shape.

Targets use dot-path notation: "instance.FOO" — sets a contract-template field "params.FOO" — sets an action param

Values are ComputeSpec, the same type create_instance.fields uses, so all three "name → how to produce a value" maps in the format read alike. In hook position only the expression forms are meaningful; validate rejects the rest (see validate::check_hook).

Within an input's own on_resolved, two bare keywords are self-referential: "asset" resolves to that input's computed issuance asset ID (or its UTXO asset for non-issuance inputs), and "reissuance_token" to the computed reissuance token asset ID.

set — map of string → ComputeSpec, required

No description in the schema.

Input

amount_sat — any

No description in the schema.

asset — any

No description in the schema.

blinding — BlindingFactors

The blinding factors of the covenant UTXO this input spends, when it is confidential. Both halves are required. See BlindingFactors.

description — string

No description in the schema.

from_address — string

For utxo_source: "wallet" inputs: constrain coin selection to UTXOs whose scriptPubKey equals this address's. A reference (instance.X / params.X) or a literal address string. Use this to pin an input to a committed address — e.g. so a covenant's collateral is spent from the exact address whose hash it commits to.

id — string, required

No description in the schema.

issuance — any

An Elements asset issuance carried by this input.

• {"kind": "new", "asset_amount_sat": <expr>, "inflation_amount_sat": <expr>} — mint a brand-new asset, whose id is derived from this input's outpoint. Either amount may be 0 (reissuance tokens only, or a fixed supply with no reissuance rights). - {"kind": "reissue", "asset_amount_sat": <expr>, "entropy": <ref>} — mint more of an existing asset by spending its reissuance token.

A reissuance needs the issuance entropy of the original mint — fast_merkle_root([sha256d(defining outpoint), contract_hash]), the value the asset id itself is derived from. It cannot be recovered from anything on chain: the reissuance token UTXO carries no trace of the outpoint that created it. So a constructor has to capture it at the one moment it exists, and hand it back later:

json // in the minting action's create_instance: "YES_ISSUANCE_ENTROPY": "$inputs.yes_defining_in.issuance_entropy" // in the reissuing action's input: "issuance": { "kind": "reissue", "asset_amount_sat": "params.PAIRS", "entropy": "instance.YES_ISSUANCE_ENTROPY", "issued_asset": "instance.YES_TOKEN_ASSET" }

issued_asset is optional and is a check, not an input: the engine re-derives the asset id from the entropy and refuses to build if the two disagree. An entropy is opaque, and the byte order block explorers print is the reverse of the one used here — without the check a transposed value still builds a broadcastable transaction that reissues the wrong asset.

Failing that, the entropy may come from provided_inputs.<input_id>.issuance_entropy in the instance file. That works, but it travels with an outpoint override which pins the input for every action sharing its id — long after the pin is correct.

on_resolved — HookBlock

Inline hook evaluated after this input's UTXO is resolved and its issuance attrs (asset, reissuance_token) are computed.

optional — boolean

When true, the transaction proceeds even if this UTXO is not found. Spec §6.

⚠️ Parsed but NOT enforced — the engine has no optional-input path, so a missing UTXO fails resolution regardless. examples/dex marks its fee_input optional and does not get that behaviour.

required_index — integer

Required transaction input index: 0-based absolute, or negative to count from the end (-1 = last). Spec §6.

⚠️ Parsed but NOT enforced. Nothing in the engine reads this field; inputs land in declaration order and that ordering happens to satisfy the covenants. Manifests assert an index here 106 times and none of it is checked, so a reordering that breaks a covenant's introspection would surface only as an on-chain failure. See validate.rs for where a static check belongs.

sequence — any

Per-input nSequence. Drives BIP68 relative timelocks (the check_lock_distance / check_lock_duration Simplicity jets). Accepts:

• {"relative_blocks": <expr>} — block-based relative lock (≤ 65535 blocks)
• {"relative_seconds": <expr>} — time-based relative lock, rounded up to 512s units - a bare integer / expression — raw nSequence value

Omitted → the input stays at Sequence::MAX (relative locktime disabled).

ui — UiSpec

Clear-signing UI hint for this input (net-effect debit line).

utxo_source — any, required

"wallet" or {"utxo_type": "..."} or conditional object

witnesses — any

Simplicity witnesses for this input: map of witness name → definition.

Must name every witness the input's program declares, and nothing else. A definition is either an object carrying a type — simplicityhl (a concrete value), Signature (a BIP340 signature the engine computes), taproot_leaf (a leaf selector, which is not a program witness and so is exempt from both halves of that rule) — or the bare string "unused" for a witness this spending path does not depend on, which supplies the zero its pruned branch wants.

Nothing is inferred from an omission. Anything left out is an error, at validate time against the .simf and again at run time against the compiled program.

InstanceCreate

Describes the new instance written after broadcast.

An action carrying this block is a constructor — there is no separate flag. The instance is always of the contract template the action is declared in, so the template is not named here: create_instance is only legal inside contract_templates.<T>.actions.*, and always creates a <T>.

fields — map of string → ComputeSpec, required

Maps field names to their initial values. Each value is either a string expression ("$params.FOO") or a compute spec ({ "compute": "tapleaf", ... }).

Output

amount_sat — any

No description in the schema.

asset — any

No description in the schema.

blinding — BlindingFactors

Pin this confidential output's blinding factors instead of letting the builder pick them. See BlindingFactors.

condition — string

No description in the schema.

confidential — boolean

Whether this output is blinded. The only place confidentiality is declared: a utxo_type describes an address, and two outputs paying the same covenant address need not agree — deadcat_v3's state-1 address holds blinded reissuance tokens beside an explicit collateral UTXO, because the program introspects one as a Pedersen commitment and the other as a plain amount.

Defaults to true for wallet and address destinations on Liquid, and to false for covenant (utxo_type) destinations, where a Simplicity program usually has to read the value and asset. true on a covenant output is not supported yet and is an error rather than a silent downgrade — the address it produces would be right and the UTXO at it unspendable by the paths that expect a commitment.

data — any

OP_RETURN payload, for destination: {"type":"op_return"} outputs. Either a concat(ref, …) string, or an object {"parts": [ … ]} of typed fields (for exact binary layouts — LE integers, program_id, asset-internal bytes). Evaluated to raw bytes and embedded after OP_RETURN. Omit for a bare data-less OP_RETURN (NFT burns).

description — string

No description in the schema.

destination — OutputDestination, required

Where this output's value goes. See OutputDestination for the accepted forms.

id — string, required

No description in the schema.

optional — boolean

No description in the schema.

required_index — integer

Required transaction output index; same semantics and same caveat as Input::required_index (Spec §7) — parsed, never enforced.

ui — UiSpec

Clear-signing UI hint for this output (net-effect credit line).

OutputDestination

Where this output's value goes. A string is change (wallet change, amount auto-computed), wallet (a fresh receive address), or an address / params.X reference resolving to one.

• string change, wallet, a literal address, or a params.X / instance.X reference that resolves to one.

• object The covenant address derived for a declared utxo_type.

  Fields: args?, compile_params?, utxo_type — ? marks an optional field.

• object P2TR output built from a 32-byte script hash.

  Fields: script_hash

• "type": "op_return" op_return / burn embed the output's own data field (bare OP_RETURN when absent). fee declares the fee leg and produces no PSET output of its own.

• object Conditional destination. Parsed but NOT implemented — the engine has no arm for it and skips the output entirely.

ParamCompute

Auto-computation spec for a derived compile param or action param.

Dispatched by type, the same discriminator every other tagged object in the format uses (script.type, destination.type, a witness's type). Note this is the method of computation; the value's data type is ParamDef::type_, one level up. The legacy key lang is still accepted as an alias for the discriminator:

• "expr": arithmetic expression over other compile params (pow(base, exp) supported)
• "tapleaf": compile a .simf file and return its Simplicity tapleaf hash (32 bytes hex)
• "simf_fn": call a named function in a .simf file and use its return value
• "wallet": take the value from the executing wallet rather than the manifest, with wallet selecting which (WalletValue)

The wallet variant differs from the others in kind: expr, tapleaf and simf_fn are reproducible by anyone holding the manifest, whereas a wallet_* value depends on who is running the action. They live here anyway because from an author's point of view they answer the same question — where does this value come from, if not the user? — and having two fields for that (the old source) meant two things to check and a name that collided with script.source, a file path.

• "type": "expr"

  Fields: expr

• "type": "tapleaf"

  Fields: depends_on?, extra_leaves?, params?, simf — ? marks an optional field.

• "type": "script_hash" sha256(scriptPubKey) of an address — the exact value the Simplicity output_script_hash / input_script_hash jets return for a UTXO paying it.

  An address and its script hash are two views of one destination: the covenant commits to the hash, the transaction pays to the address, and if they ever disagree the spend fails on-chain. Deriving one from the other is the only way to keep that true — a manifest that asks for both separately is asking to be given two values that must match and cannot be checked.

  Blinding is irrelevant here: a confidential address has the same scriptPubKey as its unconfidential form, so both hash alike (script_hash_of_address pins this).

  Fields: address

• "type": "hook" A value a hook supplies later in this run — declared here, set by an on_resolved / on_pre_broadcast block targeting params.<name>.

  This exists so a hook cannot invent an identifier. Without it, "set": { "params.YES_TOKN_ASSET": "asset" } is accepted, fills a slot nobody reads, and surfaces as a wrong covenant address much later; with it, validate rejects the typo and the declaration carries the type that byte-order handling depends on.

  It lives under compute rather than as a separate deferred: true flag because compute already means exactly "this value is derived, do not prompt for it" — the only thing that differs here is who derives it. A second flag would need its own prompt-suppression path and would have to define what it means alongside a compute that is also present.

• "type": "wallet" A value taken from the executing wallet rather than the manifest.

  Grouped under one tag rather than spread across three so that "is this wallet-derived?" is a single check on compute before dispatching on wallet — and so adding a new wallet-derived value does not grow the top-level variant list.

  Fields: wallet

• "type": "simf_fn" Call a named function in a .simf file after inputs are resolved. The function is compiled with compile_params as param:: constants. Its runtime input is read from input (a dot-path into ctx, e.g. "params.STATE_BYTES"). The return value is stored as the param value.

  Fields: compile_params?, fn?, input?, simf — ? marks an optional field.

ParamDef

compute — ComputeSpec

How this param's value is derived. When present the user is never prompted.

Either a bare expression string — "instance.PRINCIPAL_AMOUNT * 2" — or a structured spec for the cases an expression cannot express (tapleaf, simf_fn). The bare form is what formula used to be; they were two ways to say "this value is computed, do not ask", so they are now one.

default — string

Default value shown as a pre-fill in the prompt.

description — string

No description in the schema.

type — string, required

No description in the schema.

SimplicityHl

SimplicityHL toolchain settings — how the .simf programs are compiled, as distinct from what the protocol does.

Deliberately carries no compiler-version field. SimplicityHL has its own simc "<range>"; source directive, which the compiler enforces fail-fast before lexing, across the entry file and every reachable dependency — none of which a manifest key can do. Tooling that wants the requirement without compiling can read it via version::SimcDirective::requirement_of. Declaring it here as well would only create a second place to disagree.

debug_symbols — boolean, default false

Whether covenant .simf programs are compiled with debug symbols included.

This changes the program's CMR and therefore every covenant address, because assert!/panic! embed source info into fail-node commitments. Set it to match the toolchain of any protocol this manifest must interoperate with — e.g. true for simplicity-lending / smplx-sdk, which compiles with debug symbols on.

Defaults to false (production; debug symbols are a transitional feature).

unstable_features — array of UnstableFeatureName

Unstable SimplicityHL compiler features this manifest's programs are allowed to use — the manifest form of simc -Z <name>, one entry per feature:

json "simplicity_hl": { "unstable_features": ["enums"] }

The compiler rejects gated syntax unless the feature is enabled, so a program using enum fails to compile until "enums" is listed here. Enabling a feature the programs don't use is harmless: this only lifts a restriction, it never changes generated code, and therefore never changes a CMR or covenant address.

Manifest-wide rather than per-utxo_type, mirroring simc's own per-invocation -Z flag — the whole point of a gate is that a reader can see, in one place, which unstable syntax this protocol depends on.

Defaults to empty: nothing unstable is enabled.

TapleafParam

A single entry in a ParamCompute::Tapleaf params map. Combines the value reference (compile-param name or literal) with an optional type hint.

type — string

Manifest type, e.g. "liquid.asset_id", "u64", "bool". When absent, the type is inferred from the compile-param of the same name.

value — string, required

A compile-param name reference OR a string literal like "1", "true".

TaprootLeafKind

The hashing scheme for a TaprootLeafSpec's payload.

• "tapdata" Elements taproot data leaf — the only scheme the engine implements.

TaprootLeafPayloadItem

One item of a taproot leaf payload. Items are concatenated, in order, into the bytes that get hashed as the leaf.

• string Hex literal taken as raw bytes, e.g. "0x01". Whole bytes only.

• "type": "u8" Computed value, resolved against the run's params/instance fields and encoded per type / endian / pad_to.

  Fields: align?, endian?, pad_to?, value — ? marks an optional field.

• object Reference to a state_vars entry; its default_value is encoded as a single u8.

  Fields: state_var

TaprootLeafSpec

Describes one additional taproot leaf appended to the Simplicity program leaf.

Each leaf's payload is hashed as tapdata — SHA256(SHA256("TapData") ‖ SHA256("TapData") ‖ payload), which is the value a program computes with jet::tapdata_init(), sha_256_ctx_8_add_* and finalize — then folded into the tap tree with TapBranch/elements in declaration order, matching jet::build_tapbranch. The payload's width must match what the .simf hashes: sha_256_ctx_8_add_32 wants exactly 32 bytes, add_8 exactly 8. A mismatch yields a perfectly valid address that the covenant then refuses to recognize as its own.

payload — array of TaprootLeafPayloadItem, required

Ordered payload items, concatenated into this leaf's byte string.

type — TaprootLeafKind, required

How the payload is hashed. Only tapdata is implemented, and it was previously accepted as a free string — so any other spelling was silently hashed as tapdata anyway, producing an address whose derivation nobody had written down.

UiDetail

group — string

Override the net-effect account/bucket heading (else derived from source/destination).

hide — boolean, default false

Suppress this leg from the net-effect diff (e.g. pure protocol data).

label — string

Human-readable one-line description of this leg — the only signer-facing text for it (description is not a fallback; see preview::input_label).

Capped at crate::validate::MAX_UI_LABEL characters so it fits one net-effect row alongside the amount and asset symbol. The cap reaches the schema as a maxLength — injected by crate::schema from that constant rather than written here as a literal, so the two cannot drift — and an editor flags an over-long label while typing rather than at validate time.

role — string

Optional semantic tag (e.g. "collateral", "auth_nft").

UiSpec

Per-input / per-output UI hint. Accepts either a bare label string ("collateral locked") or a detailed object for finer control.

Hand-deserialized rather than #[serde(untagged)]: an untagged enum reports only data did not match any variant of untagged enum UiSpec, swallowing the real reason. Dispatching on the JSON shape lets UiDetail's own error through, so a misspelled key names itself.

• string Shorthand for { "label": "..." }.

• object

  Fields: group?, hide?, label?, role? — ? marks an optional field.

UnstableFeatureName

Unstable SimplicityHL compiler feature (simc -Z <name>).

• imports — Module system syntax: 'use' imports, 'mod' modules, 'as' aliases, 'crate::' paths
• enums — Enum syntax: 'enum' declarations and 'EnumName::Variant' match expressions

One of: "imports", "enums"

UtxoParamDef

One entry of a UtxoType::params interface.

default — string

Value to use when a site binds no args entry for this param.

Evaluated in instance scope: a literal, or instance.X naming a field fixed when the contract was instantiated. Action scope is deliberately unreachable — a value that varies per run is exactly what a site must bind explicitly.

Without a default, every site must bind it, and validate says which ones don't.

description — string

No description in the schema.

type — string, required

Manifest type, used as the compile-param type hint (u64, bytes32, liquid.asset_id, …) — the same vocabulary action params use.

UtxoScript

compile_params — map of string → string, default {}

Per-utxo-type compile param remappings: simf_param_name → compile_param_reference. e.g. { "SCRIPT_HASH": "LENDING_COV_HASH" } passes the value of LENDING_COV_HASH to the simf as SCRIPT_HASH.

extra_leaves — array of TaprootLeafSpec

No description in the schema.

source — string

No description in the schema.

type — string, required

No description in the schema.

UtxoType

asset — string

No description in the schema.

description — string, required

No description in the schema.

params — map of string → UtxoParamDef

This type's parameter interface — everything the address derivation may read.

Declaring it switches the type to a closed scope: script.compile_params and extra_leaves resolve params.X against these params and nothing else. A site binds them with args ({"utxo_type": "t", "args": {"STATE": "params.x"}}), whose values are expressions evaluated in the action's scope.

Without it, the type keeps the legacy behaviour: leaves and compile params resolve against whatever is ambient at each mention. That is what makes one utxo_type derive two different addresses in two actions — params.foo means one thing where the action declares foo and something else where it does not — with no error, because an address is a hash and a wrong one looks exactly like a right one.

script — UtxoScript

No description in the schema.

state_vars — any

No description in the schema.

WalletValue

Which wallet-derived value a ParamCompute::Wallet spec resolves to.

• "key" The wallet's x-only BIP340 pubkey. The wallet chooses the derivation path.

• "script_hash" sha256(scriptPubKey) of the wallet's index-0 explicit output — the committed payout target a covenant checks repayment against.

• "address" The explicit address matching WalletValue::ScriptHash. The two are a pair: the covenant commits to the hash, the wallet receives at the address, so they must be derived together.