[[c_authorization_authentication]] == Authorization and Authentication When you receive bitcoins, you have to decide who will have permission to spend them, ((("authorization")))((("authentication")))called _authorization_. You also have to decide how full nodes will distinguish the authorized spenders from everyone else, called _authentication_. Your authorization instructions and the spender proof of authentication will be checked by thousands of independent full nodes, which all need to come to the same conclusion that a spend was authorized and authenticated in order for the transaction containing it to be valid. The original description of Bitcoin used a public key for authorization. Alice paid Bob by putting his public key in the output of a transaction. Authentication came from Bob in the form of a signature that committed to a spending transaction, such as from Bob to Carol. The actual version of Bitcoin that was originally released provided a more flexible mechanism for both authorization and authentication. Improvements since then have only increased that flexibility. In this chapter, we'll explore those features and see how they're most commonly used. [[tx_script]] === Transaction Scripts and Script Language The((("transaction scripts", see="scripts")))((("Script programming language"))) original version of Bitcoin introduced a new programming language called _Script_, a Forth-like stack-based language. Both the script placed in an output and the legacy input script used in a spending transaction are written in this scripting language. Script is a very simple language. It requires minimal processing and cannot easily do many of the fancy things modern programming languages can do. When legacy transactions were the most commonly used type of transaction, the majority of transactions processed through the Bitcoin network had the form "Payment to Bob's Bitcoin address" and used a script called a pay to public key hash (P2PKH) script. However, Bitcoin transactions are not limited to the "Payment to Bob's Bitcoin address" script. In fact, scripts can be written to express a vast variety of complex conditions. In order to understand these more complex scripts, we must first understand the basics of transaction scripts and Script language. In this section, we will demonstrate the basic components of the Bitcoin transaction scripting language and show how it can be used to express conditions for spending and how those conditions can be satisfied. [TIP] ==== Bitcoin transaction validation((("transactions", "validating")))((("validating", "transactions"))) is not based on a static pattern but instead is achieved through the execution of a scripting language. This language allows for a nearly infinite variety of conditions to be expressed. ==== ==== Turing Incompleteness The ((("scripts", "Turing incompleteness")))((("Turing Complete")))Bitcoin transaction script language contains many operators, but is deliberately limited in one important way--there are no loops or complex flow control capabilities other than conditional flow control. This ensures that the language is not _Turing Complete_, meaning that scripts have limited complexity and predictable execution times. Script is not a general-purpose language. These limitations ensure that the language cannot be used to create an infinite loop or other form of "logic bomb" that could be embedded in a transaction in a way that causes a denial-of-service attack against the Bitcoin network. Remember, every transaction is validated by every full node on the Bitcoin network. A limited language prevents the transaction validation mechanism from being used as a vulnerability. ==== Stateless Verification The ((("scripts", "stateless verification")))((("stateless script verification")))((("verifying", "scripts")))Bitcoin transaction script language is stateless, in that there is no state prior to execution of the script or state saved after execution of the script. All the information needed to execute a script is contained within the script and the transaction executing the script. A script will predictably execute the same way on any system. If your system verified a script, you can be sure that every other system in the Bitcoin network will also verify the script, meaning that a valid transaction is valid for everyone and everyone knows this. This predictability of outcomes is an essential benefit of the Bitcoin system. [[tx_lock_unlock]] ==== Script Construction Bitcoin's ((("scripts", "input/output", "constructing", id="script-input-output-construct")))((("input scripts", "constructing", id="input-script-construct")))((("output scripts", "constructing", id="output-script-construct")))legacy transaction validation engine relies on two parts of scripts to validate transactions: an output script and an input script. An output script specifies the conditions that must be met to spend the output in the future, such as who is authorized to spend the output and how they will be authenticated. An input script is a script that satisfies the conditions placed in an output script and allows the output to be spent. Input scripts are part of every transaction input. Most of the time in legacy transactions they contain a digital signature produced by the user's wallet from his or her private key, but not all input scripts must contain signatures. Every Bitcoin((("transactions", "validating")))((("validating", "transactions"))) validating node will validate transactions by executing the output and input scripts. As we saw in <>, each input contains an outpoint that refers to a previous transaction output. The input also contains an input script. The validation software will copy the input script, retrieve the UTXO referenced by the input, and copy the output script from that UTXO. The input and output scripts are then executed together. The input is valid if the input script satisfies the output script's conditions (see <>). All the inputs are validated independently as part of the overall validation of the transaction. Note that the preceding steps involve making copies of all data. The original data in the previous output and current input is never changed. In particular, the previous output is invariable and unaffected by failed attempts to spend it. Only a valid transaction that correctly satisfies the conditions of the output script results in the output being considered as "spent." <> is an example of the output and input scripts for the most common type of legacy Bitcoin transaction (a payment to a public key hash), showing the combined script resulting from the concatenation of the scripts prior((("scripts", "input/output", "constructing", startref="script-input-output-construct")))((("input scripts", "constructing", startref="input-script-construct")))((("output scripts", "constructing", startref="output-script-construct"))) to validation. [[input_and_output_scripts_legacy]] .Combining input and output scripts to evaluate a transaction script. image::images/mbc3_0701.png["input_and_output_scripts"] ===== The script execution stack Bitcoin's ((("scripts", "stack", id="script-stack")))((("stack", id="stack")))scripting language is called a stack-based language because it uses a data structure called a _stack_. A stack is a very simple data structure that can be visualized as a stack of cards. A stack has two base operations: push and pop. Push adds an item on top of the stack. Pop removes the top item from the stack. The scripting language executes the script by processing each item from left to right. Numbers (data constants) are pushed onto the stack. Operators push or pop one or more parameters from the stack, act on them, and might push a result onto the stack. For example, +OP_ADD+ will pop two items from the stack, add them, and push the resulting sum onto the stack. Conditional operators evaluate a condition, producing a boolean result of +TRUE+ or +FALSE+. For example, +OP_EQUAL+ pops two items from the stack and pushes +TRUE+ (+TRUE+ is represented by the number 1) if they are equal or +FALSE+ (represented by 0) if they are not equal. Bitcoin transaction scripts usually contain a conditional operator so that they can produce the +TRUE+ result that signifies a valid ((("scripts", "stack", startref="script-stack")))((("stack", startref="stack")))transaction. ===== A simple script Now let's ((("scripts", "input/output", "examples of", id="script-input-output-example")))((("input scripts", "examples of", id="input-script-example")))((("output scripts", "examples of", id="output-script-example")))apply what we've learned about scripts and stacks to some simple examples. As we will see in <>, the script +2 3 OP_ADD 5 OP_EQUAL+ demonstrates the arithmetic addition operator +OP_ADD+, adding two numbers and putting the result on the stack, followed by the conditional operator +OP_EQUAL+, which checks that the resulting sum is equal to +5+. For brevity, the +OP_+ prefix may sometimes be omitted in examples in this book. For more details on the available script operators and functions, see https://oreil.ly/21vH9[Bitcoin Wiki's script page]. Although most legacy output scripts refer to a public key hash (essentially, a legacy Bitcoin address), thereby requiring proof of ownership to spend the funds, the script does not have to be that complex. Any combination of output and input scripts that results in a +TRUE+ value is valid. The simple arithmetic we used as an example of the scripting language is also a valid script. Use part of the arithmetic example script as the output script: ---- 3 OP_ADD 5 OP_EQUAL ---- which can be satisfied by a transaction containing an input with the input script: ---- 2 ---- The validation software combines the scripts: ---- 2 3 OP_ADD 5 OP_EQUAL ---- As we see in <>, when this script is executed, the result is +OP_TRUE+, making the transaction valid. Not only have we shown a valid transaction output script, but the resulting UTXO could be spent by anyone with the arithmetic skills to know that the number 2 satisfies the script. [[simplemath_script]] .Bitcoin's script validation doing simple math. image::images/mbc3_0702.png["TxScriptSimpleMathExample"] [TIP] ==== Transactions are valid if the top result on the stack is +TRUE+, which is any nonzero value. Transactions are invalid if the top value on the stack is +FALSE+ (the value zero or an empty stack), the script execution is halted explicitly by an operator (such as +VERIFY+, +OP_RETURN+), or the script was not semantically valid (such as containing an +OP_IF+ statement that was not terminated by an +OP_ENDIF+ opcode). For details, see https://oreil.ly/J2DXt[Bitcoin Wiki's script page]. ==== The following is a slightly more complex script, which calculates 2 + 7 – 3 + 1. Notice that when the script contains several operators in a row, the stack allows the results of one operator to be acted upon by the next operator: ---- 2 7 OP_ADD 3 OP_SUB 1 OP_ADD 7 OP_EQUAL ---- Try validating the preceding script yourself using pencil and paper. When the script execution ends, you should be left with a +TRUE+ value on the ((("scripts", "input/output", "examples of", startref="script-input-output-example")))((("input scripts", "examples of", startref="input-script-example")))((("output scripts", "examples of", startref="output-script-example")))stack. [[script_exec]] ===== Separate execution of output and input scripts In the ((("scripts", "input/output", "separate execution")))((("input scripts", "separate execution from output scripts")))((("output scripts", "separate execution from input scripts")))original Bitcoin client, output and input scripts were concatenated and executed in sequence. For security reasons, this was changed in 2010 because of a vulnerability known as the +1 OP_RETURN+ bug. In the current implementation, the scripts are executed separately with the stack transferred between the two executions. First, the input script is executed using the stack execution engine. If the input script is executed without errors and has no operations left over, the stack is copied and the output script is executed. If the result of executing the output script with the stack data copied from the input script is +TRUE+, the input script has succeeded in resolving the conditions imposed by the output script and, therefore, the input is a valid authorization to spend the UTXO. If any result other than +TRUE+ remains after execution of the combined script, the input is invalid because it has failed to satisfy the spending conditions placed on the output. //SOMEDAY:implications of not being able to use script in input script [[p2pkh]] ==== Pay to Public Key Hash A ((("P2PKH (pay to public key hash)")))((("addresses", "P2PKH (pay to public key hash)")))((("scripts", "P2PKH (pay to public key hash)")))pay to public key hash (P2PKH) script uses an output script that contains a hash that commits to a public key. P2PKH is best known as the basis for a legacy Bitcoin address. A P2PKH output can be spent by presenting a public key that matches the hash commitment and a digital signature created by the corresponding private key (see <>). Let's look at an example of a P2PKH output script: ---- OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG ---- [role="less_space pagebreak-before"] The +Key Hash+ is the data that would be encoded into a legacy base58check address. Most applications would show the _public key hash_ in a script using hexadecimal encoding and not the familiar Bitcoin address base58check format that begins with [.keep-together]#a "1."# The preceding output script can be satisfied with an input script of the form: ---- ---- The two scripts together would form the following combined validation script: ---- OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG ---- The result will be +TRUE+ if the input script has a valid signature from Bob's private key that corresponds to the public key hash set as an encumbrance. Figures pass:[#P2PubKHash1] and pass:[#P2PubKHash2] show (in two parts) a step-by-step execution of the combined script, which will prove this is a valid transaction. [[P2PubKHash1]] .Evaluating a script for a P2PKH transaction (part 1 of 2). image::images/mbc3_0703.png["Tx_Script_P2PubKeyHash_1"] [[P2PubKHash2]] .Evaluating a script for a P2PKH transaction (part 2 of 2). image::images/mbc3_0704.png["Tx_Script_P2PubKeyHash_2"] [[multisig]] === Scripted Multisignatures Multisignature scripts((("scripted multisignatures", id="script-multisignature")))((("multisignature scripts", id="multi-script"))) set a condition where _k_ public keys are recorded in the script and at least _t_ of those must provide signatures to spend the funds, called _t_-of-_k_. For example, a 2-of-3 multisignature is one where three public keys are listed as potential signers and at least two of those must be used to create signatures for a valid transaction to spend the funds. [TIP] ==== Some Bitcoin documentation, including earlier editions of this book, uses the term "m-of-n" for a traditional multisignature. However, it's hard to tell "m" and "n" apart when they're spoken, so we use the alternative _t_-of-_k_. Both phrases refer to the same type of signature scheme. ==== The general form of an output script setting a _t_-of-_k_ multisignature condition is: ---- t ... k OP_CHECKMULTISIG ---- where _k_ is the total number of listed public keys and _t_ is the threshold of required signatures to spend the output. An output script setting a 2-of-3 multisignature condition looks like this: ---- 2 3 OP_CHECKMULTISIG ---- The preceding output script can be satisfied with an input script containing [.keep-together]#signatures:# ---- ---- or any combination of two signatures from the private keys corresponding to the three listed public keys. The two scripts together would form the combined validation script: ---- 2 3 OP_CHECKMULTISIG ---- When executed, this combined script will evaluate to +TRUE+ if the input script has two valid signatures from private keys that correspond to two of the three public keys set as an encumbrance. At this time, Bitcoin Core's transaction relay policy limits multisignature output scripts to, at most, three listed public keys, meaning you can do anything from a 1-of-1 to a 3-of-3 multisignature or any combination within that range. You may want to check the +IsStandard()+ function to see what is currently accepted by the network. Note that the limit of three keys applies only to standard (also known as "bare") multisignature scripts, not to scripts wrapped in another structure like P2SH, P2WSH, or P2TR. P2SH multisignature scripts are limited by both policy and consensus to 15 keys, allowing for up to a 15-of-15 multisignature. We will learn about P2SH in <>. All other scripts are consensus limited to 20 keys per +OP_CHECKMULTISIG+ or +OP_CHECKMULTISIGVERIFY+ opcode, although one script may include multiple of those opcodes. [role="less_space pagebreak-before"] [[multisig_bug]] ==== An Oddity in CHECKMULTISIG Execution There ((("OP_CHECKMULTISIG execution", id="op-checkmultisig")))is an oddity in ++OP_CHECKMULTISIG++'s execution that requires a slight workaround. When +OP_CHECKMULTISIG+ executes, it should consume _t_ + _k_ + 2 items on the stack as parameters. However, due to the oddity, +OP_CHECKMULTISIG+ will pop an extra value or one value more than expected. Let's look at this in greater detail using the previous validation example: ---- 2 3 OP_CHECKMULTISIG ---- First, +OP_CHECKMULTISIG+ pops the top item, which is _k_ (in this example "3"). Then it pops _k_ items, which are the public keys that can sign; in this example, public keys A, B, and C. Then, it pops one item, which is _t_, the quorum (how many signatures are needed). Here _t_ = 2. At this point, +OP_CHECKMULTISIG+ should pop the final _t_ items, which are the signatures, and see if they are valid. However, unfortunately, an oddity in the implementation causes +OP_CHECKMULTISIG+ to pop one more item (_t_ + 1 total) than it should. The extra item is called((("dummy stack element"))) the _dummy stack element_, and it is disregarded when checking the signatures so it has no direct effect on +OP_CHECKMULTISIG+ itself. However, the dummy element must be present because, if it isn't present when +OP_CHECKMULTISIG+ attempts to pop on an empty stack, it will cause a stack error and script failure (marking the transaction as invalid). Because the dummy element is disregarded, it can be anything. It became the custom early on to use +OP_0+, which later became a relay policy rule and eventually a consensus rule (with the enforcement of BIP147). Because popping the dummy element is part of the consensus rules, it must now be replicated forever. Therefore a script should look like this: ---- OP_0 2 3 OP_CHECKMULTISIG ---- Thus the input script actually used in multisig is not: ---- ---- but instead it is: ---- OP_0 ---- Some people believe this oddity was a bug in the original code for Bitcoin, but a plausible alternative explanation exists. Verifying _t_-of-_k_ signatures can require many more than _t_ or _k_ signature checking operations. Let's consider a simple example of 1-in-5, with the following combined script: ---- 1 5 OP_CHECKMULTISIG ---- The signature is checked first against +key0+, then +key1+, and then the other keys before it is finally compared to its corresponding +key4+. That means five signature checking operations need to be performed even though there's only one signature. One way to eliminate this redundancy would have been to provide +OP_CHECKMULTISIG+ a map indicating which provided signature corresponds to which public key, allowing the +OP_CHECKMULTISIG+ operation to only perform exactly _t_ signature-checking operations. It's possible that Bitcoin's original developer added the extra element (which we now call the dummy stack element) in the original version of Bitcoin so they could add the feature for allowing a map to be passed in a later soft fork. However, that feature was never implemented, and the BIP147 update to the consensus rules in 2017 makes it impossible to add that feature in the future. Only Bitcoin's original developer could tell us whether the dummy stack element was the result of a bug or a plan for a future upgrade. In this book, we simply call it an oddity. From now on, if you see a multisig script, you should expect to see an extra +OP_0+ in the beginning, whose only purpose is as a workaround to an oddity in the ((("scripted multisignatures", startref="script-multisignature")))((("multisignature scripts", startref="multi-script")))((("OP_CHECKMULTISIG execution", startref="op-checkmultisig")))consensus rules. [[p2sh]] === Pay to Script Hash Pay to script hash (P2SH) was((("scripts", "P2SH (pay to script hash)", id="script-p2sh")))((("addresses", "P2SH (pay to script hash)", id="address-p2sh-ch7")))((("P2SH (pay to script hash)", id="p2sh-ch7"))) introduced in 2012 as a powerful new type of operation that greatly simplifies the use of complex scripts. To explain the need for P2SH, let's look at a practical example. Mohammed is an electronics importer based in Dubai. Mohammed's company uses Bitcoin's multisignature feature extensively for its corporate accounts. Multisignature scripts are one of the most common uses of Bitcoin's advanced scripting capabilities and are a very powerful feature. Mohammed's company uses a multisignature script for all customer payments. Any payments made by customers are locked in such a way that they require at least two signatures to release. Mohammed, his three partners, and their attorney can each provide one signature. A multisignature scheme like that offers corporate governance controls and protects against theft, embezzlement, or loss. The resulting script is quite long and looks like this: ---- 2 5 OP_CHECKMULTISIG ---- Although multisignature scripts are a powerful feature, they are cumbersome to use. Given the preceding script, Mohammed would have to communicate this script to every customer prior to payment. Each customer would have to use special Bitcoin wallet software with the ability to create custom transaction scripts. Furthermore, the resulting transaction would be about five times larger than a simple payment transaction, because this script contains very long public keys. The burden of that extra data would be borne by the customer in the form of extra transaction fees. Finally, a large transaction script like this would be carried in the UTXO set in every full node, until it was spent. All of these issues make using complex output scripts difficult in practice. P2SH was developed to resolve these practical difficulties and to make the use of complex scripts as easy as a payment to a single-key Bitcoin address. With P2SH payments, the complex script is replaced with a commitment, the digest of a cryptographic hash. When a transaction attempting to spend the UTXO is presented later, it must contain the script that matches the commitment in addition to the data that satisfies the script. In simple terms, P2SH means "pay to a script matching this hash, a script that will be presented later when this output is spent." In P2SH transactions, the script that is replaced by a hash is ((("redeem scripts")))referred to as the _redeem script_ because it is presented to the system at redemption time rather than as an output script. <> shows the script without P2SH and <> shows the same script encoded with P2SH. ++++
Complex script without P2SH

Output script

2 PubKey1 PubKey2 PubKey3 PubKey4 PubKey5 5 OP_CHECKMULTISIG

Input script

Sig1 Sig2
Complex script as P2SH

Redeem script

2 PubKey1 PubKey2 PubKey3 PubKey4 PubKey5 5 OP_CHECKMULTISIG

Output script

OP_HASH160 <20-byte hash of redeem script> OP_EQUAL

Input script

Sig1 Sig2 <redeem script>
++++ As you can see from the tables, with P2SH, the complex script that details the conditions for spending the output (redeem script) is not presented in the output script. Instead, only a hash of it is in the output script, and the redeem script itself is presented later as part of the input script when the output is spent. This shifts the burden in fees and complexity from the spender to the receiver of the transaction. Let's look at Mohammed's company, the complex multisignature script, and the resulting P2SH scripts. First, the multisignature script that Mohammed's company uses for all incoming payments from customers: ---- 2 5 OP_CHECKMULTISIG ---- This entire script can instead be represented by a 20-byte cryptographic hash by first applying the SHA256 hashing algorithm and then applying the RIPEMD-160 algorithm on the result. For example, starting with the hash of Mohammed's redeem script: ---- 54c557e07dde5bb6cb791c7a540e0a4796f5e97e ---- A P2SH transaction locks the output to this hash instead of the longer redeem script, using a special output script template: ---- OP_HASH160 54c557e07dde5bb6cb791c7a540e0a4796f5e97e OP_EQUAL ---- which, as you can see, is much shorter. Instead of "pay to this 5-key multisignature script," the P2SH equivalent transaction is "pay to a script with this hash." A customer making a payment to Mohammed's company need only include this much shorter output script in his payment. When Mohammed and his partners want to spend this UTXO, they must present the original redeem script (the one whose hash locked the UTXO) and the signatures necessary to unlock it, like this: ---- <2 PK1 PK2 PK3 PK4 PK5 5 OP_CHECKMULTISIG> ---- The two scripts are combined in two stages. First, the redeem script is checked against the output script to make sure the hash matches: ---- <2 PK1 PK2 PK3 PK4 PK5 5 OP_CHECKMULTISIG> OP_HASH160