P2WSH

P2WSH stands for pay to witness script hash. It locks an output to the SHA-256 hash of a custom locking script, which is called the witness script. To spend the output, you reveal that script as the last item of the witness and supply any data it needs in the items before it. P2WSH works like the older P2SH script, but its unlocking data goes in the witness, so spending it costs less.

The witness script can be almost any script you like. Most are multisignature scripts, which need several keys to sign.

What does a P2WSH lock look like?

A P2WSH scriptPubKey is OP_0 followed by a 32-byte push. The push is the script hash:

OP_0
OP_PUSHBYTES_32
65f91a53cb7120057db3d378bd0f7d944167d43a7dcbff15d6afc4823f1d3ed3

As hex, the lock is 34 bytes:

002065f91a53cb7120057db3d378bd0f7d944167d43a7dcbff15d6afc4823f1d3ed3

Output 1 of 46ebe264b0115a439732554b2b390b11b332b5b5692958b1754aa0ee57b64265 carries this lock.

The OP_0 is the witness version, the same as in P2WPKH. A lock that starts with OP_0 and a 32-byte push is always read as P2WSH. A 20-byte push after OP_0 means P2WPKH instead.

The script hash uses one pass of SHA-256. Blocks and transactions use double SHA-256, and P2SH uses HASH160. P2WSH uses neither. The 32-byte hash gives more room against collisions, as the next section explains.

Why a single SHA-256 and not HASH160?

P2SH uses HASH160, which gives a 160-bit hash. In a P2SH multisig, a co-signer can vary parts of the scripts and search for a pair that shares one hash. One script is the multisig the other signers agree to. The other is a script the co-signer can satisfy alone. This is a collision search. By the birthday bound, it takes about 2^80 hash computations for 160 bits. For a 256-bit hash, the same search takes about 2^128, which is out of reach.

This is the security reason for the change. The longer hash costs 11 more bytes in the lock.

What goes in the witness?

The scriptSig of a P2WSH input must be empty. The witness holds the unlocking items, then the witness script as the last item. The witness script plays the role that a redeem script plays in P2SH. The example below spends a 2-of-3 multisig, which needs two signatures. The witness has four items:

Item	Size	Contents
0	0 bytes (00)	An empty dummy value, needed by OP_CHECKMULTISIG
1	71 bytes (47)	The first signature
2	71 bytes (47)	The second signature
3	105 bytes (69)	The witness script, the 2-of-3 multisig itself

The item 0 dummy exists because OP_CHECKMULTISIG pops one more item off the stack than it uses. Every multisig witness script needs it. The whole witness, as hex, is:

04004730440220415899bbee08e42376d06e8f86c92b4987613c2816352fe09cd1479fd639f18c02200db57f508f69e266d76c23891708158bda18690c165a41b0aa88303b97609f780147304402203973de2303e8787767090dd25c8a4dc97ce1aa7eb4c0962f13952ed4e856ff8e02203f1bb425def789eea8be46407d10b3c8730407176aef4dc2c29865eb5e5542bf0169522103848e308569b644372a5eb26665f1a8c34ca393c130b376db2fae75c43500013c2103cec1ee615c17e06d4f4b0a08617dffb8e568936bdff18fb057832a58ad4d1b752103eed7ae80c34d70f5ba93f93965f69f3c691da0f4607f242f4fd6c7a48789233e53ae

The first byte, 04, is the item count. The witness script at the end decodes to a 2-of-3 multisig:

OP_2
OP_PUSHBYTES_33 03848e308569b644372a5eb26665f1a8c34ca393c130b376db2fae75c43500013c
OP_PUSHBYTES_33 03cec1ee615c17e06d4f4b0a08617dffb8e568936bdff18fb057832a58ad4d1b75
OP_PUSHBYTES_33 03eed7ae80c34d70f5ba93f93965f69f3c691da0f4607f242f4fd6c7a48789233e
OP_3
OP_CHECKMULTISIG

Each key is a compressed public key. The input that spends it is input 0 of b38a88b073743bcc84170071cff4b68dec6fb5dc0bc8ffcb3d4ca632c2c78255.

How does Bitcoin check a P2WSH spend?

P2WSH is a special case. The script is not run from the lock. Instead, Bitcoin runs three steps with the witness:

1. It hashes the last witness item, the witness script, with SHA-256. The result must equal the 32-byte hash in the lock.
2. It pushes the other witness items onto the stack, in order.
3. It runs the witness script as a normal script, using that stack.

If all three succeed, the input is unlocked.

Signatures inside a witness script follow the BIP 143 rules, the same as for P2WPKH.

How do you make a P2WSH address?

The address is the bech32 encoding of the witness program, which is the version and the 32-byte hash. You take the witness script, hash it with SHA-256, and build the lock 0020 followed by the hash. Then you encode the lock with bech32 and witness version 0.

The 2-of-3 lock above gives bc1qvhu3557twysq2ldn6dut6rmaj3qk04p60h9l79wk4lzgy0ca8mfsnffz65. The address starts with bc1q and is always 62 characters long, because the hash in it is 32 bytes. Output 1 of 46ebe264b0115a439732554b2b390b11b332b5b5692958b1754aa0ee57b64265 shows it on our explorer.

What limits apply to a P2WSH script?

Bitcoin Core sets three standardness limits on a P2WSH spend. Consensus allows a larger script, up to 10,000 bytes, as BIP 141 defines. The limits below decide what nodes relay:

• The witness script is at most 3,600 bytes.
• The items before the script are at most 100 in number.
• Each of those items is at most 80 bytes.

A transaction that breaks one of these limits is non-standard. Nodes do not relay it, although a miner could still include it in a block. The numbers are in Bitcoin Core's policy.h. For comparison, a P2SH redeem script must fit the 520-byte push limit.

Why use P2WSH instead of P2SH?

P2WSH and P2SH do the same job: they lock coins to a script that you reveal later. P2WSH has two advantages:

• Its unlocking data sits in the witness, which costs fewer virtual bytes. You pay less in fees when you spend.
• Its witness script can be up to 3,600 bytes under the relay rules (10,000 by consensus), against 520 bytes for a P2SH redeem script.

Use P2WSH when your wallet can send to bc1q addresses. If it cannot, P2SH-P2WSH wraps the same script in a P2SH output.

What do real P2WSH transactions look like?

Example 1: a 2-of-3 multisig. Output 1 of 0ca3ce42ca8037d955d04ed8fd89d10581793fc1ab451dec1116fb63a74c24f4 locks coins to bc1qwqdg6squsna38e46795at95yu9atm8azzmyvckulcc7kytlcckxswvvzej. Input 0 of 1b2a44f4f8b59d6d7075a3dbd72493a6a158218589e722d7525d1d99b7f287a5 spends it. The witness script inside is a 2-of-3 multisig, with the same layout as the example above.

Example 2: a hash puzzle. Output 0 of c6cfbac310715dc35ae5a1edbeae78def5955a67cd891aa3457d8cd4cdb5398a locks coins to bc1qae8a988zl89ggyth378fg6rate67c05xe3fse2ddz7r72gyvextqh3f88c. Its witness script is:

OP_HASH256 OP_PUSHBYTES_32 a23421f2ba909c885a3077bb6f8eb4312487797693bbcfe7e311f797e3c5b8fa OP_EQUAL

The spend supplies two bytes, 1234 in hex. Its double SHA-256 is a23421f2…, which matches the script. Input 0 of 64f427122f7951687aea608b5474509a30616d4e5773a83bc1ed8b8271ad1991 is the spend.

This is a teaching example, and it is not safe to copy. The spend contains no signature, so anyone who sees the data 1234 can reuse it in a transaction that sends the coins elsewhere. Real P2WSH locks should check a signature.