palladiumcore/doc/TAPROOT.md

Taproot Implementation in Palladium Core

Introduction

Taproot is a major protocol upgrade to Palladium Core that enhances privacy, improves efficiency, and enables more flexible smart contract development. Introduced in version 2.0.0, this implementation brings the benefits of Bitcoin's Taproot upgrade to the Palladium blockchain through a complete backport from Bitcoin Core v24.2.

Taproot combines three key innovations:

• Schnorr signatures (BIP340) for more efficient and private transactions
• Taproot outputs (BIP341) enabling key-path and script-path spending
• Tapscript (BIP342) with updated validation rules and new opcodes
• Bech32m addresses (BIP350) for encoding Taproot outputs

BIP Implementation Reference

BIP340: Schnorr Signatures for secp256k1

Status: Fully implemented in v2.0.0 Specification: https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki

BIP340 defines the Schnorr signature scheme for secp256k1, replacing ECDSA for witness version 1 outputs. Key features:

• 64-byte signatures: More compact than DER-encoded ECDSA (71-72 bytes)
• X-only public keys: 32-byte representation (only x-coordinate)
• Linearity: Enables key and signature aggregation (foundation for future multisig improvements)
• Provable security: Based on discrete logarithm assumption
• Batch verification: Multiple signatures can be verified more efficiently together

Implementation components:

• XOnlyPubKey class: 32-byte x-only public key representation
• CKey::SignSchnorr(): BIP340-compliant signature generation
• XOnlyPubKey::VerifySchnorr(): Signature verification
• CPubKey::GetXOnlyPubKey(): Extraction of x-only key from compressed pubkey
• Integration with libsecp256k1's extrakeys and schnorrsig modules

BIP341: Taproot: SegWit version 1 spending rules

Status: Fully implemented in v2.0.0 Specification: https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki

BIP341 introduces Taproot outputs (witness version 1), enabling two spending paths:

1. Key-path spending: Direct signature verification (default, most efficient)
2. Script-path spending: Reveal and execute a script from a Merkle tree

Key innovations:

• Unified spending: Key-path and script-path spends are indistinguishable until spent
• MAST (Merkelized Alternative Script Trees): Only reveal executed script branch
• TapTweak: Output key is internal key tweaked with script tree commitment
• Parity bit: Even/odd y-coordinate handled implicitly

Implementation components:

• SigVersion::TAPROOT: New signature version for key-path spending
• CKey::SignSchnorrTaproot(): Key-path signature with BIP341 tweaking
• XOnlyPubKey::ComputeTapTweak(): Taproot tweak calculation
• XOnlyPubKey::CreatePayToTaprootPubKey(): Output key derivation with parity handling
• Control block validation: 33-4129 bytes, 32-byte node increments
• Taproot signature hash with SHA256 tagged hashing

BIP342: Validation of Taproot Scripts

Status: Fully implemented in v2.0.0 Specification: https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki

BIP342 defines validation rules for scripts revealed via script-path spending:

New features:

• OP_CHECKSIGADD: Replaces OP_CHECKMULTISIG with better semantics
• Validation weight limits: Prevent DoS attacks in script validation
• OP_SUCCESS opcodes: Reserved for future soft-fork upgrades (80, 98, 126-129, 131-134, 137-138, 141-142, 149-153)
• Signature opcodes: Use Schnorr instead of ECDSA
• Taproot leaf version: 0xc0 (extensible to 0xc1-0xfe)

Implementation components:

• SigVersion::TAPSCRIPT: New signature version for script-path
• ScriptExecutionData: Tracks tapleaf hash, codeseparator position, annex, validation weight
• Validation weight constraints:
  • VALIDATION_WEIGHT_PER_SIGOP_PASSED = 50 units
  • VALIDATION_WEIGHT_OFFSET = 50 units
• Annex support with tag 0x50
• Minimal-if requirement for tapscript conditionals
• CHECKMULTISIG disabled in tapscript (use OP_CHECKSIGADD instead)

BIP350: Bech32m format for v1+ witness addresses

Status: Fully implemented in v2.0.0 Specification: https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki

BIP350 introduces Bech32m, a modified version of Bech32 for witness version 1+ addresses:

Key differences from Bech32:

• Different constant: Polymod check uses 0x2bc830a3 (vs 1 for Bech32)
• Witness version: v0 uses Bech32, v1+ uses Bech32m
• Length mutation protection: Better resistance to certain error patterns

Address format:

• Taproot addresses: plm1p... (witness v1)
• SegWit v0 addresses: plm1q... (witness v0, uses Bech32)

Implementation components:

• bech32::Encoding enum: BECH32 and BECH32M
• Dual-constant checksum creation/verification
• Automatic encoding selection based on witness version
• Palladium-specific HRP (Human Readable Part): "plm"

Source Attribution

This implementation is a backport of Taproot functionality from Bitcoin Core v24.2 with appropriate adaptations for Palladium's chain parameters, consensus rules, and testing infrastructure.

Bitcoin Core components:

• secp256k1 library upgraded to Bitcoin Core v24.2 tag
• Schnorr signature implementation from Bitcoin Core
• Taproot consensus rules from Bitcoin Core
• Bech32m encoding logic from Bitcoin Core

Palladium-specific adaptations:

• Chain parameters (deployment timing, genesis blocks, maturity rules)
• Address prefixes (HRP: "plm" for mainnet)
• Test vector alignment to Palladium's consensus
• Wallet infrastructure integration
• Deployment schedule for Palladium mainnet/testnet

Architecture Overview

Crypto Layer

Files: src/key.cpp, src/key.h, src/pubkey.cpp, src/pubkey.h

Classes and methods:

• XOnlyPubKey: 32-byte x-only public key

  • VerifySchnorr(msg, sig): BIP340 signature verification
  • ComputeTapTweak(merkle_root): Calculate BIP341 taproot tweak
  • CreatePayToTaprootPubKey(merkle_root, &output_key): Derive output key
  • CheckTapTweak(internal_key, merkle_root, parity): Verify taproot tweak

• CKey: Private key operations

  • SignSchnorr(msg, &sig): Basic Schnorr signature (BIP340)
  • SignSchnorrTaproot(msg, merkle_root, &sig): Taproot key-path signature (BIP341)

• CPubKey: Compressed public key (33 bytes)

  • GetXOnlyPubKey(): Extract x-only representation

Statistics:

• key.cpp: +26 lines
• key.h: +11 lines
• pubkey.cpp: +49 lines
• pubkey.h: +66 lines
• test/key_tests.cpp: +60 lines (Schnorr test coverage)

Encoding Layer

Files: src/bech32.cpp, src/bech32.h, src/key_io.cpp

Key changes:

• bech32::Encoding enum for dual-mode operation
• Encode(encoding, hrp, values): Supports both BECH32 and BECH32M
• Decode(str): Auto-detects encoding based on witness version
• Address encoding/decoding logic updated for automatic selection

Statistics:

• bech32.cpp: +67/-48 lines
• bech32.h: +15/-1 lines
• key_io.cpp: +22/-9 lines

Script Layer

Files: src/script/interpreter.cpp, src/script/interpreter.h, src/script/script.h, src/script/script_error.cpp, src/script/script_error.h, src/script/standard.cpp, src/script/standard.h

Major additions:

• SigVersion::TAPROOT: Key-path spending
• SigVersion::TAPSCRIPT: Script-path spending
• EvalScript(): Taproot/tapscript execution paths
• BaseSignatureChecker::CheckSchnorrSignature(): Schnorr verification hook
• Taproot signature hash computation with precomputed data
• Control block parsing and validation
• OP_CHECKSIGADD implementation
• Validation weight tracking

New error codes:

• SCRIPT_ERR_SCHNORR_SIG_SIZE
• SCRIPT_ERR_SCHNORR_SIG_HASHTYPE
• SCRIPT_ERR_SCHNORR_SIG
• SCRIPT_ERR_TAPROOT_WRONG_CONTROL_SIZE
• SCRIPT_ERR_TAPSCRIPT_VALIDATION_WEIGHT
• SCRIPT_ERR_TAPSCRIPT_CHECKMULTISIG
• SCRIPT_ERR_TAPSCRIPT_MINIMALIF

Statistics:

• interpreter.cpp: +469/-36 lines
• interpreter.h: +69/-1 lines
• script.h: +22/-1 lines
• script_error.cpp: +20 lines
• script_error.h: +12 lines
• standard.cpp: +12 lines
• standard.h: +1 line

Consensus Layer

Files: src/chainparams.cpp, src/consensus/params.h, src/versionbitsinfo.cpp

Deployment parameters:

Mainnet:

• Deployment: BIP9 soft fork
• Bit: 2
• Start time: 1771027200 (February 14, 2026 00:00:00 UTC)
• Timeout: 1803859200 (March 1, 2027 00:00:00 UTC)
• Min activation height: Not specified (activation determined by signaling threshold)

Testnet:

• Same parameters as mainnet

Regtest:

• Status: ALWAYS_ACTIVE (immediate activation for testing)

Statistics:

• chainparams.cpp: +9 lines
• consensus/params.h: +3/-1 lines
• versionbitsinfo.cpp: +4 lines

Wallet Layer

Files: src/outputtype.cpp, src/outputtype.h, src/script/descriptor.cpp, src/script/sign.cpp, src/script/signingprovider.cpp, src/wallet/scriptpubkeyman.cpp, src/wallet/rpcwallet.cpp

Key additions:

• OutputType::BECH32M: New output type for Taproot
• GetDestinationForTaprootKey(): Create witness v1 destination
• CreateSig(): Updated for Schnorr signature generation
  • Key-path: Uses SignSchnorrTaproot() with empty scriptCode
  • Script-path: Uses SignSchnorr() for tapscript validation
• Taproot internal key storage: m_taproot_internal_keys map
• GetTaprootInternalKey(): Lookup internal key from output key

RPC changes:

• getnewaddress supports "bech32m" address type
• createmultisig extended for bech32m (with taproot limitations)
• getaddressinfo reports address type correctly for taproot

Statistics:

• outputtype.cpp: +35/-1 lines
• outputtype.h: +3/-1 lines
• descriptor.cpp: +72/-2 lines
• sign.cpp: +90/-27 lines
• signingprovider.cpp: +17 lines
• scriptpubkeyman.cpp: +36 lines
• rpcwallet.cpp: +12/-3 lines

Policy Layer

Files: src/policy/policy.cpp, src/policy/policy.h, src/validation.cpp

Script verification flags:

• SCRIPT_VERIFY_TAPROOT (bit 17): Enable taproot/tapscript consensus
• SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION (bit 18): Reject unknown taproot versions
• SCRIPT_VERIFY_DISCOURAGE_OP_SUCCESS (bit 19): Reject OP_SUCCESS opcodes
• SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE (bit 20): Reject unknown pubkey types

Standardness limits:

• MAX_STANDARD_TAPSCRIPT_STACK_ITEMS = 100
• MAX_STANDARD_TAPSCRIPT_STACK_ITEM_SIZE = 80 bytes
• MAX_STANDARD_TAPSCRIPT_SCRIPT_SIZE = 3600 bytes
• TAPROOT_CONTROL_BASE_SIZE = 33 bytes (control block minimum)
• TAPROOT_CONTROL_NODE_SIZE = 32 bytes (each merkle node)
• TAPROOT_CONTROL_MAX_SIZE = 4129 bytes (max control block)

Statistics:

• policy/policy.cpp: +46/-1 lines
• policy/policy.h: +12/-1 lines
• validation.cpp: +10 lines

Consensus Rules

Deployment Activation

Taproot activates via BIP9 signaling:

1. Miners signal readiness by setting bit 2 in block version
2. When 540 of 720 blocks in a confirmation window signal (75% threshold), deployment is LOCKED_IN
3. After LOCKED_IN period ends, deployment becomes ACTIVE for all subsequent blocks
4. Timeout on March 1, 2027 if insufficient signaling

Note: Palladium uses a 75% activation threshold (540/720 blocks) compared to Bitcoin's 90% (1815/2016 blocks), with a shorter confirmation window to facilitate faster network coordination while maintaining security.

Script Verification Flags

Standard transaction validation (mempool/relay):

SCRIPT_VERIFY_TAPROOT |
SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_TAPROOT_VERSION |
SCRIPT_VERIFY_DISCOURAGE_OP_SUCCESS |
SCRIPT_VERIFY_DISCOURAGE_UPGRADABLE_PUBKEYTYPE

Consensus validation (blocks):

SCRIPT_VERIFY_TAPROOT

Taproot Spending Rules

Key-path spending (witness v1 with single witness element):

1. Witness must contain exactly 1 element (signature, or 65 bytes after annex removal)
2. Signature must be 64 or 65 bytes (65 = 64-byte sig + SIGHASH byte)
3. Extract internal key from output key using BIP341 taproot tweak
4. Verify Schnorr signature against tweaked pubkey
5. Empty scriptCode per BIP341

Script-path spending (witness v1 with multiple elements):

1. Last witness element is control block (33-4129 bytes, 33 + 32n)
2. Second-to-last element is tapscript (max 3600 bytes for standard)
3. Control block format: [leaf_version || internal_key_parity || internal_key[1:] || merkle_proof]
4. Verify control block reconstructs output key
5. Execute tapscript with TAPSCRIPT signature version
6. Track validation weight (max 1650 units)

Annex handling:

• If first witness stack element starts with 0x50, it's the annex
• Annex is removed before script validation
• Annex hash is committed in signature hash

Validation Weight

Tapscript execution tracks validation weight to prevent DoS:

• Each signature operation: 50 weight units (if signature validates)
• Initial offset: 50 weight units
• Maximum: 1650 units per script-path spend
• Formula: weight = 50 + 50 * num_successful_checksigs
• Limit: num_successful_checksigs <= 32 (1650 / 50 - 1)

Standardness Policy

Tapscript stack limits:

• Max stack items: 100
• Max stack item size: 80 bytes
• Max script size: 3600 bytes

Control block validation:

• Minimum size: 33 bytes (version + internal key)
• Maximum size: 4129 bytes (33 + 32 * 128 merkle nodes)
• Size must be 33 + 32n for integer n

Leaf version:

• Standard: 0xc0 (tapscript)
• Non-standard: 0xc1-0xfe (reserved for future soft forks)
• Invalid: 0x00-0xbf, 0xff

Key Files Modified

Summary by Layer

Layer	Files Modified	Lines Added	Lines Removed
Crypto	5	212	6
Encoding	3	104	58
Script	7	604	38
Consensus	3	16	1
Wallet	9	265	37
Policy	3	68	2
Testing	Multiple	Extensive	-
Total	30+	~1269	~142

Critical Implementation Files

Cryptographic primitives:

• src/key.cpp, src/key.h: Schnorr signing with BIP340/BIP341
• src/pubkey.cpp, src/pubkey.h: XOnlyPubKey, signature verification, taproot tweaking
• src/secp256k1/: Upgraded to Bitcoin Core v24.2 with extrakeys and schnorrsig modules

Consensus rules:

• src/script/interpreter.cpp: Taproot/tapscript validation logic (469 lines added)
• src/script/script_error.h: New error codes for taproot
• src/chainparams.cpp: BIP9 deployment parameters

Address encoding:

• src/bech32.cpp: Bech32m implementation
• src/key_io.cpp: Address encoding/decoding with automatic format selection

Wallet integration:

• src/outputtype.cpp: BECH32M output type
• src/script/sign.cpp: Schnorr signature generation for transactions
• src/wallet/scriptpubkeyman.cpp: Internal key tracking for taproot

Testing:

• test/functional/feature_taproot.py: End-to-end taproot functional test
• src/test/key_tests.cpp: Schnorr signature unit tests
• src/test/data/: Bech32m test vectors aligned to Palladium

Testing

Functional Tests

Feature test: test/functional/feature_taproot.py

Test coverage:

1. Wallet creation with default bech32m support
2. Taproot address generation: getnewaddress("", "bech32m")
3. Funding test: Send to P2TR address
4. Balance verification
5. Spending test: Send from P2TR address
6. Transaction confirmation
7. End-to-end P2TR lifecycle validation

Test framework:

• Python segwit_addr module updated for Bech32m
• Address validation for Palladium HRP ("plm")
• Consensus rule alignment to Palladium parameters

Unit Tests

Schnorr signatures: src/test/key_tests.cpp

Test coverage:

• XOnlyPubKey construction and validation
• Schnorr signature round-trip (sign + verify)
• Signature size validation (64 bytes)
• XOnlyPubKey invariants (negation property)
• ECDSA interoperability (same key, both signatures valid)
• BIP340 test vectors

Bech32m encoding: src/test/bech32_tests.cpp

Test coverage:

• Bech32m encoding/decoding
• Checksum validation
• Witness version detection
• Error detection (insertions, deletions, substitutions)
• Palladium-specific test vectors

Integration Tests

RPC interface:

• getnewaddress with "bech32m" type
• getaddressinfo for taproot addresses
• sendtoaddress to/from taproot outputs
• createmultisig taproot limitations
• getblockchaininfo taproot deployment status

Wallet operations:

• Create taproot receive address
• Send to taproot address
• Spend from taproot address (key-path)
• Fee estimation for taproot transactions
• UTXO selection with taproot inputs

References

BIP Specifications

• BIP340: Schnorr Signatures for secp256k1 https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki

• BIP341: Taproot: SegWit version 1 spending rules https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki

• BIP342: Validation of Taproot Scripts https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki

• BIP350: Bech32m format for v1+ witness addresses https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki

Additional Resources

• Bitcoin Core v24.2 release: Source for Taproot backport https://github.com/bitcoin/bitcoin/releases/tag/v24.2

• secp256k1 library: Cryptographic primitives https://github.com/bitcoin-core/secp256k1

• Taproot Workshop: Technical deep-dive (Bitcoin-focused but applicable) https://github.com/bitcoinops/taproot-workshop

Palladium-Specific Documentation

• User guide: doc/taproot-guide.md
• Release notes: doc/release-notes.md (v2.0.0)
• BIP implementation list: doc/bips.md

---

Version: Palladium Core 2.0.0 Last Updated: February 2026 Status: Production-ready, mainnet deployment March 2026