You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/14_0_Expanding_Bitcoin_Scripts.md
+6-4Lines changed: 6 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
-
# Chapter 12: Expanding Bitcoin Scripts
1
+
# Chapter 14: Expanding Bitcoin Scripts
2
2
3
-
There's still a little more to Bitcoin Scripts. Conditionals give you full access to flow control, while a variety of other opcodes can expand your possibilities.
3
+
There's still a little more to Bitcoin Scripts. Conditionals give you
4
+
full access to flow control, while a variety of other opcodes can
5
+
expand your possibilities.
4
6
5
7
## Objectives for This Chapter
6
8
@@ -16,5 +18,5 @@ Supporting objectives include the ability to:
16
18
17
19
## Table of Contents
18
20
19
-
*[Section One: Using Script Conditionals](12_1_Using_Script_Conditionals.md)
20
-
*[Section Two: Using Other Script Commands](12_2_Using_Other_Script_Commands.md)
21
+
*[Section One: Using Script Conditionals](14_1_Using_Script_Conditionals.md)
22
+
*[Section Two: Using Other Script Commands](14_2_Using_Other_Script_Commands.md)
There's one final aspect of Bitcoin Scripting that's crucial to unlocking its true power: conditionals allow you create various paths of execution.
3
+
There's one final aspect of Bitcoin Scripting that's crucial to
4
+
unlocking its true power: conditionals allow you create various paths
5
+
of execution.
4
6
5
7
## Understand Verify
6
8
7
-
You've already seen one conditional in scripts: `OP_VERIFY` (0x69). It pops the top item on the stack and sees if it's true; if not _it ends execution of the script_.
8
-
9
-
Verify is usually incorporated into other opcodes. You've already seen `OP_EQUALVERIFY` (0xad), `OP_CHECKLOCKTIMEVERIFY` (0xb1), and `OP_CHECKSEQUENCEVERIFY` (0xb2). Each of these opcodes does its core action (equal, checklocktime, or checksequence) and then does a verify afterward. The other verify opcodes that you haven't seen are: `OP_NUMEQUALVERIFY` (0x9d), `OP_CHECKSIGVERIFY` (0xad), and `OP_CHECKMULTISIGVERIFY` (0xaf).
10
-
11
-
So how is `OP_VERIFY` a conditional? It's the most powerful sort of conditional. Using `OP_VERIFY`, _if_ a condition is true, the Script continues executing, _else_ the Script exits. This is how you check conditions that are absolutely required for a Script to succeed. For example, the P2PKH script (`OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG`) has two required conditions: (1) that the supplied public key match the public-key hash; and (2) that the supplied signature match that public key. An `OP_EQUALVERIFY` is used for the comparison of the hashed public key and the public-key hash because it's an absolutely required condition. You don't _want_ the script to continue on if that fails.
12
-
13
-
You may notice there's no `OP_VERIFY` at the end of this (or most any) script, despite the final condition being required as well. That's because Bitcoin effectively does an `OP_VERIFY` at the very end of each Script, to ensure that the final stack result is true. You don't _want_ to do an `OP_VERIFY` before the end of the script, because you need to leave something on the stack to be tested!
9
+
You've already seen one conditional in scripts: `OP_VERIFY` (0x69). It
10
+
pops the top item on the stack and sees if it's true; if not _it ends
11
+
execution of the script_.
12
+
13
+
Verify is usually incorporated into other opcodes. You've already seen
14
+
`OP_EQUALVERIFY` (0xad), `OP_CHECKLOCKTIMEVERIFY` (0xb1), and
15
+
`OP_CHECKSEQUENCEVERIFY` (0xb2). Each of these opcodes does its core
16
+
action (equal, checklocktime, or checksequence) and then does a verify
17
+
afterward. The other verify opcodes that you haven't seen are:
18
+
`OP_NUMEQUALVERIFY` (0x9d), `OP_CHECKSIGVERIFY` (0xad), and
19
+
`OP_CHECKMULTISIGVERIFY` (0xaf).
20
+
21
+
So how is `OP_VERIFY` a conditional? It's the most powerful sort of
22
+
conditional. Using `OP_VERIFY`, _if_ a condition is true, the Script
23
+
continues executing, _else_ the Script exits. This is how you check
24
+
conditions that are absolutely required for a Script to succeed. For
25
+
example, the P2PKH script (`OP_DUP OP_HASH160 <pubKeyHash>
26
+
OP_EQUALVERIFY OP_CHECKSIG`) has two required conditions: (1) that the
27
+
supplied public key match the public-key hash; and (2) that the
28
+
supplied signature match that public key. An `OP_EQUALVERIFY` is used
29
+
for the comparison of the hashed public key and the public-key hash
30
+
because it's an absolutely required condition. You don't _want_ the
31
+
script to continue on if that fails.
32
+
33
+
You may notice there's no `OP_VERIFY` at the end of this (or most any)
34
+
script, despite the final condition being required as well. That's
35
+
because Bitcoin effectively does an `OP_VERIFY` at the very end of
36
+
each Script, to ensure that the final stack result is true. You don't
37
+
_want_ to do an `OP_VERIFY` before the end of the script, because you
38
+
need to leave something on the stack to be tested!
14
39
15
40
## Understand If/Then
16
41
17
-
The other major conditional in Bitcoin Script is the classic `OP_IF` (0x63) / `OP_ELSE` (0x67) / `OP_ENDIF` (0x68). This is typical flow control: if `OP_IF` detects a true statement, it executes the block under it; otherwise, if there's an `OP_ELSE`, it executes that; and `OP_ENDIF` marks the end of the final block.
42
+
The other major conditional in Bitcoin Script is the classic `OP_IF`
43
+
(0x63) / `OP_ELSE` (0x67) / `OP_ENDIF` (0x68). This is typical flow
44
+
control: if `OP_IF` detects a true statement, it executes the block
45
+
under it; otherwise, if there's an `OP_ELSE`, it executes that; and
46
+
`OP_ENDIF` marks the end of the final block.
18
47
19
-
> :warning:**WARNING:** These conditionals are technically opcodes too, but as with small numbers, we're going to leave the `OP_` prefix off for brevity and clarity. Thus we'll write `IF`, `ELSE`, and `ENDIF` instead of `OP_IF`, `OP_ELSE`, and `OP_ENDIF`.
48
+
> ⚠️ **Conditionals are Written Shorthand.** These conditionals are
49
+
technically opcodes too, but as with small numbers, we're going to
50
+
leave the `OP_` prefix off for brevity and clarity from here on. Thus
51
+
we'll write `IF`, `ELSE`, and `ENDIF` instead of `OP_IF`, `OP_ELSE`,
52
+
and `OP_ENDIF`.
20
53
21
54
### Understand If/Then Ordering
22
55
23
-
There are two big catches to conditionals. They make it harder to read and assess scripts if you're not careful.
56
+
There are two big catches to conditionals that make it harder to read
57
+
and assess scripts if you're not careful.
24
58
25
-
First, the `IF` conditional checks the truth of what's _before it_ (which is to say what's in the stack), not what's after it.
59
+
First, the `IF` conditional checks the truth of what's _before it_
60
+
(which is to say what's in the stack), not what's after it.
26
61
27
-
Second, the `IF` conditional tends to be in the locking script and what it's checking tends to be in the unlocking script.
62
+
Second, the `IF` conditional tends to be in the locking script and
63
+
what it's checking tends to be in the unlocking script.
28
64
29
-
Of course, you might say, that's how Bitcoin Script works. Conditionals use reverse Polish notation and they adopt the standard unlocking/locking paradigm, just like _everything else_ in Bitcoin Scripting. That's all true, but it also goes contrary to the standard way we read IF/ELSE conditionals in other programming languages; thus, it's easy to unconsciously read Bitcoin conditionals wrong.
65
+
Of course, you might say, that's how Bitcoin Script
66
+
works. Conditionals use reverse Polish notation and they adopt the
67
+
standard unlocking/locking paradigm, just like _everything else_ in
68
+
Bitcoin Scripting. That's all true, but it also goes contrary to the
69
+
standard way we read IF/ELSE conditionals in other programming
70
+
languages; thus, it's easy to unconsciously read Bitcoin conditionals
71
+
wrong.
30
72
31
-
Consider the following code: `IF OP_DUP OP_HASH160 <pubKeyHashA> ELSE OP_DUP OP_HASH160 <pubKeyHashB> ENDIF OP_EQUALVERIFY OP_CHECKSIG `.
73
+
Consider the following code: `IF OP_DUP OP_HASH160 <pubKeyHashA> ELSE
Incorrectly looking at conditionals in prefix notation might lead you
77
+
to read this as:
32
78
33
-
Looking at conditionals in prefix notation might lead you to read this as:
34
79
```
35
80
IF (OP_DUP) THEN
36
81
@@ -50,7 +95,9 @@ ENDIF
50
95
```
51
96
So, you might think, if the `OP_DUP` is successful, then we get to do the first block, else the second. But that doesn't make any sense! Why wouldn't the `OP_DUP` succeed?!
52
97
53
-
And, indeed, it doesn't make any sense, because we accidentally read the statement using the wrong notation. The correct reading of this is:
98
+
And, indeed, it doesn't make any sense, because we accidentally read
99
+
the statement using thewrong notation. The correct reading of this is:
100
+
54
101
```
55
102
IF
56
103
@@ -69,13 +116,29 @@ ENDIF
69
116
OP_EQUALVERIFY
70
117
OP_CHECKSIG
71
118
```
72
-
The statement that will evaluate to `True` or `False` is placed on the stack _prior_ to running the `IF`, then the correct block of code is run based on that result.
73
119
74
-
This particular example code is intended as a poor man's 1-of-2 multisignature. The owner of `<privKeyA>` would put `<signatureA> <pubKeyA> True` in his unlocking script, while the owner of `<privKeyB>` would put `<signatureB> <pubKeyB> False` in her unlocking script. That trailing `True` or `False` is what's checked by the `IF`/`ELSE` statement. It tells the script which public-key hash to check against, then the `OP_EQUALVERIFY` and the `OP_CHECKSIG` at the end do the real work.
120
+
The statement that will evaluate to `True` or `False` is placed on the
121
+
stack _prior_ to running the `IF`, then the correct block of code is
122
+
run based on that result.
123
+
124
+
This particular example code is intended as a poor man's 1-of-2
125
+
multisignature. The owner of `<privKeyA>` would put `<signatureA>
126
+
<pubKeyA> True` in his unlocking script, while the owner of
127
+
`<privKeyB>` would put `<signatureB> <pubKeyB> False` in her unlocking
128
+
script. That trailing `True` or `False` is what's checked by the
129
+
`IF`/`ELSE` statement. It tells the script which public-key hash to
130
+
check against, then the `OP_EQUALVERIFY` and the `OP_CHECKSIG` at the
131
+
end do the real work.
75
132
76
133
### Run an If/Then Multisig
77
134
78
-
With a core understanding of Bitcoin conditionals in hand, we're now ready to run through a script. We're going to do so by creating a slight variant of our poor man's 1-of-2 multisignature where our users don't have to remember if they're `True` or `False`. Instead, if need be, the script checks both public-key hashes, just requiring one success:
135
+
With a core understanding of Bitcoin conditionals in hand, we're now
136
+
ready to run through a script. We're going to do so by creating a
137
+
slight variant of our poor man's 1-of-2 multisignature where our users
138
+
don't have to remember if they're `True` or `False`. Instead, if need
139
+
be, the script checks both public-key hashes, just requiring one
140
+
success:
141
+
79
142
```
80
143
OP_DUP OP_HASH160 <pubKeyHashA> OP_EQUAL
81
144
IF
@@ -93,7 +156,8 @@ Remember your reverse Polish notation! That `IF` statement is referring to the `
93
156
94
157
#### Run the True Branch
95
158
96
-
Here's how it actally runs if unlocked with `<signatureA> <pubKeyA>`:
159
+
Here's how it runs if unlocked with `<signatureA> <pubKeyA>`:
This probably isn't nearly as efficient as a true Bitcoin multisig, but it's a good example of how results pushed onto the stack by previous tests can be used to feed future conditionals. In this case, it's the failure of the first signature which tells the conditional that it should go check the second one.
259
+
260
+
This certainly isn't nearly as efficient as a true Bitcoin multisig,
261
+
but it's a good example of how results pushed onto the stack by
262
+
previous tests can be used to feed future conditionals. In this case,
263
+
it's the failure of the first signature which tells the conditional
264
+
that it should go check the second one.
196
265
197
266
## Understand Other Conditionals
198
267
@@ -204,10 +273,17 @@ These options are used much less often than the main `IF`/`ELSE`/`ENDIF` constru
204
273
205
274
## Summary: Using Script Conditionals
206
275
207
-
Conditionals in Bitcoin Script allow you to halt the script (using `OP_VERIFY`) or to choose different branches of execution (using `OP_IF`). However, reading `OP_IF` can be a bit tricky. Remember that it's the item pushed onto the stack _before_ the `OP_IF` is run that controls its execution; that item will typically be part of the unlocking script (or else a direct result of items in the unlocking script).
276
+
Conditionals in Bitcoin Script allow you to halt the script (using
277
+
`OP_VERIFY`) or to choose different branches of execution (using
278
+
`OP_IF`). However, reading `OP_IF` can be a bit tricky. Remember that
279
+
it's the item pushed onto the stack _before_ the `OP_IF` is run that
280
+
controls its execution; that item will typically be part of the
281
+
unlocking script (or else a direct result of items in the unlocking
282
+
script).
208
283
209
-
> :fire:***What is the power of conditionals?*** Script Conditionals are the final major building block in Bitcoin Script. They're what are required to turn simple, static Bitcoin Scripts into complex, dynamic Bitcoin Scripts that can evaluate differently based on different times, different circumstances, or different user inputs. In other words, they're the final basis of smart contracts.
284
+
> 🔥***What is the power of conditionals?*** Script Conditionals are the final major building block in Bitcoin Script. They're what are required to turn simple, static Bitcoin Scripts into complex, dynamic Bitcoin Scripts that can evaluate differently based on different times, different circumstances, or different user inputs. In other words, they're the final basis of smart contracts.
210
285
211
286
## What's Next?
212
287
213
-
Continue "Expanding Bitcoin Scripts" with [§12.2: Using Other Script Commands](12_2_Using_Other_Script_Commands.md).
288
+
Continue "Expanding Bitcoin Scripts" with [§14.2: Using Other Script
Copy file name to clipboardExpand all lines: docs/14_2_Using_Other_Script_Commands.md
+20-6Lines changed: 20 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,14 @@
1
-
# 12.2: Using Other Script Commands
1
+
# 14.2: Using Other Script Commands
2
2
3
-
You may already have in hand most of the Bitcoin Script opcodes that you'll be using in most scripts. However, Bitcoin Script offers a lot more options, which might be exactly what you need to create the financial instrument of your dreams.
3
+
You may already have in hand most of the Bitcoin Script opcodes that
4
+
you'll be using in most scripts. However, Bitcoin Script offers a lot
5
+
more options, which might be exactly what you need to create the
6
+
financial instrument of your dreams.
4
7
5
-
You should consult the [Bitcoin Script page](https://en.bitcoin.it/wiki/Script) for a more thorough look at all of these and many other commands. This section only highlights the most notable opcodes.
8
+
You should consult the [Bitcoin Script
9
+
page](https://en.bitcoin.it/wiki/Script) for a more thorough look at
10
+
all of these and many other commands. This section only highlights the
11
+
most notable opcodes.
6
12
7
13
## Understand Arithmetic Opcodes
8
14
@@ -46,7 +52,10 @@ Test three numbers:
46
52
47
53
## Understand Stack Opcodes
48
54
49
-
There are a shocking number of stack opcodes, but other than `OP_DROP`, `OP_DUP`, and sometimes `OP_SWAP` they're generally not necessary if you're careful about stack ordering. Nonetheless, here are a few of the more interesting ones:
55
+
There are a shocking number of stack opcodes, but other than
56
+
`OP_DROP`, `OP_DUP`, and sometimes `OP_SWAP` they're generally not
57
+
necessary if you're careful about stack ordering. Nonetheless, here
58
+
are a few of the more interesting ones:
50
59
51
60
* OP_DEPTH (0x74) — Pushes the size of the stack
52
61
* OP_DROP (0x75) — Pops the top stack item
@@ -78,8 +87,13 @@ Also see: `OP_CODESEPARATOR` (0xab), `OP_CHECKSIGVERIFY` (0xad), and `OP_CHECKMU
78
87
79
88
## Summary: Using Other Script Commands
80
89
81
-
Bitcoin Script includes a wide array of arithmetic, stack, and cryptographic opcodes. Most of these additional opcodes are probably not as common as the ones discussed in previous sections, but nonetheless they're available if they're just what you need to write your Script!
90
+
Bitcoin Script includes a wide array of arithmetic, stack, and
91
+
cryptographic opcodes. Most of these additional opcodes are probably
92
+
not as common as the ones discussed in previous sections, but
93
+
nonetheless they're available if they're just what you need to write
94
+
your Script!
82
95
83
96
## What's Next?
84
97
85
-
Advance through "Bitcoin Scripting" with [Chapter Thirteen: Designing Real Bitcoin Scripts](13_0_Designing_Real_Bitcoin_Scripts.md).
98
+
Advance through "Bitcoin Scripting" with [Chapter Fifteen: Designing
99
+
Real Bitcoin Scripts](15_0_Designing_Real_Bitcoin_Scripts.md).
*[14.1: Using Script Conditionals](14_1_Using_Script_Conditionals.md)
104
+
*[14.2: Using Other Script Commands](14_2_Using_Other_Script_Commands.md)
105
+
103
106
---
104
107
105
108
> _Learning Bitcoin v1.0 was created in part under the sponsorship of [Blockstream](https://blockstream.com/). Learning Bitcoin v2.0 was self-funded by [Blockchain Commons](https://www.blockchaincommons.com/). Learning Bitcoin v3.0 was funded by a grant from [HRF](https://hrf.org/)._
0 commit comments