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/11_2_Running_a_Bitcoin_Script.md
+85-25Lines changed: 85 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,26 +1,51 @@
1
-
# 9.2: Running a Bitcoin Script
1
+
# 11.2: Running a Bitcoin Script
2
2
3
-
Bitcoin Scripts may not initially seem that intuitive, but their execution is quite simple, using reverse Polish notation and a stack.
3
+
Bitcoin Scripts may not initially seem that intuitive, but their
4
+
execution is quite simple, using reverse Polish notation and a stack.
4
5
5
6
## Understand the Scripting Language
6
7
7
-
A Bitcoin Script has three parts: it has a line of input; it has a stack for storage; and it has specific commands for execution.
8
+
A Bitcoin Script has three parts: it has a line of input; it has a
9
+
stack for storage; and it has specific commands ("opcodes") for
10
+
execution.
8
11
9
12
### Understand the Ordering
10
13
11
-
Bitcoin Scripts are run from left to right. That sounds easy enough, because it's the same way you read. However, it might actually be the most non-intuitive element of Bitcoin Script, because it means that functions don't look like you'd expect. Instead, _the operands go before the operator._
12
-
13
-
For example, if you were adding together "1" and "2", your Bitcoin Script for that would be `1 2 OP_ADD`, _not_ "1 + 2". Since we know that OP_ADD operator takes two inputs, we know that the two inputs before it are its operands.
14
-
15
-
> :warning:**WARNING:** Technically, everything in Bitcoin Script is an opcode, thus it would be most appropriate to record the above example as `OP_1 OP_2 OP_ADD`. In our examples, we don't worry about how the constants will be evaluated, as that's a topic of translation, as is explained in [§10.2: Building the Structure of P2SH](10_2_Building_the_Structure_of_P2SH.md). Some writers prefer to also leave the "OP" prefix off all operators, but we have opted not to.
14
+
Bitcoin Scripts are run from left to right. That sounds easy enough,
15
+
because it's the same way you read. However, it might actually be the
16
+
most non-intuitive element of Bitcoin Script, because it means that
17
+
functions don't look like you'd expect. Instead, _the operands go
18
+
before the operator._
19
+
20
+
For example, if you were adding together "1" and "2", your Bitcoin
21
+
Script for that would be `1 2 OP_ADD`, _not_ "1 + 2". Since we know
22
+
that OP_ADD operator takes two inputs, we know that the two inputs
23
+
before it are its operands.
24
+
25
+
> ⚠️ **It's Opcodes All the Way Down.** Technically, everything in
26
+
Bitcoin Script is an opcode, thus it would be most appropriate to
27
+
record the above example as `OP_1 OP_2 OP_ADD`. In our examples, we
28
+
don't worry about how the constants will be evaluated, as that's a
29
+
topic of translation, as is explained in [§12.2: Building the
30
+
Structure of P2SH](12_2_Building_the_Structure_of_P2SH.md). Some
31
+
writers prefer to also leave the "OP" prefix off all operators, but we
32
+
have opted not to.
16
33
17
34
### Understand the Stack
18
35
19
-
It's actually not quite correct to say that an operator applies to the inputs before it. Really, an operator applies to the top inputs in Bitcoin's stack.
36
+
It's actually not quite correct to say that an operator applies to the
37
+
inputs before it. Really, an operator applies to the top inputs in
38
+
Bitcoin's stack.
39
+
40
+
> 📖 ***What is a stack?*** A stack is a LIFO (last-in-first-out) data
41
+
structure. It has two access functions: push and pop. Push places a
42
+
new object on top of the stack, pushing down everything below it. Pop
43
+
removes the top object from the stack.
20
44
21
-
> :book:***What is a stack?*** A stack is a LIFO (last-in-first-out) data structure. It has two access functions: push and pop. Push places a new object on top of the stack, pushing down everything below it. Pop removes the top object from the stack.
45
+
Whenever Bitcoin Script encounters a constant, it pushes it on the
46
+
stack. So the above example of `1 2 OP_ADD` would actually look like
47
+
this as it was processed:
22
48
23
-
Whenever Bitcoin Script encounters a constant, it pushes it on the stack. So the above example of `1 2 OP_ADD` would actually look like this as it was processed:
24
49
```
25
50
Script: 1 2 OP_ADD
26
51
Stack: [ ]
@@ -31,15 +56,20 @@ Stack: [ 1 ]
31
56
Script: OP_ADD
32
57
Stack: [ 1 2 ]
33
58
```
34
-
_Note that in this and in following examples the top of the stack is to the right and the bottom is to the left._
59
+
60
+
_Note that in this and in following examples the top of the stack is
61
+
to the right and the bottom is to the left._
35
62
36
63
### Understand the Opcodes
37
64
38
-
When a Bitcoin Script encounters an operator, it evaluates it. Each operator pops zero or more elements off the stack as inputs, usually one or two. It then processes them in a specific way before pushing zero or more elements back on the stack, usually one or two.
65
+
When a Bitcoin Script encounters an operator ("opcode"), it evaluates
66
+
it. Each operator pops zero or more elements off the stack as inputs,
67
+
usually one or two. It then processes them in a specific way before
68
+
pushing zero or more elements back on the stack, usually one or two.
39
69
40
-
> :book:***What is an Opcode?*** Opcode stands for "operation code". It's typically associated with machine-language code, and is a simple function (or "operator").
70
+
OP_ADD pops two items off the stack (here: 2 then 1), adds then
71
+
together, and pushes the result back on the stack (here: 3).
41
72
42
-
OP_ADD pops two items off the stack (here: 2 then 1), adds then together, and pushes the result back on the stack (here: 3).
43
73
```
44
74
Script:
45
75
Running: 1 2 OP_ADD
@@ -48,7 +78,11 @@ Stack: [ 3 ]
48
78
49
79
## Build Up Complexity
50
80
51
-
More complex scripts are created by running more commands in order. They need to be carefully evaluated from left to right, so that you can understand the state of the stack as each new command is run. It will constantly change, as a result of previous operators:
81
+
More complex scripts are created by running more commands in
82
+
order. They need to be carefully evaluated from left to right, so that
83
+
you can understand the state of the stack as each new command is
84
+
run. It will constantly change, as a result of previous operators:
85
+
52
86
```
53
87
Script: 3 2 OP_ADD 4 OP_SUB
54
88
Stack: [ ]
@@ -73,13 +107,21 @@ Stack: [ 1 ]
73
107
74
108
## Understand the Usage of Bitcoin Script
75
109
76
-
That's pretty much Bitcoin Scripting ... other than a few intricacies for how this scripting language interacts with Bitcoin itself.
110
+
That's pretty much Bitcoin Scripting ... other than a few intricacies
111
+
for how this scripting language interacts with Bitcoin itself.
77
112
78
113
### Understand scriptSig and scriptPubKey
79
114
80
-
As we've seen, every input for a Bitcoin transaction contains a `scriptSig` that is used to unlock the `scriptPubKey` for the associated UTXO. They are _effectively_ concatenated together, meaning that `scriptSig` and `scriptPubKey` are run together, in that order.
115
+
As we've seen, every input for a Bitcoin transaction contains a
116
+
`scriptSig` that is used to unlock the `scriptPubKey` for the
117
+
associated UTXO. They are _effectively_ concatenated together, meaning
118
+
that `scriptSig` and `scriptPubKey` are run together, in that order.
81
119
82
-
So, presume that a UTXO were locked with a `scriptPubKey` that read `OP_ADD 99 OP_EQUAL`, requiring as input two numbers that add up to ninety-nine, and presume that the `scriptSig` of `1 98` were run to unlock it. The two scripts would effectively be run in order as `1 98 OP_ADD 99 OP_EQUAL`.
120
+
So, presume that a UTXO were locked with a `scriptPubKey` that read
121
+
`OP_ADD 99 OP_EQUAL`, requiring as input two numbers that add up to
122
+
ninety-nine, and presume that the `scriptSig` of `1 98` were run to
123
+
unlock it. The two scripts would effectively be run in order as `1 98
124
+
OP_ADD 99 OP_EQUAL`.
83
125
84
126
Evaluate the result:
85
127
```
@@ -103,23 +145,41 @@ Script:
103
145
Running: 99 99 OP_EQUAL
104
146
Stack: [ True ]
105
147
```
106
-
This abstraction isn't quite accurate: for security reasons, the `scriptSig` is run, then the contents of the stack are transferred for the `scriptPubKey` to run, but it's accurate enough for understanding how the key of `scriptSig` fits into the lock of `scriptPubKey`.
107
148
108
-
> :warning:**WARNING** The above is a non-standard transaction type. It would not actually be accepted by nodes running Bitcoin Core with the standard settings. [§10.1: Building a Bitcoin Script with P2SH](10_1_Understanding_the_Foundation_of_P2SH.md) discusses how you actually _could_ run a Bitcoin Script like this, using the power of P2SH.
149
+
This abstraction isn't quite accurate: for security reasons, the
150
+
`scriptSig` is run, then the contents of the stack are transferred for
151
+
the `scriptPubKey` to run, but it's accurate enough for understanding
152
+
how the key of `scriptSig` fits into the lock of `scriptPubKey`.
153
+
154
+
> ⚠️ **Standards Required!** The above is a non-standard transaction
155
+
type. It would not actually be accepted by nodes running Bitcoin Core
156
+
with the standard settings. [§12.1: Building a Bitcoin Script with
157
+
P2SH](12_1_Understanding_the_Foundation_of_P2SH.md) discusses how you
158
+
actually _could_ run a Bitcoin Script like this, using the power of
159
+
P2SH.
109
160
110
161
### Get the Results
111
162
112
-
Bitcoin will verify a transaction and allow the UTXO to be respent if two criteria are met when running `scriptSig` and `scriptPubKey`:
163
+
Bitcoin will verify a transaction and allow the UTXO to be respent if
164
+
two criteria are met when running `scriptSig` and `scriptPubKey`:
113
165
114
166
1. The execution did not get marked as invalid at any point, for example with a failed OP_VERIFY or the usage of a disabled opcode.
115
167
2. The top item in the stack at the end of execution is true (non-zero).
116
168
117
-
In the above example, the transaction would succeed because the stack has a `True` at its top. But, it would be just as permissible to end with a full stack and the number `42` on top.
169
+
In the above example, the transaction would succeed because the stack
170
+
has a `True` at its top. But, it would be just as permissible to end
171
+
with a full stack and the number `42` on top.
118
172
119
173
## Summary: Running a Bitcoin Script
120
174
121
-
To process a Bitcoin Script, a `scriptSig` is run followed by the `scriptPubKey` that it's unlocking. These commands are run in order, from left to right, with constants being pushed onto a stack and operators popping elements off that stack, then pushing results back onto it. If the Script doesn't halt in the middle and if the item on top of the stack at the end is non-zero, then the UTXO is unlocked.
175
+
To process a Bitcoin Script, a `scriptSig` is run followed by the
176
+
`scriptPubKey` that it's unlocking. These commands are run in order,
177
+
from left to right, with constants being pushed onto a stack and
178
+
operators popping elements off that stack, then pushing results back
179
+
onto it. If the Script doesn't halt in the middle and if the item on
180
+
top of the stack at the end is non-zero, then the UTXO is unlocked.
122
181
123
182
## What's Next?
124
183
125
-
Continue "Introducing Bitcoin Scripts" with [§9.3: Testing a Bitcoin Script](09_3_Testing_a_Bitcoin_Script.md).
184
+
Continue "Introducing Bitcoin Scripts" with [§11.3: Testing a Bitcoin
0 commit comments