BIP360 P2MR

BTQ Core includes full wallet-level support for BIP360 Pay-to-Merkle-Root (P2MR) as a native witness v2 script type. P2MR enables script-tree committed destinations that can be created, funded, spent, validated against mempool policy, broadcast, and confirmed using wallet RPC workflows.

Protocol Model

P2MR in BTQ is a script-tree commitment model with these properties:

• Witness program version is v2.
• Program length is 32 bytes.
• Program payload commits to a script-tree Merkle root.
• Spending is script-path based, with no key-path branch.

This model allows the protocol to separate destination commitment from witness disclosure: the output commits to a tree root, and spending reveals only the chosen leaf path and witness arguments required for validation.

End-to-End Wallet Lifecycle

BTQ now supports a complete wallet-driven P2MR lifecycle:

1. Destination creation with script-tree and metadata registration.
2. Funding of the created P2MR destination from wallet balance.
3. Discovery of spendable P2MR outputs using metadata and script matching.
4. Construction of an unsigned spend transaction from eligible P2MR UTXOs.
5. Witness finalization and signing for the selected script path.
6. Mempool dry-run validation before network submission.
7. Broadcast and chain confirmation checks.

This closes the operational loop for P2MR entirely through wallet RPCs, without requiring external signing infrastructure.

Wallet RPC Surface

The wallet RPC layer includes seven P2MR-focused methods covering the full lifecycle:

• getnewp2mraddress for creating metadata-backed P2MR destinations.
• sendtop2mr for funding P2MR outputs.
• listp2mr for listing known metadata entries.
• getp2mrinfo for querying metadata and destination state.
• createp2mrspend for constructing unsigned spends from qualifying UTXOs.
• signp2mrtransaction for witness completion and signed transaction output.
• testp2mrtransaction for pre-broadcast mempool policy checks.

Together, these methods provide deterministic operational phases from setup through confirmation readiness.

Metadata Persistence Model

P2MR destinations are persisted in wallet metadata storage, allowing the wallet to treat P2MR as a discoverable stateful workflow rather than a one-off script output.

Persistence behavior includes:

• Storing destination-linked metadata at creation time.
• Looking up metadata for targeted spend construction.
• Enumerating known P2MR entries for operator inspection and tooling.
• Reusing metadata linkage to resolve spend candidates and witness context.

This design keeps wallet state and P2MR spendability aligned across restarts and repeated workflows.

Validation Rules and Boundaries

For witness v2 outputs that match the P2MR commitment shape, BTQ applies P2MR-specific script-path rules:

• Witness data must include script-path material and cannot be empty.
• Control-block structure must be well-formed for a Merkle-path reveal.
• The revealed path must recompute to the committed output root.
• Leaf execution is validated under the P2MR script-versioning path.

Validation boundaries are intentionally layered:

• Wallet-layer checks ensure metadata, spend candidate selection, and witness assembly are coherent.
• Mempool policy checks provide pre-broadcast acceptance feedback.
• Consensus validation enforces P2MR rules during block validation for fully validating nodes.

Operational Invariants

Reliable P2MR operation depends on these invariants:

• Destination metadata must remain available for the outputs being managed.
• Script-tree and witness arguments must match the funded commitment path.
• Spend construction must target eligible and unspent P2MR outputs.
• Finalized transactions should pass dry-run policy checks before broadcast.
• Confirmation should be tracked post-broadcast to close lifecycle state.

Typical failure cases include missing metadata linkage, no spendable outputs for a requested identifier, witness-path mismatch, and dry-run policy rejection.

Validation Evidence in This Release

The release adds both automated and operator-facing validation coverage:

• Functional testing validates address creation, metadata retrieval, funding, unsigned spend creation, signing/finalization, policy dry-run, broadcast, and mined confirmation.

• Descriptor wallet execution mode is included to validate current wallet deployment targets.

• Manual and scripted operator flows verify the same lifecycle under regtest with explicit completion and confirmation checks.

• Dilithium Overview

• P2MR Wallet RPC Lifecycle

• Dilithium Addresses

• BTQ Architecture