P2MR Wallet RPC Lifecycle

This page describes the operator-facing lifecycle for P2MR in BTQ Core using wallet RPCs only. It focuses on protocol states, transitions, and verification outcomes rather than implementation details.

Lifecycle Phases

Phase 1: Create a P2MR Destination

The lifecycle begins by creating a new P2MR destination from a script tree and storing associated metadata in the wallet.

Expected outcomes:

• A new P2MR destination is created and linked to metadata.
• A stable identifier is available for later lookup and spend workflows.
• The wallet records enough context to rediscover this destination in later sessions.

Phase 2: Fund the Destination

The wallet funds the destination with a P2MR output from spendable wallet balance.

Expected outcomes:

• A funding transaction is created and accepted.
• The destination now has associated on-chain value.
• The wallet can later discover this value as a spend candidate for the same metadata context.

Phase 3: Inspect and Resolve Metadata State

Before spending, operators use metadata-oriented methods to validate that destination state is complete and internally consistent.

Expected outcomes:

• Metadata listing returns the expected P2MR entries.
• Direct metadata lookup resolves the created identifier.
• Destination and metadata linkage remain consistent after funding.

Phase 4: Build Unsigned Spend

The wallet constructs an unsigned spend from eligible P2MR UTXOs that match the selected metadata or script context.

Expected outcomes:

• Candidate selection returns spendable P2MR outputs.
• An unsigned transaction artifact is produced for finalization.
• Destination and amount planning are reflected in the transaction template.

Phase 5: Finalize Witness and Sign

The wallet finalizes witness data for the selected script path and produces a signed transaction artifact.

Expected outcomes:

• Witness-path requirements are satisfied for the selected branch.
• Finalization reports complete signing state.
• The resulting signed transaction is ready for policy pre-check.

Phase 6: Dry-Run Policy Validation

Before broadcast, the wallet performs mempool dry-run acceptance checks.

Expected outcomes:

• The transaction receives explicit allow or reject policy feedback.
• Reject reasons can be treated as pre-broadcast diagnostics.
• Successful dry-run indicates policy readiness, not final confirmation.

Phase 7: Broadcast and Confirm

A policy-allowed transaction is broadcast and then validated for confirmation on-chain.

Expected outcomes:

• Broadcast succeeds and returns transaction identity.
• Confirmation state reaches the target threshold.
• Lifecycle state transitions from prepared to confirmed.

RPC Responsibilities by Method

The seven P2MR wallet RPC methods map directly to lifecycle responsibilities:

• getnewp2mraddress: create metadata-backed destination state.
• sendtop2mr: fund destination outputs.
• listp2mr: enumerate stored destination metadata.
• getp2mrinfo: retrieve destination metadata and state.
• createp2mrspend: build unsigned spends from eligible P2MR outputs.
• signp2mrtransaction: finalize witness path and return signed transaction data.
• testp2mrtransaction: evaluate mempool policy acceptance before broadcast.

Data Artifacts and Their Meaning

P2MR operations revolve around a small set of persistent and transitional artifacts:

• Script tree definition: defines committed spend paths at destination creation.
• Metadata identifier: stable handle used for listing, lookup, and spend coordination.
• Unsigned transaction artifact: spend intent before witness finalization.
• Signed transaction artifact: finalized transaction suitable for policy check and broadcast.
• Acceptance state: dry-run policy outcome used as a deployment gate.
• Confirmation state: post-broadcast chain inclusion status.

Validation Strategy in This Release

P2MR coverage is validated through both automated and manual paths:

• Automated functional testing verifies the full lifecycle from creation through confirmation.
• Descriptor wallet mode is exercised to ensure compatibility with current wallet deployment modes.
• Manual and scripted operator workflows validate practical behavior under regtest with explicit success criteria.

Success Criteria and Operational Interpretation

Three runtime signals are especially important in production-like workflows:

• Complete signing state indicates witness finalization succeeded for the intended path.
• Mempool allow state indicates policy readiness for broadcast.
• Positive confirmation count indicates successful chain inclusion.

When these signals appear in sequence, operators can treat the end-to-end P2MR path as validated for that scenario.

Common Failure Modes

The most common issues occur at state boundaries:

• Metadata not found for the target identifier.
• No spendable P2MR outputs for the requested context.
• Witness finalization incomplete for the intended spend path.
• Policy dry-run rejection before broadcast.
• Broadcast succeeds but confirmation target is not reached in expected time.

Operationally, these should be treated as lifecycle checkpoints rather than opaque errors: each one identifies a specific phase that needs correction.

Related Topics

• BIP360 P2MR
• Dilithium Overview
• Wallet Basics