Script

Category: Utility · Node Type ID: utility-script

Runs a built-in script (Python subset) over bytes/int/bool/string ports

Overview

Executes a sandboxed, deterministic Python-subset script over user-defined dynamic input and output ports of types Bytes, Int, Bool, and String. Every dynamic input port is bound as a read-only variable by its port name (standardized to valid identifiers), and the script must assign a value of the matching type to every declared dynamic output port variable before finishing.

The built-in Script engine supports arbitrary-precision int arithmetic, first-class bit/byte indexing and slicing (b.bit[i], b[offset, len]), loops with a static safety bound, user-defined functions, and a rich standard library of cryptographic helpers, finite-field arithmetic (gf2_128_mul), and byte/integer conversions. See the dedicated Script Guide for the complete language reference.

When to Use

Implementing custom framing, TLV/ASN.1 parsing, subkey derivation, or finite-field arithmetic that would require many individual utility nodes.
Prototyping custom cryptographic algorithms, Feistel rounds, or protocol state transitions directly inside a workflow.

Parameter Configuration

Parameter (ID)	Type & Default	Visibility Condition	Description & Options
Code `code`	`textarea` Default: `""` (empty)	Always visible	Python-subset source code executed when the node runs. See Syntax, Types, Built-in Functions, and Error Codes.
Unify Errors `errorUnify`	`boolean` Default: `false` Supports Variable Reference (`$var`: `bool`)	Always visible	When enabled (`true`), replaces any compile-time or runtime script error (`SCRIPT_` / `BYTES_`) with the single custom error code and message configured below.
Unified Error Code `errorUnifyCode`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error code emitted when Unify Errors is enabled.
Unified Error Message `errorUnifyMessage`	`text` Default: `""` (empty) Supports Variable Reference (`$var`: `string`)	When `errorUnify` is `true`	Custom error message emitted when Unify Errors is enabled.

Port I/O Specification

See Ports & Connections for general wiring rules, data type colors, and dynamic port creation.

Input Ports

Attribute	Specification
Port Nature	Dynamic / Variable Input Ports
Initial Default on Canvas	Starts with 0 input ports (`inputs: []`).
Port Count Range	0 or more input ports.
Allowed Data Types	`Bytes`, `Int`, `Bool`, or `String`.
Adding & Managing Ports	Add input ports in the Script inspector or drag an upstream wire onto the `[+]` input handle on the left side of the card. Each port's name becomes a variable in the script scope.
Evaluation & Ordering Rule	Each input port is bound by its identifier name in the script global scope before execution starts.

Output Ports

Attribute	Specification
Port Nature	Dynamic / Variable Output Ports
Initial Default on Canvas	Starts with 0 output ports (`outputs: []`).
Port Count Range	0 or more output ports.
Allowed Data Types	`Bytes`, `Int`, `Bool`, or `String`.
Adding & Managing Ports	Add output ports in the Script inspector or drag from the `[+]` output handle on the right side of the card to a downstream node.
Evaluation & Ordering Rule	Every declared output port variable must be assigned a value of its declared type along all execution paths (verified by static analysis before execution).

Error Cases

When any of the following conditions occurs at runtime, this node transitions to an ERROR state and downstream nodes connected to its outputs do not execute. Enabling Unify Errors (errorUnify) replaces all error codes below with your configured unified error code and message.

Error Code	Default Engine Message	Trigger Condition
`BYTES_OUT_OF_RANGE`	Index or range is outside the value	Raised when a byte or bit index/slice range falls outside the valid bounds of the buffer.
`BYTES_LENGTH_MISMATCH`	Two values that must be the same length differ in length	Raised when connected byte array operands do not all have the exact same byte length.
`BYTES_INT_OVERFLOW`	The integer cannot be represented with the given length and sign	Raised when the integer value cannot fit within the specified fixed or port byte length.
`BYTES_INVALID_HEX`	Invalid hex string	Raised when a hexadecimal input field contains non-hex characters or an odd digit count.
`BYTES_INVALID_UTF8`	The bytes cannot be decoded as UTF-8	Raised when a byte sequence is not valid UTF-8.
`BYTES_INVALID_ARGUMENT`	Invalid argument value	Raised when an argument (such as bit shift count, byte length, or negative integer) is invalid or negative.
`BYTES_SIZE_LIMIT`	Result length exceeds the limit	Raised when the resulting byte buffer would exceed the engine's maximum allocation limit.
`SCRIPT_COMPILE_ERROR`	The script failed validation	Raised when the script fails syntax checking, static type checking, or output-assignment verification before execution. See Script Error Codes.
`SCRIPT_DIVISION_BY_ZERO`	Division by zero	Raised when the script attempts integer division (`//`) or modulo (`%`) by `0`.
`SCRIPT_INDEX_OUT_OF_RANGE`	List index or range is out of range	Raised when a script list, byte, or bit index is out of bounds.
`SCRIPT_INVALID_ARGUMENT`	Invalid argument value	Raised when a built-in script function receives an out-of-domain argument.
`SCRIPT_INVALID_ERROR_CODE`	The code passed to fail uses a reserved prefix	Raised when `fail(code, msg)` is called with a reserved system prefix.
`SCRIPT_SIZE_LIMIT`	int bit count or list length exceeds the limit	Raised when a script integer bit width or list/bytes length exceeds the sandbox safety limit.
`SCRIPT_STEP_LIMIT`	Execution step limit exceeded	Raised when a script exceeds the maximum allowed execution steps.
`SCRIPT_TIMEOUT`	Execution time limit exceeded	Raised when a script exceeds the maximum wall-clock execution time.
`SCRIPT_INTERNAL_ERROR`	Internal error in the script interpreter	Raised on an unexpected internal error in the script interpreter.

Examples

Computing GF(2^128) Doubling on a 16-Byte Block

Use a Script node with one Bytes input (blk) and one Bytes output (out).

Add an input port named blk (Bytes) and an output port named out (Bytes).
Enter the script: msb = blk.bit[0]; shifted = shl(blk, 1); out = xor(shifted, 0x00000000000000000000000000000087) if msb == 1 else shifted.