BSV.VM (BSV v2.1.0) View Source

Pure Elixir Bitcoin Script VM.

Bitcoin Script is a Forth-like scripting language used to define the locking mechanism for a transaction output.

Transaction outputs each contain a "locking script" which lock a number of satoshis. Transaction inputs contain an "unlocking script" which unlock the satoshis contained in a previous output. Both the unlocking script and previous locking script are concatenated in the following order:

unlocking_script <> locking_script

The entire script is evaluated and when if the end result contains a truthy value on the top of the stack, it is a valid script. Otherwise it is invalid. This is known as a predicate - an equation that evaluates to true or false.

Link to this section Summary

Types

ctx()

Transaction context.

t()

VM struct

Functions

eval(vm, chunk)

Evaluates the given script and returns a VM state.

eval!(vm, script)

As eval/2 but returns the VM struct or raises an error.

init(opts)

Initiates a new VM struct

op_0notequal(vm)

If the top stack element is not false it is made true. Otherwise it is made false.

op_1add(vm)

Adds 1 onto the top stack element.

op_1sub(vm)

Subtracks 1 from the top stack element.

op_2div(vm)

Divides the top stack element by 2. DISABLED

op_2drop(vm)

Removes the top two items from the stack.

op_2dup(vm)

Duplicates the top two items on the stack.

op_2mul(vm)

Multiplies the top stack element by 2. DISABLED

op_2over(vm)

Copies two items two spaces back to the top of the stack.

op_2rot(vm)

Moves the 5th and 6th items to top of stack.

op_2swap(vm)

Swaps the top two pairs of items.

op_3dup(vm)

Duplicates the top three items on the stack.

op_abs(vm)

Makes positive the numeric value of the top stack element.

op_add(vm)

The top two stack elements are added and replaced on the stack with the result.

op_and(vm)

Calculates the bitwise AND of the top two elements of the stack. Both elements must be the same length.

op_bin2num(vm)

Converts the binary value into a numeric value.

op_booland(vm)

Checks the top two stack elements are both truthy and replaces them with the boolean result.

op_boolor(vm)

Checks if either of the top two stack elements are truthy and replaces them with the boolean result.

op_cat(vm)

Concatenates the top two stack items into one binary.

op_checkmultisig(vm)

The top stack element is the number of public keys. The next n elements are the public keys. The next element is the number of signatures and the next n elements are the signatures.

op_checkmultisigverify(vm)

Runs op_checkmultisig/1 and op_verify/1.

op_checksig(vm)

Verifies the signature in the second top stack element against the current transaction sighash using the pubkey on top of the stack. Replaces them with the boolean result.

op_checksigverify(vm)

Runs op_checksig/1 and op_verify/1.

op_depth(vm)

Counts the stack lenth and puts the result on the top of the stack.

op_div(vm)

The top stack element is divided from the second, and both are replaced on the stack with the result.

op_drop(vm)

Removes the top item from the stack.

op_dup(vm)

Duplicates the top item on the stack.

op_else(vm)

If the preceding OP_IF or OP_NOTIF was not executed, the the following statements are executed. If the preceding OP_IF or OP_NOTIF was executed, the following statements are not.

op_endif(vm)

Ends the current IF/ELSE block. All blocks must end or the script is invalid.

op_equal(vm)

Compares the equality of the top two stack items and replaces them with the boolean result.

op_equalverify(vm)

Runs op_equal/1 and op_verify/1.

op_fromaltstack(vm)

Removes the top of the alt stack and puts it into the stack.

op_greaterthan(vm)

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is greater than the first.

op_greaterthanorequal(vm)

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is greater than or equal to the first.

op_hash160(vm)

The top element on the stack is hashed using SHA256 then RIPEMD160.

op_hash256(vm)

The top element on the stack is hashed using SHA256 then SHA256 again.

op_if(vm)

Removes the top of the stack. If the top value is truthy, statements between OP_IF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed.

op_ifdup(vm)

Duplicates the top stack item if it is truthy.

op_invert(vm)

Flips all bits on the top element of the stack.

op_lessthan(vm)

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is less than the first.

op_lessthanorequal(vm)

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is less than or equal to the first.

op_lshift(vm)

The second from top element numeric value is bitshifted to the left by the number of bits in the top element numeric value. Both elements are replaced on the stack with the result.

op_max(vm)

Compares numeric value of the top two stack elements, and both are replaced with the greater value.

op_min(vm)

Compares numeric value of the top two stack elements, and both are replaced with the smaller value.

op_mod(vm)

The top stack element is divided from the second, and both are replaced on the stack with the remainder.

op_mul(vm)

The top two stack elements are multiplied and replaced on the stack with the result.

op_negate(vm)

Negates the numeric value of the top stack element.

op_nip(vm)

Removes the second to top item from the stack.

op_nop(vm)

No op. Does nothing and returns the vm.

op_not(vm)

If the top stack element is false it is made true. Otherwise it is made false.

op_notif(vm)

Removes the top of the stack. If the top value is false, statements between OP_NOTIF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed.

op_num2bin(vm)

Converts the second from top stack item into a binary of the length given in the top stack item.

op_numequal(vm)

Compares the equality of the numeric value of the top two stack items and replaces them with the boolean result.

op_numequalverify(vm)

Runs op_numequal/1 and op_verify/1.

op_numnotequal(vm)

Checks the numeric value of the top two stack items are not equal and replaces them with the boolean result.

op_or(vm)

Calculates the bitwise OR of the top two elements of the stack. Both elements must be the same length.

op_over(vm)

Copies the second to top stack item to the top.

op_pick(vm)

Removes the top stack item and uses it as an index length, then copies the nth item on the stack to the top.

op_pushdata(vm, data)

Generic pushdata. Pushes any given binary or integer to the stack.

op_reserved(vm)

Unused. Makes transaction invalid.

op_return(vm, chunks)

Returns the vm and no further statements are evaluated.

op_ripemd160(vm)

The top element on the stack is hashed using RIPEMD160.

op_roll(vm)

Removes the top stack item and uses it as an index length, then moves the nth item on the stack to the top.

op_rot(vm)

Rotates the top three items on the stack, effictively moving the 3rd item to the top of the stack.

op_rshift(vm)

The second from top element numeric value is bitshifted to the right by the number of bits in the top element numeric value. Both elements are replaced on the stack with the result.

op_sha1(vm)

The top element on the stack is hashed using SHA1.

op_sha256(vm)

The top element on the stack is hashed using SHA256.

op_size(vm)

Pushes the byte length of the top element of the stack, without popping it.

op_split(vm)

Splits the second from top stack item by the index given in the top stack item.

op_sub(vm)

The top stack element is subtracted from the second, and both are replaced on the stack with the result.

op_swap(vm)

Rotates the top two items on the stack, effectively moving the 2nd item to the top of the stack.

op_toaltstack(vm)

Removes the top of the stack and puts it into the alt stack.

op_tuck(vm)

Copies the top item on the stack and inserts it before the second to top item.

op_ver(vm)

Puts the version of the protocol under which this transaction will be evaluated onto the stack. DISABLED

op_verif(vm)

Removes the top of the stack. If the top value is equal to the version of the protocol under which the transaction is evaluated, statements between OP_IF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed. DISABLED

op_verify(vm)

Mmarks the script as invalid unless the stack is truthy. Removes the top of the stack.

op_vernotif(vm)

Removes the top of the stack. If the top value is not equal to the version of the protocol under which the transaction is evaluated, statements between OP_IF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed. DISABLED

op_within(vm)

The top (max) and second (min) numeric values on the stack define a range and the third element is checked to see if it is within the range. All three elements are replaced on the stack with the boolean result.

op_xor(vm)

Calculates the bitwise XOR of the top two elements of the stack. Both elements must be the same length.

valid?(vm)

Determines if the Script VM is truthy or falsey.

Link to this section Types

ctx()

Specs

ctx() :: {BSV.Tx.t(), non_neg_integer(), BSV.TxOut.t()}

Transaction context.

A tuple containing a BSV.Tx.t/0, BSV.TxIn.vin/0 and BSV.TxOut.t/0. If not present, then op_checksig/1 and op_checkmultisig/1 will raise errors and the script will fail.

t()

Specs

t() :: %BSV.VM{
  alt_stack: list(),
  ctx: ctx() | nil,
  error: nil | String.t(),
  if_stack: list(),
  op_return: list(),
  opts: map(),
  stack: list()
}

VM struct

Link to this section Functions

eval(vm, chunk)

Specs

eval(t(), BSV.Script.t() | list()) :: {:ok, t()} | {:error, t()}

Evaluates the given script and returns a VM state.

eval!(vm, script)

Specs

eval!(t(), BSV.Script.t() | list()) :: t()

As eval/2 but returns the VM struct or raises an error.

init(opts)

Specs

init(keyword()) :: t()

Initiates a new VM struct

op_0notequal(vm)

Specs

op_0notequal(t()) :: t()

If the top stack element is not false it is made true. Otherwise it is made false.

op_1add(vm)

Specs

op_1add(t()) :: t()

Adds 1 onto the top stack element.

op_1sub(vm)

Specs

op_1sub(t()) :: t()

Subtracks 1 from the top stack element.

op_2div(vm)

Specs

op_2div(t()) :: t()

Divides the top stack element by 2. DISABLED

op_2drop(vm)

Specs

op_2drop(t()) :: t()

Removes the top two items from the stack.

op_2dup(vm)

Specs

op_2dup(t()) :: t()

Duplicates the top two items on the stack.

op_2mul(vm)

Specs

op_2mul(t()) :: t()

Multiplies the top stack element by 2. DISABLED

op_2over(vm)

Specs

op_2over(t()) :: t()

Copies two items two spaces back to the top of the stack.

op_2rot(vm)

Specs

op_2rot(t()) :: t()

Moves the 5th and 6th items to top of stack.

op_2swap(vm)

Specs

op_2swap(t()) :: t()

Swaps the top two pairs of items.

op_3dup(vm)

Specs

op_3dup(t()) :: t()

Duplicates the top three items on the stack.

op_abs(vm)

Specs

op_abs(t()) :: t()

Makes positive the numeric value of the top stack element.

op_add(vm)

Specs

op_add(t()) :: t()

The top two stack elements are added and replaced on the stack with the result.

op_and(vm)

Specs

op_and(t()) :: t()

Calculates the bitwise AND of the top two elements of the stack. Both elements must be the same length.

op_bin2num(vm)

Specs

op_bin2num(t()) :: t()

Converts the binary value into a numeric value.

op_booland(vm)

Specs

op_booland(t()) :: t()

Checks the top two stack elements are both truthy and replaces them with the boolean result.

op_boolor(vm)

Specs

op_boolor(t()) :: t()

Checks if either of the top two stack elements are truthy and replaces them with the boolean result.

op_cat(vm)

Specs

op_cat(t()) :: t()

Concatenates the top two stack items into one binary.

op_checkmultisig(vm)

Specs

op_checkmultisig(t()) :: t()

The top stack element is the number of public keys. The next n elements are the public keys. The next element is the number of signatures and the next n elements are the signatures.

Each signature is itereated over and each public key is checked if it verifies the signature against the current transactions sighash. Once a public key is checked it is not checked again, so signatures must be pushed onto the stack in the same order as the corresponding public keys.

op_checkmultisigverify(vm)

Specs

op_checkmultisigverify(t()) :: t()

Runs op_checkmultisig/1 and op_verify/1.

op_checksig(vm)

Specs

op_checksig(t()) :: t()

Verifies the signature in the second top stack element against the current transaction sighash using the pubkey on top of the stack. Replaces them with the boolean result.

op_checksigverify(vm)

Specs

op_checksigverify(t()) :: t()

Runs op_checksig/1 and op_verify/1.

op_depth(vm)

Specs

op_depth(t()) :: t()

Counts the stack lenth and puts the result on the top of the stack.

op_div(vm)

Specs

op_div(t()) :: t()

The top stack element is divided from the second, and both are replaced on the stack with the result.

op_drop(vm)

Specs

op_drop(t()) :: t()

Removes the top item from the stack.

op_dup(vm)

Specs

op_dup(t()) :: t()

Duplicates the top item on the stack.

op_else(vm)

Specs

op_else(t()) :: t()

If the preceding OP_IF or OP_NOTIF was not executed, the the following statements are executed. If the preceding OP_IF or OP_NOTIF was executed, the following statements are not.

op_endif(vm)

Specs

op_endif(t()) :: t()

Ends the current IF/ELSE block. All blocks must end or the script is invalid.

op_equal(vm)

Specs

op_equal(t()) :: t()

Compares the equality of the top two stack items and replaces them with the boolean result.

op_equalverify(vm)

Specs

op_equalverify(t()) :: t()

Runs op_equal/1 and op_verify/1.

op_fromaltstack(vm)

Specs

op_fromaltstack(t()) :: t()

Removes the top of the alt stack and puts it into the stack.

op_greaterthan(vm)

Specs

op_greaterthan(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is greater than the first.

op_greaterthanorequal(vm)

Specs

op_greaterthanorequal(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is greater than or equal to the first.

op_hash160(vm)

Specs

op_hash160(t()) :: t()

The top element on the stack is hashed using SHA256 then RIPEMD160.

op_hash256(vm)

Specs

op_hash256(t()) :: t()

The top element on the stack is hashed using SHA256 then SHA256 again.

op_if(vm)

Specs

op_if(t()) :: t()

Removes the top of the stack. If the top value is truthy, statements between OP_IF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed.

op_ifdup(vm)

Specs

op_ifdup(t()) :: t()

Duplicates the top stack item if it is truthy.

op_invert(vm)

Specs

op_invert(t()) :: t()

Flips all bits on the top element of the stack.

op_lessthan(vm)

Specs

op_lessthan(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is less than the first.

op_lessthanorequal(vm)

Specs

op_lessthanorequal(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced on the stack with the result. Is true if the second element is less than or equal to the first.

op_lshift(vm)

Specs

op_lshift(t()) :: t()

The second from top element numeric value is bitshifted to the left by the number of bits in the top element numeric value. Both elements are replaced on the stack with the result.

op_max(vm)

Specs

op_max(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced with the greater value.

op_min(vm)

Specs

op_min(t()) :: t()

Compares numeric value of the top two stack elements, and both are replaced with the smaller value.

op_mod(vm)

Specs

op_mod(t()) :: t()

The top stack element is divided from the second, and both are replaced on the stack with the remainder.

op_mul(vm)

Specs

op_mul(t()) :: t()

The top two stack elements are multiplied and replaced on the stack with the result.

op_negate(vm)

Specs

op_negate(t()) :: t()

Negates the numeric value of the top stack element.

op_nip(vm)

Specs

op_nip(t()) :: t()

Removes the second to top item from the stack.

op_nop(vm)

Specs

op_nop(t()) :: t()

No op. Does nothing and returns the vm.

op_not(vm)

Specs

op_not(t()) :: t()

If the top stack element is false it is made true. Otherwise it is made false.

op_notif(vm)

Specs

op_notif(t()) :: t()

Removes the top of the stack. If the top value is false, statements between OP_NOTIF and OP_ELSE are executed. Otherwise statements between OP_ELSE and OP_ENDIF are executed.

op_num2bin(vm)

Specs

op_num2bin(t()) :: t()

Converts the second from top stack item into a binary of the length given in the top stack item.

op_numequal(vm)

Specs

op_numequal(t()) :: t()

Compares the equality of the numeric value of the top two stack items and replaces them with the boolean result.

op_numequalverify(vm)

Specs

op_numequalverify(t()) :: t()

Runs op_numequal/1 and op_verify/1.

op_numnotequal(vm)

Specs

op_numnotequal(t()) :: t()

Checks the numeric value of the top two stack items are not equal and replaces them with the boolean result.

op_or(vm)

Specs

op_or(t()) :: t()

Calculates the bitwise OR of the top two elements of the stack. Both elements must be the same length.

op_over(vm)

Specs

op_over(t()) :: t()

Copies the second to top stack item to the top.

op_pick(vm)

Specs

op_pick(t()) :: t()

Removes the top stack item and uses it as an index length, then copies the nth item on the stack to the top.

op_pushdata(vm, data)

Specs

op_pushdata(t(), binary() | number()) :: t()

Generic pushdata. Pushes any given binary or integer to the stack.

op_reserved(vm)

Specs

op_reserved(t()) :: t()

Unused. Makes transaction invalid.

op_return(vm, chunks)

Specs

op_return(t(), list()) :: t()

Returns the vm and no further statements are evaluated.

op_ripemd160(vm)

Specs

op_ripemd160(t()) :: t()

The top element on the stack is hashed using RIPEMD160.

op_roll(vm)

Specs

op_roll(t()) :: t()

Removes the top stack item and uses it as an index length, then moves the nth item on the stack to the top.

op_rot(vm)

Specs

op_rot(t()) :: t()

Rotates the top three items on the stack, effictively moving the 3rd item to the top of the stack.

op_rshift(vm)

Specs

op_rshift(t()) :: t()

The second from top element numeric value is bitshifted to the right by the number of bits in the top element numeric value. Both elements are replaced on the stack with the result.

op_sha1(vm)

Specs

op_sha1(t()) :: t()

The top element on the stack is hashed using SHA1.

op_sha256(vm)

Specs

op_sha256(t()) :: t()

The top element on the stack is hashed using SHA256.

op_size(vm)

Specs

op_size(t()) :: t()

Pushes the byte length of the top element of the stack, without popping it.

op_split(vm)

Specs

op_split(t()) :: t()

Splits the second from top stack item by the index given in the top stack item.

op_sub(vm)

Specs

op_sub(t()) :: t()

The top stack element is subtracted from the second, and both are replaced on the stack with the result.

op_swap(vm)

Specs

op_swap(t()) :: t()

Rotates the top two items on the stack, effectively moving the 2nd item to the top of the stack.

op_toaltstack(vm)

Specs

op_toaltstack(t()) :: t()

Removes the top of the stack and puts it into the alt stack.

op_tuck(vm)

Specs

op_tuck(t()) :: t()

Copies the top item on the stack and inserts it before the second to top item.

op_ver(vm)

Specs

op_ver(t()) :: t()

Puts the version of the protocol under which this transaction will be evaluated onto the stack. DISABLED

op_verif(vm)

Specs

op_verif(t()) :: t()

op_verify(vm)

Specs

op_verify(t()) :: t()

Mmarks the script as invalid unless the stack is truthy. Removes the top of the stack.

op_vernotif(vm)

Specs

op_vernotif(t()) :: t()

op_within(vm)

Specs

op_within(t()) :: t()

op_xor(vm)

Specs

op_xor(t()) :: t()

Calculates the bitwise XOR of the top two elements of the stack. Both elements must be the same length.

valid?(vm)

Specs

valid?(t()) :: boolean()

Determines if the Script VM is truthy or falsey.