Bitcoin uses a scripting system for transactions. Forth-like, Script is simple, stack-based, and processed from left to right. It is purposefully not Turing-complete, with no loops or nesting if statements.
A transaction is valid if nothing in the combined script triggers failure and the top stack item is true (1).
FIXME: How is Script represented on the network, and how are constants expressed?
Words
This is a list of most Script words (commands/functions). A few (like OP_0-OP_16) are omitted. Some are currently disabled for security reasons.
True=1 and False=0.
Flow control
| Word
|
Input
|
Output
|
Description
|
| OP_NOP
|
Nothing
|
Nothing
|
Does nothing.
|
| OP_IF
|
<expression> if [statements] [else [statements]] endif
|
|
If the top stack value is 1, the statements are executed. The top stack value is removed.
|
| OP_NOTIF
|
<expression> if [statements] [else [statements]] endif
|
|
If the top stack value is 0, the statements are executed. The top stack value is removed.
|
| OP_ELSE
|
<expression> if [statements] [else [statements]] endif
|
|
If the preceding OP_IF was not executed, these statements are.
|
| OP_ENDIF
|
<expression> if [statements] [else [statements]] endif
|
|
Ends an if/else block.
|
| OP_VERIFY
|
True / false
|
Nothing / False
|
Marks transaction as invalid if top stack value is not true. True is removed, but false is not.
|
| OP_RETURN
|
Nothing
|
Nothing
|
Marks transaction as invalid.
|
Stack
| Word
|
Input
|
Output
|
Description
|
| OP_TOALTSTACK
|
x1
|
(alt)x1
|
Puts the input onto the top of the alt stack. Removes it from the main stack.
|
| OP_FROMALTSTACK
|
(alt)x1
|
x1
|
Puts the input onto the top of the main stack. Removes it from the alt stack.
|
| OP_IFDUP
|
x
|
x / x x
|
If the input is true or false, duplicate it.
|
| OP_DEPTH
|
Nothing
|
<Stack size>
|
Puts the number of stack items onto the stack.
|
| OP_DROP
|
x
|
Nothing
|
Removes the top stack item.
|
| OP_DUP
|
x
|
x x
|
Duplicates the top stack item.
|
| OP_NIP
|
x1 x2
|
x2
|
Removes the second-to-top stack item.
|
| OP_OVER
|
x1 x2
|
x1 x2 x1
|
Copies the second-to-top stack item to the top.
|
| OP_PICK
|
xn ... x2 x1 x0 <n>
|
xn ... x2 x1 x0 xn
|
The item n back in the stack is copied to the top.
|
| OP_ROLL
|
xn ... x2 x1 x0 <n>
|
... x2 x1 x0 xn
|
The item n back in the stack is moved to the top.
|
| OP_ROT
|
x1 x2 x3
|
x2 x3 x1
|
The top three items on the stack are rotated to the left.
|
| OP_SWAP
|
x1 x2
|
x2 x1
|
The top two items on the stack are swapped.
|
| OP_TUCK
|
x1 x2
|
x2 x1 x2
|
The item at the top of the stack is copied and inserted before the second-to-top item.
|
| OP_2DROP
|
x1 x2
|
Nothing
|
Removes the top two stack items.
|
| OP_2DUP
|
x1 x2
|
x1 x2 x1 x2
|
Duplicates the top two stack items.
|
| OP_3DUP
|
x1 x2 x3
|
x1 x2 x3 x1 x2 x3
|
Duplicates the top three stack items.
|
| OP_2OVER
|
x1 x2 x3 x4
|
x1 x2 x3 x4 x1 x2
|
Copies the pair of items two spaces back in the stack to the front.
|
| OP_2ROT
|
x1 x2 x3 x4 x5 x6
|
x3 x4 x5 x6 x1 x2
|
The fifth and sixth items back are moved to the top of the stack.
|
| OP_2SWAP
|
x1 x2 x3 x4
|
x3 x4 x1 x2
|
Swaps the top two pairs of items.
|
Splice
| Word
|
Input
|
Output
|
Description
|
| OP_CAT
|
x1 x2
|
out
|
Concatenates two strings. Currently disabled.
|
| OP_SUBSTR
|
in begin size
|
out
|
Returns a section of a string. Currently disabled.
|
| OP_LEFT
|
in size
|
out
|
Keeps only characters left of the specified point in a string. Currently disabled.
|
| OP_RIGHT
|
in size
|
out
|
Keeps only characters right of the specified point in a string. Currently disabled.
|
| OP_SIZE
|
in
|
in size
|
Returns the length of the input string.
|
Bitwise logic
| Word
|
Input
|
Output
|
Description
|
| OP_INVERT
|
in
|
out
|
Flips all of the bits in the input. Currently disabled.
|
| OP_AND
|
x1 x2
|
out
|
Boolean and between each bit in the inputs. Currently disabled.
|
| OP_OR
|
x1 x2
|
out
|
Boolean or between each bit in the inputs. Currently disabled.
|
| OP_XOR
|
x1 x2
|
out
|
Boolean exclusive or between each bit in the inputs. Currently disabled.
|
| OP_EQUAL
|
x1 x2
|
True / false
|
Returns 1 if the inputs are exactly equal, 0 otherwise.
|
| OP_EQUALVERIFY
|
x1 x2
|
True / false
|
Same as OP_EQUAL, but runs OP_VERIFY afterward.
|
Arithmetic
| Word
|
Input
|
Output
|
Description
|
| OP_1ADD
|
in
|
out
|
1 is added to the input.
|
| OP_1SUB
|
in
|
out
|
1 is subtracted from the input.
|
| OP_2MUL
|
in
|
out
|
The input is multiplied by 2. Currently disabled.
|
| OP_2DIV
|
in
|
out
|
The input is divided by 2. Currently disabled.
|
| OP_NEGATE
|
in
|
out
|
The sign of the input is flipped.
|
| OP_ABS
|
in
|
out
|
The input is made positive.
|
| OP_NOT
|
in
|
out
|
If the input is 0 or 1, it is flipped. Otherwise the output will be 0.
|
| OP_0NOTEQUAL
|
in
|
out
|
Returns 1 if the input is 0. 0 otherwise.
|
| OP_ADD
|
a b
|
out
|
a is added to b.
|
| OP_SUB
|
a b
|
out
|
b is subtracted from a.
|
| OP_MUL
|
a b
|
out
|
a is multiplied by b. Currently disabled.
|
| OP_DIV
|
a b
|
out
|
a is divided by b. Currently disabled.
|
| OP_MOD
|
a b
|
out
|
Returns the remainder after dividing a by b. Currently disabled.
|
| OP_LSHIFT
|
a b
|
out
|
Shifts a left b bits, preserving sign. Currently disabled.
|
| OP_RSHIFT
|
a b
|
out
|
Shifts a right b bits, preserving sign. Currently disabled.
|
| OP_BOOLAND
|
a b
|
out
|
If both a and b are not 0, the output is 1. Otherwise 0.
|
| OP_BOOLOR
|
a b
|
out
|
If a or b is not 0, the output is 1. Otherwise 0.
|
| OP_NUMEQUAL
|
a b
|
out
|
Returns 1 if the numbers are equal, 0 otherwise.
|
| OP_NUMEQUALVERIFY
|
a b
|
out
|
Same as OP_NUMEQUAL, but runs OP_VERIFY afterward.
|
| OP_NUMNOTEQUAL
|
a b
|
out
|
Returns 1 if the numbers are not equal, 0 otherwise.
|
| OP_LESSTHAN
|
a b
|
out
|
Returns 1 if a is less than b, 0 otherwise.
|
| OP_GREATERTHAN
|
a b
|
out
|
Returns 1 if a is greater than b, 0 otherwise.
|
| OP_LESSTHANOREQUAL
|
a b
|
out
|
Returns 1 if a is less than or equal to b, 0 otherwise.
|
| OP_GREATERTHANOREQUAL
|
a b
|
out
|
Returns 1 if a is greater than or equal to b, 0 otherwise.
|
| OP_MIN
|
a b
|
out
|
Returns the smaller of a and b.
|
| OP_MAX
|
a b
|
out
|
Returns the larger of a and b.
|
| OP_WITHIN
|
x min max
|
out
|
Returns 1 if x is within the specified range (left-inclusive), 0 otherwise.
|
Crypto
| Word
|
Input
|
Output
|
Description
|
| OP_RIPEMD160
|
in
|
hash
|
The input is hashed using RIPEMD-160.
|
| OP_SHA1
|
in
|
hash
|
The input is hashed using SHA-1.
|
| OP_SHA256
|
in
|
hash
|
The input is hashed using SHA-256.
|
| OP_HASH160
|
in
|
hash
|
The input is hashed twice: first with SHA-256 and then with RIPEMD-160.
|
| OP_HASH256
|
in
|
hash
|
The input is hashed two times with SHA-256.
|
| OP_CODESEPARATOR
|
Nothing
|
Nothing
|
All of the signature checking words will only match signatures to the data after the most recently-executed OP_CODESEPARATOR.
|
| OP_CHECKSIG
|
sig pubkey
|
True / false
|
The entire transaction's outputs, inputs, and script (from the most recently-executed OP_CODESEPARATOR to the end) are hashed. The signature used by OP_CHECKSIG must be a valid signature for this hash and public key. If it is, 1 is returned, 0 otherwise.
|
| OP_CHECKSIGVERIFY
|
sig pubkey
|
True / false
|
Same as OP_CHECKSIG, but OP_VERIFY is executed afterward.
|
| OP_CHECKMULTISIG
|
sig1 sig2 ... <number of signatures> pub1 pub2 <number of public keys>
|
True / False
|
For each signature and public key pair, OP_CHECKSIG is executed. If more public keys than signatures are listed, some key/sig pairs can fail. All signatures need to match a public key. If all signatures are valid, 1 is returned, 0 otherwise.
|
| OP_CHECKMULTISIGVERIFY
|
sig1 sig2 ... <number of signatures> pub1 pub2 ... <number of public keys>
|
True / False
|
Same as OP_CHECKMULTISIG, but OP_VERIFY is executed afterward.
|
Scripts
Standard Transaction to Bitcoin address
scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>
| Stack
|
Script
|
Description
|
| Empty.
|
<sig> <pubKey> OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
|
scriptSig and scriptPubKey are combined.
|
| <sig> <pubKey>
|
OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
|
Constants are added to the stack.
|
| <sig> <pubKey> <pubKey>
|
OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
|
Top stack item is duplicated.
|
| <sig <pubKey> <pubHashA>
|
<pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
|
Top stack item is hashed.
|
| <sig <pubKey> <pubHashA> <pubKeyHash>
|
OP_EQUALVERIFY OP_CHECKSIG
|
Constant added.
|
| <sig <pubKey>
|
OP_CHECKSIG
|
Equality is checked between the top two stack items.
|
| true
|
Empty.
|
Signature is checked for top two stack items.
|
Standard Generation / transaction to IP address
scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>
| Stack
|
Script
|
Description
|
| Empty.
|
<sig> <pubKey> OP_CHECKSIG
|
scriptSig and scriptPubKey are combined.
|
| <sig> <pubKey>
|
OP_CHECKSIG
|
Constants are added to the stack.
|
| true
|
Empty.
|
Signature is checked for top two stack items.
|
Transaction with a message
It's possible to add arbitrary data to any transaction by just adding some data along with OP_DROP (or ommitting OP_DROP and allowing the value to sit on the stack unused). Scripts are limited to 10,000 bytes and 201 instructions/values, and each individual instruction/value is limited to 520 bytes.
scriptPubKey: <message> OP_DROP <pubKey> OP_CHECKSIG
scriptSig: <sig>
| Stack
|
Script
|
Description
|
| Empty.
|
<sig> <pubKey> OP_CHECKSIG
|
scriptSig and scriptPubKey are combined.
|
| <sig> <pubKey> <message>
|
OP_DROP OP_CHECKSIG
|
Constants are added to the stack.
|
| <sig> <pubKey>
|
OP_CHECKSIG
|
Top item in the stack is removed.
|
| true
|
Empty.
|
Signature is checked for top two stack items.
|