Script

A mini programming language

A diagram showing the basics of the Script language in Bitcoin.

Script is a mini programming language used as a locking mechanism for outputs in bitcoin transactions.

If a full script (unlocking + locking) is valid, the output is "unlocked" and can be spent.

Script Language

What is Script?

Script is a very basic programming language. It consists of two things:

  1. Opcodes – Simple functions that operate on data.
  2. Data – Such as public keys and signatures.

Here's a simple diagram of a typical P2PKH script used in Bitcoin:

A diagram showing an example Script in Bitcoin (P2PKH).
tool-667198b986ff7
Tool Icon

Script

Decode and encode a script.

 
Decrease Text Box Size Increase Text Box Size
0 bytes
0 characters
0 secs

1. Opcodes

Here's a quick list of all the opcodes available in the Script language (along with the corresponding hexadecimal byte used to represent each one).

Push Data (97)
00 OP_0
01 OP_PUSHBYTES_1
02 OP_PUSHBYTES_2
03 OP_PUSHBYTES_3
04 OP_PUSHBYTES_4
05 OP_PUSHBYTES_5
06 OP_PUSHBYTES_6
07 OP_PUSHBYTES_7
08 OP_PUSHBYTES_8
09 OP_PUSHBYTES_9
0a OP_PUSHBYTES_10
0b OP_PUSHBYTES_11
0c OP_PUSHBYTES_12
0d OP_PUSHBYTES_13
0e OP_PUSHBYTES_14
0f OP_PUSHBYTES_15
10 OP_PUSHBYTES_16
11 OP_PUSHBYTES_17
12 OP_PUSHBYTES_18
13 OP_PUSHBYTES_19
14 OP_PUSHBYTES_20
15 OP_PUSHBYTES_21
16 OP_PUSHBYTES_22
17 OP_PUSHBYTES_23
18 OP_PUSHBYTES_24
19 OP_PUSHBYTES_25
1a OP_PUSHBYTES_26
1b OP_PUSHBYTES_27
1c OP_PUSHBYTES_28
1d OP_PUSHBYTES_29
1e OP_PUSHBYTES_30
1f OP_PUSHBYTES_31
20 OP_PUSHBYTES_32
21 OP_PUSHBYTES_33
22 OP_PUSHBYTES_34
23 OP_PUSHBYTES_35
24 OP_PUSHBYTES_36
25 OP_PUSHBYTES_37
26 OP_PUSHBYTES_38
27 OP_PUSHBYTES_39
28 OP_PUSHBYTES_40
29 OP_PUSHBYTES_41
2a OP_PUSHBYTES_42
2b OP_PUSHBYTES_43
2c OP_PUSHBYTES_44
2d OP_PUSHBYTES_45
2e OP_PUSHBYTES_46
2f OP_PUSHBYTES_47
30 OP_PUSHBYTES_48
31 OP_PUSHBYTES_49
32 OP_PUSHBYTES_50
33 OP_PUSHBYTES_51
34 OP_PUSHBYTES_52
35 OP_PUSHBYTES_53
36 OP_PUSHBYTES_54
37 OP_PUSHBYTES_55
38 OP_PUSHBYTES_56
39 OP_PUSHBYTES_57
3a OP_PUSHBYTES_58
3b OP_PUSHBYTES_59
3c OP_PUSHBYTES_60
3d OP_PUSHBYTES_61
3e OP_PUSHBYTES_62
3f OP_PUSHBYTES_63
40 OP_PUSHBYTES_64
41 OP_PUSHBYTES_65
42 OP_PUSHBYTES_66
43 OP_PUSHBYTES_67
44 OP_PUSHBYTES_68
45 OP_PUSHBYTES_69
46 OP_PUSHBYTES_70
47 OP_PUSHBYTES_71
48 OP_PUSHBYTES_72
49 OP_PUSHBYTES_73
4a OP_PUSHBYTES_74
4b OP_PUSHBYTES_75
4c OP_PUSHDATA1
4d OP_PUSHDATA2
4e OP_PUSHDATA4
4f OP_1NEGATE
50 OP_RESERVED
51 OP_1
52 OP_2
53 OP_3
54 OP_4
55 OP_5
56 OP_6
57 OP_7
58 OP_8
59 OP_9
5a OP_10
5b OP_11
5c OP_12
5d OP_13
5e OP_14
5f OP_15
60 OP_16
Control Flow (10)
61 OP_NOP
62 OP_VER
63 OP_IF
64 OP_NOTIF
65 OP_VERIF
66 OP_VERNOTIF
67 OP_ELSE
68 OP_ENDIF
69 OP_VERIFY
6a OP_RETURN
Stack Operators (19)
6b OP_TOALTSTACK
6c OP_FROMALTSTACK
6d OP_2DROP
6e OP_2DUP
6f OP_3DUP
70 OP_2OVER
71 OP_2ROT
72 OP_2SWAP
73 OP_IFDUP
74 OP_DEPTH
75 OP_DROP
76 OP_DUP
77 OP_NIP
78 OP_OVER
79 OP_PICK
7a OP_ROLL
7b OP_ROT
7c OP_SWAP
7d OP_TUCK
Strings (5)
7e OP_CAT
7f OP_SUBSTR
80 OP_LEFT
81 OP_RIGHT
82 OP_SIZE
Bitwise Logic (8)
83 OP_INVERT
84 OP_AND
85 OP_OR
86 OP_XOR
87 OP_EQUAL
88 OP_EQUALVERIFY
89 OP_RESERVED1
8a OP_RESERVED2
Numeric (27)
8b OP_1ADD
8c OP_1SUB
8d OP_2MUL
8e OP_2DIV
8f OP_NEGATE
90 OP_ABS
91 OP_NOT
92 OP_0NOTEQUAL
93 OP_ADD
94 OP_SUB
95 OP_MUL
96 OP_DIV
97 OP_MOD
98 OP_LSHIFT
99 OP_RSHIFT
9a OP_BOOLAND
9b OP_BOOLOR
9c OP_NUMEQUAL
9d OP_NUMEQUALVERIFY
9e OP_NUMNOTEQUAL
9f OP_LESSTHAN
a0 OP_GREATERTHAN
a1 OP_LESSTHANOREQUAL
a2 OP_GREATERTHANOREQUAL
a3 OP_MIN
a4 OP_MAX
a5 OP_WITHIN
Cryptography (10)
a6 OP_RIPEMD160
a7 OP_SHA1
a8 OP_SHA256
a9 OP_HASH160
aa OP_HASH256
ab OP_CODESEPARATOR
ac OP_CHECKSIG
ad OP_CHECKSIGVERIFY
ae OP_CHECKMULTISIG
af OP_CHECKMULTISIGVERIFY
Other (80)
b0 OP_NOP1
b1 OP_CHECKLOCKTIMEVERIFY
b2 OP_CHECKSEQUENCEVERIFY
b3 OP_NOP4
b4 OP_NOP5
b5 OP_NOP6
b6 OP_NOP7
b7 OP_NOP8
b8 OP_NOP9
b9 OP_NOP10
ba OP_CHECKSIGADD
bb OP_RETURN_187
bc OP_RETURN_188
bd OP_RETURN_189
be OP_RETURN_190
bf OP_RETURN_191
c0 OP_RETURN_192
c1 OP_RETURN_193
c2 OP_RETURN_194
c3 OP_RETURN_195
c4 OP_RETURN_196
c5 OP_RETURN_197
c6 OP_RETURN_198
c7 OP_RETURN_199
c8 OP_RETURN_200
c9 OP_RETURN_201
ca OP_RETURN_202
cb OP_RETURN_203
cc OP_RETURN_204
cd OP_RETURN_205
ce OP_RETURN_206
cf OP_RETURN_207
d0 OP_RETURN_208
d1 OP_RETURN_209
d2 OP_RETURN_210
d3 OP_RETURN_211
d4 OP_RETURN_212
d5 OP_RETURN_213
d6 OP_RETURN_214
d7 OP_RETURN_215
d8 OP_RETURN_216
d9 OP_RETURN_217
da OP_RETURN_218
db OP_RETURN_219
dc OP_RETURN_220
dd OP_RETURN_221
de OP_RETURN_222
df OP_RETURN_223
e0 OP_RETURN_224
e1 OP_RETURN_225
e2 OP_RETURN_226
e3 OP_RETURN_227
e4 OP_RETURN_228
e5 OP_RETURN_229
e6 OP_RETURN_230
e7 OP_RETURN_231
e8 OP_RETURN_232
e9 OP_RETURN_233
ea OP_RETURN_234
eb OP_RETURN_235
ec OP_RETURN_236
ed OP_RETURN_237
ee OP_RETURN_238
ef OP_RETURN_239
f0 OP_RETURN_240
f1 OP_RETURN_241
f2 OP_RETURN_242
f3 OP_RETURN_243
f4 OP_RETURN_244
f5 OP_RETURN_245
f6 OP_RETURN_246
f7 OP_RETURN_247
f8 OP_RETURN_248
f9 OP_RETURN_249
fa OP_RETURN_250
fb OP_RETURN_251
fc OP_RETURN_252
fd OP_RETURN_253
fe OP_RETURN_254
ff OP_INVALIDOPCODE

2. Data

The data elements inside a Script (e.g. public keys, signatures) have to be manually pushed on to the stack using an opcode.

There are a few specific opcodes you can choose from to do this, and the one you use depends on how many bytes you want to push on to the stack.

OP_0 to OP_16: (single byte representing numbers 0 to 16)

The bytes 0x00, and 0x51 to 0x60 (representing the numbers 0 to 16) have been given their own opcodes from OP_0 to OP_16.

These bytes are automatically pushed on to the stack, so you don't need to use any explicit push operation before them. For example:

OP_1
51

The bytes used to represent the opcodes OP_1 to OP_16 are not the hexadecimal equivalent of these numbers (i.e. 0x01 to 0x10). Instead, the opcodes for these numbers have been assigned bytes in the range 0x51 to 0x60. It's a bit awkward, I know, but that's how they've been assigned.

OP_PUSHBYTES_X: 1 to 75 bytes

The OP_PUSHBYTES_X opcodes (0x01 to 0x4b) are used to push up to 75 bytes on to the stack.

Just replace the X with the number of upcoming bytes you want pushed on to the stack.

For example, here I'm pushing 20 bytes on to the stack:

OP_PUSHBYTES_20 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
14aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

This is the most commonly used opcode for pushing data on to the stack.

OP_PUSHDATA1: 76 to 255 bytes

The OP_PUSHDATA1 opcode (0x4c) is followed by 1 byte indicating the number of bytes you want pushed on to the stack, followed by the actual bytes.

This is used when you want to push more data on the stack than you can with OP_PUSHBYTES_X.

For example, here I'm pushing 76 bytes on to the stack:

OP_PUSHDATA1 4c aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
4c4caaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

OP_PUSHDATA2: 256 to 65535 bytes

The OP_PUSHDATA2 opcode (0x4d) works in the same was as OP_PUSHDATA1, except it's followed by 2 bytes to indicate the number of upcoming bytes to be pushed on to the stack.

This is used when you want to push more data on the stack than you can with OP_PUSHDATA1.

For example, here I'm pushing 256 bytes on to the stack:

OP_PUSHDATA2 0001 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
4d0001aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

The 2 bytes after OP_PUSHDATA2 are in little-endian byte order. For example, 256 converted to hexadecimal is 0100, and in little-endian that's 0001.

OP_PUSHDATA4: 65536 to 4294967295 bytes

The OP_PUSHDATA4 opcode (0x4e) works in the same was as OP_PUSHDATA2, but is followed by 4 bytes to indicate the number of upcoming bytes to be pushed on to the stack.

This is used when you want to push more data on the stack than you can with OP_PUSHDATA2.

For example, here I'm pushing 65536 bytes on to the stack (the actual data push is not shown as it would be pretty long):

OP_PUSHDATA4 00000100 [65536 bytes]
4e00000100[65536 bytes]

The 4 bytes after OP_PUSHDATA4 are in little-endian byte order. For example, 65536 converted to hexadecimal is 00010000, and in little-endian that's 00000100.

OP_PUSHDATA4 is pretty useless, because data pushes in Bitcoin scripts are limited to 520 bytes.

For simplicity, the diagrams on this page do not show the OP_PUSHBYTES_X opcodes. However, these push operations are required to push data on to the stack.

Minimal push operations

You should always use the smallest push operation available to push data on to the stack.

For example, there are multiple ways to push the number 8 on to the stack:

OP_8
OP_PUSHBYTES_1 08
OP_PUSHDATA1 01 08
OP_PUSHDATA2 0100 08
OP_PUSHDATA4 01000000 08

Similarly, there are multiple ways to push two bytes on to the stack:

OP_PUSHBYTES_2 aaaa
OP_PUSHDATA1 02 aaaa
OP_PUSHDATA2 0200 aaaa
OP_PUSHDATA4 02000000 aaaa

The first operation in both examples uses the fewest bytes to push data on to the stack, and you should always use the most efficient option you can.

This rule was introduced in BIP 62, and is enforced by the CheckMinimalPush() function in script.cpp. This is a standardness rule, so whilst using a less efficient operation does not make the Script technically invalid, nodes will not accept any transactions in to their mempool that use anything other than minimal push operations.

Execution

How is Script executed?

A complete script is run from left-to-right. As it runs, it makes use of a data structure called a stack.

Data is pushed on to the stack.

Animation showing data being pushed on to the stack.

Opcodes pop elements off the stack, do something with them, then optionally push new elements back on to the stack.

Animation showing an OP_CODE performing an operation on some data on the stack. The OP_DUP opcode for example duplicates the top element on the stack.

Validity

A complete script is determined to be valid or invalid after it has finished executing.

A script is valid if the only element left on the stack is a OP_1 (or any non-zero value).

A script is invalid if:

  1. The final stack is empty
  2. The only element left on the stack is OP_0
  3. There is more than one element left on the stack at the end of execution.
  4. The script exits prematurely (e.g. OP_RETURN).

Here's an example of the execution of a complete P2PKH script:

Animation showing a full P2PKH Script successfully validating because a single OP_1 is left on the stack after the script has finished executing.

Location

Where is Script used in Bitcoin?

A locking script (ScriptPubKey) is placed on every output you create in a transaction:

A diagram showing the location of a locking script (ScriptPubKey) on a transaction output.

An unlocking script (ScriptSig or Witness) must be provided for every input you want to spend in a transaction:

A diagram showing the location of an unlocking script (ScripSig) on a transaction input.

Every node will then combine and run these two scripts for each input in each transaction they receive to make sure they validate.

If the unlocking scripts on inputs do not successfully unlock the locking scripts on the outputs being spent, then the transaction is considered invalid and will not be relayed (or mined in to a block).

The unlocking script goes first.

Even though the unlocking script is provided after the initial locking script (in terms of how transactions work), we actually put the unlocking script first when we execute the full script.

A diagram showing the unlocking script coming before the locking script during script execution.

Usage

Why do we use Script in Bitcoin?

Why do we use a mini programming language for locking up bitcoins? Why not just use a simple public key and signature comparison and do away with all of these opcodes and stacks?

Well, because by using Script you can create different types of locks by using different combinations of OP_CODES.

For example, here are some cool locking scripts you can create:

1. Math Puzzle

To spend this output, you need to provide two numbers that add up to 8.

A diagram showing a mathematical puzzle being used as a locking script.

This may not be the most secure locking script in the world, as anyone can figure it out and unlock it.

2. Hash Puzzle

Here you just need something that hashes to the same result as what's inside the locking script.

A diagram showing a hash puzzle being used as a locking script.

3. Hash Collision Puzzle

This is a cool one. You can unlock it by providing two different strings of data that produce the same hash result.

In other words, it acts as an incentive to find a "hash collision".

A diagram showing a hash collision puzzle being used as a locking script.

This particular locking script can be found on this output. However, the script has been wrapped in a P2SH locking script, so you can't actually see the original locking script (until someone unlocks them).

All of the above locking scripts are non-standard. Whilst these scripts are valid (and can be mined on to the blockchain), typical Bitcoin Core nodes will not relay them from their memory pools, which makes it difficult for them to get mined in the first place.

Standard Scripts

What are the most common Script patterns in Bitcoin?

Despite being able to create a variety of different locking scripts with various combinations of OPCODES, most nodes will only relay a handful of "standard scripts":

Legacy

A diagram showing a complete list of the legacy standard scripts used in bitcoin.

These were the standard scripts available in bitcoin between 2009 and 2016 (before the Segwit upgrade).

They are unlocked via the ScriptSig field.

Although these are not used as much today (in favour of the newer Segwit scripts below), they're still perfectly valid and you can use them for locking up your coins if you want to.

Segwit

A diagram showing a complete list of the segwit standard scripts used in bitcoin.

These standard scripts were introduced after the Segwit upgrade in 2016 (and then also the Taproot upgrade in 2021). They were basically introduced to replace the legacy P2PKH and P2SH locking scripts above.

They are unlocked via the Witness field.

These locking scripts do not actually use the fully-fledged Script language.

Instead, each locking script has its own specific pattern, and they are executed in a set way internally when being unlocked. So they have actually done away with the Script language to a degree (except for when you wrap a fully-fledged script inside a P2WSH).

So when I said "why not just use a simple public key and signature comparison and do away with all of these opcodes and stacks?", well, that's what these scripts have done.

Why don't nodes relay non-standard scripts?

I know, it's a shame.

However, not every combination of OP_CODE has been tested. So if nodes relayed every non-standard script they received, it would introduce the risk of an attack from someone spamming the network with scripts that take a long time to verify. This could "clog up" nodes and bring the network to a halt.

On the other hand, the standard scripts have been thoroughly tested and can be validated quickly. So the whole non-relaying of non-standard transactions is just a safety measure.

Non-standard scripts are valid, they are just not relayed. Even though a non-standard transaction does not get relayed between memory pools, it can still be mined in to a block. So if you want a transaction with a non-standard script to be added to the blockchain, you either need to send it directly to a miner who will mine it for you, or mine it on to the blockchain yourself.

Limits

What is the maximum size of a script?

Scripts in bitcoin have certain limits on their size. There are two types of limits:

  1. Validity Limits. Any transaction that contains a script that exceeds these limits will be considered invalid. This means it will be rejected by nodes and cannot be mined in to the blockchain.
  2. Standardness Limits. A transaction can break these limits and still be mined in to the blockchain, but nodes will consider them non-standard and will refuse to relay them between memory pools.

1. Validity Limits

A diagram showing the limits for a valid script.

These limits can be found in script.h.

These limits only apply during script execution. So you could place a ScriptPubKey on an output that exceeds these limits and it would get mined. But when you come to try and spend it as an input (i.e. when the script is being executed), the spending transaction will be considered invalid. In other words, the output would be unspendable.

2. Standardness Limits

A diagram showing the limits for a standard script.

So whilst it's valid for a transaction to exceed these limits, it's going to be difficult to get it mined in to the blockchain unless you can mine it yourself or get a miner to add it to the blockchain for you.

These limits can be found in policy.h.

Summary

Script is just a mini programming language used in Bitcoin to provide the locking mechanism for outputs.

When a node receives the spending transaction, it will combine both of these scripts together and run them. If a OP_1 (and nothing else) is left on the top of the stack after the script has finished executing, then the script is valid and the output can be spent.

The newer segwit locking scripts have moved away from using traditional Script slightly, but the Script language is still used for legacy locking scripts, and can also continue to be used within the newer P2WSH locking script.

The script is actually a predicate. It's just an equation that evaluates to true or false. Predicate is a long and unfamiliar word so I called it script.
Satoshi Nakamoto, bitcointalk.org

Resources