Covenant IDs & Bindings

Reconstructing a successor’s address proves its contents are right. It does not prove the UTXO you are spending is the real one.

Anyone can deploy a byte-identical copy of your token covenant and fund it. It will have the same program, the same address, and behave identically. Pure script cannot tell your lineage from a counterfeit, because there is nothing in the bytes that distinguishes them.

KIP-20 fixes this in consensus. Everything on this page is a network rule, not a convention — it holds for every covenant regardless of how its bytes are laid out.

The two fields

A Covenant ID is an optional 32-byte value stored on a UTXO. When present, the UTXO is a member of that covenant’s lineage.

A covenant binding is an optional field on a transaction output carrying two things:

• authorizing_input — the index of the input that authorizes this output’s creation
• covenant_id — the covenant the output belongs to

Covenant bindings require transaction version ≥ 1. A covenant UTXO comes into existence one of two ways:

Genesis

Genesis is where a Covenant ID is minted, and it is the step that has to be unforgeable — otherwise anyone could claim an existing lineage.

The transaction creator must compute the same ID that consensus will, store it in the output’s covenant binding, and submit. If consensus derives a different value, the transaction is rejected. The authorizing_input may be any valid input index.

covenant_id = BLAKE2b("CovenantID",
    outpoint.tx_id
    || le_u32(outpoint.index)
    || le_u64(len(auth_outputs))
    || for each output:
        le_u32(output_index)
        || le_u64(output.value)
        || le_u16(spk.version)
        || le_u64(len(spk.script))
        || spk.script
)

Uniqueness comes from the outpoint: it names a specific UTXO, which can only ever be spent once. Two genesis events therefore cannot collide, and no one can retroactively manufacture an ID matching a lineage they do not control.

Note that the preimage commits to the full set of authorized outputs, not just the one being created — their indexes, values, and complete script public keys. A genesis transaction cannot be rearranged after the fact without changing the ID it produces.

Continuation

A continuation output’s binding ties it back to an input from the same lineage. The output inherits its Covenant ID from the UTXO spent by its authorizing input, and consensus validates that the two match.

authorizing_input : index of the input from the same lineage
covenant_id       : the inherited Covenant ID

What this buys a script

The payoff: consensus enforces the lineage, so scripts do not have to. A script that reads a non-empty Covenant ID off its own input knows, for free, that the chain of custody back to genesis is intact. It never has to walk history or verify a parent.

So the two halves divide cleanly, and this division runs through the whole covenant model:

• The script proves the successor’s contents are correct.
• Consensus proves the successor’s lineage is correct.

Querying the structure from script

Three opcodes read the binding fields directly:

Beyond those, consensus exposes covenant structure through two different scopes, and choosing the wrong one is a security bug rather than a style choice:

The shared context is ordered by transaction input index. When to use which — and what goes wrong when a covenant picks the local scope for a rule that is really about the whole group — is covered in Leaders & Delegators.

Next

That completes the consensus layer. Everything from here is convention: how programs agree to lay their bytes out so that tooling written by one author can read a covenant written by another.

The P2SH Covenant Envelope — how a covenant program is committed to, revealed, and executed.

References

• KIP-20 — Covenant IDs
• Covenant Opcodes
• covenant_id.rs — genesis and continuation exercised in rusty-kaspa
• Covenants Overview — the same ideas in plain language