@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 +138 -16
- package/dist/NeuraiScripts.global.js +1432 -483
- package/dist/NeuraiScripts.global.js.map +1 -1
- package/dist/browser.js +1419 -481
- package/dist/browser.js.map +1 -1
- package/dist/core/opcodes.d.ts +1 -0
- package/dist/covenants/asset-auth/index.d.ts +6 -0
- package/dist/covenants/asset-auth/policy.d.ts +47 -0
- package/dist/covenants/asset-auth/proposal.d.ts +28 -0
- package/dist/covenants/asset-auth/vote.d.ts +43 -0
- package/dist/covenants/index.d.ts +2 -0
- package/dist/covenants/partial-fill/fill-branches.d.ts +74 -0
- package/dist/covenants/partial-fill/parse-pq.d.ts +2 -3
- package/dist/covenants/partial-fill/parse.d.ts +8 -10
- package/dist/covenants/partial-fill/script-pq.d.ts +4 -4
- package/dist/covenants/partial-fill/script.d.ts +9 -10
- package/dist/index.cjs +1432 -483
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +181 -41
- package/dist/index.d.ts +2 -1
- package/dist/index.js +1419 -481
- package/dist/index.js.map +1 -1
- package/dist/types.d.ts +31 -11
- package/package.json +3 -2
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
|
-
//
|
|
440
|
-
//
|
|
441
|
-
|
|
442
|
-
//
|
|
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
|
-
//
|
|
465
|
-
//
|
|
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 (
|
|
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 <
|
|
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 <
|
|
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
|
-
| |
|
|
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
|
|
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
|
-
...
|
|
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
|