@nexscript/interpreter

Consensus-exact Nexscript interpreter and step-debugger, ported from Nexa's src/script/interpreter.cpp.

Features

• ScriptMachine — full opcode execution engine supporting stack manipulation, control flow, arithmetic, hashing, signatures, locktime, transaction introspection, and extended BigNum operations
• DebugSession — step-by-step debugger over unoptimised bytecode with source-span mapping via debugMap
• Signature checking — TxSignatureChecker (consensus-real, bound to a spending transaction) and DataOnlySignatureChecker (data signatures only, no transaction context)
• BigNum support — arbitrary-precision integer stack items with configurable modulo (OP_SETBMD)
• Script flags — a ScriptFlags bitfield mirroring the node's script_flags.h; SCRIPT_UPGRADE2_OPCODES gates bug-for-bug pre/post-hard-fork behaviour (bignum operand order, control-opcode checks)

Installation

npm install @nexscript/interpreter
# or
yarn add @nexscript/interpreter

Usage

Running a script

import { ScriptMachine } from '@nexscript/interpreter'
import { Script } from 'libnexa-ts'

const machine = new ScriptMachine()
machine.beginStep(Script.fromASM('OP_1 OP_2 OP_ADD'))
machine.continue()
machine.endStep()
// machine.stack => [ <Buffer 03> ]

Step debugging

import { DebugSession, DebugSpan } from '@nexscript/interpreter'

const debugMap: DebugSpan[] = [
  { start: 0, end: 1, kind: 'OP_1', location: { start: { line: 1, column: 0 }, end: { line: 1, column: 4 } } },
  { start: 1, end: 2, kind: 'OP_2', location: { start: { line: 1, column: 5 }, end: { line: 1, column: 8 } } },
]

const session = new DebugSession('OP_1 OP_2 OP_ADD', { debugMap })
let frame = session.step()
while (!session.isDone()) {
  console.log(`pos: ${frame.pos}, span: ${frame.span?.kind}, stack: ${frame.stack.length}`)
  frame = session.step()
}
console.log('succeeded:', session.succeeded())

Evaluating an unlocking script

import { evalUnlockingScript } from '@nexscript/interpreter'

const stack = evalUnlockingScript('OP_1 OP_2 OP_3')
// stack => [ <Buffer 01>, <Buffer 02>, <Buffer 03> ]

Signature verification

import { TxSignatureChecker, DataOnlySignatureChecker, verifyDataSignature } from '@nexscript/interpreter'

// Data-only (no transaction context)
const valid = verifyDataSignature(sigBytes, message, pubkeyBytes)

// Transaction-bound (consensus-real OP_CHECKSIG)
const checker = new TxSignatureChecker(tx, inputIndex, subscript)
const machine = new ScriptMachine({ signatureChecker: checker })

API

| Export | Description | |---|---| | ScriptMachine | Full script execution engine | | MachineConfig | Configuration for ScriptMachine | | StackItem | Union type: Uint8Array \| BigNumItem | | DebugSession | Step-debugger with source-span mapping | | DebugSpan | Source span interface (emitted by nexc compiler) | | DebugFrame | Machine state snapshot after each step | | evalUnlockingScript | Run a push-only script and return resulting stack | | spanForPos | Find the innermost debug span covering a position | | ScriptError | Enum of all script error codes | | BigNumItem | Arbitrary-precision integer stack item | | isBigNum | Type guard for BigNumItem | | decodeBigNum / encodeBigNum | BigNum serialization | | decodeScriptNum | CScriptNum decoding with overflow/minimality checks (encode via @nexscript/utils minimallyEncodeInt) | | TxSignatureChecker | Transaction-bound signature verifier | | DataOnlySignatureChecker | Data-signature-only verifier | | verifyDataSignature | Standalone data signature verification | | SignatureChecker | Interface for signature checking | | ImportedState | Transaction context interface | | GroupBalance | Per-group aggregate balance | | TxStateSpecifier | Enum of OP_PUSH_TX_STATE specifiers | | ScriptFlags | Script verify flags bitfield (mirrors the node's script_flags.h) | | DEFAULT_SCRIPT_FLAGS | Default flags used when MachineConfig.flags is omitted | | setFlag / hasFlag | Set/clear and test flag bits |

Dependencies

• libnexa-ts ^3.0.3
• @nexscript/utils ^1.1.1

License

MIT