Emulator - Build on Arkade

Bitcoin Script is limited: it cannot inspect the transaction that spends an output, constrain that transaction’s outputs, reason about assets, or read offchain attested facts. The Emulator is the signing service that adds these functions. Before it signs a spend, it runs Arkade Script, Bitcoin Script with more opcodes. Arkade Script adds about 50 opcodes for transaction introspection, asset flows, cryptography, and offchain time, and the opcodes that Bitcoin disabled also work. The Emulator powers the Arkade VM, a second VM layer over the unspent transaction output graph of Bitcoin that adds virtual outputs, assets, and Arkade Script.

Bitcoin Script and Arkade Script

An Arkade virtual output is a Taproot output. Its script tree has two kinds of leaf. A tapscript leaf is Bitcoin Script that miners run when someone spends the leaf on L1. The CSV exit leaf is one of these, and it needs no signature from the operator or the Emulator. A covenant leaf holds a spending condition in Arkade Script, which Bitcoin never runs. The leaf that Bitcoin sees needs two signatures, one from the Arkade operator and one from the Emulator key, and the script tweaks that key. The Emulator signs only if the script passes.

	Bitcoin Script	Arkade Script
Who runs it	Each Bitcoin node runs the leaf when someone spends it on L1.	The Emulator runs it before it signs.
What it reads	The stack. No opcode reads the outputs, the amounts, or the other inputs of the spending transaction.	The whole spending transaction, its packets, and its assets.
Numbers	Operands have at most 4 bytes.	BigNums have at most 520 bytes.
Disabled opcodes	`OP_CAT`, `OP_SUBSTR`, `OP_LEFT`, `OP_RIGHT`, `OP_INVERT`, `OP_AND`, `OP_OR`, `OP_XOR`, `OP_2MUL`, `OP_2DIV`, `OP_MUL`, `OP_DIV`, `OP_MOD`, `OP_LSHIFT`, and `OP_RSHIFT` fail the script.	These opcodes work.
After you unroll a virtual output	Bitcoin checks the leaf.	Bitcoin does not run the script. It checks only the signatures of the leaf.

You write contracts in Arkade Language, and arkadec makes both kinds of leaf. The Bitcoin Script wiki lists the opcodes of Bitcoin.

How a covenant spend is checked

The wallet adds an Emulator Packet to the Arkade transaction. The packet holds the Arkade Script and the witness of each covenant input.
The wallet sends the transaction to the /v1/tx endpoint of the Emulator.
The Emulator runs each script in the packet against the transaction.
The Emulator signs only if each script succeeds.
The Emulator sends the transaction to the Arkade operator and returns the finalized transaction.

If another signer besides the operator must still sign, the Emulator returns only its own signatures.

Opcodes

Arkade Script keeps the opcode values of Bitcoin Script and uses unused values for new opcodes. OP_MERKLEBRANCHROOT uses the value of OP_NOP4. The opcode table of the engine is opcode.go. The README describes the new opcodes. The groups follow the Bitcoin Script wiki. A stack effect shows the inputs, an arrow, and the outputs. The top of the stack is on the right.

Same as Bitcoin Script

Type	Opcodes
Constants	`OP_0`, data pushes `0x01` to `0x4b`, `OP_PUSHDATA1`, `OP_PUSHDATA2`, `OP_PUSHDATA4`, `OP_1NEGATE`, `OP_1`–`OP_16`
Flow control	`OP_NOP`, `OP_IF`, `OP_NOTIF`, `OP_ELSE`, `OP_ENDIF`, `OP_VERIFY`, `OP_RETURN`
Stack	`OP_TOALTSTACK`, `OP_FROMALTSTACK`, `OP_2DROP`, `OP_2DUP`, `OP_3DUP`, `OP_2OVER`, `OP_2ROT`, `OP_2SWAP`, `OP_IFDUP`, `OP_DEPTH`, `OP_DROP`, `OP_DUP`, `OP_NIP`, `OP_OVER`, `OP_PICK`, `OP_ROLL`, `OP_ROT`, `OP_SWAP`, `OP_TUCK`
Splice	`OP_SIZE`
Bitwise logic	`OP_EQUAL`, `OP_EQUALVERIFY`
Arithmetic	`OP_1ADD`, `OP_1SUB`, `OP_NEGATE`, `OP_ABS`, `OP_NOT`, `OP_0NOTEQUAL`, `OP_ADD`, `OP_SUB`, `OP_BOOLAND`, `OP_BOOLOR`, `OP_NUMEQUAL`, `OP_NUMEQUALVERIFY`, `OP_NUMNOTEQUAL`, `OP_LESSTHAN`, `OP_GREATERTHAN`, `OP_LESSTHANOREQUAL`, `OP_GREATERTHANOREQUAL`, `OP_MIN`, `OP_MAX`, `OP_WITHIN`
Crypto	`OP_RIPEMD160`, `OP_SHA1`, `OP_SHA256`, `OP_HASH160`, `OP_HASH256`, `OP_CODESEPARATOR`
Locktime	`OP_CHECKLOCKTIMEVERIFY`, `OP_CHECKSEQUENCEVERIFY`

The numeric opcodes take BigNums, not 4-byte numbers.

Stack

OP_PUT is new.

Opcode	Hex	Stack	Notes
`OP_PUT`	`0xbb`	`value n →`	It replaces the item `n` places back with `value`.

Splice

Bitcoin Script disables OP_CAT, OP_SUBSTR, OP_LEFT, and OP_RIGHT, but they work in Arkade Script, and OP_REVERSEBYTES is new.

Opcode	Hex	Stack	Notes
`OP_CAT`	`0x7e`	`x1 x2 → x1\|x2`	It joins two byte arrays.
`OP_SUBSTR`	`0x7f`	`x n size → x[n:n+size]`
`OP_LEFT`	`0x80`	`x n → x[:n]`
`OP_RIGHT`	`0x81`	`x n → x[len(x)-n:]`
`OP_REVERSEBYTES`	`0xd9`	`x → reverse(x)`

Bitwise logic

Bitcoin Script disables these opcodes, but they work in Arkade Script.

Opcode	Hex	Stack	Notes
`OP_INVERT`	`0x83`	`x → ~x`
`OP_AND`	`0x84`	`x1 x2 → x1&x2`	The operands must have the same length.
`OP_OR`	`0x85`	`x1 x2 → x1\|x2`	The operands must have the same length.
`OP_XOR`	`0x86`	`x1 x2 → x1^x2`	The operands must have the same length.

Arithmetic

A BigNum is a minimally encoded integer of up to 520 bytes. Bitcoin Script disables the first seven opcodes below, but they work in Arkade Script, and the last three opcodes are new. OP_NUM2BIN and OP_BIN2NUM convert between BigNums and byte strings of fixed width. Disabled in Bitcoin Script

Opcode	Hex	Stack	Notes
`OP_2MUL`	`0x8d`	`x → x*2`
`OP_2DIV`	`0x8e`	`x → x/2`
`OP_MUL`	`0x95`	`a b → a*b`
`OP_DIV`	`0x96`	`a b → a/b`	It truncates. The script fails if `b` is 0.
`OP_MOD`	`0x97`	`a b → a%b`	The result has the sign of `a`. The script fails if `b` is 0.
`OP_LSHIFT`	`0x98`	`x n → x<<n`	It discards sign data.
`OP_RSHIFT`	`0x99`	`x n → x>>n`	It discards sign data.

New

Opcode	Hex	Stack	Notes
`OP_NUM2BIN`	`0xd7`	`num size → bytes`	The script fails if the number does not fit in `size` bytes.
`OP_BIN2NUM`	`0xd8`	`bytes → num`	The result is minimally encoded.
`OP_MODEXP`	`0xda`	`base exp modulus → result`	Each operand has at most 64 bytes. The script fails if `modulus` is 0 or less, or if `exp` is negative.

Cryptography

OP_CHECKSIG, OP_CHECKSIGVERIFY, and OP_CHECKSIGADD keep their words but check a different digest (Signature checks). OP_CHECKMULTISIG and OP_CHECKMULTISIGVERIFY fail, as in tapscript. Use OP_CHECKSIGADD. These opcodes are new:

Opcode	Hex	Stack	Notes
`OP_DIGEST`	`0xc3`	`data hash_type → hash`	`hash_type` `1` is SHA-256, `2` is SHA-1, `3` is RIPEMD-160, `4` is Keccak-256, and `5` is SHA3-256. Other values fail the script.
`OP_CHECKSIGFROMSTACK`	`0xcc`	`sig message pubkey → True/false`	It checks a 64-byte signature over `message`. The key is a 32-byte x-only Schnorr key, `0x10` plus a compressed secp256k1 key (ECDSA), or `0x11` plus a compressed P-256 key (ECDSA). An ECDSA message must be a 32-byte digest.
`OP_MERKLEBRANCHROOT`	`0xb3`	`leaf_tag branch_tag proof leaf_data → computed_root`	It uses BIP-341 tagged hashes and sorts siblings in lexicographic order. An empty `leaf_tag` means that `leaf_data` (32 bytes) is already a hash. `OP_MERKLEBRANCHVERIFY` is an alias.
`OP_SIGHASH`	`0xf6`	`hashType → sighash`	It pushes the digest that `OP_CHECKSIG` checks in the same context (Signature checks). The flag must be `0x00`, `0x01`, `0x02`, `0x03`, `0x81`, `0x82`, or `0x83`. The `SIGHASH_SINGLE` flags need an output at the input index.
`OP_SHA256INITIALIZE`	`0xc4`	`data → state`
`OP_SHA256UPDATE`	`0xc5`	`data state → newState`
`OP_SHA256FINALIZE`	`0xc6`	`data state → hash`

Elliptic curves

All opcodes in this group are new. curve_id selects the curve. Coordinates are BigNums.

`curve_id`	Curve	Operations
`0`	`secp256k1`	addition, scalar multiplication
`1`	`secp256r1` (NIST P-256)	addition, scalar multiplication
`2`	`alt_bn128` (BN254)	addition, scalar multiplication, pairing

Opcode	Hex	Stack	Notes
`OP_ECADD`	`0xe0`	`x1 y1 x2 y2 curve_id → x3 y3`	The pair of zeros is the point at infinity.
`OP_ECMUL`	`0xe1`	`x y k curve_id → x2 y2`	A scalar `k` of 0 gives the point at infinity.
`OP_ECPAIRING`	`0xe2`	`[g1_x g1_y g2_x_c1 g2_x_c0 g2_y_c1 g2_y_c0]... pair_count curve_id → bool`	It supports `alt_bn128` only, with at most 16 pairs.
`OP_ECMULSCALARVERIFY`	`0xe3`	`k P Q → Nothing/fail`	It checks that `Q` is `k` times `P` on secp256k1. `k` has 32 bytes. `P` and `Q` are keys in compressed form.
`OP_TWEAKVERIFY`	`0xe4`	`P k Q → Nothing/fail`	It checks that `Q` is `P` plus `k` times the generator point. `P` is a 32-byte x-only key. `k` is a 32-byte big-endian scalar. `Q` is a compressed point.

Locktime and time

OP_CHECKLOCKTIMEVERIFY and OP_CHECKSEQUENCEVERIFY work as in Bitcoin Script. They compare with the locktime of the spending transaction and the sequence of the input. The SDK builds covenant spends with nLockTime 0, so these opcodes cannot control those spends. These opcodes are new:

Opcode	Hex	Stack	Notes
`OP_PUSHEXPIRY`	`0xdb`	`→ expiry`	The script fails if no expiry is available.
`OP_CHECKTIME`	`0xdc`	`timestamp → bool`	A future timestamp gives false. A negative timestamp fails the script.

OP_CHECKTIME checks the clock of the Emulator, not Bitcoin block time. The first script below fails before a time threshold, and the second script passes from the given number of seconds before the virtual output expires.

<timestamp> OP_CHECKTIME OP_VERIFY
OP_PUSHEXPIRY <seconds> OP_SUB OP_CHECKTIME OP_VERIFY

The clock is the clock of the machine that runs the Emulator. Nitro Enclaves explains how an enclave controls it.

Transaction introspection

All opcodes in this group are new. Inputs

Opcode	Hex	Stack	Notes
`OP_INSPECTINPUTOUTPOINT`	`0xc7`	`index → txid index`
`OP_INSPECTINPUTARKADESCRIPTHASH`	`0xc8`	`index → script_hash`	The hash tweaks the Emulator key. The script fails if the input has no entry.
`OP_INSPECTINPUTVALUE`	`0xc9`	`index → value`	It is the value of the previous output that the input spends.
`OP_INSPECTINPUTSCRIPTPUBKEY`	`0xca`	`index → program version`	For a witness program, it pushes the program and its segwit version. Otherwise it pushes the SHA-256 of the scriptPubKey and `-1`.
`OP_INSPECTINPUTSEQUENCE`	`0xcb`	`index → sequence`
`OP_PUSHCURRENTINPUTINDEX`	`0xcd`	`→ index`
`OP_INSPECTINPUTARKADEWITNESSHASH`	`0xce`	`index → witness_hash`	It pushes 32 zero bytes if the witness is empty. The script fails if the input has no entry.

Outputs

Opcode	Hex	Stack	Notes
`OP_INSPECTOUTPUTVALUE`	`0xcf`	`index → value`
`OP_INSPECTOUTPUTSCRIPTPUBKEY`	`0xd1`	`index → program version`	For a witness program, it pushes the program and its segwit version. Otherwise it pushes the SHA-256 of the scriptPubKey and `-1`.

Transaction

Opcode	Hex	Stack	Notes
`OP_INSPECTVERSION`	`0xd2`	`→ version`
`OP_INSPECTLOCKTIME`	`0xd3`	`→ locktime`
`OP_INSPECTNUMINPUTS`	`0xd4`	`→ numInputs`
`OP_INSPECTNUMOUTPUTS`	`0xd5`	`→ numOutputs`
`OP_TXWEIGHT`	`0xd6`	`→ weight`	The weight is four times the stripped size of the transaction.
`OP_TXID`	`0xf3`	`→ txid`

Packets and intents

All opcodes in this group are new. OP_INSPECTPACKET and OP_INSPECTINPUTPACKET read ARK extension packets, for example the asset packet.

Opcode	Hex	Stack	Notes
`OP_INSPECTPACKET`	`0xf4`	`packet_type → content 1 (or <empty> 0)`	It reads the current transaction. On a hit, it pushes the raw packet content and `1`. Otherwise it pushes an empty array and `0`.
`OP_INSPECTINPUTPACKET`	`0xf5`	`packet_type input_index → content 1 (or <empty> 0)`	It reads the previous Arkade transaction that the input spends. The script fails if `input_index` is negative or out of range.
`OP_INSPECTINTENTMESSAGE`	`0xf8`	`path → value 1 (or <empty> 0)`	Only an intent proof sets the message. Otherwise the opcode pushes an empty array and `0`. `path` is dot-separated lowercase keys and array indexes, for example `outpoints.0`. The script fails if the value is more than 520 bytes.

Continuation

OP_TUNNEL is new. It expresses native delegation: someone other than the owner renews a virtual output in each batch settlement.

Opcode	Hex	Stack	Notes
`OP_TUNNEL`	`0xf7`	`output_index flags [asset_txid asset_gidx]... exception_count → True/fail`	The output at `output_index` must keep the input fields that `flags` selects. `1` is the logical virtual output scriptPubKey, `2` is the value of the directly spent output, and `4` is the input-local assets. Flags add up and must not be 0. The check skips the Asset IDs before `exception_count`. They need flag `4`.

Assets

All opcodes in this group are new. An Asset ID has two stack items: asset_txid, the ID of the issuance transaction, and asset_gidx, the group index of the issuance. k is the position of a group in the asset packet of the transaction. OP_FINDASSETGROUPBYASSETID converts an Asset ID to k. The source transaction ID of an intent input is not an Asset ID.

Opcode	Hex	Stack	Notes
`OP_INSPECTNUMASSETGROUPS`	`0xe5`	`→ K`
`OP_INSPECTASSETGROUPASSETID`	`0xe6`	`k → asset_txid asset_gidx`
`OP_INSPECTASSETGROUPCTRL`	`0xe7`	`k → control_asset_txid control_asset_gidx 1, or empty_bytes 0 0`	If the group has no control asset, it pushes `empty_bytes` and two zeros.
`OP_FINDASSETGROUPBYASSETID`	`0xe8`	`asset_txid asset_gidx → k 1, or 0 0`	If the packet has no such group, it pushes two zeros.
`OP_INSPECTASSETGROUPMETADATAHASH`	`0xe9`	`k → hash32`	It is the immutable metadata Merkle root from genesis.
`OP_INSPECTASSETGROUPNUM`	`0xea`	`k source_u8 → count_u16 or in_u16 out_u16`	For `source`, `0` means inputs, `1` means outputs, and `2` means both.
`OP_INSPECTASSETGROUP`	`0xeb`	`k j source_u8 → type_u8 [data...] amount`	`source` `0` reads an input and `1` reads an output. A local input gives the type `1`, the input index, and the amount. An intent input gives the type `2`, the transaction ID, the output index, and the amount. A local output gives the type `1`, the output index, and the amount.
`OP_INSPECTASSETGROUPSUM`	`0xec`	`k source_u8 → sum or in_sum out_sum`	The sum cannot overflow. For `source`, `0` means inputs, `1` means outputs, and `2` means both.
`OP_INSPECTOUTASSETCOUNT`	`0xed`	`o → n`
`OP_INSPECTOUTASSETAT`	`0xee`	`o t → asset_txid asset_gidx amount`
`OP_INSPECTOUTASSETLOOKUP`	`0xef`	`o asset_txid asset_gidx → amount 1, or 0 0`	If the asset is absent, it pushes two zeros.
`OP_INSPECTINASSETCOUNT`	`0xf0`	`i → n`
`OP_INSPECTINASSETAT`	`0xf1`	`i t → asset_txid asset_gidx amount`	`asset_txid` is always the issuance transaction ID.
`OP_INSPECTINASSETLOOKUP`	`0xf2`	`i asset_txid asset_gidx → amount 1, or 0 0`	If the asset is absent, it pushes two zeros. It never accepts the source transaction ID of an intent input as an Asset ID.

Reserved

OP_NOP1 and OP_NOP5–OP_NOP10 do nothing. OP_RESERVED, OP_VER, OP_VERIF, OP_VERNOTIF, OP_RESERVED1, OP_RESERVED2, and each unassigned value fail the script.

Advanced

Key tweak

A covenant leaf uses the Emulator key. The hash of the Arkade Script of the leaf tweaks the key:

h = tagged_hash("ArkScriptHash", script)
P_tweaked = P_even + int(h)·G

P_even is the Emulator key with even y. The tweak binds the key to one script. A different script gives a different key, so nobody can show another script when the Emulator signs. The SDK function computeArkadeScriptPublicKey calculates P_tweaked. OP_INSPECTINPUTARKADESCRIPTHASH pushes h.

Signature checks

OP_CHECKSIG, OP_CHECKSIGVERIFY, OP_CHECKSIGADD, and OP_SIGHASH use a digest that is not the BIP342 digest. There are two differences. The final BIP-340 tag is ArkadeTapSighash, not TapSighash. A signature for one digest fails for the other. The digest also ignores the witness of each Emulator Packet entry: the witness length is 0 in sha_outputs. A party can sign a script before anyone gives witness arguments. The arguments can change between spend attempts. The signatures that the Emulator adds to the transaction use the standard BIP342 digest. The TypeScript SDK does not calculate the Arkade digest. To check a signature over your own message, use OP_CHECKSIGFROMSTACK. The complete function of the escrow vault does this.

Emulator Packet

An Emulator Packet carries the script and the witness of each covenant input. It is a TLV record of type 0x01 in an ARK extension. An ARK extension is an OP_RETURN output that starts with the bytes ARK (0x41524b). The README gives the format and the limits. OP_INSPECTPACKET and OP_INSPECTINPUTPACKET read the packet bytes. A script that uses them depends on the exact byte format. A format change is a protocol change.

Compute limits

The Emulator limits how many times each heavy opcode can run in one input. Other opcodes have no limit. One request can use the limits of 4 inputs in total. An operator can change the limits with EMULATOR_COMPUTE_LIMITS.

Opcode	Maximum runs in one input
`OP_CHECKSIG`, `OP_CHECKSIGVERIFY`, `OP_CHECKSIGADD`, `OP_CHECKSIGFROMSTACK`	50 each
`OP_ECMUL`, `OP_ECMULSCALARVERIFY`, `OP_TWEAKVERIFY`	50 each
`OP_ECADD`	1000
`OP_ECPAIRING`	2
`OP_MODEXP`	64
`OP_INSPECTINTENTMESSAGE`	16

Endpoints

The /v1/info endpoint returns signerPubkey and deprecatedSignerPubkeys.

Network	URL	Key pinned in the SDK
Mutinynet	`https://emulator.mutinynet.arkade.sh`	`03f823b9…af889a`
Regtest (arkade-regtest)	`http://localhost:7073`	`02999413…5fb2a9`

Other networks have no pin. Pass the key of the Emulator as emulatorPubkey to Arkade.connect.

Check the pinned key

The SDK builds covenants with the key that it pins for the network, and it never uses the key that the Emulator reports. If this code prints false, the Emulator has a new key. Halt covenant operations and verify the cause before you upgrade @arkade-os/sdk — a mismatch can also indicate a compromised key or a man-in-the-middle at the network boundary. During a key rotation, the Emulator also signs with deprecated keys. The operator can set EMULATOR_DEPRECATED_KEYS_VALID_UNTIL to end that period.

emulator-key.ts

import { MUTINYNET_EMULATOR_PUBKEY, RestEmulatorProvider } from "@arkade-os/sdk";

const emulator = new RestEmulatorProvider("https://emulator.mutinynet.arkade.sh");
const { signerPubkey } = await emulator.getInfo();
console.log(signerPubkey === MUTINYNET_EMULATOR_PUBKEY); // true

​Bitcoin Script and Arkade Script

​How a covenant spend is checked

​Opcodes

​Same as Bitcoin Script

​Stack

​Splice

​Bitwise logic

​Arithmetic

​Cryptography

​Elliptic curves

​Locktime and time

​Transaction introspection

​Packets and intents

​Continuation

​Assets

​Reserved

​Advanced

​Key tweak

​Signature checks

​Emulator Packet

​Compute limits

​Endpoints

​Check the pinned key