Nexa Script Debugger

This webapp allows you to test and debug smart contracts written for the Nexa blockchain. Please use on landscape aspect ratio devices.

This is unfinished software, so it WILL have issues! Please report issues here!

Basic Layout

The scripts that are to be run are shown in tabs near this help. The Nexa Script Machine state is shown on the right. This consists of a banner showing machine registers and status, and two large windows showing the main and alt stacks.

The main and alt stacks grow downwards. The first element on the stack is at the BOTTOM of the screen. Why? Because the stack is represented in the same direction as scripts push, so a script "1 2 3" results in a stack shown as "1 2 3", not "3 2 1". Trust me, if you do a lot of script debugging you'll thank me for this!

Each stack line comprises the index from the top, the data type, the length, the hex representation of the item, and the "natural" representation. This last representation depends on the type of the item.

In the top bar you see a few buttons. The "<<<" button reinitializes Script Machine state. The "<<" button rewinds to the beginning of the template script. The ">>" button continues execution of the current script, while the ">" button steps.

Simple Script

Cut and paste a script into the "template" tab. A clean script machine will be initialized. Try the following script. Note that the first number is a 256-bit little-endian sign magnitude number specified as a byte array. So if you read it backwards and note that the last byte 00 is the sign you may recognise it.

0x2ffcfffffeffffffffffffffffffffffffffffffffffffffffffffffffffffff00 SETBMD

This script demonstrates large integer (bignum) capabilities and how all bignum operations are modulo the Bignum Modulo Divisor (BMD). Run this python equivalent and match the printouts with the top of the stack (occasionally -- every step does not match) as the script executes:

BMD = 0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f
tmp = 1 + (1<<16)
tmp = tmp + (tmp<<16)
for i in range(0,8):
   tmp = (tmp*tmp)%BMD

Nexa Machine State Setup

Interesting scripts can access information within the current transaction and in the outpoints being spent. To set up some state data get the hex dump of two transactions, one of which spends an output of the other. The two transactions should be separated by whitespace. Cut and paste both of these transactions into this window.

Here is an example for you to try:


After pasting, the debugger will automatically do the following steps:

  • Based on the two transactions determine which input/output you are interested in
  • Discover the relevant scripts
  • Load the script, prevouts, and transaction state into the Nexa Script Machine (other prevouts get empty data)
  • Execute all push-only scripts (constraint and satisfier), and pause at the beginning of the template script

So you should see the "Constraint" and "Satisfier" tabs filled with 1 data push each, and the "Template" tab filled with 2 instructions: "FROMALTSTACK CHECKSIGVERIFY". This is the standard "Pay-to-script-template" Nexa transaction. It is similar to the "pay-to-public-key-hash" format of Bitcoin/Bitcoin Cash, except that the constraint script supplies the pubkey and the satisfier script supplies the signature.

Now use the ">" button to step through execution of this code, until the script succeeds.

You can use the "<<" button to restart the template script execution. Or you can use the "<<<" button to rewind to the very beginning and watch the constraint and satisfier scripts execute as well (since they may ONLY push data onto the alt and main stacks respectively the debugger by default automatically executes these for you).

Debug different scripts

With the 2 transactions still loaded, write a simple script and paste it into the template script buffer.

For example:

You can see template script change. Note that your instruction pointer will not change. Depending on how different the new script is, you may need to reset the machine. Step through this script and in the last instruction you will see a failure in the "Nexa Machine Status":

Signature must be zero for failed CHECK(MULTI)SIG operation(39)

What happened here? Well, you changed the script, and therefore the transaction. But the transaction's signature was unchanged (the first push in the satisfier script), so the signature failed.

Numerical Example

Try pasting the above example into the template script and stepping through it. You can see that the 0x02 produces a machine error "data larger than necessary". This is not a minimally encoded number, so the script fails at that point. Because this is a debugger though, you can continue as if the error never happened.


You can launch this debugger via a link. If you are debugging a script template, most of the data is available in the transaction. So you can just specify the transaction hex and which input to debug: Try /tx/000100010200000000000000000000000000000000000000000000000000000000003207036c7575015153ffffffffe80300000000000001008403000000000000015100000000?idx=0

Note the warning that appears when the debugger sets itself up. This warning is because some information is missing, so the debugger hopes that your scripts won't use that data. If your script template DOES access the missing data -- outpoint data or constraint script public arguments, then you will need to specify additional parameters to this URL as follows: /tx/000100010200000000000000000000000000000000000000000000000000000000003207036c7575015153ffffffffe80300000000000001008403000000000000015100000000?idx=0&utxo=01e8030000000000002b00147d4861012039dab2c9f78120a4a50d2c85db9af214da1745e9b549bd0bfa1a569971c77eba30cd5a4b
The utxo parameter is a network serialized transaction output (see libnexakotlin NexaTxOutput).


This spend simply adds 3 numbers and verifies they equal 5. One number is provided by the satisfier, hidden constraints and public constraints each. Try pasting a script with different numbers into the constraint or satisfier, restart the script machine to the beginning (<<<) and step thru to see it fail.
Nexa Machine status:
Main Stack
Alt Stack