Each OP_ function has an alias that excludes the OP_ prefix.
All OP_ functions have the following signature:
def OP_WHATEVER(tape: Tape, stack: Stack, cache: dict) -> None:
...All OPs advance the Tape pointer by the amount they read.
Puts a null byte onto the stack.
Aliases:
- FALSE
Puts a 0xFF byte onto the stack.
Aliases:
- TRUE
Read the next byte from the tape; put it onto the stack.
Aliases:
- PUSH0
Read the next byte from the tape, interpreting as an unsigned int; take that many bytes from the tape; put them onto the stack.
Aliases:
- PUSH1
Read the next 2 bytes from the tape, interpreting as an unsigned int; take that many bytes from the tape; put them onto the stack.
Aliases:
- PUSH2
Reads a byte from tape as the sigflags; constructs the message that will be used by OP_SIGN and OP_CHECK_SIG/_VERIFY from the sigfields; puts the result onto the stack. Runs the signature extension plugins beforehand.
Aliases:
- GET_MESSAGE
- OP_MSG
- MSG
Remove the first item from the stack and put it in the cache at key b'P' (can be put back onto the stack with @P).
Aliases:
- POP0
Read the next byte from the tape, interpreting as an unsigned int; remove that many items from the stack and put them in the cache at key b'P' (can be put back onto the stack with @P).
Aliases:
- POP1
Pull a value from the stack; put the size of the value onto the stack as signed int.
Aliases:
- SIZE
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from tape as cache key; read another byte from the tape, interpreting as an int; read that many items from the stack and write them to the cache.
Aliases:
- WRITE_CACHE
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from tape as cache key; read those values from the cache and place them onto the stack.
Aliases:
- READ_CACHE
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from tape as cache key; count how many values exist at that point in the cache and place that int onto the stack.
Aliases:
- READ_CACHE_SIZE
- OP_RCZ
- RCZ
Pull a value from the stack as a cache key; put those values from the cache onto the stack.
Aliases:
- READ_CACHE_STACK
- OP_RCS
- RCS
Pull a value from the stack as a cache key; count the number of values in the cache at that key; put the result onto the stack as a signed int.
Aliases:
- READ_CACHE_STACK_SIZE
- OP_RCSZ
- RCSZ
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack, interpreting them as signed ints; add them together; put the result back onto the stack.
Aliases:
- ADD_INTS
- OP_ADD
- ADD
Read the next byte from the tape, interpreting as uint count; pull that many values from the stack, interpreting them as signed ints; subtract count-1 of them from the first (top) one; put the result onto the stack.
Aliases:
- SUBTRACT_INTS
- OP_SUB
- SUB
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack, interpreting them as signed ints; multiply them together; put the result back onto the stack.
Aliases:
- MULT_INTS
- OP_MULT
- MULT
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from the tape, interpreting as a signed int divisor (denominator); pull a value from the stack, interpreting as a signed int dividend (numerator); divide the dividend by the divisor; put the result onto the stack.
Aliases:
- DIV_INT
Pull two values from the stack, interpreting as signed ints; divide the first (top) by the second; put the result onto the stack.
Aliases:
- DIV_INTS
- OP_DIV
- DIV
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from the tape, interpreting as a signed int divisor; pull a value from the stack, interpreting as a signed int dividend; perform integer modulus: dividend % divisor; put the result onto the stack.
Aliases:
- MOD_INT
Pull two values from the stack, interpreting as signed ints; perform integer modulus: first (top) % second; put the result onto the stack.
Aliases:
- MOD_INTS
- OP_MOD
- MOD
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack, interpreting them as floats; add them together; put the result back onto the stack.
Aliases:
- ADD_FLOATS
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack, interpreting them as floats; subtract them from the first (top) one; put the result back onto the stack.
Aliases:
- SUBTRACT_FLOATS
- OP_SUBF
- SUBF
Read the next 4 bytes from the tape, interpreting as a float divisor; pull a value from the stack, interpreting as a float dividend; divide the dividend by the divisor; put the result onto the stack.
Aliases:
- DIV_FLOAT
Pull two values from the stack, interpreting as floats; divide the second by the first (top); put the result onto the stack.
Aliases:
- DIV_FLOATS
Read the next 4 bytes from the tape, interpreting as a float divisor; pull a value from the stack, interpreting as a float dividend; perform float modulus: dividend % divisor; put the result onto the stack.
Aliases:
- MOD_FLOAT
- OP_MODF
- MODF
Pull two values from the stack, interpreting as floats; perform float modulus: second % first (top); put the result onto the stack.
Aliases:
- MOD_FLOATS
- OP_MODFS
- MODFS
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack; add them together using ed25519 point addition; replace the result onto the stack.
Aliases:
- ADD_POINTS
Read the next byte from the tape, interpreting as an unsigned int; pull a value from the stack; place that value and a number of copies corresponding to the int from the tape back onto the stack.
Aliases:
- COPY
OP_COPY but with only 1 copy and no reading from the tape or advancing the pointer. Equivalent to OP_DUP in Bitcoin script.
Aliases:
- DUP
Pull an item from the stack and put its sha256 hash back onto the stack.
Aliases:
- SHA256
Read the next byte from the tape, interpreting as an unsigned int; pull an item from the stack; put its shake_256 hash of the spcified length back onto the stack.
Aliases:
- SHAKE256
Pull a value from the stack; evaluate it as a bool; and raise a ScriptExecutionError if it is False.
Aliases:
- VERIFY
Pull 2 items from the stack; compare them; put the bool result onto the stack.
Aliases:
- EQUAL
- OP_EQ
- EQ
Runs OP_EQUAL then OP_VERIFY.
Aliases:
- EQUAL_VERIFY
- OP_EQV
- EQV
Take a byte from the tape, interpreting as the encoded allowable sigflags; pull a value from the stack, interpreting as a VerifyKey; pull a value from the stack, interpreting as a signature; check the signature against the VerifyKey and the cached sigfields not disabled by a sig flag; put True onto the stack if verification succeeds, otherwise put False onto the stack. Runs the signature extension plugins beforehand.
Aliases:
- CHECK_SIG
- OP_CS
- CS
Runs OP_CHECK_SIG, then OP_VERIFY.
Aliases:
- CHECK_SIG_VERIFY
- OP_CSV
- CSV
Pulls a value from the stack, interpreting as an unsigned int constraint; gets the timestamp to check against from the cache; compares the two values; if the cache timestamp is less than the stack time, or if the cache time is in the future by more than the ts_threshold according to the current Unix epoch, put False onto the stack; otherwise, put True onto the stack. If the ts_threshold flag is <= 0, the future timestamp check will be skipped.
Aliases:
- CHECK_TIMESTAMP
- OP_CTS
- CTS
Runs OP_CHECK_TIMESTAMP, then OP_VERIFY.
Aliases:
- CHECK_TIMESTAMP_VERIFY
- OP_CTSV
- CTSV
Pulls a value from the stack, interpreting as an unsigned int; gets the current Unix epoch time; compares the two values; if current time is less than the stack time, put False onto the stack; otherwise, put True onto the stack.
Aliases:
- CHECK_EPOCH
Runs OP_CHECK_EPOCH, then OP_VERIFY.
Aliases:
- CHECK_EPOCH_VERIFY
- OP_CEV
- CEV
Read the next byte from the tape as the definition number; read the next 2 bytes from the tape, interpreting as an unsigned int; read that many bytes from the tape as the subroutine definition.
Aliases:
- DEF
Read the next byte from the tape as the definition number; call run_tape passing that definition tape, the stack, and the cache.
Aliases:
- CALL
Read the next 2 bytes from the tape, interpreting as an unsigned int; read that many bytes from the tape as a subroutine definition; pull a value from the stack and evaluate as a bool; if it is true, run the subroutine.
Aliases:
- IF
Read the next 2 bytes from the tape, interpreting as an unsigned int; read that many bytes from the tape as the IF subroutine definition; read the next 2 bytes from the tape, interpreting as an unsigned int; read that many bytes from the tape as the ELSE subroutine definition; pull a value from the stack and evaluate as a bool; if it is true, run the IF subroutine; else run the ELSE subroutine.
Aliases:
- IF_ELSE
Pulls a value from the stack then attempts to run it as a script. OP_EVAL shares a common stack and cache with other ops. Script is disallowed from modifying tape.flags or tape.definitions; it is executed with callstack_count=tape.callstack_count+1 and copies of tape.flags and tape.definitions; it also has access to all loaded contracts.
Aliases:
- EVAL
Pulls a value from the stack; performs bitwise NOT operation; puts result onto the stack.
Aliases:
- NOT
Pull an item from the tape, interpreting as a signed int; put that many random bytes onto the stack.
Aliases:
- RANDOM
Ends the script.
Aliases:
- RETURN
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from the tape as a flag; set that flag.
Aliases:
- SET_FLAG
Read the next byte from the tape, interpreting as an unsigned int; read that many bytes from the tape as a flag; unset that flag.
Aliases:
- UNSET_FLAG
Put the stack item count onto the stack.
Aliases:
- DEPTH
Read the next 2 bytes from the tape, interpreting as unsigned ints; swap the stack items at those depths.
Aliases:
- SWAP
Swap the order of the top two items of the stack.
Aliases:
- SWAP2
Read the next byte from the tape, interpreting as an unsigned int; reverse that number of items from the top of the stack.
Aliases:
- REVERSE
Pull two items from the stack; concatenate them bottom+top; put the result onto the stack.
Aliases:
- CONCAT
- OP_CAT
- CAT
Pull a signed int index from the stack; pull an item from the stack; split the item bytes at the index; put the first byte sequence onto the stack, then put the second byte sequence onto the stack. Raises ScriptExecutionError for invalid index.
Aliases:
- SPLIT
Pull two items from the stack, interpreting as UTF-8 strings; concatenate them; put the result onto the stack.
Aliases:
- CONCAT_STR
- OP_CATS
- CATS
Pull a signed int index from the stack; pull an item from the stack, interpreting as a UTF-8 str; split the item str at the index; put the first str onto the stack, then put the second str onto the stack.
Aliases:
- SPLIT_STR
Take an item from the stack as a contract ID; take an item from the stack as an amount; take an item from the stack as a serialized txn constraint; take an item from the stack as a destination (address, locking script hash, etc); take an item from the stack, interpreting as an unsigned int count; take count number of items from the stack as sources; take the count number of items from the stack as transaction proofs; verify that the aggregate of the transfers to the destination from the sources equals or exceeds the amount; verify that the transfers were valid using the proofs and the contract code; verify that any constraints were followed; and put True onto the stack if successful and False otherwise. Sources and proofs must be in corresponding order.
Aliases:
- CHECK_TRANSFER
Read 32 bytes from the tape as the root digest; call OP_DUP then OP_SHA256 twice; move stack item at index 2 to the top and call OP_SHA256 once; call OP_XOR; call OP_SHA256; push root hash onto the stack; call OP_EQUAL_VERIFY; call OP_EVAL.
Aliases:
- MERKLEVAL
Read the next 2 bytes from the tape, interpreting as an unsigned int; read that many bytes from the tape as the TRY subroutine definition; read 2 bytes from the tape, interpreting as an unsigned int; read that many bytes as the EXCEPT subroutine definition; execute the TRY subroutine in a try block; if an error occurs, serialize it and put it in the cache then run the EXCEPT subroutine.
Aliases:
- TRY_EXCEPT
Pull two signed ints val1 (top) and val2 from stack; put (v1<v2) onto stack.
Aliases:
- LESS
Pull two signed ints val1 (top) and val2 from stack; put (v1<=v2) onto stack.
Aliases:
- LESS_OR_EQUAL
- OP_LEQ
- LEQ
Read one byte from the tape as uint size; read size bytes from the tape, interpreting as utf-8 string; put the read-only cache value(s) at that cache key onto the stack, serialized as bytes.
Aliases:
- GET_VALUE
- OP_VAL
- VAL
Pull two floats val1 (top) and val2 from stack; put (v1<v2) onto stack.
Aliases:
- FLOAT_LESS
- OP_FLESS
- FLESS
Pull two floats val1 (top) and val2 from stack; put (v1<=v2) onto stack.
Aliases:
- FLOAT_LESS_OR_EQUAL
- OP_FLEQ
- FLEQ
Pull a signed int from the stack and put it back as a float.
Aliases:
- INT_TO_FLOAT
- OP_I2F
- I2F
Pull a float from the stack and put it back as a signed int.
Aliases:
- FLOAT_TO_INT
- OP_F2I
- F2I
Read 2 bytes from the tape as uint len; read that many bytes from the tape as the loop definition; run the loop as long as the top value of the stack is not false or until a callstack limit exceeded error is raised.
Aliases:
- LOOP
Reads 1 byte from tape as allowable flags; reads 1 byte from tape as uint m; reads 1 byte from tape as uint n; pulls n values from stack as vkeys; pulls m values from stack as signatures; verifies each signature against vkeys; puts false onto the stack if any signature fails to validate with one of the vkeys or if any vkey is used more than once; puts true onto the stack otherwise.
Aliases:
- CHECK_MULTISIG
- OP_CMS
- CMS
Runs OP_CHECK_MULTISIG then OP_VERIFY.
Aliases:
- CHECK_MULTISIG_VERIFY
- OP_CMSV
- CMSV
Reads 1 byte from the tape as the sig_flag; pulls a value from the stack, interpreting as a SigningKey; creates a signature using the correct sigfields; puts the signature onto the stack. Raises ValueError for invalid key seed length. Runs the signature extension plugins beforehand. Resulting signature will have the sig_flag appended to it if a non-null sig_flag is specified.
Aliases:
- SIGN
Pulls a value from the stack, interpreting as a SigningKey; pulls a message from the stack; signs the message with the SigningKey; puts the signature onto the stack. Raises ValueError for invalid key seed length.
Aliases:
- SIGN_STACK
Pulls a value from the stack, interpreting as a VerifyKey; pulls a message from the stack; pulls a value from the stack, interpreting as a signature; puts True onto the stack if the signature is valid for the message and the VerifyKey, otherwise puts False onto the stack. Raises ValueError for invalid vkey or signature.
Aliases:
- CHECK_SIG_STACK
- OP_CSS
- CSS
Takes a value seed from stack; derives an ed25519 key scalar from the seed; puts the key scalar onto the stack. Sets cache key b'x' to x if allowed by tape.flags.
Aliases:
- DERIVE_SCALAR
Reads a byte from the tape, interpreting as a bool is_key; takes a value from the stack; clamps it to an ed25519 scalar; puts the clamped ed25519 scalar onto the stack. Raises ValueError for invalid value.
Aliases:
- CLAMP_SCALAR
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack; add them together using ed25519 scalar addition; put the sum onto the stack.
Aliases:
- ADD_SCALARS
Read the next byte from the tape, interpreting as uint count; pull that many values from the stack, interpreting them as ed25519 scalars; subtract count-1 of them from the first (top) one; put the difference onto the stack.
Aliases:
- SUBTRACT_SCALARS
Takes an an ed25519 scalar value x from the stack; derives a curve point X from scalar value x; puts X onto stack; sets cache key b'X' to X if allowed by tape.flags (can be used in code with @X).
Aliases:
- DERIVE_POINT
Read the next byte from the tape, interpreting as an unsigned int; pull that many values from the stack, interpreting them as ed25519 scalars; subtract the rest from the first (top) one; put the result onto the stack.
Aliases:
- SUBTRACT_POINTS
Takes three items from stack: public tweak point T (top), message m, and prvkey seed; creates a signature adapter sa; puts nonce point R onto stack; puts signature adapter sa onto stack; sets cache keys b'R' to R, b'T' to T, and b'sa' to sa if allowed by tape.flags (can be used in code with @R, @T, and @sa).
Aliases:
- MAKE_ADAPTER_SIG_PUBLIC
- OP_MASU
- MASU
Takes three values from the stack: seed (top), t, and message m; derives prvkey x from seed; derives pubkey X from x; derives private nonce r from seed and m; derives public nonce point R from r; derives public tweak point T from t; creates signature adapter sa; puts T, R, and sa onto stack; sets cache keys b't' to t if tape.flags[5], b'T' to T if tape.flags[6], b'R' to R if tape.flags[4], and b'sa' to sa if tape.flags[8] (can be used in code with @t, @T, @R, and @sa). Values seed and t should be 32 bytes each. Values T, R, and sa are all public 32 byte values and necessary for verification; t is used to decrypt the signature.
Aliases:
- MAKE_ADAPTER_SIG_PRIVATE
- OP_MASV
- MASV
Takes public key X (top), tweak point T, message m, nonce point R, and signature adapter sa from the stack; puts True onto stack if the signature adapter is valid and False otherwise.
Aliases:
- CHECK_ADAPTER_SIG
- OP_CAS
- CAS
Takes tweak scalar t (top), nonce point R, and signature adapter sa from stack; calculates nonce RT; decrypts signature s from sa; puts RT onto the stack; puts s onto stack; sets cache keys b's' to s if tape.flags[9] and b'RT' to RT if tape.flags[7] (can be used in code with @s and @RT).
Aliases:
- DECRYPT_ADAPTER_SIG
- OP_DAS
- DAS
Takes an item from the stack as contract_id; takes an int from the stack as
argcount; takes argcount items from the stack as arguments; tries to invoke
the contract's abi method, passing it the arguments; puts any return values onto
the stack. Raises ScriptExecutionError if the argcount is negative, contract is
missing, or the contract does not implement the CanBeInvoked interface. Raises
TypeError if the return value type is not bytes or NoneType. If allowed by
tape.flag[0], will put any return values into cache at key b'IR'.
Aliases:
- INVOKE
Takes two values from the stack; XORs them together; puts result onto the stack. Pads the shorter length value with x00.
Aliases:
- XOR
Takes two values from the stack; ORs them together; puts result onto the stack. Pads the shorter length value with x00.
Aliases:
- OR
Takes two values from the stack; ANDs them together; puts result onto the stack. Pads the shorter length value with x00.
Aliases:
- AND
Reads 1 byte from the tape, interpreting as sigflags; pull an item from the stack for each indicated sigfield as a template; check that all indicated sigfields validate against the template using the plugin system; put True onto the stack if every sigfield validated against its template by at least one ctv plugin function, and False otherwise. Runs the signature extension plugins first if tape.flags[10] is set to True, which is the default behavior. (The stack passed to the plugin will contain the template on the top and the sigfield beneath.) Templates will be pulled from the stack in order of ascending sigfield number; e.g. for sigflag x03, sigfield1 and sigfield2 will be pulled from the top of the stack in that order.
Aliases:
- CHECK_TEMPLATE
- OP_CT
- CT
Runs OP_CHECK_TEMPLATE and then OP_VERIFY.
Aliases:
- CHECK_TEMPLATE_VERIFY
- OP_CTV
- CTV
Reads 1 byte from the tape as allowable sigflags; pops the top item of the stack
as the root; gets a copy of the next stack item (using stack.peek); if the item
has length 32, it is an ed25519 public key, otherwise it is a signature; if it
was a public key, then it is executing the committed script; if it is a
signature, then it is executing the key-spend path. For committed script
execution, get the public key and script from the stack, concatenate the
pubkey||sha256(script), sha256, clamp to the ed25519 scalar field, derive a
point, and add the point to the public key; if the result was the root, then put
the script back on the stack and OP_EVAL, otherwise remove the script and put
0x00 (False) onto the stack. For key-spend, run OP_CHECK_SIG using the
allowable sigflags.
https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2018-January/015614.html
Aliases:
- TAPROOT
- OP_TR
- TR
Codes in 92-255 (x5C-FF) Read the next byte from the tape, interpreting as a signed int and pull that many values from the stack. Does nothing with the values. Useful for later soft-forks by redefining byte codes. Raises ScriptExecutionError if count is negative.
run_script(script: bytes | ScriptProtocol, cache_vals: dict = {}, contracts: dict = {}, additional_flags: dict = {}, plugins: dict = {}, stack_max_items: int = 1024, stack_max_item_size: int = 1024, callstack_limit: int = 128): -> tuple[Tape, Stack, dict]
Run the given script byte code. Returns a tape, stack, and dict.
Run the given tape using the stack and cache.
run_auth_script(script: bytes | ScriptProtocol, cache_vals: dict = {}, contracts: dict = {}, plugins: dict = {}, stack_max_items: int = 1024, stack_max_item_size: int = 1024, callstack_limit: int = 128): -> bool
Deprecated. Functionality will be maintained until the 0.8.0 release. See
documentation for details on how to use the replacement function
run_auth_scripts.
run_auth_scripts(scripts: list[bytes | ScriptProtocol], cache_vals: dict = {}, contracts: dict = {}, plugins: dict = {}, stack_max_items: int = 1024, stack_max_item_size: int = 1024, callstack_limit: int = 128): -> bool
Run the given auth scripts in order. Returns True iff the stack has a single
\xff value after all scripts have executed and no errors were raised; otherwise,
returns False. Each script is executed with the same stack and cache;
definitions are copied between tapes; and the callstack_limit is enforced
across the total execution via a cumulative callstack_count. When using
locking and unlocking scripts, the locking script must be the last item in the
scripts list so it is executed last and thus properly enforced.
Adds an OP implementation with the code, name, and function. Raises TypeError for invalid arg types and ValueError for invalid code or name.
Add a contract to be loaded on each script execution. Raises TypeError if contract_id is not bytes. Calls _check_contract, which raises ScriptExecutionError if the contract does not match at least one contract interface.
Remove a loaded contract to prevent it from being included on script execution. Raises TypeError if contract_id is not bytes.
Adds an interface for type checking contracts. Interface must be a runtime_checkable Protocol. Raises TypeError if the interface is not a Protocol.
Removes an interface for type checking contracts. Raises TypeError if the interface is not a Protocol.
Split the script source into symbols. Raises SyntaxError for unterminated string values.
Preparses a list of symbols, replacing any comptime blocks with the compiled byte code of the block as a hex value symbol or the top stack item as a hex value symbol by compiling and executing the contents of the block. Returns a modified list of symbols in which all comptime blocks have been replaced. Any macros defined within the comptime block will be accessible outside of it, and macros defined outside a comptime block can be invoked within it.
Assemble the symbols into bytecode. Raises SyntaxError and ValueError for invalid syntax or values.
Compile the given human-readable script into byte code. Bubbles any SyntaxError or ValueError raised by assemble.
Decompile the byte code into human-readable script.
add_opcode_parsing_handlers(opname: str, compiler_handler: Callable, decompiler_handler: Callable): -> None
Adds the handlers for parsing a new OP. The opname should start with OP_. The compiler_handler should have this annotation: ( opname: str, symbols: list[str], symbols_to_advance: int, symbol_index: int) -> tuple[int, tuple[bytes]]. The decompiler_handler should have this annotation: (op_name: str, tape: Tape) -> list[str]. The OP implementation must be added to the interpreter via the add_opcode function, else parsing will fail.
Represent a script as a pairing of source and byte code.
- src: str
- bytes: bytes
Create an instance from tapescript source code.
Create an instance from tapescript byte code.
Return a cryptographic commitment for the Script.
A leaf in a Merklized script tree.
- hash: bytes
- script: Script | None
- parent: ScriptNode | None
Create an instance from a Script object.
Create an instance from the source code.
Create an instance from the byte code.
Return the cryptographic commitment for the leaf.
Calculate an unlocking script recursively, traveling up the parents. Returns a
Script with the source and byte codes. When executed, this will validate the
LeafScript against the root ScriptNode commitment (within an OP_MERKLEVAL
locking script), and then OP_MERKLEVAL will execute the underlying script.
Serialize the instance to bytes.
Deserialize an instance from bytes.
A node in a Merklized script tree.
- left: ScriptLeaf | ScriptNode
- right: ScriptLeaf | ScriptNode
- parent: ScriptNode | None
Initialize the instance.
Calculate and return the local root between the two branches.
Calculates the locking script for the node. Returns a Script with the source and
byte codes in the form OP_MERKLEVAL <root>.
Calculates the commitment to execute this ScriptNode and returns as bytes.
Calculates a recursive unlocking script for the node. Returns a Script with the source and byte codes.
Serialize the script tree to bytes.
Deserialize a script tree from bytes.
Provides a REPL (Read Execute Print Loop). Lines of source code are read, compiled, and executed, and the runtime state is shared between executions. If a code block is opened, the Read functionality will continue accepting input until all opened code blocks have closed, and it will automatically indent the input line. To exit the loop, type "return", "exit", or "quit".
make_script_tree_prioritized(leaves: list[str | ScriptProtocol], tree: ScriptNode | None = None): -> ScriptNode
Construct a script tree from the leaves using a ScriptLeaf for each leaf script, combining the last two into a ScriptNode and then recursively combining a ScriptLeaf for the last of the remaining script leaves with the previously generated ScriptNode until all leaves have been included, priorizing the lower index leaf scripts with smaller unlocking script sizes.
make_merklized_script_prioritized(leaves: list[str | ScriptProtocol]): -> tuple[Script, list[Script]]
Produces a Merklized, branching script structure with one leaf and one node at every level except for the last node, which is balanced. Returns a tuple of root locking script and list of unlocking scripts. The tree is unbalanced; execution is optimized for earlier branches (lower index leaf scripts), and execution is linearly worse for each subsequent branch. In practice, the input scripts should be locking scripts, and then they should be used by concatenating the corresponding unlocking script and the unlocking script from this function.
Create a balanced script tree from the leaves, filling with filler
leaves/branches to make sure the tree is balanced. The filler leaves take the
form of push x{16 random bytes} return, so they can never validate, and they
will have unique hashes to avoid revealing the presence of empty leaves/branches
during execution of actual leaf scripts. Used internally by the
make_merklized_script_balanced function.
Produces a Merklized, branching script with a balanced tree structure, filling
with filler branches to make sure the tree is balanced (calls
make_script_tree_balanced under the hood). Returns a tuple of root locking
script and list of unlocking scripts corresponding to the input scripts. In
practice, the input scripts should be locking scripts, and then they should be
used by concatenating the corresponding unlocking script and the unlocking
script from this function.
Makes a lock that enforces that the runtime timestamp is greater than the given
ts but not greater than the local clock by more than the allowable slack
configured in the runtime. If op_verify is set to True, it will use
OP_CHECK_TIMESTAMP_VERIFY instead of OP_CHECK_TIMESTAMP, making it useful as
an additional check within more complex scripts, e.g. to add time constraints to
graftroot delegate scripts.
Makes a lock that enforces that the runtime timestamp is less than the given ts.
If op_verify is set to True, it will run OP_VERIFY instead of leaving the
result on the stack, making it useful as an additional check within more complex
scripts, e.g. to add time constraints to graftroot delegate scripts.
Makes a lock that enforces that the runtime timestamp is greater than begin_ts
and less than end_ts. If op_verify is True, the final check will run
OP_VERIFY instead of leaving the result on the stack. Calls
OP_CHECK_TIMESTAMP_VERIFY on the first check.
Make an adapter locking script that verifies a sig adapter, decrypts it, and
then verifies the decrypted signature. DEPRECATED: use make_adapter_locks_pub
instead.
Make an adapter locking script that verifies a sig adapter, decrypts it, and
then verifies the decrypted signature. DEPRECATED: use make_adapter_locks_prv
instead.
Make a locking Script that requires a valid signature from a single key to unlock.
Make a locking Script that commits to and requires a public key and then valid signature from the pubkey to unlock. Saves 8 bytes in locking script at expense of an additional 33 bytes in the witness.
make_single_sig_witness(prvkey: bytes | SigningKey, sigfields: dict[str, bytes], sigflags: str = 00, sign_script_prefix: str = ): -> Script
Make an unlocking script that validates for a single sig locking script by
signing the sigfields. Returns Script that pushes the signature onto the stack.
Passing a sign_script_prefix will prefix the signing operation with the given
script source.
make_single_sig_witness2(prvkey: bytes | SigningKey, sigfields: dict[str, bytes], sigflags: str = 00, sign_script_prefix: str = ): -> Script
Make an unlocking script that validates for a single sig locking script by
signing the sigfields. Returns a Script that pushes the signature and pubkey
onto the stack. 33 bytes larger witness than make_single_sig_witness to save 8
bytes in the locking script. Passing a sign_script_prefix will prefix the
signing operation with the given script source.
make_multisig_lock(pubkeys: list[bytes | VerifyKey], quorum_size: int, sigflags: str = 00): -> Script
Make a locking Script that requires quorum_size valid signatures from unique
keys within the pubkeys list. Can be unlocked by joining the results of
quorum_size calls to make_single_sig_witness by different key holders. The
quorum_size argument must be less than or equal to the number of unique public
keys.
make_adapter_locks_pub(pubkey: bytes | VerifyKey, tweak_point: bytes, sigflags: str = 00): -> tuple[Script, Script]
Make adapter locking scripts using a public key and a tweak point. Returns 2 Scripts: one that checks if a sig adapter is valid, and one that verifies the decrypted signature.
Make adapter decryption script from a tweak scalar.
Decrypt an adapter signature with the given tweak scalar, returning the decrypted signature.
make_adapter_locks_prv(pubkey: bytes | VerifyKey, tweak: bytes, sigflags: str = 00): -> tuple[Script, Script, Script]
Make adapter locking scripts using a public key and a tweak scalar. Returns a tuple of 3 Scripts: one that checks if a sig adapter is valid, one that decrypts the signature, and one that verifies the decrypted signature.
make_adapter_witness(prvkey: bytes | SigningKey, tweak_point: bytes, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Make an adapter signature witness using a private key and a tweak point. Returns
a Script that pushes the adapter signature and nonce point onto the stack.
Passing a sign_script_prefix will prefix the signing operation with the given
script source.
Takes a root_pubkey and returns a locking Script that is unlocked with a signature from the delegate key and a signed certificate from the root key authorizing the delegate key.
make_delegate_key_cert(root_skey: bytes | SigningKey, delegate_pubkey: bytes | VerifyKey, begin_ts: int, end_ts: int, can_further_delegate: bool = True): -> Certificate
Returns a signed key delegation cert. By default, this cert will authorize the
delegate_pubkey holder to create further delegate certs, allowing authorization
by a chain of certs. To disable this behavior and create a terminal cert, pass
False as the can_further_delegate argument.
make_delegate_key_witness(delegate_prvkey: bytes | SigningKey, cert: bytes | Certificate, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns an unlocking (witness) Script including a signature from the delegate
key as well as the delegation certificate. Passing a sign_script_prefix will
prefix the signing operation with the given script source.
make_delegate_key_chain_witness(delegate_prvkey: bytes | SigningKey, certs: list[bytes | Certificate], sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns an unlocking (witness) Script including a signature from the delegate
key as well as the chain of delegation certificates ordered from the one
authorizing this key down to the first cert authorized by the root. Passing a
sign_script_prefix will prefix the signing operation with the given script
source.
make_htlc_sha256_lock(receiver_pubkey: bytes | VerifyKey, refund_pubkey: bytes | VerifyKey, preimage: bytes | None = None, digest: bytes | None = None, timeout: int = 86400, sigflags: str = 00): -> Script
Returns an HTLC that can be unlocked either with the preimage and a signature matching receiver_pubkey or with a signature matching the refund_pubkey after the timeout has expired. Suitable only for systems with guaranteed causal ordering and non-repudiation of transactions. Preimage should be at least 16 random bytes but not more than 32; digest must be 32 bytes. Must supply either the preimage or the digest.
make_htlc_shake256_lock(receiver_pubkey: bytes | VerifyKey, refund_pubkey: bytes | VerifyKey, preimage: bytes | None = None, digest: bytes | None = None, hash_size: int = 20, timeout: int = 86400, sigflags: str = 00): -> Script
Returns an HTLC that can be unlocked either with the preimage and a signature
matching receiver_pubkey or with a signature matching the refund_pubkey after
the timeout has expired. Suitable only for systems with guaranteed causal
ordering and non-repudiation of transactions. Using a hash_size of 20 saves 11
bytes compared to the sha256 version with a 96 bit reduction in security
(remaining 160 bits) for the hash lock. Preimage should be at least 16 random
bytes but not more than 32; digest must be hash_size long. Must supply either
preimage or digest.
make_htlc_witness(prvkey: bytes | SigningKey, preimage: bytes, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns a witness to unlock either the hash lock or the time lock path of an
HTLC, depending upon whether or not the preimage matches. To use the time
lock/refund path, pass a preimage of 1 byte to save space in the witness.
Passing a sign_script_prefix will prefix the signing operation with the given
script source.
make_htlc2_sha256_lock(receiver_pubkey: bytes | VerifyKey, refund_pubkey: bytes | VerifyKey, preimage: bytes | None = None, digest: bytes | None = None, timeout: int = 86400, sigflags: str = 00): -> Script
Returns an HTLC that can be unlocked either with the preimage and a signature matching receiver_pubkey or with a signature matching the refund_pubkey after the timeout has expired. Suitable only for systems with guaranteed causal ordering and non-repudiation of transactions. This version is optimized for smaller locking script size (-18 bytes) at the expense of larger witnesses (+33 bytes) for larger overall txn size (+15 bytes). Which to use will depend upon the intended use case: for public blockchains where all nodes must hold a UTXO set in memory and can trim witness data after consensus, the lock script size reduction is significant and useful; for other use cases, in particular systems where witness data cannot be trimmed, the other version is more appropriate. Either preimage or digest must be supplied.
make_htlc2_shake256_lock(receiver_pubkey: bytes | VerifyKey, refund_pubkey: bytes | VerifyKey, preimage: bytes | None = None, digest: bytes | None = None, hash_size: int = 20, timeout: int = 86400, sigflags: str = 00): -> Script
Returns an HTLC that can be unlocked either with the preimage and a signature matching receiver_pubkey or with a signature matching the refund_pubkey after the timeout has expired. Suitable only for systems with guaranteed causal ordering and non-repudiation of transactions. Using a hash_size of 20 saves 11 bytes compared to the sha256 version with a 96 bit reduction in security (remaining 160 bits) for the hash lock. This version is optimized for smaller locking script size (-18 bytes) at the expense of larger witnesses (+33 bytes) for larger overall txn size (+15 bytes). Which to use will depend upon the intended use case: for public blockchains where all nodes must hold a UTXO set in memory and can trim witness data after consensus, the lock script size reduction is significant and useful; for other use cases, in particular systems where witness data cannot be trimmed, the other version is more appropriate. Must supply either preimage or digest.
make_htlc2_witness(prvkey: bytes | SigningKey, preimage: bytes, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns a witness Script to unlock either the hash lock or the time lock path of
an HTLC, depending upon whether or not the preimage matches. This version is
optimized for smaller locking script size (-18 bytes) at the expense of larger
witnesses (+33 bytes) for larger overall txn size (+15 bytes). Which to use will
depend upon the intended use case: for public blockchains where all nodes must
hold a UTXO set in memory and can trim witness data after consensus, the lock
script size reduction is significant and useful; for other use cases, in
particular systems where witness data cannot be trimmed or in which witness size
should be minimized, the other version is more appropriate. Passing a
sign_script_prefix will prefix the signing operation with the given script
source.
make_ptlc_lock(receiver_pubkey: bytes | VerifyKey, refund_pubkey: bytes | VerifyKey, tweak_point: bytes = None, timeout: int = 86400, sigflags: str = 00): -> Script
Returns a Point Time Locked Contract (PTLC) Script that can be unlocked with either a signature matching the receiver_pubkey or with a signature matching the refund_pubkey after the timeout has expired. Suitable only for systems with guaranteed causal ordering and non-repudiation of transactions. If a tweak_point is passed, use tweak_point+receiver_pubkey as the point lock.
make_ptlc_witness(prvkey: bytes | SigningKey, sigfields: dict, tweak_scalar: bytes = None, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns a PTLC witness unlocking the main branch. If a tweak_scalar is passed,
add tweak_scalar to x within signature generation to unlock the point
corresponding to derive_point(tweak_scalar) + derive_point(x). Passing a
sign_script_prefix will prefix the signing operation with the given script
source.
make_ptlc_refund_witness(prvkey: bytes | SigningKey, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns a PTLC witness unlocking the time locked refund branch. Passing a
sign_script_prefix will prefix the signing operation with the given script
source.
make_taproot_lock(pubkey: bytes | VerifyKey, script: Script = None, script_commitment: bytes = None, sigflags: str = 00): -> Script
Returns a Script for a taproot locking script that can either be unlocked with a signature that validates using the taproot root commitment as a public key or by supplying both the committed script and the committed public key to execute the committed script.
make_taproot_witness_keyspend(prvkey: bytes | SigningKey, sigfields: dict, committed_script: Script = None, script_commitment: bytes = None, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Returns a Script witness for a taproot keyspend. Passing a sign_script_prefix
will prefix the signing operation with the given script source.
Returns a Script witness for a taproot scriptspend, i.e. a witness that causes the committed script to be executed.
make_nonnative_taproot_lock(pubkey: bytes | VerifyKey, script: Script = None, script_commitment: bytes = None, sigflags: str = 00): -> Script
Returns a locking Script for non-native taproot. This Script exists primarily to compare against the native taproot lock and the nonnative graftroot lock.
Make a taproot lock committing to the (internal) pubkey and a graftroot lock.
make_graftap_witness_keyspend(prvkey: bytes | SigningKey, sigfields: dict, sigflags: str = 00, sign_script_prefix: str = ): -> Script
Make a Script witness for a taproot keyspend, providing the committed graftroot
lock hash and a signature. Passing a sign_script_prefix will prefix the
signing operation with the given script source.
Make a Script witness for a taproot scriptspend, providing the committed graftroot lock, the internal pubkey, and the graftroot surrogate witness script.
setup_amhl(seed: bytes, pubkeys: list[bytes | VerifyKey], sigflags: str = 00, refund_pubkeys: dict[bytes | VerifyKey, bytes] = None, timeout: int = 86400): -> dict[bytes | str, bytes | tuple[Script | bytes, ...]]
Sets up an annoymous multi-hop lock for a sorted list of pubkeys. Returns a dict mapping each public key to a tuple containing the tuple of scripts returned by make_adapter_locks_pub and the tweak point for the hop, and mapping the key 'key' to the first tweak scalar needed to unlock the last hop in the AMHL and begin the cascade back to the funding source. The order of pubkeys must start with the originator and end with the correspondent of the receiver. If refund_pubkeys dict is passed, then for any pk in pubkeys that is also a key in the refund_pubkeys dict, the single sig lock (2nd value) will be replaced with a PTLC.
release_left_amhl_lock(adapter_witness: bytes | ScriptProtocol, signature: bytes, y: bytes): -> bytes
Release the next lock using an adapter witness and a decrypted signature from right lock. Returns the tweak scalar used to decrypt the left adapter signature.
Adds a soft fork, adding the op to the interpreter and handlers for compiling and decompiling.
Generates the docs file using annotations and docstrings. Requires the autodox library, which is included in the optional "docs" dependencies.
The virtual machine includes a flag system for configuring some ops. The following flags are standard:
- ts_threshold: int amount of slack allowable in timestamp comparisons (default 60)
- epoch_threshold: int amount of slack allowable in epoch comparisons (default 60)
- 0: when True (default True),
OP_INVOKEsets cache key b'IR' to return value - 1: when True (default True), relevant ops set cache key b'x' (private key)
- 2: when True (default True), relevant ops set cache key b'X' (public key)
- 3: when True (default True), relevant ops set cache key b'r' (nonce scalar)
- 4: when True (default True), relevant ops set cache key b'R' (nonce point)
- 5: when True (default True), relevant ops set cache key b't' (tweak scalar)
- 6: when True (default True), relevant ops set cache key b'T' (tweak point)
- 7: when True (default True), relevant ops set cache key b'RT' (nonce point * tweak point)
- 8: when True (default True), relevant ops set cache key b'sa' (signature adapter)
- 9: when True (default True), relevant ops set cache key b's' (signature)
- 10: when True (default True),
OP_CHECK_TEMPLATEwill run the signature extension plugins
These values can be changed by updating the functions.flags dict. Additional
flags can be defined with similar syntax.
functions.flags['ts_threshold'] = 120
functions.flags[69] = 420Integer flags 0-255 can be set or unset by OP_SET_FLAG and OP_UNSET_FLAG.
Flag keys must have type int or str, and flag values must have type int or bool.
The script running functions, run_tape, run_script, and run_auth_script
set all flags with keys contained in functions.flags_to_set before running the
script; other flags must be enabled with OP_SET_FLAG.
At this time, the CLI does not support setting custom flags.