Skip to main content
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 enforces these additional opcodes and spending conditions, which Bitcoin alone cannot validate, by cosigning the spends that run them.

Bitcoin Script and Arkade Script

A contract’s output is a Taproot output: either a virtual output, or an ordinary Bitcoin output that never enters the virtual mempool. Its script tree holds two kinds of spending path. A consensus-enforceable path is Bitcoin Script that Bitcoin nodes check when someone spends through it onchain. The CSV exit path is one of these, and it needs no signature from the operator or the emulator. An emulator-enforced path holds a spending condition in Arkade Script, which Bitcoin never runs. The part of the path that Bitcoin sees needs two signatures: one from the Arkade operator, one from the emulator key. The script itself tweaks that key, binding it to this one script (see Key tweak). The emulator signs only if the script passes. You write contracts in Arkade Script, and arkadec makes both kinds of path. The Bitcoin Script wiki lists the opcodes of Bitcoin.

How an emulator-enforced spend is checked

  1. The wallet adds an Emulator Packet to the Arkade transaction. The packet holds the Arkade Script and the witness of each input that spends through an emulator-enforced path.
  2. The wallet sends the transaction to the /v1/tx endpoint of the emulator.
  3. The emulator runs each script in the packet against the transaction.
  4. The emulator signs only if each script succeeds.
  5. 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

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

Stack

OP_PUT is new.

Splice

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

Bitwise logic

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

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 New

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:

Elliptic curves

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

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 emulator-enforced spends with nLockTime and sequence 0, so these opcodes cannot control those spends. These opcodes are new: OP_CHECKTIME checks the clock of the emulator, not Bitcoin block time. The first script below fails before a time threshold, and the second passes once the virtual output is within the given number of seconds of its expiry.
The clock is the clock of the machine that runs the emulator.

Transaction introspection

All opcodes in this group are new. Inputs Outputs Transaction

Packets and operator-request inputs

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

Continuation

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

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 operator-request input is not 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

An emulator-enforced path uses the emulator key. The hash of the Arkade Script of the path tweaks the key:
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 emulator-enforced 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. Whoever runs the emulator can change the limits with EMULATOR_COMPUTE_LIMITS.

Endpoints

The /v1/info endpoint returns signerPubkey. The SDK also pins a mainnet key, BITCOIN_EMULATOR_PUBKEY. Signet and other networks have no pin: pass the key of the emulator as emulatorPubkey to Arkade.connect.

Check the pinned key

The SDK builds emulator-enforced paths 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 emulator-enforced spends 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. Whoever runs the emulator can set EMULATOR_DEPRECATED_KEYS_VALID_UNTIL to end that period.
emulator-key.ts