@neuraiproject/neurai-scripts 0.9.1 → 0.10.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/README.md CHANGED
@@ -124,15 +124,17 @@ stack, arithmetic, bitwise, crypto) plus every DePIN-Test addition
124
124
  `OP_INPUTCOUNT`/`OP_OUTPUTCOUNT`, `OP_OUTPUTASSETFIELD`,
125
125
  `OP_INPUTASSETFIELD`, `OP_REFINPUTCOUNT`/`OP_REFINPUTFIELD`/
126
126
  `OP_REFINPUTASSETFIELD`, `OP_CHAINCONTEXT`, `OP_CAT`, `OP_SPLIT`,
127
- `OP_REVERSEBYTES`, 64-bit `OP_MUL`/`OP_DIV`/`OP_MOD`).
127
+ `OP_REVERSEBYTES`, `OP_OUTPUTAUTHDEST`, `OP_ZKVERIFY`, `OP_INPUTFIELD`,
128
+ 64-bit `OP_MUL`/`OP_DIV`/`OP_MOD`).
128
129
 
129
130
  Also exports selector tables:
130
131
 
131
132
  ```ts
132
- // For OP_TXFIELD and OP_REFINPUTFIELD
133
+ // For OP_TXFIELD, OP_INPUTFIELD and OP_REFINPUTFIELD
133
134
  opcodes.TXFIELD_VALUE // 0x01
134
135
  opcodes.TXFIELD_AUTHSCRIPT_COMMITMENT // 0x02
135
136
  opcodes.TXFIELD_SCRIPTPUBKEY // 0x03
137
+ opcodes.TXFIELD_AUTHDEST // 0x04 (NIP-041)
136
138
 
137
139
  // For OP_OUTPUTASSETFIELD / OP_INPUTASSETFIELD / OP_REFINPUTASSETFIELD
138
140
  opcodes.ASSETFIELD_NAME // 0x01
@@ -142,13 +144,14 @@ opcodes.ASSETFIELD_REISSUABLE // 0x04
142
144
  opcodes.ASSETFIELD_HAS_IPFS // 0x05
143
145
  opcodes.ASSETFIELD_IPFS_HASH // 0x06
144
146
  opcodes.ASSETFIELD_TYPE // 0x07
147
+ opcodes.ASSETFIELD_MESSAGE // 0x08 (NIP-043)
145
148
 
146
149
  // For OP_CHAINCONTEXT
147
150
  opcodes.CHAINCONTEXT_HEIGHT // 0x01
148
151
  opcodes.CHAINCONTEXT_MTP // 0x02
149
152
  opcodes.CHAINCONTEXT_CHAIN_ID // 0x03
150
153
 
151
- // Bitmask selectors for OP_TXHASH (any non-zero combination is valid)
154
+ // NIP-042: push every OP_TXHASH mask as two raw LE bytes (0x001..0x1ff).
152
155
  opcodes.TXHASH_VERSION // 0x01
153
156
  opcodes.TXHASH_LOCKTIME // 0x02
154
157
  opcodes.TXHASH_INPUT_PREVOUTS // 0x04
@@ -157,7 +160,8 @@ opcodes.TXHASH_OUTPUTS // 0x10
157
160
  opcodes.TXHASH_CURRENT_PREVOUT // 0x20
158
161
  opcodes.TXHASH_CURRENT_SEQUENCE // 0x40
159
162
  opcodes.TXHASH_CURRENT_INDEX // 0x80
160
- opcodes.TXHASH_ALL // 0xff
163
+ opcodes.TXHASH_REFINPUTS // 0x100
164
+ opcodes.TXHASH_ALL // 0x1ff
161
165
  ```
162
166
 
163
167
  ### `ScriptBuilder` (`./core/script-builder.ts`)
@@ -227,8 +231,8 @@ version of the address family:
227
231
  `buildStrictWitnessPQ({ signature, pubKey })` and
228
232
  `buildStrictWitnessECDSA({ signature, pubKey })` build the fixed 4-item stacks
229
233
  of the strict families (the PQ key must be the 1313-byte `0x05`-prefixed key,
230
- the ECDSA key must be compressed). Strict v2 / v3 are active on regtest only
231
- today; generic v1 on testnet and regtest.
234
+ the ECDSA key must be compressed). All three families activate on the reset testnet at block 10 and on
235
+ regtest at block 1.
232
236
 
233
237
  Generic AuthScript v1 spend modes, selected by a 1-byte `auth_type` in the witness stack:
234
238
 
@@ -355,6 +359,22 @@ checked against the covenant's hardcoded parameters using
355
359
  `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
356
360
  enforces every rule; there is no trusted off-chain layer.
357
361
 
362
+ **The order is always input 0.** `OP_INPUTASSETFIELD` takes an absolute
363
+ input index and Script cannot ask for the index of the input being
364
+ evaluated, so both fill branches open with an input-0 binding:
365
+
366
+ ```
367
+ <0x80 0x00> OP_TXHASH <OP_TXHASH(0x0080) at input 0> OP_EQUALVERIFY
368
+ ```
369
+
370
+ NIP-042 mask `0x0080` commits only to the current input index, so the
371
+ digest matches the hardcoded constant only when the order is spent as
372
+ input 0. Without it (covenants built before 0.10.0) a buyer could put a
373
+ foreign asset UTXO at input 0 to price the fill and take the rest of the
374
+ order through an unconstrained output, or settle several identical orders
375
+ with one payment. A transaction can fill at most one order; the cancel
376
+ branch is not bound.
377
+
358
378
  Three spending branches are selected by the top of the unlock stack:
359
379
 
360
380
  - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
@@ -432,15 +452,23 @@ const scriptPubKeyHex = buildPartialFillScriptHex({
432
452
  value: 1_250_000n // fills are rejected at/after this value
433
453
  }
434
454
  });
435
- // Throws if the address is not a legacy P2PKH — the legacy covenant uses
436
- // OP_HASH160 + OP_CHECKSIG on the cancel branch and cannot commit to an
437
- // AuthScript program. Use `buildPartialFillScriptPQ` for bech32m / PQ
438
- // destinations.
455
+ // `sellerAddress` must be a legacy P2PKH: it is both the payment
456
+ // destination and the cancel key hash.
457
+
458
+ // A seller with another secp256k1 address (a strict ECDSA v3 `tnq1r…`
459
+ // wallet) is paid at that address and cancels with the same key:
460
+ const v3OrderHex = buildPartialFillScriptHex({
461
+ paymentAddress: aliceV3Address, // any address type
462
+ sellerPubKeyHash: hash160(alicePubKey33), // key allowed to cancel
463
+ tokenId: 'CAT',
464
+ unitPriceSats: 100_000_000n
465
+ });
466
+ // Use `buildPartialFillScriptPQ` to cancel with an ML-DSA-44 key.
439
467
 
440
468
  // 2) Bob spends 5 CAT from the covenant.
441
469
  const bobScriptSigHex = buildFillScriptSigHex(5n);
442
470
  // Fill-tx layout (built with neurai-create-transaction):
443
- // vin[0] = covenant UTXO, scriptSig = bobScriptSigHex
471
+ // vin[0] = covenant UTXO (must be input 0), scriptSig = bobScriptSigHex
444
472
  // vin[1+] = buyer's XNA inputs (standard P2PKH, SIGHASH_ALL)
445
473
  // vout[0] = unitPriceSats * 5 XNA to Alice
446
474
  // vout[1] = 5 CAT to Bob
@@ -456,29 +484,29 @@ for (const utxo of candidateUtxos) {
456
484
  try {
457
485
  const order = parsePartialFillScript(utxo.scriptPubKeyHex, 'xna-test');
458
486
  // order.tokenId, order.unitPriceSats, order.sellerPubKeyHash,
459
- // order.expiration, order.network
460
- // The parser returns the 20-byte PKH; base58check-encode with the
461
- // network's legacy prefix (0x35 mainnet / 0x7f testnet) if you need
462
- // to display the seller's address.
487
+ // order.paymentScriptPubKey, order.expiration, order.network
488
+ // sellerPubKeyHash is the cancel key; paymentScriptPubKey is where
489
+ // fills pay (the P2PKH of that same hash for sellerAddress orders).
463
490
  } catch {
464
491
  // not a partial-fill covenant, skip
465
492
  }
466
493
  }
467
494
  ```
468
495
 
469
- #### Script layout (legacy, three-branch)
496
+ #### Script layout (ECDSA cancel, three-branch)
470
497
 
471
498
  ```
472
499
  OP_IF // cancel branch
473
500
  OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG
474
501
  OP_ELSE
502
+ <0x80 0x00> OP_TXHASH <INPUT_ZERO_TXHASH> OP_EQUALVERIFY // order is input 0
475
503
  OP_IF // full-fill branch
476
504
  # Stack entering: [ ] (scriptSig pushed <1> <0>)
477
505
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
478
506
  <0> <0x02> OP_INPUTASSETFIELD // N = inputAmount
479
507
  OP_DUP <unitPriceSats> OP_MUL
480
508
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
481
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
509
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
482
510
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
483
511
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
484
512
  OP_DROP OP_1 // no vout[2] required
@@ -487,7 +515,7 @@ OP_ELSE
487
515
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
488
516
  OP_DUP <unitPriceSats> OP_MUL
489
517
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
490
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
518
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
491
519
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
492
520
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
493
521
  <2> OP_OUTPUTAUTHCOMMITMENT <0x02> OP_TXFIELD OP_EQUALVERIFY // continuity (NIP-023)
@@ -505,6 +533,7 @@ OP_ENDIF
505
533
  - **No `MinFill` / `MaxFill` / `Expiry`.** Planned for v0.2.
506
534
  - **Fixed output layout** (`vout[0..2]`). The covenant rejects
507
535
  reorderings. Buyer change must go to `vout[3+]`.
536
+ - **One order per transaction**, always at `vin[0]` (input-0 binding).
508
537
  - **AMM is out of scope.** Covered by a later phase of the NIP roadmap.
509
538
 
510
539
  ### Partial-Fill PQ variant (post-quantum seller, NIP-18)
@@ -515,12 +544,12 @@ ECDSA `OP_CHECKSIG`. NIP-18 raises the per-element push cap to 3072 B so
515
544
  the ~2421 B signature and ~1313 B pubkey fit as stack items. All three
516
545
  are active on DePIN-Test testnet.
517
546
 
518
- | | Legacy | PQ |
547
+ | | ECDSA (`buildPartialFillScript`) | PQ |
519
548
  |---|---|---|
520
549
  | Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
521
550
  | 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` |
522
551
  | What Alice signs | tx sighash (standard) | `SHA256(OP_TXHASH(selector))` — CSFS single-SHA256s the message |
523
- | Payment destination | P2PKH only | P2PKH **or** any AuthScript bech32m address — `nc1p` v1, `pq1z` v2, `nq1r` v3 (scriptPubKey bytes hardcoded, `OP_1`/`OP_2`/`OP_3` included) |
552
+ | Payment destination | `sellerAddress` P2PKH, or any address with `paymentAddress` + `sellerPubKeyHash` | P2PKH **or** any AuthScript bech32m address — `nc1p` v1, `pq1z` v2, `nq1r` v3 (scriptPubKey bytes hardcoded, `OP_1`/`OP_2`/`OP_3` included) |
524
553
 
525
554
  ```ts
526
555
  import {
@@ -537,7 +566,7 @@ const scriptPubKeyHex = buildPartialFillScriptPQHex({
537
566
  pubKeyCommitment: sha256(alicePQPubKey), // 32 bytes
538
567
  tokenId: 'CAT',
539
568
  unitPriceSats: 100_000_000n,
540
- txHashSelector: DEFAULT_PQ_TXHASH_SELECTOR // 0xff = all eight tx fields
569
+ txHashSelector: DEFAULT_PQ_TXHASH_SELECTOR // 0x1ff = all nine fields
541
570
  });
542
571
 
543
572
  const cancelScriptSigHex = buildCancelScriptSigPQHex(mlDsa44SigWithSighash, alicePQPubKey);
@@ -555,12 +584,12 @@ OP_IF // scriptSig pushed <sig> <pubKey> OP_1
555
584
  OP_DUP OP_SHA256
556
585
  <pubKeyCommitment 32B>
557
586
  OP_EQUALVERIFY
558
- <txHashSelector 1B>
559
- OP_TXHASH // msg = dSHA256(selected_tx_fields)
587
+ <txHashSelector uint16LE, exactly 2 bytes>
588
+ OP_TXHASH // msg = tagged NeuraiTxHash(mask || fields)
560
589
  OP_SWAP
561
590
  OP_CHECKSIGFROMSTACK // verifies sig over SHA256(msg) for pubKey
562
591
  OP_ELSE
563
- ... partial-fill branch (identical to legacy) ...
592
+ ... input-0 binding + fill branches (identical to the ECDSA variant) ...
564
593
  OP_ENDIF
565
594
  ```
566
595
 
@@ -634,6 +663,44 @@ consumable; callers import directly from the package root.
634
663
 
635
664
  ## Version notes
636
665
 
666
+ ### 0.10.0
667
+
668
+ Security fix for the partial-fill covenant. Orders built with an earlier
669
+ version stay exposed until they are cancelled: cancel them with
670
+ neurai-sign-transaction 3.1.0 (the last release whose parser reads them)
671
+ and publish them again.
672
+
673
+ - **Input-0 binding.** The fill branches read the order amount from input 0
674
+ but did not check that the order was input 0. A buyer could place a
675
+ foreign asset UTXO at input 0 and take the whole order for the price of
676
+ that UTXO, or settle several identical orders with one payment (both
677
+ reproduced against a regtest node). Both fill branches now open with
678
+ `<0x80 0x00> OP_TXHASH <OP_TXHASH(0x0080) at input 0> OP_EQUALVERIFY`,
679
+ so an order can only be filled as input 0 and at most one order per
680
+ transaction. Requires NIP-042 `OP_TXHASH`.
681
+ - `parsePartialFillScript` / `parsePartialFillScriptPQ` reject covenants
682
+ without the binding, so signers refuse to treat old orders as fillable or
683
+ cancellable through them.
684
+ - ECDSA-cancel orders take `paymentAddress` + `sellerPubKeyHash` as an
685
+ alternative to `sellerAddress`: the payment destination can be any
686
+ address type (for example the strict ECDSA v3 `nq1r…` wallet of the key
687
+ that cancels). `ParsedPartialFillOrder` gains `paymentScriptPubKey`, and
688
+ the parser no longer requires it to be the P2PKH of `sellerPubKeyHash`.
689
+ - Both variants share one implementation of the fill branches
690
+ (`covenants/partial-fill/fill-branches.ts`).
691
+
692
+ ### 0.9.2
693
+
694
+ Requires `@neuraiproject/neurai-create-transaction` `^0.9.2` so new
695
+ installations use the reset-testnet activation height and network metadata.
696
+ The asset-wrapper fixtures from the previous testnet remain historical codec
697
+ examples; live transactions must use the asset marker returned by the node for
698
+ the candidate block. NIP-041/043 and NIP-018 opcode constants and selectors
699
+ match the reset node. PQ cancel covenants now push a two-byte NIP-042 mask;
700
+ the default `0x1ff` also commits reference inputs. Historical one-byte masks
701
+ are rejected by the PQ covenant parser because they cannot execute under the
702
+ current `OP_TXHASH` rule.
703
+
637
704
  ### 0.9.1
638
705
 
639
706
  TypeScript declarations for CommonJS. `require()` loads `dist/index.cjs`, but