Taproot
The Lotus Taproot output, its two ways of spending (one signature, or a script proven by a Merkle path), the hashes involved and the consensus rules.
A Taproot output commits to one public key and, hidden behind it, to a tree of scripts. It can be spent in two ways:
- Key path: one Schnorr signature for the committed key. Nothing about the scripts is revealed.
- Script path: reveal one script of the tree, prove that it is part of the commitment, and satisfy it.
Taproot outputs are accepted since the 2nd Samuel upgrade (mainnet median time past 1766329380, 21 December 2025, 15:03 UTC). A block before that upgrade that contains one is rejected with taproot-not-active-yet.
Output script #
OP_SCRIPTTYPE OP_1 <33-byte commitment>
OP_SCRIPTTYPE OP_1 <33-byte commitment> <32-byte state>| Offset | Size | Value | Meaning |
|---|---|---|---|
| 0 | 1 | 0x62 | OP_SCRIPTTYPE, marks a typed output |
| 1 | 1 | 0x51 | OP_1, the Taproot script type |
| 2 | 1 | 0x21 | Push of 33 bytes |
| 3 | 33 | Commitment: a compressed public key (0x02 or 0x03 prefix) | |
| 36 | 1 | 0x20 | Optional: push of 32 bytes |
| 37 | 32 | Optional: state |
The script is 36 bytes without state and 69 bytes with it. No other form is a Taproot output. OP_SCRIPTTYPE is only a marker: executing it in a script fails with INVALID_OP_SCRIPTTYPE.
The address of a Taproot output is an address of type 2 whose payload is the commitment. See Address format.
Commitment #
tagged_hash(tag, msg) = SHA256( SHA256(tag) || SHA256(tag) || msg )
leaf_hash = tagged_hash("TapLeaf", 0xc0 || compact_size(len(script)) || script)
branch_hash = tagged_hash("TapBranch", smaller || larger)
tweak = tagged_hash("TapTweak", internal_pubkey || merkle_root)
commitment = internal_pubkey + tweak x Ginternal_pubkeyis a 33-byte compressed public key, and so is the commitment.- A branch hashes its two children with the lexicographically smaller 32-byte value first.
merkle_rootis the root of the script tree. For a tree with a single script it is that script's leaf hash.- To sign for the key path, add
tweakto the internal private key.
Consensus does not look at the tweak on a key path spend: it only checks the signature against the commitment.
Coming in 12.4.16: the node's wallet can build and sign key-path-only Taproot outputs. Their commitment is the internal key tweaked with a Merkle root of 32 zero bytes, so the output provably has no usable script path.
Spend by key path #
The scriptSig pushes exactly one item, the signature.
| Rule | Error |
|---|---|
| The signature is a 64-byte Schnorr signature followed by the sighash byte | TAPROOT_KEY_SPEND_MUST_USE_SCHNORR_SIG |
The sighash type uses SIGHASH_LOTUS (for example 0x61) | TAPROOT_KEY_SPEND_MUST_USE_LOTUS_SIGHASH |
| The signature verifies against the commitment key | TAPROOT_VERIFY_SIGNATURE_FAILED |
The signed hash is the SIGHASH_LOTUS hash with spend type 0 and without the script execution fields. The state, if the output has one, plays no role.
Spend by script path #
The scriptSig pushes, in this order:
<argument 1> ... <argument n> <script> <control block>The control block is 33 + 32 x n bytes:
| Size | Field |
|---|---|
| 1 | 0xc0 (leaf version) with the low bit set when the internal public key has an odd Y coordinate (prefix 0x03) |
| 32 | X coordinate of the internal public key |
| 32 x n | Merkle path: the sibling hash at each level, from the leaf up |
The node then:
- Checks the control block size and that the leaf version is
0xc0. - Computes the leaf hash of
<script>, folds in each path node as a branch hash, and gets the Merkle root. - Rebuilds the internal public key from the first 33 bytes, computes
internal_pubkey + tweak x Gand compares it with the commitment in the output. - If the output has a state, pushes the 32-byte state on top of the stack.
- Executes
<script>with the arguments (and the state) on the stack. - Requires the script to end with exactly one item on the stack, and that item to be true.
| Rule | Error |
|---|---|
Control block size is 33 + 32 x n, with n at most 128 | TAPROOT_WRONG_CONTROL_SIZE |
Leaf version is 0xc0 | TAPROOT_LEAF_VERSION_NOT_SUPPORTED |
| The commitment matches | TAPROOT_VERIFY_COMMITMENT_FAILED |
With two or more items, the last one does not start with 0x50 (no annex) | TAPROOT_ANNEX_NOT_SUPPORTED |
| The script succeeds | EVAL_FALSE, or the script's own error |
| One item is left on the stack | CLEANSTACK |
Signatures checked inside the script may be Schnorr or ECDSA and may use SIGHASH_FORKID or SIGHASH_LOTUS. With SIGHASH_LOTUS the executed script hash in the preimage is the leaf hash.
Limits #
| Limit | Value |
|---|---|
| Size of one pushed item, including the script and the control block | 520 bytes |
| Merkle path length that fits in 520 bytes | 15 nodes (513-byte control block) |
| Opcodes per script | 400 |
| Script size | 10,000 bytes |
| Stack items | 1,000 |
From the Napoleon activation (median time past 1797886200, 21 December 2026, 20:50 UTC), with the contract opcodes, the revealed script and the control block of a Taproot spend may be up to 10,000 bytes each; the other pushed items stay limited to 520 bytes. A leaf may also run more than 400 opcodes within an operation budget that grows with the size of the scriptSig.
State #
The optional 32-byte state is data stored in the output. On a script path spend the node pushes it on top of the stack before the script runs, so the script can read it without it being part of the script tree. Two outputs with the same commitment and different states are locked by the same scripts.
Differences to keep in mind #
- Public keys are 33 bytes everywhere in the output; only the control block carries a 32-byte X coordinate, with the parity of the internal key in its first byte.
- The key path needs
SIGHASH_LOTUS; a signature withSIGHASH_FORKIDis refused there. - The Schnorr scheme is the one Lotus uses for all its 64-byte signatures. It is not the BIP340 scheme, so do not assume that BIP340 signing code produces valid Lotus signatures.
- Relative and absolute lock times in scripts count Lotus blocks, which are 2 minutes apart.
