@neuraiproject/neurai-scripts 0.9.2 → 0.11.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
@@ -71,6 +71,7 @@ src/
71
71
  │ └── index.ts Barrel
72
72
  ├── covenants/ Covenant scripts
73
73
  │ ├── partial-fill/ Legacy (ECDSA cancel) + PQ (ML-DSA-44 via CSFS)
74
+ │ ├── asset-auth/ P2AH custody (NIP-054 OP_CHECKASSETAUTH): policy, proposal hash, vote lock
74
75
  │ └── index.ts Barrel
75
76
  ├── address.ts encodeSellerScriptPubKey (bech32m / base58check → spk)
76
77
  ├── types.ts Public types
@@ -125,7 +126,7 @@ stack, arithmetic, bitwise, crypto) plus every DePIN-Test addition
125
126
  `OP_INPUTASSETFIELD`, `OP_REFINPUTCOUNT`/`OP_REFINPUTFIELD`/
126
127
  `OP_REFINPUTASSETFIELD`, `OP_CHAINCONTEXT`, `OP_CAT`, `OP_SPLIT`,
127
128
  `OP_REVERSEBYTES`, `OP_OUTPUTAUTHDEST`, `OP_ZKVERIFY`, `OP_INPUTFIELD`,
128
- 64-bit `OP_MUL`/`OP_DIV`/`OP_MOD`).
129
+ `OP_CHECKASSETAUTH` (NIP-054), 64-bit `OP_MUL`/`OP_DIV`/`OP_MOD`).
129
130
 
130
131
  Also exports selector tables:
131
132
 
@@ -359,6 +360,22 @@ checked against the covenant's hardcoded parameters using
359
360
  `OP_OUTPUTASSETFIELD`, `OP_OUTPUTSCRIPT` and `OP_OUTPUTVALUE`. Consensus
360
361
  enforces every rule; there is no trusted off-chain layer.
361
362
 
363
+ **The order is always input 0.** `OP_INPUTASSETFIELD` takes an absolute
364
+ input index and Script cannot ask for the index of the input being
365
+ evaluated, so both fill branches open with an input-0 binding:
366
+
367
+ ```
368
+ <0x80 0x00> OP_TXHASH <OP_TXHASH(0x0080) at input 0> OP_EQUALVERIFY
369
+ ```
370
+
371
+ NIP-042 mask `0x0080` commits only to the current input index, so the
372
+ digest matches the hardcoded constant only when the order is spent as
373
+ input 0. Without it (covenants built before 0.10.0) a buyer could put a
374
+ foreign asset UTXO at input 0 to price the fill and take the rest of the
375
+ order through an unconstrained output, or settle several identical orders
376
+ with one payment. A transaction can fill at most one order; the cancel
377
+ branch is not bound.
378
+
362
379
  Three spending branches are selected by the top of the unlock stack:
363
380
 
364
381
  - `OP_IF` (unlock pushed `1`) — **Cancel**. The seller signs and
@@ -436,15 +453,23 @@ const scriptPubKeyHex = buildPartialFillScriptHex({
436
453
  value: 1_250_000n // fills are rejected at/after this value
437
454
  }
438
455
  });
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.
456
+ // `sellerAddress` must be a legacy P2PKH: it is both the payment
457
+ // destination and the cancel key hash.
458
+
459
+ // A seller with another secp256k1 address (a strict ECDSA v3 `tnq1r…`
460
+ // wallet) is paid at that address and cancels with the same key:
461
+ const v3OrderHex = buildPartialFillScriptHex({
462
+ paymentAddress: aliceV3Address, // any address type
463
+ sellerPubKeyHash: hash160(alicePubKey33), // key allowed to cancel
464
+ tokenId: 'CAT',
465
+ unitPriceSats: 100_000_000n
466
+ });
467
+ // Use `buildPartialFillScriptPQ` to cancel with an ML-DSA-44 key.
443
468
 
444
469
  // 2) Bob spends 5 CAT from the covenant.
445
470
  const bobScriptSigHex = buildFillScriptSigHex(5n);
446
471
  // Fill-tx layout (built with neurai-create-transaction):
447
- // vin[0] = covenant UTXO, scriptSig = bobScriptSigHex
472
+ // vin[0] = covenant UTXO (must be input 0), scriptSig = bobScriptSigHex
448
473
  // vin[1+] = buyer's XNA inputs (standard P2PKH, SIGHASH_ALL)
449
474
  // vout[0] = unitPriceSats * 5 XNA to Alice
450
475
  // vout[1] = 5 CAT to Bob
@@ -460,29 +485,29 @@ for (const utxo of candidateUtxos) {
460
485
  try {
461
486
  const order = parsePartialFillScript(utxo.scriptPubKeyHex, 'xna-test');
462
487
  // 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.
488
+ // order.paymentScriptPubKey, order.expiration, order.network
489
+ // sellerPubKeyHash is the cancel key; paymentScriptPubKey is where
490
+ // fills pay (the P2PKH of that same hash for sellerAddress orders).
467
491
  } catch {
468
492
  // not a partial-fill covenant, skip
469
493
  }
470
494
  }
471
495
  ```
472
496
 
473
- #### Script layout (legacy, three-branch)
497
+ #### Script layout (ECDSA cancel, three-branch)
474
498
 
475
499
  ```
476
500
  OP_IF // cancel branch
477
501
  OP_DUP OP_HASH160 <sellerPKH> OP_EQUALVERIFY OP_CHECKSIG
478
502
  OP_ELSE
503
+ <0x80 0x00> OP_TXHASH <INPUT_ZERO_TXHASH> OP_EQUALVERIFY // order is input 0
479
504
  OP_IF // full-fill branch
480
505
  # Stack entering: [ ] (scriptSig pushed <1> <0>)
481
506
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
482
507
  <0> <0x02> OP_INPUTASSETFIELD // N = inputAmount
483
508
  OP_DUP <unitPriceSats> OP_MUL
484
509
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
485
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
510
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
486
511
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
487
512
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
488
513
  OP_DROP OP_1 // no vout[2] required
@@ -491,7 +516,7 @@ OP_ELSE
491
516
  # Optional expiry: <deadline> <HEIGHT|MTP> OP_CHAINCONTEXT OP_GREATERTHAN OP_VERIFY
492
517
  OP_DUP <unitPriceSats> OP_MUL
493
518
  <0> OP_OUTPUTVALUE OP_SWAP OP_GREATERTHANOREQUAL OP_VERIFY // payment value
494
- <0> OP_OUTPUTSCRIPT <sellerP2PKH> OP_EQUALVERIFY // payment dest
519
+ <0> OP_OUTPUTSCRIPT <paymentSpk> OP_EQUALVERIFY // payment dest
495
520
  OP_DUP <1> <0x02> OP_OUTPUTASSETFIELD OP_EQUALVERIFY // buyer amount == N
496
521
  <1> <0x01> OP_OUTPUTASSETFIELD <tokenId> OP_EQUALVERIFY // buyer name
497
522
  <2> OP_OUTPUTAUTHCOMMITMENT <0x02> OP_TXFIELD OP_EQUALVERIFY // continuity (NIP-023)
@@ -509,6 +534,7 @@ OP_ENDIF
509
534
  - **No `MinFill` / `MaxFill` / `Expiry`.** Planned for v0.2.
510
535
  - **Fixed output layout** (`vout[0..2]`). The covenant rejects
511
536
  reorderings. Buyer change must go to `vout[3+]`.
537
+ - **One order per transaction**, always at `vin[0]` (input-0 binding).
512
538
  - **AMM is out of scope.** Covered by a later phase of the NIP roadmap.
513
539
 
514
540
  ### Partial-Fill PQ variant (post-quantum seller, NIP-18)
@@ -519,12 +545,12 @@ ECDSA `OP_CHECKSIG`. NIP-18 raises the per-element push cap to 3072 B so
519
545
  the ~2421 B signature and ~1313 B pubkey fit as stack items. All three
520
546
  are active on DePIN-Test testnet.
521
547
 
522
- | | Legacy | PQ |
548
+ | | ECDSA (`buildPartialFillScript`) | PQ |
523
549
  |---|---|---|
524
550
  | Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
525
551
  | 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
552
  | 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) |
553
+ | 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
554
 
529
555
  ```ts
530
556
  import {
@@ -564,10 +590,70 @@ OP_IF // scriptSig pushed <sig> <pubKey> OP_1
564
590
  OP_SWAP
565
591
  OP_CHECKSIGFROMSTACK // verifies sig over SHA256(msg) for pubKey
566
592
  OP_ELSE
567
- ... partial-fill branch (identical to legacy) ...
593
+ ... input-0 binding + fill branches (identical to the ECDSA variant) ...
568
594
  OP_ENDIF
569
595
  ```
570
596
 
597
+ ### P2AH custody (NIP-054 `OP_CHECKASSETAUTH`)
598
+
599
+ A custody is a generic AuthScript v1 (NoAuth) address whose witnessScript is
600
+ a policy: M of N owner-token roles (`NAME!`, `&NAME!`) must approve a spend,
601
+ G of them when an owner token held by the custody leaves it. Whoever holds a
602
+ role's owner token can approve. Active on testnet from block 100 and on
603
+ regtest from block 0; not scheduled on mainnet. The node rules are in
604
+ `doc/covenants.md` of Neurai.
605
+
606
+ ```ts
607
+ import { getNoAuthAddress } from '@neuraiproject/neurai-key';
608
+ import {
609
+ assetAuthProposalHash, buildAssetAuthArgs, buildAssetAuthPolicyScript,
610
+ buildAssetAuthVoteExecuteArgs, buildAssetAuthVoteLockScript,
611
+ buildAuthScriptWitnessNoAuth, bytesToHex
612
+ } from '@neuraiproject/neurai-scripts';
613
+
614
+ // <1> <M> <G> <role_1> ... <role_n> <n> OP_CHECKASSETAUTH, roles sorted by bytes.
615
+ const policy = buildAssetAuthPolicyScript({ M: 2, G: 3, roles: ['OPS!', 'ADMIN!', 'BOARD!'] });
616
+ const custody = getNoAuthAddress('xna-authscript-test', { witnessScript: policy });
617
+ ```
618
+
619
+ **Synchronous spend.** The approving owner tokens are inputs of the same
620
+ transaction, spent from P2PKH or a strict v2/v3 address and signed with
621
+ `SIGHASH_ALL`. The custody input takes `c a b T` all 0:
622
+
623
+ ```ts
624
+ const witness = buildAuthScriptWitnessNoAuth({ args: buildAssetAuthArgs(), witnessScript: policy });
625
+ // neurai-sign-transaction: { authType: 0, witnessScript: bytesToHex(policy), functionalArgs: ['', '', '', ''] }
626
+ ```
627
+
628
+ **Votes (asynchronous spend).** A proposal fixes the custody inputs
629
+ `0..c-1`, the first `a` and the last `b` outputs, and an expiry height `T`;
630
+ its hash `H` does not cover the rest, so votes can be cast on a skeleton
631
+ before the execution exists. A holder votes by sending its owner token, with
632
+ `bytesToHex(H)` as the 64-hex transfer message (`createTransferWithMessageOutput`;
633
+ an IPFS message counts as a vote for another proposal), to a vote lock:
634
+
635
+ ```ts
636
+ const H = assetAuthProposalHash({ rawTx: skeletonHex, chain: 'testnet', c: 1, a: 2, b: 0, T });
637
+ const lock = buildAssetAuthVoteLockScript({ T, custodyCommitment: custody.commitment, returnScriptPubKey });
638
+ const lockAddress = getNoAuthAddress('xna-authscript-test', { witnessScript: lock }).address;
639
+ ```
640
+
641
+ `returnScriptPubKey` is the transfer of the owner token, amount 1, back to
642
+ its holder. Anyone then executes: the custody input with
643
+ `buildAssetAuthArgs({ c, a, b, T })`, each vote with
644
+ `buildAssetAuthVoteExecuteArgs({ custodyInput, returnOutput })`, every vote
645
+ returned at its `returnOutput`, plus fee inputs and plain XNA change. After
646
+ `T` the holder takes an unused vote back with `buildAssetAuthVoteReturnArgs`.
647
+ With a vote the node also checks the shape of the execution (inputs from `c`
648
+ on are approvals or carry no asset, outputs between the prefix and the
649
+ suffix are returns or plain XNA change, the change is at most the XNA of
650
+ those inputs).
651
+
652
+ `parseAssetAuthPolicyScript` reads a policy back, and
653
+ `buildAssetAuthProposalMessage` returns the bytes that `H` hashes.
654
+ `assetAuthProposalHash` matches the vectors of the node's
655
+ `proposal_hash_vectors` test.
656
+
571
657
  ---
572
658
 
573
659
  ## Network handling
@@ -638,6 +724,42 @@ consumable; callers import directly from the package root.
638
724
 
639
725
  ## Version notes
640
726
 
727
+ ### 0.11.0
728
+
729
+ - P2AH custody (NIP-054 `OP_CHECKASSETAUTH`, slot `0xdf`): `opcodes.OP_CHECKASSETAUTH`,
730
+ `buildAssetAuthPolicyScript` / `parseAssetAuthPolicyScript`, `buildAssetAuthArgs`,
731
+ `assetAuthProposalHash` / `buildAssetAuthProposalMessage`, `buildAssetAuthVoteLockScript`,
732
+ `buildAssetAuthVoteExecuteArgs` and `buildAssetAuthVoteReturnArgs`. Checked against a regtest
733
+ node built from Neurai `c665ba3` (`tests/node-regtest-assetauth.test.ts`).
734
+ - New dependency `@noble/hashes` (SHA-256 of the proposal hash); it already came with
735
+ neurai-create-transaction.
736
+
737
+ ### 0.10.0
738
+
739
+ Security fix for the partial-fill covenant. Orders built with an earlier
740
+ version stay exposed until they are cancelled: cancel them with
741
+ neurai-sign-transaction 3.1.0 (the last release whose parser reads them)
742
+ and publish them again.
743
+
744
+ - **Input-0 binding.** The fill branches read the order amount from input 0
745
+ but did not check that the order was input 0. A buyer could place a
746
+ foreign asset UTXO at input 0 and take the whole order for the price of
747
+ that UTXO, or settle several identical orders with one payment (both
748
+ reproduced against a regtest node). Both fill branches now open with
749
+ `<0x80 0x00> OP_TXHASH <OP_TXHASH(0x0080) at input 0> OP_EQUALVERIFY`,
750
+ so an order can only be filled as input 0 and at most one order per
751
+ transaction. Requires NIP-042 `OP_TXHASH`.
752
+ - `parsePartialFillScript` / `parsePartialFillScriptPQ` reject covenants
753
+ without the binding, so signers refuse to treat old orders as fillable or
754
+ cancellable through them.
755
+ - ECDSA-cancel orders take `paymentAddress` + `sellerPubKeyHash` as an
756
+ alternative to `sellerAddress`: the payment destination can be any
757
+ address type (for example the strict ECDSA v3 `nq1r…` wallet of the key
758
+ that cancels). `ParsedPartialFillOrder` gains `paymentScriptPubKey`, and
759
+ the parser no longer requires it to be the P2PKH of `sellerPubKeyHash`.
760
+ - Both variants share one implementation of the fill branches
761
+ (`covenants/partial-fill/fill-branches.ts`).
762
+
641
763
  ### 0.9.2
642
764
 
643
765
  Requires `@neuraiproject/neurai-create-transaction` `^0.9.2` so new