Script
Locking mechanism for outputs
Script is a mini programming language used as a locking mechanism for outputs in bitcoin transactions.
- A locking script (ScriptPubKey) is placed on every transaction output.
- An unlocking script (ScriptSig or Witness) must be provided to unlock an output (i.e. when used as an input to a transaction).
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:
- Data – Such as public keys and signatures.
OP_CODES– Simple functions that operate on the data.
Here's a simple diagram of a typical P2PKH script used in Bitcoin:
For simplicity the diagrams on this page are not showing any OP_PUSHBYTES_XX opcodes, but these are required when pushing data on to the stack. I've also removed the OP_ prefixes from the opcodes.
Here's a list of all the possible Opcodes you can use in bitcoin scripts.
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 gets pushed on to the stack.
Opcodes can then pop elements off the stack, do something with them, then optionally push new elements back on to the stack.
Validity
Here's an example of the full execution of a valid P2PKH script:
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 greater.
A script is invalid if:
- The final stack is empty
- The only element left on the stack is
OP_0 - There is more than one element left on the stack at the end of execution.
- The script exits prematurely (e.g.
OP_RETURN).
Location
Where is Script used in Bitcoin?
A locking script (ScriptPubKey) is placed on every output you create in a transaction:
An unlocking script (ScriptSig or Witness) must be provided for every input you want to spend in a transaction:
Every node will then combine and run these two scripts for each input in every 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.
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.
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.
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".
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
- P2PK (Pay To Public Key)
- P2PKH (Pay To Public Key Hash)
- P2MS (Pay To Multisig)
- P2SH (Pay To Script Hash)
- OP_RETURN
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
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:
- 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.
- 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
- The maximum size of a script is 10,000 bytes. A combined ScriptPubKey + ScriptSig cannot be greater than 10,000 bytes.
- The maximum number of
OP_CODESis 201. This limit does not include operations that push data on to the stack. - The maximum size of a single element is 520 bytes. You cannot push any data on to the stack that exceeds 520 bytes. This limit is most relevant when constructing a Redeem Script for a P2SH, as a Redeem Script is a data push of a script.
- The maximum number of stack items is 1,000. A complete script can contain more than 1,000 elements, but you cannot construct a script that will push over 1,000 items on to the stack at any one time.
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
- The ScriptSig can be a maximum of 1,650 bytes. So if you need to use more than 1,650 bytes of data and/or
OP_CODESto unlock an output, nodes will not relay your transaction. - The ScriptPubKey has no limit (other than being restricted by the block size limit). So it's perfectly fine to create a ridiculously large ScriptPubKey if you want to, but remember that it's going to be unspendable if it exceeds any of the validity limits above.
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.
- Every output is given a "locking script".
- You must then provide an "unlocking script" in the transaction that wants to spend that output.
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.