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 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 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 % 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 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; 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; 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
Runs OP_EQUAL then OP_VERIFY.
Aliases:
- EQUAL_VERIFY
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
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; gets the timestamp to check from the cache; compares the two values; if the cache timestamp is less than the stack time, or if current Unix epoch is behind cache timestamp by the flagged amount, put False onto the stack; otherwise, put True onto the stack. If the ts_threshold flag is <= 0, that 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 and val2 from stack; put (v1<v2) onto stack.
Aliases:
- LESS
Pull two signed ints val1 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 and val2 from stack; put (v1<v2) onto stack.
Aliases:
- FLOAT_LESS
- OP_FLESS
- FLESS
Pull two floats val1 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.
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 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 them from the first one; put the result onto the stack.
Aliases:
- SUBTRACT_POINTS
Takes three items from stack: public tweak point T, 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, seed, t, and message m from the stack; 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, 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, 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.)
Aliases:
- CHECK_TEMPLATE
- OP_CT
- CT
Runs OP_CHECK_TEMPLATE and then OP_VERIFY.
Aliases:
- CHECK_TEMPLATE_VERIFY
- OP_CTV
- CTV
Reads 32 bytes from the tape as the root; gets a copy of the top 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 key-spend, pull the sigflags from cache b'trsf' or 'taproot_sigflags', but
replace with 0x00 if it does not disallow exclusion of at least one sigfield
(i.e. has at least one null bit), then run OP_CHECK_SIG. For committed script
execution, get the script and public key from the stack, concatenate, 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.
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
Run the given auth script byte code. Returns True iff the stack has a single \xff value after script execution and no errors were raised; otherwise, returns False.
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): -> unseen_return_value
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
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.
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
Initialize the instance.
Calculate and return the local root between the two branches.
Calculates the locking script for the node. Returns a tuple with the source and byte codes.
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.
create_script_tree_prioritized(leaves: list[str | ScriptProtocol], tree: ScriptNode = 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.
create_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.
Make an adapter locking script that verifies a sig adapter, decrypts it, and then verifies the decrypted signature.
Make an adapter locking script that verifies a sig adapter, decrypts it, and then verifies the decrypted signature.
Make a locking script that requires a valid signature from a single key to unlock. Returns tapescript source code.
Make a locking script that requires a valid signature from a single key to unlock. Returns tapescript source code. Saves 8 bytes in locking script at expense of an additional 33 bytes in the witness.
Make an unlocking script that validates for a single sig locking script by signing the sigfields. Returns tapescript source code.
Make an unlocking script that validates for a single sig locking script by signing the sigfields. Returns tapescript source code. 33 bytes larger witness than make_single_sig_witness to save 8 bytes in the locking script.
Make a locking script that requires quorum_size valid signatures from unique keys within the pubkeys list. Returns tapescript source code. Can be unlocked by joining the results of quorum_size calls to make_single_sig_witness by different key holders.
make_adapter_locks_pub(pubkey: bytes, tweak_point: bytes, sigflags: str = 00): -> tuple[Script, Script]
Make adapter locking scripts using a public key and a tweak scalar. Returns 2 Scripts: one that checks if a sig adapter is valid, and one that verifies the decrypted signature.
Make adapter decryption script.
Decrypt an adapter signature, returning the decrypted signature.
make_adapter_locks_prv(pubkey: bytes, tweak: bytes, sigflags: str = 00): -> tuple[Script, Script, Script]
Make adapter locking scripts using a public key and a tweak scalar. Returns the source for 3 tapescripts: 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, tweak_point: bytes, sigfields: dict, sigflags: str = 00): -> Script
Make an adapter signature witness using a private key and a tweak point. Returns tapescript src code.
Takes a root_pubkey and returns the tapescript source for a locking script that is unlocked with a signature from the delegate key, the delegated public key, and a certificate from the root key committing to the delegate public key and validity time constraints.
make_delegate_key_cert_sig(root_skey: bytes, delegate_pubkey: bytes, begin_ts: int, end_ts: int): -> bytes
Returns a signature for a key delegation cert.
make_delegate_key_unlock(prvkey: bytes, pubkey: bytes, begin_ts: int, end_ts: int, cert_sig: bytes, sigfields: dict, sigflags: str = 00): -> Script
Returns an unlocking script including a signature from the delegate key as well as the delegation certificate.
make_htlc_sha256_lock(receiver_pubkey: bytes, preimage: bytes, refund_pubkey: bytes, 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.
make_htlc_shake256_lock(receiver_pubkey: bytes, preimage: bytes, refund_pubkey: bytes, 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.
Returns the tapescript source for a witness to unlock either the hash lock or the time lock path of an HTLC, depending upon whether or not the preimage matches.
make_htlc2_sha256_lock(receiver_pubkey: bytes, preimage: bytes, refund_pubkey: bytes, 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.
make_htlc2_shake256_lock(receiver_pubkey: bytes, preimage: bytes, refund_pubkey: bytes, 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.
Returns the tapescript source for a witness 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, the other version is more appropriate.
make_ptlc_lock(receiver_pubkey: bytes, refund_pubkey: bytes, tweak_point: bytes = None, timeout: int = 86400, sigflags: str = 00): -> Script
Returns the tapescript source for a Point Time Locked Contract that can be unlcoked 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, sigfields: dict, tweak_scalar: bytes = None, sigflags: str = 00): -> Script
Returns the tapescript source for 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).
Returns the tapescript source for a PTLC witness unlcoking the time locked refund branch.
setup_amhl(seed: bytes, pubkeys: tuple[bytes] | list[bytes], sigflags: str = 00, refund_pubkeys: dict[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.