BIP 0322 - Revision history

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/70d9b07ab80ab3c2/bip-0322.mediawiki

2024-05-31T18:07:27Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/70d9b07ab80ab3c2/bip-0322.mediawiki

← Older revision		Revision as of 18:07, 31 May 2024
Line 178:		Line 178:
	Produce signatures:		Produce signatures:

	* Message = "" (empty string): <code>AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>		* Message = "" (empty string): <code>AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> or <code>AkgwRQIhAPkJ1Q4oYS0htvyuSFHLxRQpFAY56b70UvE7Dxazen0ZAiAtZfFz1S6T6I23MWI2lK/pcNTWncuyL8UL+oMdydVgzAEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy</code>
	* Message = "Hello World": <code>AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>		* Message = "Hello World": <code>AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code> or <code>AkgwRQIhAOzyynlqt93lOKJr+wmmxIens//zPzl9tqIOua93wO6MAiBi5n5EyAcPScOjf1lAqIUIQtr3zKNeavYabHyR8eGhowEhAsfxIAMZZEKUPYWI4BruhAQjzFT8FSFSajuFwrDL1Yhy</code>

	=== Transaction Hashes ===		=== Transaction Hashes ===

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/6fc75b1b2153df40/bip-0322.mediawiki

2024-05-01T14:18:33Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/6fc75b1b2153df40/bip-0322.mediawiki

← Older revision		Revision as of 14:18, 1 May 2024
Line 84:		Line 84:
	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.		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.

	* <code>message_challenge</code> is unused and shall be set to <code>OP_TRUE</code>
	* Similarly, <code>message_signature</code> is then empty.
	* All outputs that the signer wishes to demonstrate control of are included as additional inputs of <code>to_sign</code>, and their witness and scriptSig data should be set as though these outputs were actually being spent.		* All outputs that the signer wishes to demonstrate control of are included as additional inputs of <code>to_sign</code>, and their witness and scriptSig data should be set as though these outputs were actually being spent.

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/df443f8db30862b4/bip-0322.mediawiki

2022-06-07T07:59:59Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/df443f8db30862b4/bip-0322.mediawiki

@@ Line 180: / Line 180: @@
 Produce signatures:
-* Message = "" (empty string): <code>AkcwRAIgFuS8y5m0ym9Gj2odoVB5NIL+cPYkeEj8LL1N/6P58X8CIA6jJ9QH2iYKRXVfmhsDzHq1bMS4Adj0nb8DDSdN/SpBASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>
+* Message = "" (empty string): <code>AkcwRAIgM2gBAQqvZX15ZiysmKmQpDrG83avLIT492QBzLnQIxYCIBaTpOaD20qRlEylyxFSeEA2ba9YOixpX8z46TSDtS40ASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>
-* Message = "Hello World": <code>AkcwRAIgG3PASL/vRTgAqogWT6S8rUOQXNnfRzX6JncmbFlHc1ACIGQdsW+rnVmsQzyAYRQisHKFMigDmKiL7LUw4x17Fw5tASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>
+* Message = "Hello World": <code>AkcwRAIgZRfIY3p7/DoVTty6YZbWS71bc5Vct9p9Fia83eRmw2QCICK/ENGfwLtptFluMGs2KsqoNSk89pO7F29zJLUx9a/sASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/97e02b2223b21753/bip-0322.mediawiki

2022-02-07T07:38:55Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/97e02b2223b21753/bip-0322.mediawiki

← Older revision		Revision as of 07:38, 7 February 2022
Line 65:		Line 65:
	vout[0].scriptPubKey = message_challenge		vout[0].scriptPubKey = message_challenge

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

	The <code>to_sign</code> transaction is:		The <code>to_sign</code> transaction is:

	nVersion = 0 or as appropriate (e.g. 2, for time locks)		nVersion = 0 or (FULL format only) as appropriate (e.g. 2, for time locks)
	nLockTime = 0 or as appropriate (for time locks)		nLockTime = 0 or (FULL format only) as appropriate (for time locks)
	vin[0].prevout.hash = to_spend.txid		vin[0].prevout.hash = to_spend.txid
	vin[0].prevout.n = 0		vin[0].prevout.n = 0
	vin[0].nSequence = 0 or as appropriate (for time locks)		vin[0].nSequence = 0 or (FULL format only) as appropriate (for time locks)
	vin[0].scriptWitness = message_signature		vin[0].scriptWitness = message_signature
	vout[0].nValue = 0		vout[0].nValue = 0
Line 148:		Line 148:
	== Reference implementation ==		== Reference implementation ==

	~~TODO~~		* Bitcoin Core pull request (basic support) at: https://github.com/bitcoin/bitcoin/pull/24058

	== Acknowledgements ==		== Acknowledgements ==
Line 164:		Line 164:
	== Test vectors ==		== Test vectors ==

	~~TODO~~		=== Message hashing ===

			Message hashes are BIP340-tagged hashes of a message, i.e. sha256_tag(m), where tag = <code>BIP0322-signed-message</code>, and m is the message as is without length prefix or null terminator:

			* Message = "" (empty string): <code>c90c269c4f8fcbe6880f72a721ddfbf1914268a794cbb21cfafee13770ae19f1</code>
			* Message = "Hello World": <code>f0eb03b1a75ac6d9847f55c624a99169b5dccba2a31f5b23bea77ba270de0a7a</code>

			=== Message signing ===

			Given below parameters:

			* private key <code>L3VFeEujGtevx9w18HD1fhRbCH67Az2dpCymeRE1SoPK6XQtaN2k</code>
			* corresponding address <code>bc1q9vza2e8x573nczrlzms0wvx3gsqjx7vavgkx0l</code>

			Produce signatures:

			* Message = "" (empty string): <code>AkcwRAIgFuS8y5m0ym9Gj2odoVB5NIL+cPYkeEj8LL1N/6P58X8CIA6jJ9QH2iYKRXVfmhsDzHq1bMS4Adj0nb8DDSdN/SpBASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>
			* Message = "Hello World": <code>AkcwRAIgG3PASL/vRTgAqogWT6S8rUOQXNnfRzX6JncmbFlHc1ACIGQdsW+rnVmsQzyAYRQisHKFMigDmKiL7LUw4x17Fw5tASECx/EgAxlkQpQ9hYjgGu6EBCPMVPwVIVJqO4XCsMvViHI=</code>

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/edffe529056f6dfd/bip-0322.mediawiki

2021-12-15T15:38:22Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/edffe529056f6dfd/bip-0322.mediawiki

← Older revision		Revision as of 15:38, 15 December 2021
Line 78:		Line 78:
	vout[0].scriptPubKey = OP_RETURN		vout[0].scriptPubKey = OP_RETURN

	A full signature consists of the base64-encoding of the <code>to_sign</code> transaction in standard network serialisation.		A full signature consists of the base64-encoding of the <code>to_sign</code> transaction in standard network serialisation once it has been signed.

	=== Full (Proof of Funds) ===		=== Full (Proof of Funds) ===
Line 124:		Line 124:
	## The version of <code>to_sign</code> must be 0 or 2.		## The version of <code>to_sign</code> must be 0 or 2.
	## The use of NOPs reserved for upgrades is forbidden.		## The use of NOPs reserved for upgrades is forbidden.
	## The use of segwit versions greater than 0 are forbidden.		## The use of segwit versions greater than 1 are forbidden.
	## If any of the above steps failed, the validator should stop and output the ''inconclusive'' state.		## If any of the above steps failed, the validator should stop and output the ''inconclusive'' state.
	# Let ''T'' by the nLockTime of <code>to_sign</code> and ''S'' be the nSequence of the first input of <code>to_sign</code>. Output the state ''valid at time T and age S''.		# Let ''T'' by the nLockTime of <code>to_sign</code> and ''S'' be the nSequence of the first input of <code>to_sign</code>. Output the state ''valid at time T and age S''.

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/19c429ee2831d898/bip-0322.mediawiki

2021-02-12T21:19:30Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/19c429ee2831d898/bip-0322.mediawiki

Show changes

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/cf0b529e78860fa2/bip-0322.mediawiki

2021-01-01T09:56:53Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/cf0b529e78860fa2/bip-0322.mediawiki

Show changes

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/c134a853a9fc0657/bip-0322.mediawiki

2020-08-02T07:36:14Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/c134a853a9fc0657/bip-0322.mediawiki

← Older revision		Revision as of 07:36, 2 August 2020
Line 37:		Line 37:

	A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.		A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.

	~~Two actions "Sign" and "Verify" are defined along with one ''purpose'', "SignMessage", with the ability to expand in the future to add a potential "ProveFunds" purpose.~~

	=== SignatureProof container ===		=== SignatureProof container ===

	~~{\|class="wikitable" style="text-align: center;"~~
	\|-
	~~!Type~~
	~~!Length~~
	~~!Name~~
	~~!Comment~~
	\|-
	~~\|Uint32\|\|4\|\|version\|\|BIP322 version format; must be equal to 1; if > 1, verifier must abort the verification process~~
	\|-
	\|Uint8\|\|1\|\|entries\|\|number of proof entries<ref><strong>Why support multiple proofs?</strong> It is non-trivial to check a large number of individual proofs for duplicates. Software could be written to do so, but it seems more efficient to build this check into the specification itself.</ref>
	\|}

	~~The above is followed by [entries] number of signature entries:~~

	{\|class="wikitable" style="text-align: center;"		{\|class="wikitable" style="text-align: center;"
Line 83:		Line 67:
	!Description		!Description
	\|-		\|-
	\|INCOMPLETE\|\|~~One or several of the given challenges had an empty proof. The prover may need some other entity to complete the~~ proof.		\|INCOMPLETE\|\|Empty proof.
	\|-		\|-
	\|INCONCLUSIVE\|\|~~One or several of the~~ given ~~proofs~~ was consensus-valid but policy-invalid.		\|INCONCLUSIVE\|\|The given proof was consensus-valid but policy-invalid.
	\|-		\|-
	\|VALID\|\|~~All proofs were deemed~~ valid.		\|VALID\|\|The proof was valid.
	\|-		\|-
	\|INVALID\|\|~~One or more of the given proofs were~~ invalid		\|INVALID\|\|The proof was invalid
	\|-		\|-
	\|ERROR\|\|An error was encountered		\|ERROR\|\|An error was encountered
Line 96:		Line 80:
	== Signing and Verifying ==		== Signing and Verifying ==

	If the challenge consists of ~~a single address and the~~ address is in the P2PKH (legacy) format, sign using the legacy format (further information below). Otherwise continue as stated ~~below.~~		If the challenge consists of an address is in the P2PKH (legacy) format, sign using the legacy format (further information below). Otherwise continue as stated below.

	~~Let there be an empty set <code>inputs</code> which is populated and tested at each call to one of the actions~~ below.

	~~=== Purpose~~: ~~SignMessage ===~~		For both cases, generate a sighash based on the given scriptPubKey and message as follows:

	~~The "SignMessage" purpose generates a sighash based on a scriptPubKey and a message. It emits a VALID verification result code unless otherwise stated.~~

	# Return INVALID if scriptPubKey already exists in <code>inputs</code> set, otherwise insert it<ref><strong>Why track duplicates?</strong> Because a 3-entry proof is not proving 3 entries unless they are all distinct</ref>
	# Define the message pre-image as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD)		# Define the message pre-image as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD)
	# Let sighash = sha256(sha256(scriptPubKey \|\| pre-image))		# Let sighash = sha256(sha256(scriptPubKey \|\| pre-image))
Line 110:		Line 89:
	A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.		A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.

	=== ~~Action: Sign~~ ===		=== Signing ===

	The ~~"Sign" action takes~~ as ~~input a purpose. It returns a signature or fails.~~		The signature is generated as follows:

	~~# Obtain the sighash and scriptPubKey from the purpose; FAIL if not VALID~~
	# Derive the private key privkey for the scriptPubKey; FAIL if not VALID		# Derive the private key privkey for the scriptPubKey; FAIL if not VALID
	# Generate and return a signature sig with privkey=privkey, sighash=sighash		# Generate and return a signature sig with privkey=privkey, sighash=sighash

	~~The resulting signature proof should be encoded using base64 encoding.~~		=== Verifying ===

	~~=== Action:~~ Verify ~~===~~		Verify a proof, given a standard flags value, a script sig, an optional witness, and a derived sighash as described above.

	~~The "Verify" action takes as input~~ a standard flags value, a script sig, an optional witness, and a ~~purpose.~~
	~~It emits one of INCONCLUSIVE, VALID, INVALID, or ERROR~~.

	While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a non-legacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.		While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a non-legacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.

	~~# Obtain the sighash and scriptPubKey from the purpose; pass on result code if not VALID~~
	# Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash		# Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
	# Return INVALID if verification fails		# Return INVALID if verification fails
	# Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash		# Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
	# Return VALID if verification succeeds, otherwise return INCONCLUSIVE		# Return VALID if verification succeeds, otherwise return INCONCLUSIVE

	~~=== Multiple Proofs ===~~

	~~When more than one proof is created or verified, repeat the operation for each proof, retaining the inputs set. As noted, if the same input appears more than once, the operation must fail accordingly.~~

	~~Note that the order of the entries in the proof must match the order of the entries given by the verifier.~~

	* If any of the proofs are empty during a verification process, skip the verification and set the INCOMPLETE flag
	* If a verification call returns ERROR or INVALID, return ERROR or INVALID immediately, ignoring as yet unverified entries
	* After all verifications complete,
	** return INCONCLUSIVE if any verification call returned INCONCLUSIVE
	** return INCOMPLETE if the INCOMPLETE flag is set
	** return VALID

	== Legacy format ==		== Legacy format ==

	The legacy format is restricted to the legacy P2PKH address format~~, and restricted to one single challenge (address)~~.		The legacy format is restricted to the legacy P2PKH address format.

	Any other input (e.~~g. multiple addresses, or~~ non-P2PKH address format~~(s)~~) must be signed using the new format described above.		Any other input (i.e. non-P2PKH address format) must be signed using the new format described above.

	=== Signing ===		=== Signing ===
Line 177:		Line 138:

	This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.		This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.

	~~== Rationale ==~~

	~~<references/>~~

	== Reference implementation ==		== Reference implementation ==
Line 231:		Line 188:

	== Test vectors ==		== Test vectors ==

			(TODO: update test vectors, which are based on previous iteration where signature proofs contained additional data)

	== Native segwit test vector ==		== Native segwit test vector ==

934: Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0322.mediawiki

2019-09-24T17:58:34Z

Update BIP text with latest version from https://github.com/bitcoin/bips/blob/b5723035e23896d0/bip-0322.mediawiki

New page

{{bip}}
{{BipMoved|bip-0322.mediawiki}}

<pre>
BIP: 322
Layer: Applications
Title: Generic Signed Message Format
Author: Karl-Johan Alm <karljohan-alm@garage.co.jp>
Comments-Summary: No comments yet.
Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-0322
Status: Draft
Type: Standards Track
Created: 2018-09-10
License: CC0-1.0
</pre>

== Abstract ==

A standard for interoperable generic signed messages based on the Bitcoin Script format.

== Background ==

* Assume two actors, a prover <code>P</code> and a verifier <code>V</code>.
* <code>P</code> wants to prove that they own the private key <code>k</code> associated with a given address <code>A</code> (which in turn is derived from the pubkey <code>kG</code>).
* Let <code>V</code> generate a message <code>M</code> and hand this to <code>P</code>.
* <code>P</code> generates a signature <code>S</code> by signing the message <code>M</code> using <code>k</code>. Given <code>S</code>, <code>V</code> can prove that <code>P</code> has the private key associated with <code>A</code>.

The astute reader will notice that the above is missing a critical part, namely the pubkey <code>kG</code>, without which the verifier cannot actually verify the message. The current message signing standard solves this via a cryptographic trick, wherein the signature <code>S</code> above is a special "recoverable signature" type. Given the message <code>M</code> and the signature <code>S</code>, it is then possible to recover the pubkey <code>kG</code>. The system thus derives the address for the pubkey <code>kG</code>, and if it does not match <code>A</code>, the proof is deemed invalid.

While this is a neat trick, it unnecessarily restricts and complicates the message signing mechanism; for instance, it is currently not possible to sign a message for a P2SH address, because there is no pubkey to recover from the resulting signature.

== Motivation ==

The current message signing standard only works for P2PKH (1...) addresses. By extending it to use a Bitcoin Script based approach, it could be made more generic without causing a too big burden on implementers, who most likely have access to Bitcoin Script interpreters already.

== Specification ==

A new structure <code>SignatureProof</code> is added, which is a simple serializable scriptSig & witness container.

Two actions "Sign" and "Verify" are defined along with one ''purpose'', "SignMessage", with the ability to expand in the future to add a potential "ProveFunds" purpose.

=== SignatureProof container ===

{|class="wikitable" style="text-align: center;"
|-
!Type
!Length
!Name
!Comment
|-
|Uint32||4||version||BIP322 version format; must be equal to 1; if > 1, verifier must abort the verification process
|-
|Uint8||1||entries||number of proof entries<ref><strong>Why support multiple proofs?</strong> It is non-trivial to check a large number of individual proofs for duplicates. Software could be written to do so, but it seems more efficient to build this check into the specification itself.</ref>
|}

The above is followed by [entries] number of signature entries:

{|class="wikitable" style="text-align: center;"
|-
!Type
!Length
!Name
!Comment
|-
|VarInt||1-8||scriptsiglen||Number of bytes in scriptSig data
|-
|Uint8*||[scriptsiglen]||scriptsig||ScriptSig data
|-
|VarInt||1-8||witlen||Number of entries in witness stack
|-
|Uint8[]*||[witlen]||wit||Witness stack, as [witlen] uint8* vectors, each one prepended with a varint of its size
|}

In some cases, the scriptsig or wit may be empty. If both are empty, the proof is incomplete.

=== Result Codes ===

A verification call will return a result code according to the table below.

{|class="wikitable" style="text-align: center;"
|-
!Code
!Description
|-
|INCOMPLETE||One or several of the given challenges had an empty proof. The prover may need some other entity to complete the proof.
|-
|INCONCLUSIVE||One or several of the given proofs was consensus-valid but policy-invalid.
|-
|VALID||All proofs were deemed valid.
|-
|INVALID||One or more of the given proofs were invalid
|-
|ERROR||An error was encountered
|}

== Signing and Verifying ==

If the challenge consists of a single address and the address is in the P2PKH (legacy) format, sign using the legacy format (further information below). Otherwise continue as stated below.

Let there be an empty set <code>inputs</code> which is populated and tested at each call to one of the actions below.

=== Purpose: SignMessage ===

The "SignMessage" purpose generates a sighash based on a scriptPubKey and a message. It emits a VALID verification result code unless otherwise stated.

# Return INVALID if scriptPubKey already exists in <code>inputs</code> set, otherwise insert it<ref><strong>Why track duplicates?</strong> Because a 3-entry proof is not proving 3 entries unless they are all distinct</ref>
# Define the message pre-image as the sequence "Bitcoin Signed Message:\n" concatenated with the message, encoded in UTF-8 using Normalization Form Compatibility Decomposition (NFKD)
# Let sighash = sha256(sha256(scriptPubKey || pre-image))

A private key may be used directly to sign a message. In this case, its P2WPKH bech32 address shall be derived, and used as the input.

=== Action: Sign ===

The "Sign" action takes as input a purpose. It returns a signature or fails.

# Obtain the sighash and scriptPubKey from the purpose; FAIL if not VALID
# Derive the private key privkey for the scriptPubKey; FAIL if not VALID
# Generate and return a signature sig with privkey=privkey, sighash=sighash

The resulting signature proof should be encoded using base64 encoding.

=== Action: Verify ===

The "Verify" action takes as input a standard flags value, a script sig, an optional witness, and a purpose.
It emits one of INCONCLUSIVE, VALID, INVALID, or ERROR.

While omitted below, ERROR is returned if an unforeseen error occurs at any point in the process. A concrete example of this is if a legacy proof is given as input to a non-legacy address; the deserialization of the proof will fail in this case, and this should result in an ERROR result.

# Obtain the sighash and scriptPubKey from the purpose; pass on result code if not VALID
# Verify Script with flags=consensus flags (currently P2SH, DERSIG, NULLDUMMY, CLTV, CSV, WITNESS), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
# Return INVALID if verification fails
# Verify Script with flags=standard flags (above plus STRICTENC, MINIMALDATA, etc.), scriptSig=script sig, scriptPubKey=scriptPubKey, witness=witness, and sighash=sighash
# Return VALID if verification succeeds, otherwise return INCONCLUSIVE

=== Multiple Proofs ===

When more than one proof is created or verified, repeat the operation for each proof, retaining the inputs set. As noted, if the same input appears more than once, the operation must fail accordingly.

Note that the order of the entries in the proof must match the order of the entries given by the verifier.

* If any of the proofs are empty during a verification process, skip the verification and set the INCOMPLETE flag
* If a verification call returns ERROR or INVALID, return ERROR or INVALID immediately, ignoring as yet unverified entries
* After all verifications complete,
** return INCONCLUSIVE if any verification call returned INCONCLUSIVE
** return INCOMPLETE if the INCOMPLETE flag is set
** return VALID

== Legacy format ==

The legacy format is restricted to the legacy P2PKH address format, and restricted to one single challenge (address).

Any other input (e.g. multiple addresses, or non-P2PKH address format(s)) must be signed using the new format described above.

=== Signing ===

Given the P2PKH address <code>a</code> and the message <code>m</code>, and the pubkey-hash function <code>pkh(P) = ripemd160(sha256(P))</code>:

# let <code>p</code> be the pubkey-hash <code>pkh(P)</code> for the pubkey <code>P</code>, contained in <code>a</code>
# let <code>x</code> be the private key associated with <code>P</code> so that <code>pkh(xG) = p</code>
# let <code>digest</code> be <code>SHA56d("Bitcoin Signed Message:\n"||m)</code>
# create a compact signature <code>sig</code> (aka "recoverable ECDSA signature") using <code>x</code> on <code>digest</code>

The resulting proof is <code>sig</code>, serialized using the base64 encoding.

=== Verifying ===

Given the P2PKH address <code>a</code>, the message <code>m</code>, the compact signature <code>sig</code>, and the pubkey-hash function <code>pkh(P) = ripemd160(sha256(P))</code>:

# let <code>p</code> be the pubkey-hash <code>pkh(P)</code> for the pubkey <code>P</code>, contained in <code>a</code>
# let <code>digest</code> be <code>SHA56d("Bitcoin Signed Message:\n"||m)</code>
# attempt pubkey recovery for <code>digest</code> using the signature <code>sig</code> and store the resulting pubkey into <code>Q</code>
## fail verification if pubkey recovery above fails
# let <code>q</code> be the pubkey-hash <code>pkh(Q)</code> for the pubkey <code>Q</code>
# if <code>p == q</code>, the proof is valid, otherwise it is invalid

== Compatibility ==

This specification is backwards compatible with the legacy signmessage/verifymessage specification through the special case as described above.

== Rationale ==

<references/>

== Reference implementation ==

# Pull request to Bitcoin Core: https://github.com/bitcoin/bitcoin/pull/16440

== Acknowledgements ==

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

== References ==

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

== Copyright ==

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

== Consensus and standard flags ==

Each flag is associated with some type of enforced rule (most often a soft fork). There are two sets of flags: consensus flags (which result in a block being rejected, if violated), and policy flags (which result in a transaction being accepted only if it is contained within an actual block, and rejected otherwise, if violated). The policy flags are a super-set of the consensus flags.

BIP322 specifies that a proof that validates for both rulesets is valid, a proof that validates for consensus rules, but not for policy rules, is "inconclusive", and a proof that does not validate for consensus rules is "invalid" (regardless of policy rule validation).

The ruleset sometimes changes. This BIP does not intend to be complete, nor does it indicate enforcement of rules, it simply lists the rules as they stand at the point of writing.

=== Consensus rules ===

* P2SH: evaluate P2SH ([https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki BIP16]) subscripts
* DERSIG: enforce strict DER ([https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki BIP66]) compliance
* NULLDUMMY: enforce NULLDUMMY ([https://github.com/bitcoin/bips/blob/master/bip-0147.mediawiki BIP147])
* CHECKLOCKTIMEVERIFY: enable CHECKLOCKTIMEVERIFY ([https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki BIP65])
* CHECKSEQUENCEVERIFY: enable CHECKSEQUENCEVERIFY ([https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki BIP112])
* WITNESS: enable WITNESS ([https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki BIP141])

=== Policy rules ===

All of the above, plus (subject to change):

* STRICTENC: non-strict DER signature or undefined hashtype
* MINIMALDATA: require minimal encodings for all push operations
* DISCOURAGE_UPGRADABLE_NOPS: discourage use of NOPs reserved for upgrades
* CLEANSTACK: require that only a single stack element remains after evaluation
* MINIMALIF: Segwit script only: require the argument of OP_IF/NOTIF to be exactly 0x01 or empty vector
* NULLFAIL: signature(s) must be empty vector if a CHECK(MULTI)SIG operation failed
* LOW_S: signature with S > order/2 in a checksig operation
* DISCOURAGE_UPGRADABLE_WITNESS_PROGRAM: v1-16 witness programs are non-standard (i.e. forbidden)
* WITNESS_PUBKEYTYPE: public keys in segregated witness scripts must be compressed
* CONST_SCRIPTCODE: OP_CODESEPARATOR and FindAndDelete fail any non-segwit scripts

== Test vectors ==

== Native segwit test vector ==

<pre>
address = bcrt1qe7nte4zk4ayly5tc53dtdjupgkz0lr8azx3rzz
scriptpubkey = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd
message = hello
preimage = 0014cfa6bcd456af49f25178a45ab6cb814584ff8cfd426974636f696e205369
676e6564204d6573736167653a0a68656c6c6f
(scriptpubkey || "Bitcoin Signed Message:\nhello")
sighash = 790eef86c204f0bff969ff822121317aa34eff0215dbd30ccf031e7b2f3f0cc1
(sha256d(preimage), displayed in big-endian)
</pre>

The proof becomes:

<pre>
HEX: 01000000010002473044022075b4fb40421d55c55462879cb352a85eeb3af2138d3f0290
2c9143f12870f5f70220119c2995c1661138142f3899c1fd6d1af7e790e0e081be72db9c
e7bf5b5b932901210290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e7c1dee9e
a6e2dcd869

Base64: AQAAAAEAAkcwRAIgdbT7QEIdVcVUYoecs1KoXus68hONPwKQLJFD8Shw9fcCIBGcKZXBZhE4
FC84mcH9bRr355Dg4IG+ctuc579bW5MpASECkL7M0Ctz7KV0Z7K28eRxYam3al5nWG58He6e
puLc2Gk=
</pre>

Split into components:

{|class="wikitable" style="text-align: center;"
|-
!Type
!Length
!Name
!Value
!Comment
|-
|Uint32||4||flags||<code>01000000</code>||proof format version
|-
|Uint8||1||entries||<code>01</code>||1 entry
|-
|VarInt||1-8||scriptsiglen||<code>00</code>||0 byte scriptsig
|-
|VarInt||1-8||wit entries||<code>02</code>||2 witness stack entries
|-
|VarInt||1-8||entry1len||<code>47</code>||71 byte entry
|-
|Uint8[71]||71||entry1||<code>3044022075b4fb40421d55c55462879cb352a85eeb3af213
8d3f02902c9143f12870f5f70220119c2995c1661138142f
3899c1fd6d1af7e790e0e081be72db9ce7bf5b5b932901</code>||Witness stack item 1
|-
|VarInt||1-8||entry2len||<code>21</code>||33 byte entry
|-
|Uint8[33]||33||entry2||<code>0290beccd02b73eca57467b2b6f1e47161a9b76a5e67586e
7c1dee9ea6e2dcd869</code>||Witness stack item 2
|}

The above test vector is for a bech32 P2WPKH (native segwit) address. (Once BIP solidifies, will add test vector for other types.)