@neuraiproject/neurai-scripts 0.9.2 → 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
@@ -359,6 +359,22 @@ checked against the covenant's hardcoded parameters using
359
359
  `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
360
360
  enforces every rule; there is no trusted off-chain layer.
361
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
+
362
378
  Three spending branches are selected by the top of the unlock stack:
363
379
 
364
380
  - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
@@ -436,15 +452,23 @@ const scriptPubKeyHex = buildPartialFillScriptHex({
436
452
  value: 1_250_000n // fills are rejected at/after this value
437
453
  }
438
454
  });
439
- // Throws if the address is not a legacy P2PKH — the legacy covenant uses
440
- // OP_HASH160 + OP_CHECKSIG on the cancel branch and cannot commit to an
441
- // AuthScript program. Use `buildPartialFillScriptPQ` for bech32m / PQ
442
- // 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.
443
467
 
444
468
  // 2) Bob spends 5 CAT from the covenant.
445
469
  const bobScriptSigHex = buildFillScriptSigHex(5n);
446
470
  // Fill-tx layout (built with neurai-create-transaction):
447
- // vin[0] = covenant UTXO, scriptSig = bobScriptSigHex
471
+ // vin[0] = covenant UTXO (must be input 0), scriptSig = bobScriptSigHex
448
472
  // vin[1+] = buyer's XNA inputs (standard P2PKH, SIGHASH_ALL)
449
473
  // vout[0] = unitPriceSats * 5 XNA to Alice
450
474
  // vout[1] = 5 CAT to Bob
@@ -460,29 +484,29 @@ for (const utxo of candidateUtxos) {
460
484
  try {
461
485
  const order = parsePartialFillScript(utxo.scriptPubKeyHex, 'xna-test');
462
486
  // order.tokenId, order.unitPriceSats, order.sellerPubKeyHash,
463
- // order.expiration, order.network
464
- // The parser returns the 20-byte PKH; base58check-encode with the
465
- // network's legacy prefix (0x35 mainnet / 0x7f testnet) if you need
466
- // 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).
467
490
  } catch {
468
491
  // not a partial-fill covenant, skip
469
492
  }
470
493
  }
471
494
  ```
472
495
 
473
- #### Script layout (legacy, three-branch)
496
+ #### Script layout (ECDSA cancel, three-branch)
474
497
 
475
498
  ```
476
499
  OP_IF // cancel branch
477
500
  OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG
478
501
  OP_ELSE
502
+ <0x80 0x00> OP_TXHASH <INPUT_ZERO_TXHASH> OP_EQUALVERIFY // order is input 0
479
503
  OP_IF // full-fill branch
480
504
  # Stack entering: [ ] (scriptSig pushed <1> <0>)
481
505
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
482
506
  <0> <0x02> OP_INPUTASSETFIELD // N = inputAmount
483
507
  OP_DUP <unitPriceSats> OP_MUL
484
508
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
485
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
509
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
486
510
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
487
511
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
488
512
  OP_DROP OP_1 // no vout[2] required
@@ -491,7 +515,7 @@ OP_ELSE
491
515
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
492
516
  OP_DUP <unitPriceSats> OP_MUL
493
517
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
494
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
518
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
495
519
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
496
520
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
497
521
  <2> OP_OUTPUTAUTHCOMMITMENT <0x02> OP_TXFIELD OP_EQUALVERIFY // continuity (NIP-023)
@@ -509,6 +533,7 @@ OP_ENDIF
509
533
  - **No `MinFill` / `MaxFill` / `Expiry`.** Planned for v0.2.
510
534
  - **Fixed output layout** (`vout[0..2]`). The covenant rejects
511
535
  reorderings. Buyer change must go to `vout[3+]`.
536
+ - **One order per transaction**, always at `vin[0]` (input-0 binding).
512
537
  - **AMM is out of scope.** Covered by a later phase of the NIP roadmap.
513
538
 
514
539
  ### Partial-Fill PQ variant (post-quantum seller, NIP-18)
@@ -519,12 +544,12 @@ ECDSA `OP_CHECKSIG`. NIP-18 raises the per-element push cap to 3072 B so
519
544
  the ~2421 B signature and ~1313 B pubkey fit as stack items. All three
520
545
  are active on DePIN-Test testnet.
521
546
 
522
- | | Legacy | PQ |
547
+ | | ECDSA (`buildPartialFillScript`) | PQ |
523
548
  |---|---|---|
524
549
  | Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
525
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` |
526
551
  | What Alice signs | tx sighash (standard) | `SHA256(OP_TXHASH(selector))` — CSFS single-SHA256s the message |
527
- | 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) |
528
553
 
529
554
  ```ts
530
555
  import {
@@ -564,7 +589,7 @@ OP_IF // scriptSig pushed <sig> <pubKey> OP_1
564
589
  OP_SWAP
565
590
  OP_CHECKSIGFROMSTACK // verifies sig over SHA256(msg) for pubKey
566
591
  OP_ELSE
567
- ... partial-fill branch (identical to legacy) ...
592
+ ... input-0 binding + fill branches (identical to the ECDSA variant) ...
568
593
  OP_ENDIF
569
594
  ```
570
595
 
@@ -638,6 +663,32 @@ consumable; callers import directly from the package root.
638
663
 
639
664
  ## Version notes
640
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
+
641
692
  ### 0.9.2
642
693
 
643
694
  Requires `@neuraiproject/neurai-create-transaction` `^0.9.2` so new