BIP 372 Pay-to-Contract Tweak Fields for PSBT

BIP 372 is a Draft proposal for carrying pay-to-contract key-tweak information in PSBT version 0 or 2 inputs. A P2C output commits to external data by tweaking a public key; later spending requires the signer to apply the same scalar tweak to the corresponding private key. The proposed field associates an original compressed public key with a 32-byte tweak so an external signer can recognise and sign the committed output.

Status and scope

BIP 372 remains Draft, requires BIP 174 and has a work-in-progress implementation with test vectors still marked TBD. Do not advertise interoperable support without bilateral version testing.

Label Draft.

P2C concept

A contract message is hashed into a scalar and added times G to an original public key. Spending needs the original secret plus the same tweak modulo the curve order.

Pin field encoding.

PSBT field

PSBT_IN_P2C_TWEAK uses key type 0x19, a 33-byte compact original public key as keydata and a 32-byte tweak as valuedata. BIP 340 keys are represented with a prefixed compressed form.

Validate scalar.

Signer duty

The signer should identify a controlled original key, apply the supplied tweak, verify that the result matches the key committed in the input script and only then produce ECDSA or Schnorr signature material.

Recompute tweaked key.

Supported boundary

The draft describes several bare, legacy and SegWit v0 scripts. Its compatibility discussion warns that post-v0 witness forms, including Taproot, may need additional treatment despite broader motivation text.

Match spent script.

Security

A malicious or mistaken tweak can redirect signing authority. Never apply an unverified scalar, accept zero or out-of-range encodings or sign without matching the resulting public key to the actual spent output.

Do not assume Taproot.

Testing

Because normative vectors are absent, create independent positive and negative fixtures, wrong original keys, wrong tweaks, curve edges, duplicated fields, mixed scripts, PSBT versions and finalisation removal. Build a revision-pinned evidence pack on an isolated node, wallet or protocol harness. Record source commit, binary hash, network, chain identity, configuration and dependencies. Exercise the intended path, explicit rejection, restart, interruption, reorganisation and primary-to-failover transition where relevant. Measure CPU, memory, disk, bandwidth, latency, validation state and log growth. Use synthetic transactions and disposable keys; remove credentials, wallet identifiers, customer data, addresses, peer details and private topology. A second reviewer should reproduce the result and name the observation that invalidates approval. Document owner, expiry, rollback boundary and any irreversible wallet or database transition. Rollback must not overwrite newer wallet state. State which mining, wallet, deposit, withdrawal or monitoring function pauses while evidence is uncertain. Test malformed, boundary and excessive inputs and prove bounded failure. Compare claims with decoded messages, transactions, scripts, node logs and RPC output. Repeat after node, library, signer, firmware or operating-system changes. Retain elapsed time, peak resources, and normal, warning and stop thresholds. Label historical, Closed and Draft specifications plainly, distinguish authored motivation from proven outcome, and verify supported current behaviour before real funds. Maintain a compatibility matrix with exact unsupported-combination evidence and repeat negative cases after restart to expose cached state. Preserve a before-and-after comparison on identical fixtures and include a forced fallback or alternate peer. Record the exact rejected input and recovery evidence so one successful implementation cannot be mistaken for network-wide interoperability. Confirm external monitoring detects silent incompatibility, explicit rejection and stale state before approval. Name the reviewer and operational decision in the retained evidence. Capture exact wallet or node identity, network, chain tip, configuration and before-and-after state. Use integer satoshis and bounded values. Test valid, invalid, restart, interruption, reorganisation and wrong-context paths. Protect wallet names, addresses, messages, signatures and peer identifiers. Require a second reviewer and explicit rollback or expiry, and pause payments, signing or network-dependent services until post-change evidence is complete. Retain timestamped, redacted test results with the change record, then compare the observed outcome against the approved intent before restoring dependent production workflows. Separate the RPC response from the operational outcome: accepted input, a true result or returned data is not proof of settlement, durable shutdown, network propagation or complete database health. Capture resource use and elapsed time, keep credentials outside command history, redact raw transactions and keys, and make automation fail closed on incomplete, ambiguous or version-mismatched results. For custody-sensitive operations, isolate the wallet, prevent secrets from entering shell history or telemetry, identify the exact loaded wallet and confirm expected lock state after success, failure, timeout and restart. A test must prove both the intended capability and the denial path when authority or evidence is incomplete. For upgrades, verify signed release artefacts, preserve configuration and wallet backups, rehearse on a representative node and define downgrade limits before the maintenance window. Record the old and new binary identity, data-format transitions, service gates and independent chain state. Resume mining and financial workflows only after the new process is stable and current. For PSBT workflows, freeze one unsigned transaction identity, keep creator, updater, signer, combiner, finalizer and broadcaster authorities distinct, and decode the packet after every trust-boundary crossing. Protect UTXO data, public keys, scripts, fingerprints, derivation paths, change identification and proprietary fields. No successful utility response replaces complete signing, policy approval or final broadcast review. Treat labels, wallet ownership fields, derivation information, publisher addresses and wallet paths as operationally sensitive. Bind every query to the exact node, network, loaded wallet, chain tip and software version. Validate array and object result shapes, handle missing optional fields explicitly, and never equate local metadata or monitoring configuration with external ownership, delivery or settlement. Treat UTXO scans, seed changes, signing and wallet lifecycle as bounded state machines. Record start, status, cancellation, completion and restart behaviour; preserve exact transaction or descriptor identity; and prevent concurrent jobs from changing wallet, keypool, chain view or signing intent. Secret-bearing calls need isolated transport, minimal memory lifetime and verified cleanup. For every workflow, separate construction, authorisation, signing, validation and publication. Preserve byte-exact artefacts and source versions between stages, fail closed on ambiguous state, and keep a reproducible evidence bundle containing hashes, policy decisions, software versions and redacted outcomes. Never treat a signature, wallet response or protocol label as proof of business intent, solvency, identity or final settlement beyond the exact claim it cryptographically establishes. Network and cross-system designs need version negotiation, strict length and count limits, deterministic parsing and independent validation of every commitment. Keep experimental, Draft, Complete and Deployed statuses distinct. For Bitcoin Core RPCs, bind results to the exact node version, network, wallet or descriptor, and treat analytical output as evidence for the next control rather than an instruction to mutate or broadcast. Canonicalisation, sampling, aggregation and joining are not authorisation. Preserve the original input, exact node version and selected wallet; record units and inclusion rules; and compare output against independent business state. Protect descriptors, peer tables, labels, watch-only membership, active RPC names and PSBT ownership as sensitive operational metadata. Bounded queries, immutable artefact hashes and explicit postconditions prevent convenient reporting calls from becoming silent control-plane dependencies. Inventory, metadata mutation, header ingestion, UTXO enrichment and consensus proposals each sit at different trust boundaries. Authorise the exact target, hash inputs and outputs, keep audit trails free of secrets and personal data, and define postconditions that prove what changed and what did not. Historical release guidance must distinguish current network rules from a Draft proposal or software maintenance patch, and every rollback must account for stored wallet, chain and index state. Versioned RPC output, consensus specifications and cryptographic test vectors must be treated as exact contracts rather than convenient descriptions. Pin software and document revisions, authenticate the node and wallet boundary, preserve byte-level inputs where appropriate, and verify results independently before allowing reporting, signing or deployment decisions. Never expose wallet topology, balances, scripts, filter interests or signing material in public logs. Maintenance releases, deterministic key hierarchies, derived entropy, test-only mining controls and peer-selection maps all have different failure domains. Keep historical facts separate from later specification revisions, authenticate every downloaded artefact, preserve custody and descriptor recovery records offline, and test migrations with byte-exact fixtures. Network diversity is a defence in depth measure, not proof that peers or routes are honest. Access lists, path templates, peer permissions and multisig setup files are executable security policy even when represented as configuration text. Bind every record to a version, network, role and owner; minimise permissions; reject ambiguous parsing; and verify negative cases as deliberately as success. A Closed proposal is historical design evidence, not a current interoperability promise, while a Complete application standard still relies on secure implementations and ceremonies. Address encodings, derivation paths, mutable PSBT construction, custom regtest blocks and asynchronous indexes must be verified at their precise boundary. A valid checksum is not recipient identity, a deployed hierarchy is not a complete backup, and an index height is not chain validation. Preserve raw artefacts and policy approvals, use published invalid as well as valid vectors, and block production decisions when network, version, script or synchronisation context is ambiguous. Wallet imports, fee replacement, payment construction, version upgrades and peer dashboards all change or expose security-relevant state. Use a version-pinned node, bind every call to the intended network and wallet, preserve pre-operation evidence, keep secrets out of logs, and verify results independently before allowing a downstream business action. Historical documentation describes the 0.21 contract and must not be silently projected onto later releases. Startup hooks, network privacy, runtime settings, test chains and soft-fork activation all cross important trust boundaries. Record the exact binary and network, minimise executable and file permissions, separate observation from authorisation, verify chain and wallet identity after restarts, and rehearse recovery before relying on a new control. Historical activation proposals must be labelled by their present status as well as their original intent. Proof-of-work proposals, transaction locktimes, Taproot derivation and output descriptors each describe different layers. Keep consensus proposals separate from deployed wallet conventions, distinguish policy privacy from spendability, preserve descriptor checksums and key origins, and verify the exact scriptPubKey derived from every policy before funding. Never infer signing authority from a public descriptor or successful address derivation. Bitcoin Core 22 introduced several operator-facing capabilities at once: Taproot descriptors, external-signer plumbing, new wallet inventory calls and network changes. Treat every command as versioned evidence, not a complete safety decision. Keep RPC access local or strongly authenticated, protect wallet and signer boundaries, stage upgrades on copies, compare outputs with independent records and rehearse rollback before production use. Overlay networking, maintenance releases, PSBT extensions, timelocked scripts and major-node upgrades operate at different trust boundaries. Pin the exact version and source revision, record which behaviours are experimental or Draft, protect keys and network metadata, validate units and encodings at every boundary, and never treat successful parsing as proof of ownership, spendability or safe deployment.

Build independent vectors.

Production decision boundary

Before adopting or retaining BIP 372 pay-to-contract PSBT, identify the exact component that implements it and the component that merely displays or transports its result. Record whether the behaviour affects consensus validation, peer policy, wallet interoperability or an application convention. That classification determines which node, test vector or independent implementation can provide authoritative evidence and prevents a successful user-interface demonstration from being mistaken for protocol verification.

Compare the proposal status and historical date with the software actually in service. A deployed BIP can still have incomplete product support, while a closed historical proposal can remain important for recovery or incident analysis. Document the supported replacement where one exists, the migration trigger and the safe fallback. Never convert production keys, transactions or node state merely to satisfy a compatibility label without a recoverable test.

For change control, save the current configuration, sanitised test artefact and expected rejection cases before upgrading. Run the same checks on every coordinator, signer, node, proxy or pool endpoint that can become active during failover. Approve the change only when all paths agree on the intended interpretation of BIP 372 pay-to-contract PSBT, monitoring distinguishes failure from delay, and rollback does not cross a consensus or custody boundary.

Use a small-value or isolated network rehearsal to connect the technical result to the business decision. Record who reviewed the evidence, which limitation remains and when the assumption expires. This creates a useful operational control instead of a one-off compatibility test that nobody can reproduce after staff, firmware, node software or service providers change.

Where two implementations disagree, stop at the boundary and reduce the case to the smallest reproducible message, transaction or derivation. Compare the primary specification line by line, including length limits, byte order, optional fields and version gates. Escalate the evidence rather than selecting whichever output appears more convenient, because silent disagreement is precisely what interoperable standards are intended to prevent.

Implementation record

Keep a dated implementation record for BIP 372 pay-to-contract PSBT. Name the primary specification, its status, the software and hardware releases tested, the network used and the exact expected result. Preserve raw transactions or peer messages where appropriate, but remove private keys, authentication data, wallet identifiers and customer information before attaching evidence to an operational ticket.

Separate protocol validity from product support. A format can be completely specified while a particular wallet, node or pool implements only part of it. Test the primary and failover path, include a deliberately invalid case, and document how the system fails. A clear rejection is safer than a silent conversion, ignored field or plausible-looking fallback.

Review the record after upgrades. Historical BIPs are versioned design evidence, while current applications may add stricter policy, newer transport or replacement standards. State the layer being tested, because consensus, peer relay, wallet interoperability and user-interface safety have different authorities and different failure costs.

Conclusion

BIP 372 addresses a real external-signer gap for pay-to-contract outputs, but its Draft status and missing vectors demand conservative interoperability testing. A signer must verify the tweak against the spent script before using any secret key.