Generic Signed Message Format

# Abstract

A standard for interoperable signed messages based on the Bitcoin Script format, either for proving availability of funds, or for committing to a message as the intended recipient of funds sent to the invoice address.

# Motivation

The current message signing standard only works for P2PKH (1...) invoice addresses. We propose to extend and generalize the standard by using an approach based on Bitcoin Script. This ensures that any coins, no matter what script they are controlled by, can in principle be signed for. For easy interoperability with existing signing hardware, we also define a signature message format that resembles a Bitcoin transaction (except that it contains an invalid input, so it cannot be spent on any real network).

Additionally, the current message signature format uses ECDSA signatures that do not commit to the public key, meaning that they do not actually prove knowledge of any secret keys. (Indeed, valid signatures can be tweaked by third parties to become valid signatures on certain related keys.)

Ultimately, no message signing protocol can actually prove control of funds, both because a signature is obsolete as soon as it is created, and because the possessor of a secret key may be willing to sign messages on others' behalf even if it would not sign actual transactions. No message signing protocol can fix these limitations.

Finally, this BIP only addresses the use case where a signer shows they will be able to control funds sent to the invoice address. Proving that a signer sent a prior transaction is not possible using this BIP.

# Terminology

In the context of this BIP, whenever the word "signature" or similar is used, it refers to the output of the signing process described below, and, depending on the script type of the message_challenge, is either a full transaction input witness stack, a full transaction, or a PSBT packet that can be validated against a Bitcoin Script Interpreter. Such a "signature" may or may not contain an actual cryptographic (ECDSA or Schnorr) signature, depending on what is required to satisfy the script corresponding to the message_challenge.

# Types of Signatures

This BIP specifies three formats for signing messages: legacy, simple and full. Additionally, a variant of the full format can be used to demonstrate control over a set of UTXOs.

¹: Possible on a technical level but SHOULD NOT be used anymore in the context of this BIP, see section Legacy below.
²: Excluding time lock scripts.

Signers MUST prefix the signature with the variant that was used to create the signature. To support backward compatibility with implementations of this BIP before it was finalized, a verifier might assume the simple variant in the absence of a prefix.

# Legacy

New proofs SHOULD use the new format for all invoice address formats, including P2PKH.

The legacy format MAY be used, but MUST be restricted to the legacy P2PKH invoice address format.

# Simple

A simple signature consists of a witness stack, consensus encoded as a vector of vectors of bytes, and base64-encoded, prefixed by the variant (smp). Validators should construct to_spend and to_sign as defined below, with default values for all fields except that

•  message_hash is a BIP340-tagged hash of the message, as specified below
•  message_challenge in to_spend is set to the scriptPubKey being signed
 with
•  message_signature in to_sign is set to the provided simple signature.

and then proceed as they would for a full signature.

# Full

Full signatures follow an analogous specification to the BIP325 challenges and solutions used by Signet.

Let there be two virtual transactions to_spend and to_sign.

The to_spend transaction is:

   nVersion = 0
   nLockTime = 0
   vin[0].prevout.hash = 0000...000
   vin[0].prevout.n = 0xFFFFFFFF
   vin[0].nSequence = 0
   vin[0].scriptSig = OP_0 PUSH32[ message_hash ]
   vin[0].scriptWitness = []
   vout[0].nValue = 0
   vout[0].scriptPubKey = message_challenge

where message_hash is a BIP340-tagged hash of the message, i.e., sha256_tag(m), where tag = BIP0322-signed-message and m is the message as-is without length prefix or null terminator, and message_challenge is the (public) key script to be proven.

The to_sign transaction is:

   nVersion = 0 or (FULL format only) as appropriate (e.g., 2 for time locks)
   nLockTime = 0 or (FULL format only) as appropriate (for time locks)
   vin[0].prevout.hash = to_spend.txid
   vin[0].prevout.n = 0
   vin[0].nSequence = 0 or (FULL format only) as appropriate (for time locks)
   vin[0].scriptSig = [] or (FULL format only) as appropriate (for non segwit-native transactions)
   vin[0].scriptWitness = message_signature
   vout[0].nValue = 0
   vout[0].scriptPubKey = OP_RETURN

A full signature consists of the variant-prefixed (ful) base64-encoding of the to_sign transaction in standard network serialisation once it has been signed.

# Full (Proof of Funds)

The Proof of Funds variant extends the basic scheme: in addition to signing a message under a single address's key, the signer proves control over an arbitrary set of UTXOs. This UTXO set is chosen freely by the signer and MAY be associated with the signing address (the message_challenge). For example, it may consist of outputs paid to that address, but any UTXOs the signer wants to show control over are permitted. In any case, however, the UTXO list does not aim to prove completeness (e.g., it does NOT mean: "these are all UTXOs that exist for an address"), nor that they are unspent (e.g., a validator must consult the blockchain to verify that).

A signer may construct a proof of funds, demonstrating control of a set of UTXOs, by constructing a full signature as above, with the following modifications.

•  The to_spend transaction is represented as a finalized PSBT instead of a raw
 transaction (see BIP174 for details on the finalization
 process).
•  All outputs that the signer wishes to demonstrate control of are included as additional inputs of
 to_sign, and their witness and scriptSig data should be set as though these outputs
 were actually being spent.
•  The Non-Witness or Witness UTXO fields (as appropriate for the type) of each additional input must
 be set to the corresponding UTXO.
•  As an optimization for large sets of Non-Witness UTXOs that spend outputs from the same
 transaction, the Non-Witness UTXO field may be omitted for any input that spends an output from
 the same transaction as an input earlier in the list.

A full Proof of Funds signature consists of the variant-prefixed (pof) base64-encoding of the finalized PSBT once it has been signed.

Unlike an ordinary signature, validators of a proof of funds need access to the current UTXO set, to learn that the claimed inputs exist on the blockchain and remain unspent. An offline validator therefore can only attest to the cryptographic validity of the additional inputs' witness stack, but not its blockchain state. An attested list of UTXOs can also never prove that there do not exist more UTXOs for a certain address.

# Detailed Specification

For all signature types, except legacy, the to_spend and to_sign transactions must be valid transactions which pass all consensus checks, except of course that the output with prevout 000...000:FFFFFFFF does not exist.

# Verification

A validator is given as input an address A, signature s and message m, and outputs one of three states:

•  valid at time T and age S indicates that the signature has set timelocks but is otherwise
 valid
•  inconclusive means the validator was unable to check the scripts
•  invalid means that some check failed

Verification Process

Validation consists of the following steps:

1. Basic validation
   1. Compute the transaction to_spend from m and A
   2. Decode s as the transaction to_sign
   3. If s was a full transaction or PSBT, confirm all fields are set as specified above; in particular that
      • to_sign has at least one input and its first input spends the output of to_spend
      • to_sign with more than one input has an appropriate Witness UTXO or Non-Witness UTXO for each input
        • If (based on the input type) a Non-Witness UTXO is required but not provided, check if the first input with the same transaction ID has a Non-Witness UTXO set and use that; fail validation if no such Non-Witness UTXO can be found
      • to_sign has exactly one output, as specified above
   4. Confirm that the two transactions together satisfy all consensus rules, except for to_spend's missing input, and except that nSequence of to_sign's first input and nLockTime of to_sign are not checked.
2. (Optional) If the validator does not have a full script interpreter, it should check that it understands all scripts being satisfied. If not, it should stop here and output inconclusive.
3. Check the required rules:
   1. All signatures MUST use the SIGHASH_ALL flag, unless the output type supports SIGHASH_DEFAULT, which then MAY be used alternatively (e.g., BIP341 P2TR).
   2. The use of CODESEPARATOR or FindAndDelete is forbidden.
   3. LOW_S, STRICTENC and NULLFAIL: valid ECDSA signatures must be strictly DER-encoded and have a low-S value; invalid ECDSA signature must be the empty push
   4. MINIMALDATA: all pushes must be minimally encoded
   5. CLEANSTACK: require that only a single stack element remains after evaluation
   6. MINIMALIF: the argument of IF/NOTIF must be exactly 0x01 or empty push
   7. If any of the above steps failed, the validator should stop and output the invalid state.
4. Check the upgradeable rules
   1. The version of to_sign must be 0 or 2.
   2. The use of NOPs reserved for upgrades is forbidden.
   3. The use of Segwit versions greater than 1 is forbidden.
   4. If any of the above steps failed, the validator should stop and output the inconclusive state.
5. Let T be the nLockTime of to_sign and S be the nSequence of the first input of to_sign. Output the state valid at time T and age S.
   1. For full Proof of Funds signatures, a validator MAY additionally report any non-zero nSequence values on the Proof of Funds inputs (i.e., vin[1..n]), and MAY verify them against the current chain state when the UTXO set is available; such checks are advisory and do not affect the output state.

# Signing

Signers who control an address A who wish to sign a message m act as follows:

1.  They construct to_spend and to_sign as specified above, using the
 scriptPubKey of A for message_challenge and tagged hash of m as
 message_hash.
2.  Optionally, they may set nVersion/nLockTime of to_sign or nSequence of its first
 input.
3.  Optionally, they may add any additional inputs to to_sign that they wish to prove
 control of.
4.  They satisfy to_sign as they would any other transaction.

They then encode their signature, choosing either simple, full or full-pof as follows:

•  If they added no inputs to to_sign, left nVersion, nSequence and nLockTime at 0, and
 A is a "native" Segwit address (P2WPKH, P2WSH, P2TR), then they may base64-encode
 message_signature with smp as prefix.
•  If they added no inputs to to_sign, they may base64-encode to_sign with
 ful as prefix.
•  Otherwise, they must base64-encode the finalized PSBT of to_sign with
 pof as prefix.

# PSBT-based signing

A valid witness stack for a multisig address must be constructed by coordinating different signers to produce a partial signature each. The coordination procedure is not specified by this BIP, but due to the use of PSBTs it should closely resemble the coordination of signing a multisig transaction for publishing to the network.

The main difference is a new global PSBT field and the way a signer presents the transaction signing request to the user. The new global type is defined as follows:

# PSBT creator

The transaction creator of a BIP322 PSBT must follow these steps:

1.  They construct to_spend and to_sign as specified above, using the
 scriptPubKey of A for message_challenge and tagged hash of m as
 message_hash.
2.  Optionally, they may set nVersion/nLockTime of to_sign or nSequence of its first
 input.
3.  Optionally, they may add any additional inputs to to_sign that they wish to prove
 control of.
4.  They set the appropriate witness_utxo and non_witness_utxo fields of the
 first input, using the to_spend transaction as a non_witness_utxo or
 the first output of the to_spend transaction as witness_utxo.
5.  They set the appropriate witness_utxo and non_witness_utxo fields of
 each additional input.
6.  They set the appropriate PSBT input and global fields as required by the signers(s) to produce a
 partial signature.
7.  They set the PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE field, using the full UTF-8-encoded
 message as the valuedata.
 
   1.  There is no specified maximum length of an input's valuedata or a PSBT as a whole in
 BIP174, but different signers might impose safety limits. It is
 recommended to use a maximum length of a few kilobytes to maximize compatibility. Very large
 messages should be committed to by hash instead.
 

# PSBT signer

A transaction signer of a BIP322 PSBT must follow these steps:

1.  They decode the base64-encoded PSBT as specified in BIP174.
2.  If they detect the following properties (all must be true, otherwise this is NOT a BIP322 PSBT
 and they should treat it as an ordinary PSBT):
 
   1.  The PSBT has the PSBT_GLOBAL_GENERIC_SIGNED_MESSAGE field set. Extract and use as
 message in the next steps.
 
   2.  The first PSBT input has either a witness_utxo or a non_witness_utxo
 field set and the scriptPubKey can be extracted. Use that as
 message_challenge in the next steps.
 
   3.  The first PSBT input has prevout.n = 0.
 
   4.  The first PSBT input has prevout.hash = to_spend.txid where
 to_spend.txid is constructed using the rules described above using the
 message and message_challenge from the previous steps.
 
   5.  The PSBT's unsigned transaction has a single output with a value of 0 and the
 scriptPubKey set to OP_RETURN (0x6a).
 
3.  If all of the above steps are true, the signer must inform the user about the message they are
 signing and the address they are signing for.
 
   1.  Even though the message being signed is a transaction, the user interaction (e.g., the steps and
 messages shown on a hardware signing device's screen) should resemble the steps to sign a legacy
 message, not the steps for signing a transaction.
 
   2.  Example: Instead of showing "spending 0 satoshi from address <challenge_address>" the
 device should show "signing message <message> for address <challenge_address>".
 
4.  Upon user approval, the signer adds a partial signature for each input it is capable of signing.

# PSBT finalizer

A transaction finalizer of a BIP322 PSBT must follow these steps:

1.  They decode the base64-encoded PSBT as specified in BIP174.
2.  They finalize the PSBT as specified in BIP174.
3.  They then encode the signature following the same steps as described in Signing
 above.

# Compatibility

This specification is backwards-compatible with the legacy signmessage/verifymessage specification through the special case as described above. To support backward compatibility with implementations of this BIP before it was finalized, a verifier might assume the simple variant in the absence of a prefix.

# Reference implementation

•  Bitcoin Core pull request (basic support) at: https://github.com/bitcoin/bitcoin/pull/24058
•  btcd pull request (complete support, source of test vectors) at:
 https://github.com/btcsuite/btcd/pull/2521

# Acknowledgements

Thanks to David Harding, Jim Posen, Kalle Rosenbaum, Pieter Wuille, Andrew Poelstra, Luke Dashjr, and many others for their feedback on the specification.

# References

1.  Original mailing list thread:
 https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-March/015818.html

# Changelog

• 2.0.0 (2026-06-04):
  • Clarify that the message_challenge is not optional for "Proof of Funds".
• 1.0.0 (2026-04-15):
  • Mark Complete
  • Breaking change: Add human-readable prefix to encoded signature
  • Breaking change: Format of "Proof of Funds" signatures to be base64-encoded finalized PSBT
  • Add new PSBT global field for PSBT-based signing
• 0.0.1 (2018-09-10):
  • Proposed as draft

# Copyright

This document is licensed under the Creative Commons CC0 1.0 Universal license.

# Test vectors

Basic test vectors for message hashing, transaction hashes and "simple" variant test cases can be found in basic-test-vectors.json.

Generated test vectors for more "simple" and "full" variant test cases can be found in generated-test-vectors.json.

They were generated using this code.