@neuraiproject/neurai-scripts 0.10.0 → 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
 
@@ -593,6 +594,66 @@ OP_ELSE
593
594
  OP_ENDIF
594
595
  ```
595
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
+
596
657
  ---
597
658
 
598
659
  ## Network handling
@@ -663,6 +724,16 @@ consumable; callers import directly from the package root.
663
724
 
664
725
  ## Version notes
665
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
+
666
737
  ### 0.10.0
667
738
 
668
739
  Security fix for the partial-fill covenant. Orders built with an earlier