@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.
@@ -109,6 +109,7 @@ export declare const OP_SHA3_256 = 202;
109
109
  export declare const OP_SHA512 = 203;
110
110
  export declare const OP_CHECKSIG_ED25519 = 221;
111
111
  export declare const OP_CHECKSIGADD = 222;
112
+ export declare const OP_CHECKASSETAUTH = 223;
112
113
  export declare const OP_NOP1 = 176;
113
114
  export declare const OP_NOP9 = 184;
114
115
  export declare const OP_NOP10 = 185;
@@ -0,0 +1,6 @@
1
+ export { ASSETAUTH_POLICY_VERSION, ASSETAUTH_MAX_ROLES, buildAssetAuthPolicyScript, parseAssetAuthPolicyScript, buildAssetAuthArgs } from './policy.js';
2
+ export type { AssetAuthPolicy, AssetAuthArgs } from './policy.js';
3
+ export { ASSETAUTH_CHAIN_IDS, buildAssetAuthProposalMessage, assetAuthProposalHash } from './proposal.js';
4
+ export type { AssetAuthChain, AssetAuthProposal } from './proposal.js';
5
+ export { buildAssetAuthVoteLockScript, buildAssetAuthVoteExecuteArgs, buildAssetAuthVoteReturnArgs } from './vote.js';
6
+ export type { AssetAuthVoteLockParams } from './vote.js';
@@ -0,0 +1,47 @@
1
+ /**
2
+ * NIP-054 P2AH custody policy (`OP_CHECKASSETAUTH`, AuthScript only).
3
+ *
4
+ * The policy is the witnessScript of a generic AuthScript v1 (NoAuth)
5
+ * address. A spend of that address needs M of the N owner-token roles of the
6
+ * list to approve it (G of them when an owner token held by the custody
7
+ * leaves it):
8
+ *
9
+ * policy: <1> <M> <G> <role_1> ... <role_n> <n> OP_CHECKASSETAUTH
10
+ * witness: [0x00, <c>, <a>, <b>, <T>, policy]
11
+ *
12
+ * Build the four arguments with `buildAssetAuthArgs` and wrap them with
13
+ * `buildAuthScriptWitnessNoAuth({ args, witnessScript: policy })`. A role
14
+ * approves either by spending its owner token from P2PKH or a strict
15
+ * AuthScript address with a SIGHASH_ALL signature (synchronous spend, every
16
+ * argument 0), or by a vote (see `vote.ts` and `proposal.ts`).
17
+ */
18
+ /** The only policy version defined by NIP-054. */
19
+ export declare const ASSETAUTH_POLICY_VERSION = 1;
20
+ /** Highest number of roles in one policy. */
21
+ export declare const ASSETAUTH_MAX_ROLES = 16;
22
+ export interface AssetAuthPolicy {
23
+ /** Roles that must approve a spend. */
24
+ M: number;
25
+ /** Roles that must approve when an owner token held by the custody leaves it (M <= G). */
26
+ G: number;
27
+ /** Owner token names (`NAME!`, `&NAME!`). Any order: the script lists them sorted by bytes. */
28
+ roles: string[];
29
+ }
30
+ export interface AssetAuthArgs {
31
+ /** Proposal inputs: inputs 0..c-1 are committed by the proposal hash. */
32
+ c: number;
33
+ /** Proposal output prefix: outputs 0..a-1. */
34
+ a: number;
35
+ /** Proposal output suffix: the last b outputs. */
36
+ b: number;
37
+ /** Expiry height of the votes. */
38
+ T: number;
39
+ }
40
+ export declare function buildAssetAuthPolicyScript(policy: AssetAuthPolicy): Uint8Array;
41
+ /** Inverse of `buildAssetAuthPolicyScript`; rejects any other script. */
42
+ export declare function parseAssetAuthPolicyScript(script: Uint8Array): AssetAuthPolicy;
43
+ /**
44
+ * Witness `args` [<c>, <a>, <b>, <T>] for the custody input: minimal script
45
+ * numbers, 0 as the empty element. All default to 0, the synchronous spend.
46
+ */
47
+ export declare function buildAssetAuthArgs({ c, a, b, T }?: Partial<AssetAuthArgs>): Uint8Array[];
@@ -0,0 +1,28 @@
1
+ /**
2
+ * NIP-054 proposal hash H, the message a vote carries.
3
+ *
4
+ * H = TaggedHash("NeuraiAssetAuthProposal", m)
5
+ * m = chainId (u8) || nVersion (i32) || nLockTime (u32) || T (u32)
6
+ * || compact(c) || compact(a) || compact(b)
7
+ * || (outpoint, nSequence) of inputs 0..c-1
8
+ * || outputs 0..a-1 || the last b outputs
9
+ * || compact(#refs) || reference inputs (version 3 only)
10
+ *
11
+ * Inputs from index c on and the outputs between the prefix and the suffix
12
+ * (approvals, returns, fees, change) are left to the executor, so a skeleton
13
+ * transaction with only the proposal inputs and outputs gives the same H as
14
+ * the execution. Votes carry H as is, as the 32-byte (64-hex) message of
15
+ * their owner-token transfer: `bytesToHex(hash)`.
16
+ */
17
+ import type { AssetAuthArgs } from './policy.js';
18
+ export type AssetAuthChain = 'mainnet' | 'testnet' | 'regtest';
19
+ /** The chain identifier the node commits to (OP_CHAINCONTEXT selector 0x03). */
20
+ export declare const ASSETAUTH_CHAIN_IDS: Readonly<Record<AssetAuthChain, number>>;
21
+ export interface AssetAuthProposal extends AssetAuthArgs {
22
+ /** The execution, or a skeleton with its proposal inputs and outputs (hex). */
23
+ rawTx: string;
24
+ chain: AssetAuthChain;
25
+ }
26
+ export declare function buildAssetAuthProposalMessage(proposal: AssetAuthProposal): Uint8Array;
27
+ /** H: 32 bytes, in the order a vote carries it. */
28
+ export declare function assetAuthProposalHash(proposal: AssetAuthProposal): Uint8Array;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * NIP-054 vote lock: a wallet template (not part of the opcode) that holds a
3
+ * role's owner token while it votes for a proposal.
4
+ *
5
+ * The holder sends the owner token, with the proposal hash H as its transfer
6
+ * message, to the generic AuthScript v1 (NoAuth) address of this script:
7
+ *
8
+ * OP_IF execute, up to height T
9
+ * OP_1 OP_CHAINCONTEXT <T> OP_LESSTHANOREQUAL OP_VERIFY
10
+ * OP_SWAP OP_4 OP_INPUTFIELD <0x01 || C> OP_EQUALVERIFY
11
+ * OP_OUTPUTSCRIPT <return> OP_EQUAL
12
+ * OP_ELSE give it back, after T
13
+ * OP_1 OP_CHAINCONTEXT <T> OP_GREATERTHAN OP_VERIFY
14
+ * OP_NIP OP_OUTPUTSCRIPT <return> OP_EQUAL
15
+ * OP_ENDIF
16
+ *
17
+ * Both branches send the token back to its owner (`return`, the full output
18
+ * script). The execute branch also needs the custody, commitment C, at the
19
+ * input it names. It must use OP_INPUTFIELD selector 04, the full
20
+ * version-plus-commitment: selector 02 only reads the first 34 bytes of the
21
+ * spent script, which a forged anyone-can-spend custody can match.
22
+ */
23
+ export interface AssetAuthVoteLockParams {
24
+ /** Expiry height of the proposal the vote is for. */
25
+ T: number;
26
+ /** 32-byte AuthScript commitment C of the custody, as in its scriptPubKey `OP_1 <C>` (hex or bytes). */
27
+ custodyCommitment: string | Uint8Array;
28
+ /** The output script that gives the owner token back to its holder (hex or bytes). */
29
+ returnScriptPubKey: string | Uint8Array;
30
+ }
31
+ export declare function buildAssetAuthVoteLockScript(params: AssetAuthVoteLockParams): Uint8Array;
32
+ /**
33
+ * Witness `args` of the execute branch: the index of the custody input and
34
+ * the index of the output that returns the token.
35
+ */
36
+ export declare function buildAssetAuthVoteExecuteArgs(params: {
37
+ custodyInput: number;
38
+ returnOutput: number;
39
+ }): Uint8Array[];
40
+ /** Witness `args` of the return branch, after T. */
41
+ export declare function buildAssetAuthVoteReturnArgs(params: {
42
+ returnOutput: number;
43
+ }): Uint8Array[];
@@ -1 +1,3 @@
1
1
  export { buildPartialFillScript, buildPartialFillScriptHex, buildFillScriptSig, buildFillScriptSigHex, buildCancelScriptSig, buildCancelScriptSigHex, parsePartialFillScript, buildPartialFillScriptPQ, buildPartialFillScriptPQHex, buildCancelScriptSigPQ, buildCancelScriptSigPQHex, parsePartialFillScriptPQ, isPartialFillScriptPQ, DEFAULT_PQ_TXHASH_SELECTOR, buildFillWitnessStack, buildCancelWitnessStack, buildCancelWitnessStackPQ } from './partial-fill/index.js';
2
+ export { ASSETAUTH_POLICY_VERSION, ASSETAUTH_MAX_ROLES, ASSETAUTH_CHAIN_IDS, buildAssetAuthPolicyScript, parseAssetAuthPolicyScript, buildAssetAuthArgs, buildAssetAuthProposalMessage, assetAuthProposalHash, buildAssetAuthVoteLockScript, buildAssetAuthVoteExecuteArgs, buildAssetAuthVoteReturnArgs } from './asset-auth/index.js';
3
+ export type { AssetAuthPolicy, AssetAuthArgs, AssetAuthChain, AssetAuthProposal, AssetAuthVoteLockParams } from './asset-auth/index.js';
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Buyer fill branches shared by both Partial-Fill Sell Order variants
3
+ * (ECDSA cancel in `./script.ts`, ML-DSA-44 cancel in `./script-pq.ts`).
4
+ * The variants only differ in their cancel branch; everything after the
5
+ * outer `OP_ELSE` is emitted and parsed here.
6
+ *
7
+ * Input-0 binding. The fill branches read the order's asset amount with
8
+ * `<0> OP_INPUTASSETFIELD` and constrain outputs 0..2 by fixed index. Input
9
+ * indices are absolute and Script cannot ask for the index of the input
10
+ * being evaluated, so without a binding a buyer could:
11
+ * - put a foreign asset UTXO at input 0 and the order at input 1: the
12
+ * order then prices the fill by the foreign amount and the rest of the
13
+ * order leaves through an unconstrained output;
14
+ * - spend several identical orders together, every one of them satisfied
15
+ * by the same payment output.
16
+ * The fill block therefore opens with
17
+ *
18
+ * <0x80 0x00> OP_TXHASH <INPUT_ZERO_TXHASH> OP_EQUALVERIFY
19
+ *
20
+ * NIP-042 mask 0x0080 commits only to the index of the input being
21
+ * evaluated, so the digest equals the constant exactly when this covenant
22
+ * is spent as input 0. At most one order per transaction can take a fill
23
+ * branch; the seller's cancel branch is not bound.
24
+ *
25
+ * Layout (after the variant's `OP_IF <cancel> OP_ELSE`):
26
+ *
27
+ * <0x80 0x00> OP_TXHASH <INPUT_ZERO_TXHASH> OP_EQUALVERIFY
28
+ * OP_IF ← full fill, unlock <1> <0>
29
+ * [expiration gate]
30
+ * <0> <2> OP_INPUTASSETFIELD (N = order amount)
31
+ * DUP <price> MUL <0> OUTPUTVALUE SWAP GE VERIFY (payment value)
32
+ * <0> OUTPUTSCRIPT <paymentSpk> EQUALVERIFY (payment destination)
33
+ * DUP <1> <2> OUTPUTASSETFIELD EQUALVERIFY (buyer amount == N)
34
+ * <1> <1> OUTPUTASSETFIELD <tokenId> EQUALVERIFY (buyer asset name)
35
+ * DROP <1>
36
+ * OP_ELSE ← partial fill, unlock <N> <0> <0>
37
+ * [expiration gate]
38
+ * payment value, payment destination, buyer amount, buyer name (as above)
39
+ * <2> OUTPUTAUTHCOMMITMENT <2> TXFIELD EQUALVERIFY (continuation, NIP-023)
40
+ * <2> <1> OUTPUTASSETFIELD <tokenId> EQUALVERIFY (continuation name)
41
+ * <2> <2> OUTPUTASSETFIELD OVER <0> <2> INPUTASSETFIELD SWAP SUB EQUALVERIFY
42
+ * DROP <1>
43
+ * OP_ENDIF
44
+ */
45
+ import type { ScriptBuilder } from '../../core/script-builder.js';
46
+ import type { Cursor } from '../../core/script-parser.js';
47
+ import type { PartialFillExpiration } from '../../types.js';
48
+ /** NIP-042 mask (two bytes, little-endian) selecting only the current input index. */
49
+ export declare const INPUT_INDEX_TXHASH_SELECTOR: Uint8Array<ArrayBuffer>;
50
+ /**
51
+ * `OP_TXHASH(0x0080)` evaluated at input 0:
52
+ * `SHA256(tag || tag || 80 00 || 00 00 00 00)` with `tag = SHA256("NeuraiTxHash")`.
53
+ */
54
+ export declare const INPUT_ZERO_TXHASH: Uint8Array<ArrayBufferLike>;
55
+ export interface FillBranchParams {
56
+ /** scriptPubKey output 0 must pay (any destination type, no asset suffix). */
57
+ paymentScriptPubKey: Uint8Array;
58
+ tokenIdBytes: Uint8Array;
59
+ unitPriceSats: bigint;
60
+ expiration?: PartialFillExpiration;
61
+ }
62
+ export interface ParsedFillBranches {
63
+ paymentScriptPubKey: Uint8Array;
64
+ tokenId: string;
65
+ unitPriceSats: bigint;
66
+ expiration?: PartialFillExpiration;
67
+ }
68
+ /** Emit the input-0 binding and both fill branches, ending with the inner `OP_ENDIF`. */
69
+ export declare function appendFillBranches(b: ScriptBuilder, p: FillBranchParams): void;
70
+ /**
71
+ * Parse what `appendFillBranches` emits. Both branches must agree on price,
72
+ * payment destination, tokenId and expiration; any deviation throws.
73
+ */
74
+ export declare function readFillBranches(c: Cursor): ParsedFillBranches;
@@ -4,9 +4,8 @@
4
4
  * payment scriptPubKey bytes (which may be P2PKH or AuthScript) and the
5
5
  * configured TXHASH selector.
6
6
  *
7
- * The full-fill and partial-fill branches share `(paymentScriptPubKey,
8
- * unitPriceSats, tokenId)`. The parser reads both branches and verifies
9
- * consistency; inconsistency throws.
7
+ * The fill branches (and their input-0 binding) are read by the shared
8
+ * `readFillBranches`; covenants built before the binding are rejected.
10
9
  */
11
10
  import type { Network, ParsedPartialFillOrderPQ } from '../../types.js';
12
11
  /** Quick discriminator without throwing — useful for indexers. */
@@ -1,15 +1,13 @@
1
1
  /**
2
- * Parser for the Partial-Fill Sell Order covenant (three-branch).
2
+ * Parser for the Partial-Fill Sell Order covenant (three-branch, ECDSA cancel).
3
3
  *
4
- * Extracts `(sellerPubKeyHash, unitPriceSats, tokenId)` from a scriptPubKey
5
- * that was produced by `buildPartialFillScript`. Walks the exact byte
6
- * layout emitted by the builder and fails on any deviation — this is
7
- * deliberate, so a downstream indexer can unambiguously classify a UTXO as
8
- * "partial-fill order" or "unknown script" with no false positives.
9
- *
10
- * The full-fill and partial-fill branches share `(sellerScriptPubKey,
11
- * unitPriceSats, tokenId)`. The parser reads both branches and verifies
12
- * consistency; inconsistency throws.
4
+ * Extracts `(sellerPubKeyHash, paymentScriptPubKey, unitPriceSats, tokenId)`
5
+ * from a scriptPubKey that was produced by `buildPartialFillScript`. Walks
6
+ * the exact byte layout emitted by the builder and fails on any deviation —
7
+ * this is deliberate, so a downstream indexer can unambiguously classify a
8
+ * UTXO as "partial-fill order" or "unknown script" with no false positives.
9
+ * Covenants built before the input-0 binding (neurai-scripts < 0.10.0) are
10
+ * rejected: their fill branches can be drained through a foreign input 0.
13
11
  */
14
12
  import type { Network, ParsedPartialFillOrder } from '../../types.js';
15
13
  /**
@@ -19,11 +19,11 @@
19
19
  *
20
20
  * The message that gets signed is **SHA256(OP_TXHASH(selector))** — CSFS
21
21
  * single-SHA256s its message argument before verification, and OP_TXHASH
22
- * produces its own 32-byte hash, so the seller computes:
23
- * `sign(pqSeckey, SHA256(doubleSHA256(selected_tx_fields)))`
22
+ * produces its own 32-byte NIP-042 tagged hash, so the seller computes:
23
+ * `sign(pqSeckey, SHA256(TaggedHash("NeuraiTxHash", mask || selected_tx_fields)))`
24
24
  *
25
- * Fill branches are identical in structure to the legacy variant — see
26
- * `./script.ts` for the three-branch layout description.
25
+ * The fill branches, including the input-0 binding, are shared with the
26
+ * ECDSA variant — see `./fill-branches.ts`.
27
27
  */
28
28
  import type { PartialFillOrderPQParams } from '../../types.js';
29
29
  export declare const DEFAULT_PQ_TXHASH_SELECTOR = 511;
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Partial-Fill Sell Order covenant script (three-branch).
2
+ * Partial-Fill Sell Order covenant script (three-branch), ECDSA cancel.
3
3
  *
4
4
  * The covenant has three branches selected by the top of the unlock stack:
5
5
  *
@@ -19,11 +19,8 @@
19
19
  * amount == inputAmount - N)
20
20
  * output[3+] = optional buyer change (not constrained by the covenant)
21
21
  *
22
- * Continuity — the remainder UTXO reuses the spent covenant's AuthScript v1
23
- * commitment via `OP_OUTPUTAUTHCOMMITMENT(2) == OP_TXFIELD(0x02)` (NIP-023).
24
- * Comparing commitments rather than full scriptPubKeys is mandatory because
25
- * the remainder's asset wrapper carries a different `amountRaw` than the
26
- * spent UTXO's wrapper.
22
+ * The order must be input 0 for either fill branch to succeed: see the
23
+ * input-0 binding in `./fill-branches.ts`.
27
24
  *
28
25
  * Unlock stack shapes (scriptSig pushes, top → bottom):
29
26
  *
@@ -31,10 +28,12 @@
31
28
  * Full fill: <1> <0> (full-flag=1, cancel-flag=0)
32
29
  * Partial fill: <N> <0> <0> (N, full-flag=0, cancel-flag=0)
33
30
  *
34
- * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`) and
35
- * commits to a 20-byte PKH — this variant only accepts legacy P2PKH
36
- * addresses as the seller destination. For AuthScript bech32m destinations
37
- * and post-quantum signing, use `buildPartialFillScriptPQ`.
31
+ * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`)
32
+ * against a 20-byte key hash. The payment destination is independent of
33
+ * that key: a legacy P2PKH seller passes `sellerAddress` (both at once),
34
+ * any other seller with a secp256k1 key — typically a strict ECDSA v3
35
+ * `nq1r…` wallet — passes `paymentAddress` and `sellerPubKeyHash`. For
36
+ * post-quantum cancellation use `buildPartialFillScriptPQ`.
38
37
  */
39
38
  import type { PartialFillOrderParams } from '../../types.js';
40
39
  export { encodeP2PKHScriptPubKey } from '../../standard/p2pkh.js';