@neuraiproject/neurai-scripts 0.9.2 → 0.10.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/dist/index.d.cts CHANGED
@@ -45,17 +45,35 @@ interface PartialFillExpiration {
45
45
  */
46
46
  value: bigint;
47
47
  }
48
+ /**
49
+ * Seller of an ECDSA-cancel order, in one of two forms:
50
+ * - `sellerAddress` alone: a legacy P2PKH address that is both the
51
+ * payment destination and the cancel key hash;
52
+ * - `paymentAddress` with `sellerPubKeyHash`: any payment destination
53
+ * and the HASH160 of the secp256k1 key that may cancel. This is the
54
+ * form for a strict ECDSA v3 (`nq1r…`) seller, whose address program is
55
+ * a commitment and not a key hash.
56
+ * Passing both forms, or neither, throws.
57
+ */
48
58
  interface PartialFillOrderParams {
49
59
  /**
50
- * Seller destination. Must be a legacy P2PKH address (base58check,
51
- * "t..." on testnet, "N..." on mainnet). The legacy covenant uses
52
- * `OP_HASH160 + OP_CHECKSIG` in its cancel branch, so every bech32m
53
- * address (AuthScript v1 `nc1p…`, PQ v2 `pq1z…` and ECDSA v3 `nq1r…`,
54
- * whose program is a commitment, not a key hash) is rejected — use
55
- * `buildPartialFillScriptPQ` for those destinations. The decoded 20-byte
56
- * PKH is hardcoded into the covenant (cancel branch + payment scriptPubKey).
60
+ * Legacy P2PKH seller (base58check, "t..." on testnet, "N..." on
61
+ * mainnet). Its 20-byte PKH is hardcoded as the cancel key hash and the
62
+ * payment output must be the P2PKH script of that same PKH. Bech32m
63
+ * addresses are rejected here: use `paymentAddress` + `sellerPubKeyHash`.
64
+ */
65
+ sellerAddress?: string;
66
+ /**
67
+ * Destination for the XNA payment: legacy P2PKH, generic AuthScript v1
68
+ * (`nc1p…`), strict PQ v2 (`pq1z…`) or strict ECDSA v3 (`nq1r…`). The
69
+ * covenant hardcodes its full scriptPubKey. Requires `sellerPubKeyHash`.
70
+ */
71
+ paymentAddress?: string;
72
+ /**
73
+ * HASH160 of the compressed secp256k1 public key allowed to cancel the
74
+ * order (20 bytes). Requires `paymentAddress`.
57
75
  */
58
- sellerAddress: string;
76
+ sellerPubKeyHash?: Uint8Array;
59
77
  /** Name of the asset being sold (e.g. "CAT"). */
60
78
  tokenId: string;
61
79
  /**
@@ -78,11 +96,13 @@ interface ParsedPartialFillOrder {
78
96
  /** Network the parser was invoked with (used for downstream address formatting). */
79
97
  network: Network;
80
98
  /**
81
- * Seller's 20-byte pubkey hash, extracted from the covenant's cancel
82
- * branch. The caller can base58check-encode this with the network's
83
- * legacy prefix to recover the seller address when needed.
99
+ * 20-byte HASH160 of the key allowed to cancel, extracted from the
100
+ * covenant's cancel branch. It equals the payment P2PKH hash only for
101
+ * orders built with `sellerAddress`.
84
102
  */
85
103
  sellerPubKeyHash: Uint8Array;
104
+ /** scriptPubKey bytes embedded in the covenant for the payment output. */
105
+ paymentScriptPubKey: Uint8Array;
86
106
  /** Asset name parsed from the covenant. */
87
107
  tokenId: string;
88
108
  /** Unit price parsed from the covenant, in XNA satoshis. */
@@ -991,7 +1011,7 @@ interface SplitAssetWrappedResult {
991
1011
  declare function splitAssetWrappedScriptPubKey(spkHex: string): SplitAssetWrappedResult;
992
1012
 
993
1013
  /**
994
- * Partial-Fill Sell Order covenant script (three-branch).
1014
+ * Partial-Fill Sell Order covenant script (three-branch), ECDSA cancel.
995
1015
  *
996
1016
  * The covenant has three branches selected by the top of the unlock stack:
997
1017
  *
@@ -1011,11 +1031,8 @@ declare function splitAssetWrappedScriptPubKey(spkHex: string): SplitAssetWrappe
1011
1031
  * amount == inputAmount - N)
1012
1032
  * output[3+] = optional buyer change (not constrained by the covenant)
1013
1033
  *
1014
- * Continuity — the remainder UTXO reuses the spent covenant's AuthScript v1
1015
- * commitment via `OP_OUTPUTAUTHCOMMITMENT(2) == OP_TXFIELD(0x02)` (NIP-023).
1016
- * Comparing commitments rather than full scriptPubKeys is mandatory because
1017
- * the remainder's asset wrapper carries a different `amountRaw` than the
1018
- * spent UTXO's wrapper.
1034
+ * The order must be input 0 for either fill branch to succeed: see the
1035
+ * input-0 binding in `./fill-branches.ts`.
1019
1036
  *
1020
1037
  * Unlock stack shapes (scriptSig pushes, top → bottom):
1021
1038
  *
@@ -1023,10 +1040,12 @@ declare function splitAssetWrappedScriptPubKey(spkHex: string): SplitAssetWrappe
1023
1040
  * Full fill: <1> <0> (full-flag=1, cancel-flag=0)
1024
1041
  * Partial fill: <N> <0> <0> (N, full-flag=0, cancel-flag=0)
1025
1042
  *
1026
- * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`) and
1027
- * commits to a 20-byte PKH — this variant only accepts legacy P2PKH
1028
- * addresses as the seller destination. For AuthScript bech32m destinations
1029
- * and post-quantum signing, use `buildPartialFillScriptPQ`.
1043
+ * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`)
1044
+ * against a 20-byte key hash. The payment destination is independent of
1045
+ * that key: a legacy P2PKH seller passes `sellerAddress` (both at once),
1046
+ * any other seller with a secp256k1 key — typically a strict ECDSA v3
1047
+ * `nq1r…` wallet — passes `paymentAddress` and `sellerPubKeyHash`. For
1048
+ * post-quantum cancellation use `buildPartialFillScriptPQ`.
1030
1049
  */
1031
1050
 
1032
1051
  /**
@@ -1058,11 +1077,11 @@ declare function buildPartialFillScriptHex(params: PartialFillOrderParams): stri
1058
1077
  *
1059
1078
  * The message that gets signed is **SHA256(OP_TXHASH(selector))** — CSFS
1060
1079
  * single-SHA256s its message argument before verification, and OP_TXHASH
1061
- * produces its own 32-byte hash, so the seller computes:
1062
- * `sign(pqSeckey, SHA256(doubleSHA256(selected_tx_fields)))`
1080
+ * produces its own 32-byte NIP-042 tagged hash, so the seller computes:
1081
+ * `sign(pqSeckey, SHA256(TaggedHash("NeuraiTxHash", mask || selected_tx_fields)))`
1063
1082
  *
1064
- * Fill branches are identical in structure to the legacy variant — see
1065
- * `./script.ts` for the three-branch layout description.
1083
+ * The fill branches, including the input-0 binding, are shared with the
1084
+ * ECDSA variant — see `./fill-branches.ts`.
1066
1085
  */
1067
1086
 
1068
1087
  declare const DEFAULT_PQ_TXHASH_SELECTOR = 511;
@@ -1185,17 +1204,15 @@ declare function buildCancelWitnessStack(signatureDer: Uint8Array, pubKey: Uint8
1185
1204
  declare function buildCancelWitnessStackPQ(sigPQ: Uint8Array, pubKey: Uint8Array): Uint8Array[];
1186
1205
 
1187
1206
  /**
1188
- * Parser for the Partial-Fill Sell Order covenant (three-branch).
1189
- *
1190
- * Extracts `(sellerPubKeyHash, unitPriceSats, tokenId)` from a scriptPubKey
1191
- * that was produced by `buildPartialFillScript`. Walks the exact byte
1192
- * layout emitted by the builder and fails on any deviation — this is
1193
- * deliberate, so a downstream indexer can unambiguously classify a UTXO as
1194
- * "partial-fill order" or "unknown script" with no false positives.
1195
- *
1196
- * The full-fill and partial-fill branches share `(sellerScriptPubKey,
1197
- * unitPriceSats, tokenId)`. The parser reads both branches and verifies
1198
- * consistency; inconsistency throws.
1207
+ * Parser for the Partial-Fill Sell Order covenant (three-branch, ECDSA cancel).
1208
+ *
1209
+ * Extracts `(sellerPubKeyHash, paymentScriptPubKey, unitPriceSats, tokenId)`
1210
+ * from a scriptPubKey that was produced by `buildPartialFillScript`. Walks
1211
+ * the exact byte layout emitted by the builder and fails on any deviation —
1212
+ * this is deliberate, so a downstream indexer can unambiguously classify a
1213
+ * UTXO as "partial-fill order" or "unknown script" with no false positives.
1214
+ * Covenants built before the input-0 binding (neurai-scripts < 0.10.0) are
1215
+ * rejected: their fill branches can be drained through a foreign input 0.
1199
1216
  */
1200
1217
 
1201
1218
  /**
@@ -1210,9 +1227,8 @@ declare function parsePartialFillScript(script: Uint8Array | string, network?: N
1210
1227
  * payment scriptPubKey bytes (which may be P2PKH or AuthScript) and the
1211
1228
  * configured TXHASH selector.
1212
1229
  *
1213
- * The full-fill and partial-fill branches share `(paymentScriptPubKey,
1214
- * unitPriceSats, tokenId)`. The parser reads both branches and verifies
1215
- * consistency; inconsistency throws.
1230
+ * The fill branches (and their input-0 binding) are read by the shared
1231
+ * `readFillBranches`; covenants built before the binding are rejected.
1216
1232
  */
1217
1233
 
1218
1234
  /** Quick discriminator without throwing — useful for indexers. */