Skip to content
LogoLogo

4. Locks and witnesses

lock = u8 kind ‖ varbytes payload

KindNamePayloadSpending witness
0BURN≤ 80 bytes of dataunspendable; never enters the UTXO set
1PUBKEY_HASHscheme_id(1) ‖ key_hash(32)[serialized_pk, signature]
2MULTISIG_HASHscheme_mask(1) ‖ policy_hash(32)[policy, slot_1 … slot_n]
3POLICYscheme_mask(1) ‖ TH("policy", encoding)(32)[encoding, item…] (§4.2)
16–127reserved1–64 bytesany non-empty witness, until a soft fork defines the kind (§4.3)
  • Kinds 4–15 and 128–255, unknown scheme ids, or a mask with unknown bits MUST fail decoding. A zero mask is invalid for MULTISIG_HASH; for POLICY it means a keyless policy.
  • PUBKEY_HASH witness: pk.scheme == payload[0], key_hash(pk) == payload[1:], and the signature verifies over the sighash (§6.4).
  • Multisig policy: u8 m ‖ varint n ‖ n × varbytes(serialized_pk), with 1 ≤ m ≤ n ≤ 15 and no duplicate keys. policy_hash = TH("multisig", policy). scheme_mask = OR of the bits of the keys' schemes, and MUST equal payload[0].
  • Multisig witness: exactly n slots; exactly m slots non-empty; each non-empty slot MUST verify against the key at the same position.
  • Witness item ≤ 65,536 bytes; at most 64 items.

4.2 Spending policies (POLICY)

A small fixed language, not a script VM:

KEY    0x01 varbytes(pk)                      AFTER  0x03 u32 height (> 0)
MULTI  0x02 u8 m, varint n, n × varbytes(pk)  OLDER  0x04 u32 blocks (1..65535)
SHA3   0x05 digest(32)                        AND 0x06 p q   OR 0x07 p q
THRESH 0x08 u8 k, varint n, n × p             SHA256 0x09 digest(32)
(1 ≤ m ≤ n ≤ 15; 1 ≤ k ≤ n ≤ 16)
  • Limits: depth ≤ 8; at most 20 keys, all distinct; at most 48 witness items; encoding ≤ 65,536 bytes. The encoding is canonical: no trailing bytes.
  • Lock: scheme_mask = OR of the key schemes (0 if the policy has no keys), and the commitment is TH("policy", encoding).
  • Witness: [encoding, item…]. Items are consumed in pre-order: KEY takes 1 (a signature or empty); MULTI takes n slots (all empty, or exactly m signatures); SHA3 and SHA256 take 1 (a 32-byte preimage or empty). AFTER, OLDER, AND, OR and THRESH take none of their own.
  • Evaluation:
    • KEY / MULTI: the signature(s) verify over the sighash (§6.4).
    • SHA3: sha3_256(preimage) == digest.
    • SHA256: sha256(preimage) == digest (FIPS 180-4). It exists for cross-chain atomic swaps: Bitcoin script and Ethereum both offer SHA-256 but not SHA3, and both sides of a swap must lock to the same digest (docs/INTEROP.md). Preimages are exactly 32 bytes, as on SHA3.
    • AFTER(h): tx.lock_time ≥ h.
    • OLDER(n): tx.version ≥ 2, the input's sequence has bit 31 clear and sequence & 0xFFFF ≥ n. §6 rule 2 enforces the coin's age.
    • AND / OR / THRESH: as their names say.
  • Validity: the root MUST be satisfied and every item consumed. A non-empty item that fails verification invalidates the transaction, even in an unused branch (bad-signature, bad-preimage), so a satisfied policy can't carry garbage.
  • Timelocks are properties of the transaction (lock_time, sequence, version), so validity never depends on which block includes it.

4.3 Reserved lock kinds (upgrade room)

Kinds 16–127 are valid to create, and are spent by any non-empty witness. A future soft fork (§9.4) gives a kind its rules, which only restricts what was allowed. This is the model of Bitcoin's undefined witness versions. Mempools treat these kinds as non-standard (§13). Defining a kind outside this range would be a hard fork.