@neuraiproject/neurai-scripts 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 NeuraiProject
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,546 @@
1
+ # @neuraiproject/neurai-scripts
2
+
3
+ Script-assembly library for Neurai. Provides:
4
+
5
+ - **Core primitives** — opcode constants, `ScriptBuilder`, byte/hex helpers.
6
+ - **Standard scripts** — P2PKH, P2WPKH, P2WSH, AuthScript (+ witness
7
+ builders for legacy ECDSA / PQ ML-DSA-44 / NoAuth / NIP-015 ref spends),
8
+ OP_RETURN null-data, classic m-of-n multisig + P2SH wrapper.
9
+ - **Covenants** — partial-fill sell-order covenant (legacy and PQ variants)
10
+ targeting the **DePIN-Test** opcode set (`OP_OUTPUTSCRIPT`,
11
+ `OP_OUTPUTVALUE`, `OP_OUTPUTASSETFIELD`, `OP_INPUTASSETFIELD`,
12
+ `OP_TXFIELD`, `OP_CHECKTEMPLATEVERIFY`, `OP_CHECKSIGFROMSTACK`, 64-bit
13
+ `OP_MUL`/`OP_SUB`, …).
14
+
15
+ This is the canonical place to add new Neurai script builders; callers
16
+ compose transactions with
17
+ [`@neuraiproject/neurai-create-transaction`](https://www.npmjs.com/package/@neuraiproject/neurai-create-transaction)
18
+ and sign with
19
+ [`@neuraiproject/neurai-sign-transaction`](https://www.npmjs.com/package/@neuraiproject/neurai-sign-transaction).
20
+
21
+ > ⚠️ DePIN-Test opcodes, `OP_CHECKSIGFROMSTACK`, `OP_TXHASH`, and `vrefin`
22
+ > are gated by consensus flags active in **testnet / regtest** today.
23
+ > Mainnet activation follows the fork process described in the NIPs. The
24
+ > library accepts both `xna-test` and `xna` networks so the same call sites
25
+ > work once mainnet activates.
26
+
27
+ ---
28
+
29
+ ## Install
30
+
31
+ ```bash
32
+ npm install @neuraiproject/neurai-scripts
33
+ ```
34
+
35
+ Build from source:
36
+
37
+ ```bash
38
+ npm install
39
+ npm run build
40
+ npm test
41
+ ```
42
+
43
+ Three bundles are produced under `dist/`:
44
+
45
+ | File | Target |
46
+ |---|---|
47
+ | `dist/index.js` / `index.cjs` | Node (ESM / CJS) |
48
+ | `dist/browser.js` | Browser ESM |
49
+ | `dist/NeuraiScripts.global.js` | IIFE global (`window.NeuraiScripts`) |
50
+
51
+ ---
52
+
53
+ ## Module layout
54
+
55
+ ```
56
+ src/
57
+ ├── core/ Low-level primitives
58
+ │ ├── opcodes.ts Opcode bytes + TXFIELD / TXHASH / ASSETFIELD selectors
59
+ │ ├── script-builder.ts CScriptNum encoding, pushBytes/Int/Hex, ScriptBuilder
60
+ │ ├── bytes.ts Hex ↔ Uint8Array helpers (ensureHex, hexToBytes, …)
61
+ │ └── index.ts Barrel
62
+ ├── standard/ Standard scripts
63
+ │ ├── p2pkh.ts encodeP2PKHScriptPubKey
64
+ │ ├── p2wpkh.ts encodeP2WPKHScriptPubKey
65
+ │ ├── p2wsh.ts encodeP2WSHScriptPubKey
66
+ │ ├── authscript.ts encodeAuthScriptScriptPubKey + witness builders
67
+ │ ├── nulldata.ts encodeNullDataScript (OP_RETURN)
68
+ │ ├── multisig.ts encodeMultisigRedeemScript / encodeP2SHScriptPubKey
69
+ │ └── index.ts Barrel
70
+ ├── covenants/ Covenant scripts
71
+ │ ├── partial-fill/ Legacy (ECDSA cancel) + PQ (ML-DSA-44 via CSFS)
72
+ │ └── index.ts Barrel
73
+ ├── address.ts encodeSellerScriptPubKey (bech32m / base58check → spk)
74
+ ├── types.ts Public types
75
+ ├── entries/ Rollup entry points (node / browser / IIFE)
76
+ └── index.ts Public API
77
+ ```
78
+
79
+ All exports are available from the top-level entry:
80
+
81
+ ```ts
82
+ import { ScriptBuilder, opcodes, encodeP2WPKHScriptPubKey, buildPartialFillScriptHex }
83
+ from '@neuraiproject/neurai-scripts';
84
+ ```
85
+
86
+ ---
87
+
88
+ ## Core primitives
89
+
90
+ ### Opcode constants (`./core/opcodes.ts`)
91
+
92
+ Complete coverage of the classic Script opcodes (push values, control,
93
+ stack, arithmetic, bitwise, crypto) plus every DePIN-Test addition
94
+ (`OP_CHECKTEMPLATEVERIFY`, `OP_CHECKSIGFROMSTACK`, `OP_TXHASH`,
95
+ `OP_TXFIELD`, `OP_TXLOCKTIME`, `OP_OUTPUTVALUE`, `OP_OUTPUTSCRIPT`,
96
+ `OP_INPUTCOUNT`/`OP_OUTPUTCOUNT`, `OP_OUTPUTASSETFIELD`,
97
+ `OP_INPUTASSETFIELD`, `OP_REFINPUTCOUNT`/`OP_REFINPUTFIELD`/
98
+ `OP_REFINPUTASSETFIELD`, `OP_CAT`, `OP_SPLIT`, `OP_REVERSEBYTES`, 64-bit
99
+ `OP_MUL`/`OP_DIV`/`OP_MOD`).
100
+
101
+ Also exports selector tables:
102
+
103
+ ```ts
104
+ // For OP_TXFIELD and OP_REFINPUTFIELD
105
+ opcodes.TXFIELD_VALUE // 0x01
106
+ opcodes.TXFIELD_AUTHSCRIPT_COMMITMENT // 0x02
107
+ opcodes.TXFIELD_SCRIPTPUBKEY // 0x03
108
+
109
+ // For OP_OUTPUTASSETFIELD / OP_INPUTASSETFIELD / OP_REFINPUTASSETFIELD
110
+ opcodes.ASSETFIELD_NAME // 0x01
111
+ opcodes.ASSETFIELD_AMOUNT // 0x02
112
+ opcodes.ASSETFIELD_UNITS // 0x03
113
+ opcodes.ASSETFIELD_REISSUABLE // 0x04
114
+ opcodes.ASSETFIELD_HAS_IPFS // 0x05
115
+ opcodes.ASSETFIELD_IPFS_HASH // 0x06
116
+ opcodes.ASSETFIELD_TYPE // 0x07
117
+
118
+ // Bitmask selectors for OP_TXHASH (any non-zero combination is valid)
119
+ opcodes.TXHASH_VERSION // 0x01
120
+ opcodes.TXHASH_LOCKTIME // 0x02
121
+ opcodes.TXHASH_INPUT_PREVOUTS // 0x04
122
+ opcodes.TXHASH_INPUT_SEQUENCES // 0x08
123
+ opcodes.TXHASH_OUTPUTS // 0x10
124
+ opcodes.TXHASH_CURRENT_PREVOUT // 0x20
125
+ opcodes.TXHASH_CURRENT_SEQUENCE // 0x40
126
+ opcodes.TXHASH_CURRENT_INDEX // 0x80
127
+ opcodes.TXHASH_ALL // 0xff
128
+ ```
129
+
130
+ ### `ScriptBuilder` (`./core/script-builder.ts`)
131
+
132
+ ```ts
133
+ import { ScriptBuilder, opcodes } from '@neuraiproject/neurai-scripts';
134
+
135
+ const script = new ScriptBuilder()
136
+ .op(opcodes.OP_DUP, opcodes.OP_HASH160)
137
+ .pushBytes(pkh20)
138
+ .op(opcodes.OP_EQUALVERIFY, opcodes.OP_CHECKSIG)
139
+ .build(); // Uint8Array
140
+ // or .buildHex() → string
141
+ ```
142
+
143
+ Also exported atomically: `pushBytes(data)`, `pushInt(value)`,
144
+ `pushHex(hex)`, `encodeScriptNum(value)`.
145
+
146
+ Push elements up to **3072 bytes** (NIP-18 cap when `CSFS` is active).
147
+ Larger pushes throw; legacy scripts should stay under 520 bytes per push.
148
+
149
+ ### Byte helpers (`./core/bytes.ts`)
150
+
151
+ `ensureHex`, `hexToBytes`, `bytesToHex`, `concatBytes`, `bytesEqual`.
152
+
153
+ ---
154
+
155
+ ## Standard scripts
156
+
157
+ All encoders return raw `Uint8Array` bytes. Caller supplies the pre-hashed
158
+ inputs where applicable (we don't bake a crypto dep into this library).
159
+
160
+ ### P2PKH — `encodeP2PKHScriptPubKey(pkh20)`
161
+
162
+ ```ts
163
+ import { encodeP2PKHScriptPubKey } from '@neuraiproject/neurai-scripts';
164
+ // OP_DUP OP_HASH160 0x14 <pkh> OP_EQUALVERIFY OP_CHECKSIG (25 bytes)
165
+ const spk = encodeP2PKHScriptPubKey(pubKeyHash20);
166
+ ```
167
+
168
+ ### P2WPKH — `encodeP2WPKHScriptPubKey(pkh20)`
169
+
170
+ ```ts
171
+ // OP_0 0x14 <pkh> (22 bytes)
172
+ const spk = encodeP2WPKHScriptPubKey(pubKeyHash20);
173
+ ```
174
+
175
+ ### P2WSH — `encodeP2WSHScriptPubKey(witnessScriptSha256)`
176
+
177
+ ```ts
178
+ // OP_0 0x20 <SHA256(witnessScript)> (34 bytes)
179
+ // Compute SHA256 via your crypto stack (not bundled here).
180
+ const spk = encodeP2WSHScriptPubKey(sha256(witnessScript));
181
+ ```
182
+
183
+ ### AuthScript — `encodeAuthScriptScriptPubKey(program32)` + witness builders
184
+
185
+ `scriptPubKey` layout: `OP_1 0x20 <32-byte program>`.
186
+
187
+ Four spend modes, selected by a 1-byte `auth_type` in the witness stack:
188
+
189
+ | Constant | Value | Meaning |
190
+ |---|---|---|
191
+ | `AUTHSCRIPT_NOAUTH` | `0x00` | No signature — gated by witnessScript alone |
192
+ | `AUTHSCRIPT_PQ` | `0x01` | ML-DSA-44 (post-quantum) |
193
+ | `AUTHSCRIPT_LEGACY` | `0x02` | secp256k1 ECDSA |
194
+ | `AUTHSCRIPT_REF` | `0x03` | NIP-015 reference-script spend (future) |
195
+
196
+ Witness-stack builders return `Uint8Array[]` — the array of raw stack
197
+ elements. Serialization into the transaction witness (compact-size +
198
+ length-prefixes) is done at tx-assembly time by
199
+ `neurai-create-transaction`.
200
+
201
+ ```ts
202
+ import {
203
+ encodeAuthScriptScriptPubKey,
204
+ buildAuthScriptWitnessLegacy,
205
+ buildAuthScriptWitnessPQ,
206
+ buildAuthScriptWitnessNoAuth,
207
+ buildAuthScriptWitnessRef
208
+ } from '@neuraiproject/neurai-scripts';
209
+
210
+ // Output spk
211
+ const spk = encodeAuthScriptScriptPubKey(program32);
212
+
213
+ // Legacy spend: [0x02, sig, pubkey, ...args, witnessScript]
214
+ const stackLegacy = buildAuthScriptWitnessLegacy({
215
+ signature: derSigWithSighash,
216
+ pubKey: compressedSecp256k1,
217
+ args: [],
218
+ witnessScript
219
+ });
220
+
221
+ // PQ spend (requires NIP-18): [0x01, sig(~2421 B), pubkey(~1313 B), ...args, witnessScript]
222
+ const stackPQ = buildAuthScriptWitnessPQ({
223
+ signature: mlDsa44SigWithSighash,
224
+ pubKey: versionedPqPubKey,
225
+ args: [],
226
+ witnessScript
227
+ });
228
+
229
+ // NoAuth (pure covenant): [0x00, ...args, witnessScript]
230
+ const stackNoAuth = buildAuthScriptWitnessNoAuth({ args, witnessScript });
231
+
232
+ // NIP-015 reference-script spend: [0x03, ...args, uint32LE(refIndex)]
233
+ const stackRef = buildAuthScriptWitnessRef({ refIndex: 2, args });
234
+ ```
235
+
236
+ ### Null-data (OP_RETURN) — `encodeNullDataScript(payload, options?)`
237
+
238
+ ```ts
239
+ import { encodeNullDataScript } from '@neuraiproject/neurai-scripts';
240
+
241
+ // OP_RETURN <push>
242
+ const spk = encodeNullDataScript(someBytes);
243
+
244
+ // Multi-push payload
245
+ const spk2 = encodeNullDataScript([tagBytes, messageBytes]);
246
+
247
+ // Oversize (> 80 B) needs an explicit opt-in
248
+ const big = encodeNullDataScript(huge, { allowNonStandard: true });
249
+ ```
250
+
251
+ `NULLDATA_STANDARD_MAX_SIZE = 80` (Neurai's mempool-relay cap inherited
252
+ from Bitcoin Core). Outputs over that are consensus-valid but not relayed
253
+ unless nodes run with `-acceptnonstdtxn=1`.
254
+
255
+ ### Multisig — `encodeMultisigRedeemScript` + `encodeP2SHScriptPubKey`
256
+
257
+ Classic bare multisig is consensus-valid but non-standard for relay in
258
+ Neurai today. Typical usage wraps the redeem script in P2SH.
259
+
260
+ ```ts
261
+ import {
262
+ encodeMultisigRedeemScript,
263
+ encodeP2SHScriptPubKey,
264
+ MULTISIG_MAX_PUBKEYS // 20
265
+ } from '@neuraiproject/neurai-scripts';
266
+
267
+ const redeemScript = encodeMultisigRedeemScript({
268
+ m: 2,
269
+ pubKeys: [pk1, pk2, pk3] // each 33 or 65 bytes
270
+ });
271
+ // <2> <pk1> <pk2> <pk3> <3> OP_CHECKMULTISIG
272
+
273
+ // Wrap in P2SH (callers compute HASH160 externally):
274
+ const scriptPubKey = encodeP2SHScriptPubKey(hash160(redeemScript));
275
+ // OP_HASH160 0x14 <h160> OP_EQUAL
276
+ ```
277
+
278
+ ---
279
+
280
+ ## Covenants
281
+
282
+ ### Partial-Fill Sell Order
283
+
284
+ A partial-fill sell order lets a seller publish a lot of tokens at a
285
+ fixed price and lets any number of buyers take arbitrary fractions of
286
+ that lot without the seller having to come back online for each sale.
287
+ The covenant that guards the seller's output is the only rulebook: the
288
+ spending transaction is valid only if it pays the seller the correct XNA
289
+ amount, delivers the right asset quantity to the buyer, and forwards the
290
+ remainder into a new UTXO carrying the same covenant script. No
291
+ custodial DEX, no off-chain matching, no second signature from the
292
+ seller.
293
+
294
+ The covenant is **stateful via UTXO continuity**. The output at `vout[2]`
295
+ of every fill must carry the same `scriptPubKey` as the input being
296
+ spent (enforced on the fly by `OP_OUTPUTSCRIPT == OP_TXFIELD 0x03`), so
297
+ the covenant self-replicates without hardcoding its own hash. The
298
+ remaining asset quantity is read directly from the input via
299
+ `OP_INPUTASSETFIELD` and the subtraction `inputAmount − N` is verified,
300
+ so the same script works for any remainder as the lot drains. Asset
301
+ name, buyer amount, payment destination script and payment value are all
302
+ checked against the covenant's hardcoded parameters using
303
+ `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
304
+ enforces every rule; there is no trusted off-chain layer.
305
+
306
+ Two spending branches are selected by the top of the unlock stack:
307
+
308
+ - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
309
+ recovers the remainder. The legacy variant uses ECDSA
310
+ (`OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG`); the PQ variant
311
+ swaps this for `OP_CHECKSIGFROMSTACK` against an ML-DSA-44 signature
312
+ (see *PQ variant* below).
313
+ - `OP_ELSE` (unlock pushed `N` then `0`) — **Public partial fill**. Any
314
+ buyer can spend the UTXO by providing the fill amount `N`; consensus
315
+ validates the whole transaction layout against the embedded price,
316
+ token id, and seller destination. No seller signature is involved.
317
+
318
+ This maps naturally onto Neurai's mempool: multiple buyers can submit
319
+ their fill transactions in sequence, each one building on the previous
320
+ fill's `vout[2]` before confirmation. Neurai's default descendant limit
321
+ of 500 allows long chains of pending fills against a single published
322
+ order, and the whole chain confirms together when the next block is
323
+ mined. If the seller wants to stop the order at any point, she spends
324
+ the current live UTXO via the cancel branch.
325
+
326
+ #### Alice / Bob / Carol flow
327
+
328
+ 1. **Alice** locks 100 CAT in a covenant UTXO (`buildPartialFillScript`).
329
+ Price 1 XNA / CAT, P2PKH as payment destination.
330
+ 2. **Bob** spends the covenant pushing `<5> <0>` as `scriptSig` and his
331
+ XNA input. The script enforces:
332
+ - `output[0]` pays Alice ≥ `5 * unitPriceSats` XNA
333
+ - `output[1]` is a transfer of 5 CAT to Bob
334
+ - `output[2]` is a new covenant UTXO with **the same** scriptPubKey
335
+ and 95 CAT
336
+ 3. **Carol** does the same on the new UTXO, leaving 90 CAT behind.
337
+ 4. **Alice** signs the cancel branch on the latest UTXO and recovers her
338
+ remaining 90 CAT. She has already received 10 XNA across Bob's and
339
+ Carol's fills.
340
+
341
+ No second signature from Alice, no custodial server: the covenant script
342
+ is the rulebook.
343
+
344
+ #### Usage (legacy ECDSA cancel)
345
+
346
+ ```ts
347
+ import {
348
+ buildPartialFillScriptHex,
349
+ buildFillScriptSigHex,
350
+ buildCancelScriptSigHex,
351
+ parsePartialFillScript
352
+ } from '@neuraiproject/neurai-scripts';
353
+
354
+ // 1) Alice publishes an order for 100 CAT at 1 XNA per CAT.
355
+ const scriptPubKeyHex = buildPartialFillScriptHex({
356
+ sellerAddress: aliceP2PKHAddress, // "t..." on testnet / "N..." on mainnet
357
+ tokenId: 'CAT',
358
+ unitPriceSats: 100_000_000n // 1 XNA = 1e8 sats per indivisible unit
359
+ });
360
+ // Throws if the address is not a legacy P2PKH — the legacy covenant uses
361
+ // OP_HASH160 + OP_CHECKSIG on the cancel branch and cannot commit to an
362
+ // AuthScript program. Use `buildPartialFillScriptPQ` for bech32m / PQ
363
+ // destinations.
364
+
365
+ // 2) Bob spends 5 CAT from the covenant.
366
+ const bobScriptSigHex = buildFillScriptSigHex(5n);
367
+ // Fill-tx layout (built with neurai-create-transaction):
368
+ // vin[0] = covenant UTXO, scriptSig = bobScriptSigHex
369
+ // vin[1+] = buyer's XNA inputs (standard P2PKH, SIGHASH_ALL)
370
+ // vout[0] = unitPriceSats * 5 XNA to Alice
371
+ // vout[1] = 5 CAT to Bob
372
+ // vout[2] = 95 CAT back to the SAME covenant scriptPubKey
373
+ // vout[3+] = buyer change (optional)
374
+
375
+ // 3) Alice cancels on the latest remainder UTXO.
376
+ const aliceCancelSig = /* produced by neurai-sign-transaction, SIGHASH_ALL */;
377
+ const cancelScriptSigHex = buildCancelScriptSigHex(aliceCancelSig, alicePubKey);
378
+
379
+ // 4) The DEX backend indexes active orders by parsing scriptPubKeys.
380
+ for (const utxo of candidateUtxos) {
381
+ try {
382
+ const order = parsePartialFillScript(utxo.scriptPubKeyHex, 'xna-test');
383
+ // order.tokenId, order.unitPriceSats, order.sellerPubKeyHash, order.network
384
+ // The parser returns the 20-byte PKH; base58check-encode with the
385
+ // network's legacy prefix (0x35 mainnet / 0x7f testnet) if you need
386
+ // to display the seller's address.
387
+ } catch {
388
+ // not a partial-fill covenant, skip
389
+ }
390
+ }
391
+ ```
392
+
393
+ #### Script layout (legacy)
394
+
395
+ ```
396
+ OP_IF
397
+ OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG // cancel branch
398
+ OP_ELSE
399
+ # Stack entering ELSE: [ N ]
400
+ OP_DUP <unitPriceSats> OP_MUL
401
+ <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
402
+ <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
403
+ OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
404
+ <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name == tokenId
405
+ <2> OP_OUTPUTSCRIPT <0x03> OP_TXFIELD OP_EQUALVERIFY // continuity
406
+ <2> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // remainder name
407
+ <2> <0x02> OP_OUTPUTASSETFIELD OP_OVER
408
+ <0> <0x02> OP_INPUTASSETFIELD OP_SWAP OP_SUB OP_EQUALVERIFY // remainder = in - N
409
+ OP_DROP OP_1
410
+ OP_ENDIF
411
+ ```
412
+
413
+ #### Limitations of v0.1
414
+
415
+ - **Payment only in XNA.** A `PaymentAsset` selector is planned for v0.2.
416
+ - **No `MinFill` / `MaxFill` / `Expiry`.** Planned for v0.2.
417
+ - **Fixed output layout** (`vout[0..2]`). The covenant rejects
418
+ reorderings. Buyer change must go to `vout[3+]`.
419
+ - **AMM is out of scope.** Covered by a later phase of the NIP roadmap.
420
+
421
+ ### Partial-Fill PQ variant (post-quantum seller, NIP-18)
422
+
423
+ With `OP_CHECKSIGFROMSTACK` (`CSFS`) and `OP_TXHASH` active, the cancel
424
+ branch can validate an **ML-DSA-44** signature in place of the classic
425
+ ECDSA `OP_CHECKSIG`. NIP-18 raises the per-element push cap to 3072 B so
426
+ the ~2421 B signature and ~1313 B pubkey fit as stack items. All three
427
+ are active on DePIN-Test testnet.
428
+
429
+ | | Legacy | PQ |
430
+ |---|---|---|
431
+ | Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
432
+ | Cancel verifier | `OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG` | `OP_DUP OP_SHA256 <commitment> OP_EQUALVERIFY <selector> OP_TXHASH OP_SWAP OP_CHECKSIGFROMSTACK` |
433
+ | What Alice signs | tx sighash (standard) | `SHA256(OP_TXHASH(selector))` — CSFS single-SHA256s the message |
434
+ | Payment destination | P2PKH only | P2PKH **or** AuthScript bech32m (scriptPubKey bytes hardcoded) |
435
+
436
+ ```ts
437
+ import {
438
+ buildPartialFillScriptPQHex,
439
+ buildCancelScriptSigPQHex,
440
+ parsePartialFillScriptPQ,
441
+ isPartialFillScriptPQ,
442
+ DEFAULT_PQ_TXHASH_SELECTOR
443
+ } from '@neuraiproject/neurai-scripts';
444
+
445
+ const scriptPubKeyHex = buildPartialFillScriptPQHex({
446
+ network: 'xna-test',
447
+ paymentAddress: 'tnq1...', // AuthScript bech32m, or legacy "t..." P2PKH
448
+ pubKeyCommitment: sha256(alicePQPubKey), // 32 bytes
449
+ tokenId: 'CAT',
450
+ unitPriceSats: 100_000_000n,
451
+ txHashSelector: DEFAULT_PQ_TXHASH_SELECTOR // 0xff = all eight tx fields
452
+ });
453
+
454
+ const cancelScriptSigHex = buildCancelScriptSigPQHex(mlDsa44SigWithSighash, alicePQPubKey);
455
+
456
+ // Indexers can tell variants apart:
457
+ if (isPartialFillScriptPQ(utxo.scriptPubKeyHex)) {
458
+ const order = parsePartialFillScriptPQ(utxo.scriptPubKeyHex);
459
+ }
460
+ ```
461
+
462
+ #### PQ cancel-branch layout
463
+
464
+ ```
465
+ OP_IF // scriptSig pushed <sig> <pubKey> OP_1
466
+ OP_DUP OP_SHA256
467
+ <pubKeyCommitment 32B>
468
+ OP_EQUALVERIFY
469
+ <txHashSelector 1B>
470
+ OP_TXHASH // msg = dSHA256(selected_tx_fields)
471
+ OP_SWAP
472
+ OP_CHECKSIGFROMSTACK // verifies sig over SHA256(msg) for pubKey
473
+ OP_ELSE
474
+ ... partial-fill branch (identical to legacy) ...
475
+ OP_ENDIF
476
+ ```
477
+
478
+ ---
479
+
480
+ ## Network handling
481
+
482
+ Builders take address strings (whose prefix already encodes the network:
483
+ `t.../N...` for P2PKH, `tnq1.../nq1...` for AuthScript bech32m) and
484
+ validate them via `decodeAddress` from `neurai-create-transaction`. No
485
+ builder accepts a separate `network` parameter — it would be redundant
486
+ with the address and invite silent mismatches.
487
+
488
+ Parsers, on the other hand, do take a `network` argument (default
489
+ `'xna-test'`). The covenant *script bytes themselves do not encode
490
+ network*: a legacy covenant is opcodes plus a 20-byte PKH, a PQ covenant
491
+ is opcodes plus a 32-byte commitment and raw payment-scriptPubKey bytes,
492
+ and neither payload differs between mainnet and testnet. The parser
493
+ receives `network` purely so the caller can later base58-encode
494
+ `sellerPubKeyHash` against the right version byte, or interpret
495
+ `paymentScriptPubKey` in the correct bech32m/base58 context.
496
+
497
+ Keep this split intact when adding new covenants: builders reject a
498
+ `network` field, parsers echo it through.
499
+
500
+ ---
501
+
502
+ ## Consensus / policy notes
503
+
504
+ - **DePIN-Test opcodes are consensus-gated.** Each one is behind an
505
+ individual flag (`nCTVEnabled`, `nCSFSEnabled`, `nTXHASHEnabled`,
506
+ `nTXFIELDEnabled`, `nOUTPUTVALUEEnabled`, `nOUTPUTSCRIPTEnabled`,
507
+ `nOUTPUTASSETFIELDEnabled`, `nINPUTASSETFIELDEnabled`,
508
+ `nINPUTOUTPUTCOUNTEnabled`, `nREFINPUTSEnabled`, `nCATEnabled`,
509
+ `nSPLITEnabled`, `nREVERSEBYTESEnabled`, `n64BitIntegersEnabled`,
510
+ `nTXLOCKTIMEEnabled`, `nPQWitnessEnabled`). All are **true** on testnet
511
+ and regtest, **false** on mainnet until each NIP's fork process lands.
512
+ - **NIP-18 per-element cap (3072 B) is also a mempool-policy win.**
513
+ Neurai's `MAX_CSFS_STANDARD_P2WSH_STACK_ITEM_SIZE` equals the consensus
514
+ cap whenever CSFS is active, so PQ witness items are standard on the
515
+ testnet today — no `-acceptnonstdtxn=1` required. The legacy 80 B cap
516
+ only applies when CSFS is off.
517
+ - **Commitment choice (PQ).** The PQ covenant commits to
518
+ `SHA256(pubKey)`, not the witness-v1 bech32m program. That keeps the
519
+ covenant decoupled from AuthScript address derivation and lets the
520
+ caller use any PQ key whose SHA256 they can compute.
521
+
522
+ ---
523
+
524
+ ## Adding new scripts to this library
525
+
526
+ The layout under `src/standard/` and `src/covenants/` is designed for
527
+ expansion. When adding a new primitive:
528
+
529
+ - **Standard scripts** (P2*, OP_RETURN, new address formats, …) go under
530
+ `src/standard/`. Keep one file per scheme and export from
531
+ `src/standard/index.ts`.
532
+ - **Covenants** (batch-fill, shared-claim, HTLC, vaults, AMM, …) go under
533
+ `src/covenants/<name>/` with the same `script.ts` / `spend.ts` /
534
+ `parse.ts` split the partial-fill module uses. Re-export from
535
+ `src/covenants/index.ts`.
536
+ - **Reference-script carriers / NIP-015 helpers** will land in a future
537
+ `src/reference-scripts/` directory when the NIP activates.
538
+
539
+ The top-level `src/index.ts` barrel should re-export everything publicly
540
+ consumable; callers import directly from the package root.
541
+
542
+ ---
543
+
544
+ ## License
545
+
546
+ MIT — same terms as the rest of the `@neuraiproject/*` libraries.
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Address helpers. Wraps `decodeAddress` from
3
+ * `@neuraiproject/neurai-create-transaction` to produce the exact
4
+ * scriptPubKey bytes a covenant needs to hardcode. The actual
5
+ * scriptPubKey encoders live in `./standard/*`; this module delegates.
6
+ *
7
+ * Two destination types are supported for the payment output (output[0]):
8
+ * - Legacy P2PKH (base58check)
9
+ * - AuthScript witness v1 (bech32m)
10
+ */
11
+ import { encodeP2PKHScriptPubKey } from './standard/p2pkh.js';
12
+ import { encodeAuthScriptScriptPubKey } from './standard/authscript.js';
13
+ export type SellerAddressKind = 'p2pkh' | 'authscript';
14
+ export interface SellerScriptPubKey {
15
+ kind: SellerAddressKind;
16
+ /** Raw scriptPubKey bytes that output[0] of a fill tx must equal. */
17
+ bytes: Uint8Array;
18
+ /**
19
+ * Address-specific hash: 20-byte PKH for P2PKH, 32-byte program for
20
+ * AuthScript. Used by the cancel branch (either as the HASH160 target or
21
+ * as the SHA256(pubKey) commitment).
22
+ */
23
+ hash: Uint8Array;
24
+ }
25
+ export { encodeP2PKHScriptPubKey, encodeAuthScriptScriptPubKey };
26
+ /**
27
+ * Resolve any accepted seller address string into its scriptPubKey.
28
+ * The returned bytes are what the covenant will hardcode and later verify
29
+ * via `OP_OUTPUTSCRIPT == <bytes>`.
30
+ */
31
+ export declare function encodeSellerScriptPubKey(address: string): SellerScriptPubKey;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Minimal byte helpers. A subset of what `neurai-create-transaction` exposes,
3
+ * duplicated here to keep this package free of runtime coupling beyond its
4
+ * declared `dependencies` field. All sizes are little-endian, per Neurai.
5
+ */
6
+ export declare function ensureHex(hex: string, label?: string): string;
7
+ export declare function hexToBytes(hex: string): Uint8Array;
8
+ export declare function bytesToHex(bytes: Uint8Array): string;
9
+ export declare function concatBytes(...parts: Uint8Array[]): Uint8Array;
10
+ export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
@@ -0,0 +1,5 @@
1
+ export { ensureHex, hexToBytes, bytesToHex, concatBytes, bytesEqual } from './bytes.js';
2
+ export { ScriptBuilder, encodeScriptNum, pushBytes, pushInt, pushHex } from './script-builder.js';
3
+ export * as opcodes from './opcodes.js';
4
+ export { makeCursor, expectByte, assertTrailing, readPush, readPushPositiveInt, decodeScriptNum } from './script-parser.js';
5
+ export type { Cursor } from './script-parser.js';