@neuraiproject/neurai-scripts 0.3.0 → 0.5.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.
@@ -121,6 +121,7 @@ export declare const OP_XNA_ASSET = 192;
121
121
  export declare const OP_REFINPUTFIELD = 210;
122
122
  export declare const OP_REFINPUTASSETFIELD = 211;
123
123
  export declare const OP_REFINPUTCOUNT = 212;
124
+ export declare const OP_OUTPUTAUTHCOMMITMENT = 213;
124
125
  export declare const OP_CAT = 126;
125
126
  export declare const OP_SPLIT = 183;
126
127
  export declare const OP_REVERSEBYTES = 188;
@@ -1,8 +1,12 @@
1
1
  /**
2
- * Parser for the PQ Partial-Fill Sell Order covenant. Returns the same
3
- * economic parameters as the legacy parser, plus the payment scriptPubKey
4
- * bytes (which may be P2PKH or AuthScript) and the configured TXHASH
5
- * selector.
2
+ * Parser for the PQ Partial-Fill Sell Order covenant (three-branch).
3
+ * Returns the same economic parameters as the legacy parser, plus the
4
+ * payment scriptPubKey bytes (which may be P2PKH or AuthScript) and the
5
+ * configured TXHASH selector.
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.
6
10
  */
7
11
  import type { Network, ParsedPartialFillOrderPQ } from '../../types.js';
8
12
  /** Quick discriminator without throwing — useful for indexers. */
@@ -1,11 +1,15 @@
1
1
  /**
2
- * Parser for the Partial-Fill Sell Order covenant.
2
+ * Parser for the Partial-Fill Sell Order covenant (three-branch).
3
3
  *
4
4
  * Extracts `(sellerPubKeyHash, unitPriceSats, tokenId)` from a scriptPubKey
5
- * that was produced by `buildPartialFillScript`. The parser walks the exact
6
- * byte layout emitted by the builder and fails on any deviation — this is
5
+ * that was produced by `buildPartialFillScript`. Walks the exact byte
6
+ * layout emitted by the builder and fails on any deviation — this is
7
7
  * deliberate, so a downstream indexer can unambiguously classify a UTXO as
8
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.
9
13
  */
10
14
  import type { Network, ParsedPartialFillOrder } from '../../types.js';
11
15
  /**
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * PQ (post-quantum) variant of the Partial-Fill Sell Order covenant.
3
3
  *
4
- * Identical partial-fill branch to the legacy covenant, but the **cancel**
5
- * branch accepts an ML-DSA-44 signature instead of an ECDSA one. This
6
- * requires:
4
+ * Identical fill branches (full + partial) to the legacy covenant, but the
5
+ * **cancel** branch accepts an ML-DSA-44 signature instead of an ECDSA one.
6
+ * This requires:
7
7
  * - `SCRIPT_VERIFY_CHECKSIGFROMSTACK` (for OP_CSFS) active
8
8
  * - `SCRIPT_VERIFY_TXHASH` (for OP_TXHASH) active
9
9
  * - NIP-18 (`MAX_PQ_SCRIPT_ELEMENT_SIZE = 3072`) active, so the ~2.4 KB
@@ -21,6 +21,9 @@
21
21
  * single-SHA256s its message argument before verification, and OP_TXHASH
22
22
  * produces its own 32-byte hash, so the seller computes:
23
23
  * `sign(pqSeckey, SHA256(doubleSHA256(selected_tx_fields)))`
24
+ *
25
+ * Fill branches are identical in structure to the legacy variant — see
26
+ * `./script.ts` for the three-branch layout description.
24
27
  */
25
28
  import type { PartialFillOrderPQParams } from '../../types.js';
26
29
  export declare const DEFAULT_PQ_TXHASH_SELECTOR = 255;
@@ -1,29 +1,40 @@
1
1
  /**
2
- * Partial-Fill Sell Order covenant script.
2
+ * Partial-Fill Sell Order covenant script (three-branch).
3
3
  *
4
- * The covenant has two branches selected by the top of the unlock stack:
4
+ * The covenant has three branches selected by the top of the unlock stack:
5
5
  *
6
- * OP_IF (unlock pushed 1) → Cancel: seller signs, recovers remainder.
7
- * OP_ELSE (unlock pushed 0) → Public partial fill: buyer provides the
8
- * fill amount `N` and the tx layout is
9
- * validated byte by byte.
6
+ * OP_IF ← Cancel: seller signs, recovers remainder.
7
+ * OP_ELSE OP_IF ← Full fill: buyer drains the covenant entirely.
8
+ * No continuation output is required.
9
+ * OP_ELSE OP_ELSE ← Partial fill: buyer takes N < total. A
10
+ * continuation UTXO at vout[2] preserves the
11
+ * covenant with amount = total - N.
10
12
  *
11
- * The partial-fill branch enforces a fixed output layout so that the script
12
- * stays compact and parseable:
13
+ * Output layout:
13
14
  *
14
15
  * output[0] = XNA payment to seller (value >= N * unitPriceSats)
15
16
  * output[1] = asset to buyer (tokenId, amount == N)
16
- * output[2] = covenant remainder (same scriptPubKey, amount == in - N)
17
+ * output[2] = covenant continuation (only for partial fill;
18
+ * same AuthScript commitment,
19
+ * amount == inputAmount - N)
17
20
  * output[3+] = optional buyer change (not constrained by the covenant)
18
21
  *
19
- * The remainder UTXO reuses the spent scriptPubKey via
20
- * `OP_OUTPUTSCRIPT == OP_TXFIELD 0x03`, so the covenant is self-replicating
21
- * without hardcoding its own hash.
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.
27
+ *
28
+ * Unlock stack shapes (scriptSig pushes, top → bottom):
29
+ *
30
+ * Cancel: <sig> <pubkey> <1>
31
+ * Full fill: <1> <0> (full-flag=1, cancel-flag=0)
32
+ * Partial fill: <N> <0> <0> (N, full-flag=0, cancel-flag=0)
22
33
  *
23
34
  * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`) and
24
- * commits to a 20-byte PKH. As a consequence this variant only accepts
25
- * legacy P2PKH addresses as the seller destination. For AuthScript bech32m
26
- * destinations and post-quantum signing, use `buildPartialFillScriptPQ`.
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`.
27
38
  */
28
39
  import type { PartialFillOrderParams } from '../../types.js';
29
40
  export { encodeP2PKHScriptPubKey } from '../../standard/p2pkh.js';
@@ -7,21 +7,27 @@
7
7
  * with `@neuraiproject/neurai-create-transaction`.
8
8
  */
9
9
  /**
10
- * Unlock the covenant via the public partial-fill branch.
10
+ * Unlock the covenant via the public fill branches.
11
11
  *
12
- * Layout on the stack before OP_IF executes (top → bottom):
13
- * 0 ← selects the OP_ELSE (fill) branch
14
- * N ← amount of asset the buyer is taking from this order
12
+ * amount === total → full-fill branch. The entire covenant drains to
13
+ * vout[1]; no vout[2] continuation is emitted.
14
+ * amount < total → partial-fill branch. vout[2] re-locks the
15
+ * continuation (`total - amount` units).
15
16
  *
16
- * so the scriptSig pushes `<N>` then `<0>`.
17
+ * Unlock stack shapes (pushed bottom → top):
17
18
  *
18
- * @param amount units of the asset the buyer is taking. Must be > 0 and
19
- * strictly less than the amount locked in the order UTXO
20
- * (equal would leave a zero-asset remainder, which isn't a
21
- * valid Neurai transfer output).
19
+ * Full fill: <1> <0> ( full-flag=1, cancel-flag=0 )
20
+ * Partial fill: <N> <0> <0> ( N, full-flag=0, cancel-flag=0 )
21
+ *
22
+ * @param amount units the buyer is taking. Must be > 0 and ≤ total.
23
+ * @param total current asset amount locked in the covenant UTXO. The
24
+ * builder reads this to decide whether to emit the full-fill
25
+ * or partial-fill witness — consensus uses `OP_INPUTASSETFIELD`
26
+ * inside the covenant to check it independently, so the value
27
+ * passed here must match on-chain reality or the script fails.
22
28
  */
23
- export declare function buildFillScriptSig(amount: bigint): Uint8Array;
24
- export declare function buildFillScriptSigHex(amount: bigint): string;
29
+ export declare function buildFillScriptSig(amount: bigint, total: bigint): Uint8Array;
30
+ export declare function buildFillScriptSigHex(amount: bigint, total: bigint): string;
25
31
  /**
26
32
  * Unlock the covenant via the seller's cancel branch.
27
33
  *