Taproot
Protocol and consensus12.4.15+

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 #

Text
OP_SCRIPTTYPE OP_1 <33-byte commitment>
OP_SCRIPTTYPE OP_1 <33-byte commitment> <32-byte state>
OffsetSizeValueMeaning
010x62OP_SCRIPTTYPE, marks a typed output
110x51OP_1, the Taproot script type
210x21Push of 33 bytes
333Commitment: a compressed public key (0x02 or 0x03 prefix)
3610x20Optional: push of 32 bytes
3732Optional: 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 #

Text
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 G
  • internal_pubkey is 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_root is 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 tweak to the internal private key.

Consensus does not look at the tweak on a key path spend: it only checks the signature against the commitment.

12.4.16+

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.

RuleError
The signature is a 64-byte Schnorr signature followed by the sighash byteTAPROOT_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 keyTAPROOT_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:

Text
<argument 1> ... <argument n> <script> <control block>

The control block is 33 + 32 x n bytes:

SizeField
10xc0 (leaf version) with the low bit set when the internal public key has an odd Y coordinate (prefix 0x03)
32X coordinate of the internal public key
32 x nMerkle path: the sibling hash at each level, from the leaf up

The node then:

  1. Checks the control block size and that the leaf version is 0xc0.
  2. Computes the leaf hash of <script>, folds in each path node as a branch hash, and gets the Merkle root.
  3. Rebuilds the internal public key from the first 33 bytes, computes internal_pubkey + tweak x G and compares it with the commitment in the output.
  4. If the output has a state, pushes the 32-byte state on top of the stack.
  5. Executes <script> with the arguments (and the state) on the stack.
  6. Requires the script to end with exactly one item on the stack, and that item to be true.
RuleError
Control block size is 33 + 32 x n, with n at most 128TAPROOT_WRONG_CONTROL_SIZE
Leaf version is 0xc0TAPROOT_LEAF_VERSION_NOT_SUPPORTED
The commitment matchesTAPROOT_VERIFY_COMMITMENT_FAILED
With two or more items, the last one does not start with 0x50 (no annex)TAPROOT_ANNEX_NOT_SUPPORTED
The script succeedsEVAL_FALSE, or the script's own error
One item is left on the stackCLEANSTACK

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 #

LimitValue
Size of one pushed item, including the script and the control block520 bytes
Merkle path length that fits in 520 bytes15 nodes (513-byte control block)
Opcodes per script400
Script size10,000 bytes
Stack items1,000
Napoleon upgrade

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 with SIGHASH_FORKID is 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.
Source share/www/docs/taproot.md in the lotusd repository
Checked against src/script/taproot.h src/script/taproot.cpp src/script/interpreter.cpp src/script/sigencoding.cpp src/script/script.h src/validation.cpp