Smart Contracts

The POSITRONIC upgrade turns Neurai from a transaction-and-asset chain into a programmable covenant environment. It does this by adding a large set of new script opcodes, a transaction-introspection layer, reference inputs (transaction v3), and AuthScript — a new execution model that decouples authentication (who may spend) from authorization (under what conditions), and that natively supports post-quantum ML-DSA-44 signatures.

This page is the technical reference for the scripting layer. For the upgrade overview (blocks, DePIN messaging, MCP, wallets), see the POSITRONIC upgrade page.

How It Fits Together​

POSITRONIC scripting rests on four pillars:

1. Introspection — scripts can read fields of the spending transaction (its outputs, inputs, locktime, values, asset payloads) and of the chain itself (height, median-time-past, chain id). Before POSITRONIC, a script could only validate the data handed to it; now it can constrain the transaction that spends it.
2. Covenants — OP_CHECKTEMPLATEVERIFY and OP_CHECKSIGFROMSTACK, combined with OP_CAT / OP_SPLIT and 64-bit arithmetic, let an output dictate the shape of the transaction that spends it. This is the basis for vaults, congestion control, DEX sell-orders and atomic swaps.
3. Reference inputs (tx v3) — a new vrefin section lets a script read an existing UTXO without spending it, providing oracles and external state to covenants.
4. AuthScript & Post-Quantum — a witness-v1 execution model whose spending condition is a 32-byte commitment, with pluggable authentication: none, post-quantum (ML-DSA-44), or legacy secp256k1.

Each new opcode is gated by its own SCRIPT_VERIFY_* flag. A flag that occupies a previously unassigned opcode slot fails closed (BAD_OPCODE) on old nodes; a flag that re-purposes a NOP/reserved slot degrades to a no-op unless DISCOURAGE_UPGRADABLE_NOPS is set. This is what makes the rollout a clean soft-fork-style activation.

Opcode Catalogue​

All opcodes below are Active (implemented with consensus handlers) unless noted. Stack effect notation is (before -- after), top of stack on the right.

Transaction Introspection​

Covenants & Signatures​

Byte Manipulation & Arithmetic​

Asset Introspection​

Reference Inputs (tx v3)​

Output Authentication​

Modern & SNARK-Friendly Hashes​

Covenants​

A covenant is a spending condition that constrains the transaction allowed to spend an output. POSITRONIC offers two complementary covenant primitives.

OP_CHECKTEMPLATEVERIFY (CTV)​

What it does. OP_CHECKTEMPLATEVERIFY (0xb3) commits an output to an exact template of the transaction that may spend it: its version, locktime, input count, sequences, output set, and the index of the spending input. If the spending transaction does not hash to the committed 32-byte template, the script fails.

Characteristics.

• No signature is needed — CTV is self-verifying by consensus rule.
• The hash is not consumed on success (NOP-upgrade semantics), so scripts usually follow it with OP_DROP.
• A non-32-byte argument behaves as a NOP unless DISCOURAGE_UPGRADABLE_NOPS rejects it as non-standard.
• Maximally rigid: it fixes every output down to the satoshi. This is its strength (anti-double-spend, deterministic outcome) and its limit (no dynamic amounts on its own).

Template fields committed by the default CTV hash:

SHA256(
  nVersion        (4 bytes LE)
  nLockTime       (4 bytes LE)
  inputCount      (4 bytes LE)
  SHA256(all sequences)
  outputCount     (4 bytes LE)
  SHA256(all serialized outputs)
  inputIndex      (4 bytes LE)
)

Example — fixed three-way distribution. An output that can only ever be spent into a transaction paying 30 / 50 / 20 XNA to three predetermined recipients:

witnessScript:
  <32-byte-CTV-hash>
  OP_CHECKTEMPLATEVERIFY
  OP_DROP
  OP_TRUE

Spending it requires no key; only a transaction whose outputs hash to the committed template is valid.

OP_CHECKSIGFROMSTACK (CSFS)​

What it does. OP_CHECKSIGFROMSTACK (0xb4) verifies a signature over a message that is popped from the stack rather than computed from the transaction. This breaks the assumption that a signature must commit to a specific transaction, enabling oracles and delegation.

Characteristics.

• The message can be any bytes: a price, a contract term, a commitment.
• Accepts both secp256k1 (33-byte pubkey) and ML-DSA-44 (0x05-prefixed, 1313-byte pubkey).
• The per-element size cap widens from 520 to 3072 bytes whenever CSFS is enabled, so it can carry a 2421-byte PQ signature and a 1313-byte PQ public key.

Example — oracle-gated spend. A script that only proceeds if a trusted oracle signed a particular price:

witness: [ price_bytes, oracle_sig, witnessScript ]

witnessScript:
  <oracle_pubkey>
  OP_CHECKSIGFROMSTACK       # verifies oracle_sig over price_bytes
  OP_VERIFY
  ...                        # downstream logic can now trust price_bytes

Building Templates Dynamically — CAT, SPLIT, 64-bit Math​

CTV alone commits to a static template. To express partially fixed transactions (the seller's payout is fixed, the buyer's change is free), a script assembles the template at validation time:

• OP_CAT (0x7e) concatenates fixed prefixes with witness-supplied output bytes.
• OP_SPLIT (0xb7) and OP_REVERSEBYTES (0xbc) parse and re-order serialized fields.
• OP_MUL / OP_DIV / OP_MOD operate on 64-bit signed integers (the old limit was 4 bytes / 32-bit), which is what makes price × quantity checks possible on full XNA amounts.

Transaction v3 and Reference Inputs​

POSITRONIC introduces transaction version 3 with a new vrefin section: a vector of outpoints the transaction references but does not spend.

tx v3 {
  vin     [ ... ]   // spent inputs (consume the UTXO, require auth)
  vrefin  [ ... ]   // reference inputs (read-only, NEW)
  vout    [ ... ]   // outputs
}

Serialization & consensus. vrefin is serialized between vout and nLockTime and only when nVersion == 3. It is committed in the txid/wtxid and the signature hash, so tampering with a reference invalidates signatures and CTV hashes. Each referenced outpoint must exist and be unspent in the UTXO set, must not also appear in vin, and remains in the UTXO set after the transaction confirms. Multiple transactions may reference the same UTXO without conflict.

Why it matters. Reference inputs turn any existing UTXO into a portable, read-only source of state. A covenant can read an oracle's published UTXO, a price tag, or a configuration object without that UTXO being consumed — the foundation for oracles and richer DePIN state machines.

The reference-input opcode family. Three opcodes read vrefin without spending it:

• OP_REFINPUTCOUNT (0xd4) — (-- n).
• OP_REFINPUTFIELD (0xd2) — (index selector -- field) with selectors:
  • 0x01 value (8-byte LE / CScriptNum under 64-bit)
  • 0x02 AuthScript commitment (32 bytes)
  • 0x03 full scriptPubKey (size-capped)
• OP_REFINPUTASSETFIELD (0xd3) — (index selector -- field), with selectors 0x01–0x07 (name, amount, units, reissuable, has-IPFS, IPFS hash, asset type).

All three are gated by SCRIPT_VERIFY_REFINPUTS and degrade to NOPs on nodes that do not recognize the flag.

Asset & Chain Introspection​

Asset fields. OP_OUTPUTASSETFIELD (0xce) and OP_INPUTASSETFIELD (0xcf) parse the Neurai asset payload embedded in a scriptPubKey and push a selected field, so a covenant does not have to hand-parse the serialized asset blob:

Chain context. OP_CHAINCONTEXT (0xd7, NIP-026) exposes blockchain position to a script via a 1-byte selector: 0x01 height, 0x02 median-time-past, 0x03 chain id (0 mainnet / 1 testnet / 2 regtest). Because height and MTP change with the chain tip, the mempool re-validates any transaction whose script observed chain context on each new block.

AuthScript & Post-Quantum​

AuthScript is the headline new script type. It is a witness version 1 program whose witness program is a 32-byte commitment (TX_WITNESS_V1_AUTHSCRIPT), encoded as a Bech32m address. Its purpose is to separate two planes that classic Script conflates:

• Authentication plane — who may spend, verified before the script runs, with the signature and public key kept out of the script stack.
• Script (authorization) plane — under what conditions, evaluated with only the functional arguments on the stack.

This separation is what lets enormous post-quantum keys and signatures coexist with covenant logic: a 2420-byte ML-DSA-44 signature and a 1312-byte public key would blow past the 80-byte standard stack-item limit if they were ordinary stack pushes, so AuthScript validates them outside the script entirely.

Witness Layout​

witness.stack = [
  auth_type,        // 1 byte: 0x00 NoAuth | 0x01 PQ | 0x02 Legacy
  <auth payload>,   // signature + pubkey (absent when auth_type = 0x00)
  arg1 ... argN,    // functional arguments for the script
  witnessScript     // the script to execute (always last)
]

Auth Types​

The verifier enforces type consistency: a 0x01 payload must carry a PQ key and a 0x02 payload must carry a non-PQ key. Under SCRIPT_VERIFY_WITNESS_PUBKEYTYPE, legacy keys must be compressed.

The Commitment​

The 32-byte program in the scriptPubKey (OP_1 0x20 <32 bytes>) is a tagged hash binding the version, the authentication descriptor, and the script:

commitment = TaggedHash("NeuraiAuthScript",
                version_byte ‖ auth_descriptor ‖ SHA256(witnessScript))

where auth_descriptor is 0x00 for NoAuth, or auth_type ‖ Hash160(pubkey) otherwise. The verifier recomputes this from the revealed witnessScript and auth payload and checks it against the committed program before running anything. OP_OUTPUTAUTHCOMMITMENT (0xd5) lets a covenant read this commitment from an output, so one AuthScript can require its spends to flow into specific other AuthScripts.

Signature Hash​

AuthScript introduces a third signature version, SIGVERSION_AUTHSCRIPT (= 2), alongside base and witness-v0. Its sighash preimage uses the literal witnessScript as the scriptCode and additionally commits the auth_type byte, so a signature made under one authentication method cannot be replayed under another.

Post-Quantum Addresses & Derivation​

• Algorithm: ML-DSA-44 (FIPS 204) — private key 2560 B, public key 1312 B, signature 2420 B.
• Address format: Bech32m, witness v1, 32-byte program. HRPs are nq (mainnet), tnq (testnet), rnq (regtest) — e.g. tnq1....
• HD derivation: PQ keys derive under purpose 100', account path m/100'/<coin>'/0', with receiving keys at m/100'/<coin>'/0'/0/i and change at .../1/i. Coin type is 1900' on mainnet and 1' on testnet/regtest. The 32-byte private bytes of each derived child seed the ML-DSA-44 keygen.
• Not WIF-compatible: a 2560-byte ML-DSA-44 secret has no WIF representation and no pubkey-recovery, so PQ keys cannot be swept via WIF import.

Policy Notes​

The auth payload (PQ signature + key) is exempt from the 80-byte standard stack-item limit because it never enters the script stack; functional arguments remain subject to the normal limits. Mempool relay, witness relay and RBF rules were widened to accommodate the larger PQ script elements, and the wallet persists a commitment → spend-data map (auth type, witnessScript, key reference) since the 32-byte commitment alone is not enough to reconstruct how to spend an AuthScript output.

Covenant Patterns​

These are reference patterns built from the primitives above. They are illustrative compositions, not canonical scripts.

Partial-Fill Sell Order (DEX)​

A stateful UTXO that lets buyers purchase fractions of an asset listing without the seller re-signing each fill. The covenant enforces correct payment, correct asset delivery, and that the remainder re-locks into the same covenant.

• Opcodes: OP_OUTPUTVALUE, OP_OUTPUTSCRIPT, OP_OUTPUTASSETFIELD, OP_MUL, plus OP_CHECKSIG on the seller-cancellation path.
• Mechanism: read output 0's value and recipient (payment to seller), read output 1's asset name/amount (delivery to buyer), read output 2's script and remaining amount (the re-locked remainder), and require payment ≥ unit_price × quantity.
• Characteristics: self-enforcing (no seller interaction per fill); first-confirmed transaction wins on contention; seller keeps a privileged cancellation branch.

OP_IF
  # --- public partial-fill branch ---
  0 OP_OUTPUTVALUE   <unit_price> <qty> OP_MUL  OP_GREATERTHANOREQUAL OP_VERIFY
  0 OP_OUTPUTSCRIPT  <seller_spk>                OP_EQUALVERIFY
  1 0x01 OP_OUTPUTASSETFIELD  <asset_name>       OP_EQUALVERIFY
  1 0x02 OP_OUTPUTASSETFIELD  <qty>              OP_EQUALVERIFY
  2 OP_OUTPUTSCRIPT  <same_covenant_spk>         OP_EQUALVERIFY
  2 0x02 OP_OUTPUTASSETFIELD  <total> <qty> OP_SUB OP_EQUALVERIFY
  OP_TRUE
OP_ELSE
  # --- seller cancellation branch ---
  <seller_pubkey> OP_CHECKSIG
OP_ENDIF

Atomic Swap with CTV + CAT​

The seller fixes the output that pays them; the buyer supplies the output that delivers the asset to their chosen address. OP_CAT assembles the full output set at validation time, OP_SHA256 hashes it, and OP_CHECKTEMPLATEVERIFY confirms the assembled template equals the actual transaction. Net effect: a swap where the buyer cannot redirect the seller's payment, the seller cannot redirect the buyer's asset, and the whole thing is atomic.

Mixed Legacy / Post-Quantum Spends​

Because authentication is per-input, a single transaction can mix a legacy ECDSA input and an AuthScript PQ input. Each input verifies under its own auth type; the transaction is atomic. This is the migration path: holders can move value from classical to post-quantum protection one input at a time.

Script Limits & Verification Flags​

Each feature is gated by a dedicated flag (bit position in the script verify bitfield):

(Introspection, byte-op and asset-field opcodes occupy the intervening bits 21–30.)

Native Merkle Inclusion​

OP_CHECKMERKLEINCLUSION (0xc1, NIP-031) verifies that a leaf belongs to a Merkle tree at a given root, with the stack effect (leaf scheme_id proof root -- bool). It supports four tree schemes:

The proof encodes a 1-byte depth (max 32), the sibling hashes, and a direction bitmap. This gives covenants an efficient, native way to validate membership (allow-lists, airdrops, state commitments) without re-implementing the hashing in script.

Proposed (Not Yet Implemented)​

The following are specified in NIPs but are not present in the node code and are documented here for forward visibility:

• Reference Scripts (NIP-015) — publish a witnessScript once in a carrier UTXO and reuse it across transactions via vrefin and a new AUTHSCRIPT_REF witness mode, instead of inlining the script in every spend. Depends on reference inputs (already active).
• Zero-knowledge opcode family (NIP-016 / NIP-018) — OP_ZKVERIFY, OP_ZKVERIFYREF and OP_ZKTXBIND to verify Groth16/BN254 proofs on-chain and bind them to transaction context. No verifier backend or opcode handlers exist yet.

See Also​

• POSITRONIC upgrade overview
• Assets — the asset types these opcodes introspect
• Developer Hub — SDKs and libraries, including @neuraiproject/neurai-scripts (a ScriptBuilder with these opcode constants) and @neuraiproject/neurai-sign-transaction (NoAuth / PQ / Legacy signing)