Witness

The witness is the region of a transaction used for unlocking segwit inputs.

It's used for unlocking outputs that have new segregated locking scripts ("witness programs") on them, such as P2WPKH, P2WSH, and P2TR. If any of the inputs to a transaction have new segwit witness programs on them, you have to use the witness section for unlocking them.

The witness area of a transaction is an upgrade that's used in preference to the ScriptSig fields. But the ScriptSig is still used for unlocking legacy locking scripts such as P2PK, P2PKH, P2MS, P2SH, and other custom scripts.

Structure

How do you unlock an input using the witness?

The witness contains a witness field for each input in the transaction.

Each witness field starts with a stack items field indicating the number of items it contains, then for each item you have a size field followed by the actual item itself.

So basically each witness field contains a bunch of data elements required to unlock the input.

A witness field is functionally the same as the ScriptSig field, but instead of using OP_CODES to push items on to the stack, you use compact size fields before each item. Therefore, you can't use any OP_CODES inside it to perform logical operations; all you can do is push data on to the stack, which is all that is required for unlocking the most common types of locking scripts anyway.

So witness data is a simplified alternative to Script that only contains data instead of opcodes.

The witness can only push data on to the stack. For example, within the ScriptSig you could use 0x58 (OP_8) to push the number 8 on to the stack, but to do the same thing in the witness you would need to use the byte 0x08 directly.

Table

This structure repeats for every input.

Note: If you're unlocking both legacy and segwit inputs in a transaction, you must set the witness field for legacy inputs to 00 (i.e. no items to be pushed on to the stack) as each input must have their own witness field.

Examples

What does a witness field look like?

Here are some examples of the witness sections from actual transactions unlocking different types of segwit locking scripts (or "witness programs").

P2WPKH

024730440220537f470c1a18dc1a9d233c0b6af1d2ce18a07f3b244e4d9d54e0e60c34c55e67022058169cd11ac42374cda217d6e28143abd0e79549f7b84acc6542817466dc9b3001210301c1768b48843933bd7f0e8782716e8439fc44723d3745feefde2d57b761f503

{
  "witness": [
    {
      "stackitems": "02",
      "0": {
        "size": "47",
        "item": "30440220537f470c1a18dc1a9d233c0b6af1d2ce18a07f3b244e4d9d54e0e60c34c55e67022058169cd11ac42374cda217d6e28143abd0e79549f7b84acc6542817466dc9b3001"
      },
      "1": {
        "size": "21",
        "item": "0301c1768b48843933bd7f0e8782716e8439fc44723d3745feefde2d57b761f503"
      }
    }
  ]
}
      

30440220537f470c1a18dc1a9d233c0b6af1d2ce18a07f3b244e4d9d54e0e60c34c55e67022058169cd11ac42374cda217d6e28143abd0e79549f7b84acc6542817466dc9b3001 
0301c1768b48843933bd7f0e8782716e8439fc44723d3745feefde2d57b761f503

This transaction contains one input that has a P2WPKH lock on it. To unlock it you need to provide a signature followed by a public key in the witness field.

This unlocking code is functionally the same as the unlocking script found inside the ScriptSig for legacy P2PKH. That is, it just contains a signature and a public key.

However, whereas the ScriptSig for a P2PKH uses OP_CODES for pushing the signature and public key on to the stack, the witness just uses compact size fields to indicate the size of the signature and public key.

OP_PUSHBYTES_72
3045022100c233c3a8a510e03ad18b0a24694ef00c78101bfd5ac075b8c1037952ce26e91e02205aa5f8f88f29bb4ad5808ebc12abfd26bd791256f367b04c6d955f01f28a772401
OP_PUSHBYTES_33
03f0609c81a45f8cab67fc2d050c21b1acd3d37c7acfd54041be6601ab4cef4f31

483045022100c233c3a8a510e03ad18b0a24694ef00c78101bfd5ac075b8c1037952ce26e91e02205aa5f8f88f29bb4ad5808ebc12abfd26bd791256f367b04c6d955f01f28a7724012103f0609c81a45f8cab67fc2d050c21b1acd3d37c7acfd54041be6601ab4cef4f31

P2WSH

04004730440220415899bbee08e42376d06e8f86c92b4987613c2816352fe09cd1479fd639f18c02200db57f508f69e266d76c23891708158bda18690c165a41b0aa88303b97609f780147304402203973de2303e8787767090dd25c8a4dc97ce1aa7eb4c0962f13952ed4e856ff8e02203f1bb425def789eea8be46407d10b3c8730407176aef4dc2c29865eb5e5542bf0169522103848e308569b644372a5eb26665f1a8c34ca393c130b376db2fae75c43500013c2103cec1ee615c17e06d4f4b0a08617dffb8e568936bdff18fb057832a58ad4d1b752103eed7ae80c34d70f5ba93f93965f69f3c691da0f4607f242f4fd6c7a48789233e53ae

{
  "witness": [
    {
      "stackitems": "04"
      "0": {
        "size": "00",
        "item": ""
      },
      "1": {
        "size": "47",
        "item": "30440220415899bbee08e42376d06e8f86c92b4987613c2816352fe09cd1479fd639f18c02200db57f508f69e266d76c23891708158bda18690c165a41b0aa88303b97609f7801"
      },
      "2": {
        "size": "47",
        "item": "304402203973de2303e8787767090dd25c8a4dc97ce1aa7eb4c0962f13952ed4e856ff8e02203f1bb425def789eea8be46407d10b3c8730407176aef4dc2c29865eb5e5542bf01"
      },
      "3": {
        "size": "69",
        "item": "522103848e308569b644372a5eb26665f1a8c34ca393c130b376db2fae75c43500013c2103cec1ee615c17e06d4f4b0a08617dffb8e568936bdff18fb057832a58ad4d1b752103eed7ae80c34d70f5ba93f93965f69f3c691da0f4607f242f4fd6c7a48789233e53ae"
      },
    }
  ]
}
      

00 
30440220415899bbee08e42376d06e8f86c92b4987613c2816352fe09cd1479fd639f18c02200db57f508f69e266d76c23891708158bda18690c165a41b0aa88303b97609f7801 
304402203973de2303e8787767090dd25c8a4dc97ce1aa7eb4c0962f13952ed4e856ff8e02203f1bb425def789eea8be46407d10b3c8730407176aef4dc2c29865eb5e5542bf01 
522103848e308569b644372a5eb26665f1a8c34ca393c130b376db2fae75c43500013c2103cec1ee615c17e06d4f4b0a08617dffb8e568936bdff18fb057832a58ad4d1b752103eed7ae80c34d70f5ba93f93965f69f3c691da0f4607f242f4fd6c7a48789233e53ae

This transaction contains one input that has a P2WSH lock on it.

The final item in this witness field is the Witness Script (equivalent to the Redeem Script in a P2SH), which in this example is a P2MS locking script. You can check this by decoding the hex bytes of the final data push to see the actual Script it contains:

All of the items before the Witness Script are the data elements required to unlock it, which in this example is two signatures (along with an extra 00 at the start due to a bug in the way P2MS works).

So again, this unlocking code contains the same kind of data as the unlocking script for a legacy P2SH.

OP_0
OP_PUSHBYTES_71
3044022100d0ed946330182916da16a6149cd313a4b1a7b41591ee52fb3e79d64e36139d66021f6ccf173040ef24cb45c4db3e9c771c938a1ba2cf8d2404416f70886e360af401
OP_PUSHBYTES_71
5121022afc20bf379bc96a2f4e9e63ffceb8652b2b6a097f63fbee6ecec2a49a48010e2103a767c7221e9f15f870f1ad9311f5ab937d79fcaeee15bb2c722bca515581b4c052ae

00473044022100d0ed946330182916da16a6149cd313a4b1a7b41591ee52fb3e79d64e36139d66021f6ccf173040ef24cb45c4db3e9c771c938a1ba2cf8d2404416f70886e360af401475121022afc20bf379bc96a2f4e9e63ffceb8652b2b6a097f63fbee6ecec2a49a48010e2103a767c7221e9f15f870f1ad9311f5ab937d79fcaeee15bb2c722bca515581b4c052ae

Whilst witness data itself is not Script, in the case of P2WSH locking scripts the final item in the witness field does actually contain Script.

P2WPKH & P2PKH

024730440220599640d1dba05cba9bf5284cf080171c736a8fef51e8975501abd995744cbc8e02202fcda9a5423cfa3c75aadb0a4a20f57d1e2f041211658bc1793974b41202bc4e01210214a6f6ff714e38376ab3afb8f10965cf1ed7940284a3bff81dc8c0bd656de43300

{
  "witness": [
    {
      "stackitems": "02"
      "0": {
        "size": "47",
        "item": "30440220599640d1dba05cba9bf5284cf080171c736a8fef51e8975501abd995744cbc8e02202fcda9a5423cfa3c75aadb0a4a20f57d1e2f041211658bc1793974b41202bc4e01"
      },
      "1": {
        "size": "21",
        "item": "0214a6f6ff714e38376ab3afb8f10965cf1ed7940284a3bff81dc8c0bd656de433"
      },
    },
    {
      "stackitems": "00"
    }
  ]
}
      

This transaction is unlocking two separate inputs: the first input has a newer P2WPKH locking script (witness program) on it, and the second has a legacy P2PKH locking script on it.

Seeing as this transaction is unlocking a segwit output, both of the inputs need to have their own witness field.

• The first witness field contains the standard unlocking code for a P2WPKH locking script. This is a signature and a public key.
• The second witness field is 00, as a P2PKH locking script does not use a witness field to be unlocked.
  • Note: The unlocking code for this input can be found in the ScriptSig instead.

And as you can see, the witness fields for each input are simply concatenated one after the other inside the witness area of a transaction.

It's perfectly fine to combine legacy and segwit inputs in a transaction. You just have to remember to set the witness field for an input to 00 if it does not require the use of a witness field to be unlocked.

P2TR

There are two methods for unlocking a P2TR lock, and the structure of the witness field varies depending on which method you're using.

1. Key Path Spend

0141b693a0797b24bae12ed0516a2f5ba765618dca89b75e498ba5b745b71644362298a45ca39230d10a02ee6290a91cebf9839600f7e35158a447ea182ea0e022ae01

{
  "witness": [
    {
      "stackitems": "01",
      "0": {
        "size": "41",
        "item": "b693a0797b24bae12ed0516a2f5ba765618dca89b75e498ba5b745b71644362298a45ca39230d10a02ee6290a91cebf9839600f7e35158a447ea182ea0e022ae01"
      }
    }
  ]
}

b693a0797b24bae12ed0516a2f5ba765618dca89b75e498ba5b745b71644362298a45ca39230d10a02ee6290a91cebf9839600f7e35158a447ea182ea0e022ae01

In a P2TR key path spend, the witness contains a single signature item only.

This signature corresponds to the tweaked public key placed in the P2TR ScriptPubKey.

This is the "default" method for unlocking a P2TR output.

2. Script Path Spend

034101769105cbcbdcaaee5e58cd201ba3152477fda31410df8b91b4aee2c4864c7700615efb425e002f146a39ca0a4f2924566762d9213bd33f825fad83977fba7f0122206d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0ac21c0924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329

{
  "witness": [
    {
      "stackitems": "03",
      "0": {
        "size": "41",
        "item": "01769105cbcbdcaaee5e58cd201ba3152477fda31410df8b91b4aee2c4864c7700615efb425e002f146a39ca0a4f2924566762d9213bd33f825fad83977fba7f01"
      },
      "1": {
        "size": "22",
        "item": "206d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0ac"
      },
      "2": {
        "size": "21",
        "item": "c0924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329"
      }
    }
  ]
}

01769105cbcbdcaaee5e58cd201ba3152477fda31410df8b91b4aee2c4864c7700615efb425e002f146a39ca0a4f2924566762d9213bd33f825fad83977fba7f01 
206d4ddc0e47d2e8f82cbe2fc2d0d749e7bd3338112cecdc76d8f831ae6620dbe0ac
c0924c163b385af7093440184af6fd6244936d1288cbb41cc3812286d3f83a3329

In a P2TR script path spend, the witness contains 2 or more items.

These items can be split in to 3 sections:

1. Script Inputs (optional) — The items at the start of the witness field are used to unlock the upcoming leaf script item. This is usually a single signature, but it could be made up of multiple stack items (depending on what's required to unlock the leaf script).
2. Leaf Script — This is the second-to-last item in the witness field and comes after the script inputs. This is a complete locking script that has been used as one of the additional custom locks for the output.
3. Control Block — This is the last item in the witness field. It contains information that proves the leaf script was part of the script tree that was used to create the tweaked public key placed in to the original ScriptPubKey.

This is the "secondary" method for unlocking a P2TR output. This script path spend method is used as an alternative to the key path spend method above.

This witness structure for a P2TR script path spend is the same as the witness structure for a P2WSH, but with an additional control block at the end.

Limits

What is the maximum size of a witness field?

Similar to Script, the witness data of a transaction has certain size limits for standard P2WPKH, P2WSH, and P2TR locking scripts:

• Each witness field can contain a maximum of 100 stack items.
• Each stack item can be a maximum of 80 bytes.

The Witness Script in a P2WSH (the final stack item) can be up to 3,600 bytes. This is the data push of the actual locking script.

A transaction can exceed these limits and it will still be considered valid, but it will also be considered non-standard and therefore will not be relayed by nodes.

These limits can be found in policy.h.

Benefits

Why use the witness instead of the ScriptSig field?

There are two benefits to using the witness instead of the ScriptSig field for unlocking inputs.

1. Witness data weighs less

Each byte inside the witness carries less weight than each byte inside the ScriptSig:

Or in terms of virtual bytes that's:

For example, the typical unlocking code inside a ScriptSig for a legacy P2PKH contains 106 bytes, which is equal to 424 weight units or 106 vbytes:

47304402205aea7d8d4896c5057a96f1b9fc76dd2b00f30ab0df46149047b5f4294f88796202205ce938d9f14f5238192b369d79861ade5a25884ece7afe9b9dde8a6a683c4af7012102af26f51735ff252de2972f06f2bb47456108c2e8a6554187cf3bb4a0c657590f

Transaction: 842c4626a8ef8eebe46ed8d591b643c5d7be84ea1aa199fb76e5d78fe8d6819f (Input 0)

However, the typical unlocking code inside a witness field for a segwit P2WPKH contains 107 bytes, which is equal to 107 weight units or 26.75 vbytes:

0247304402202a11945f55d174686cd48e9b3e0db3bfbe5fb9557a76fa546c6772c434f03f14022010be503e37c1cb6e0519ce9f8532c89fa2cbec6667d93a4f3bdef43fb047dba30121032704e02eb63d8ea323b0386bf3b47c0d9058f36c9c486ac102a34b929d862abb

Transaction: 7a466b5ed43e5022121918d9e9fdef923a7a5e2d01c9abd6a4998e30e77d2ad3 (Input 0)

As a result, the unlocking code for segwit locking scripts takes up less space inside a block. This means you don't have to pay as much in transaction fees in terms of sats-per-vbyte to get the transaction mined.

Using the witness gives you a discount on the amount you have to pay in transaction fees compared to using the ScriptSig.

2. The witness field prevents transaction malleability

The ScriptSig field usually contains a signature, and this field is included when creating the TXID. However, the witness is not included as part of the TXID, so any signatures included in the witness are no longer included when creating the TXID:

This is important because signatures can be modified whilst still keeping the transaction valid, which means that it's possible for a transaction's TXID to change before it gets mined in to a block. So by using the witness field to unlock inputs you can be confident that the TXID will remain the same after the transaction has been sent in to the network.

This change was the driving force behind the Segregated Witness upgrade, and it's the main reason we use the new witness section of a transaction over the ScriptSig fields for unlocking inputs.

Witness Reserved Value

Space for committing new data to the block

The witness for the input to a coinbase transaction contains a witness reserved value, which is a 32-byte space reserved for a commitment for new data in a future upgrade to bitcoin.

The input in a coinbase transaction does not reference any previous output for spending, so there is no need to unlock anything. This means that the unlocking code sections for that input (i.e. the ScriptSig and witness) are basically "spare" fields.

Therefore, the witness field for the input in a coinbase transaction has been reserved as a space to store extra data in a potential future upgrade. For example, if a new upgrade added a some new data to transactions, then that all new data could be hashed and stored in the witness reserved value, and everyone could see that the data was indeed included as part of the block.

At the moment the witness reserved value is not being used, so it's usually set to an empty 32-byte value of 0000000000000000000000000000000000000000000000000000000000000000.

Terminology

Why is it called a witness?

The term "witness" was designated by Pieter Wuille (the developer behind the Segregate Witness upgrade):

So it's just a fancy technical name for the "unlocking code" area for segwit outputs.

Resources

• BIP 141: Segregated Witness
• Pieter Wuille: Segregated witness and its impact on scalability
• What is the Witness and what data does it contain?
• What is the "witness reserved value" for BIP-141?