@neuraiproject/neurai-scripts 0.4.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.
package/dist/index.cjs CHANGED
@@ -1746,35 +1746,42 @@ function splitAssetWrappedScriptPubKey(spkHex) {
1746
1746
  }
1747
1747
 
1748
1748
  /**
1749
- * Partial-Fill Sell Order covenant script.
1749
+ * Partial-Fill Sell Order covenant script (three-branch).
1750
1750
  *
1751
- * The covenant has two branches selected by the top of the unlock stack:
1751
+ * The covenant has three branches selected by the top of the unlock stack:
1752
1752
  *
1753
- * OP_IF (unlock pushed 1) → Cancel: seller signs, recovers remainder.
1754
- * OP_ELSE (unlock pushed 0) → Public partial fill: buyer provides the
1755
- * fill amount `N` and the tx layout is
1756
- * validated byte by byte.
1753
+ * OP_IF ← Cancel: seller signs, recovers remainder.
1754
+ * OP_ELSE OP_IF ← Full fill: buyer drains the covenant entirely.
1755
+ * No continuation output is required.
1756
+ * OP_ELSE OP_ELSE ← Partial fill: buyer takes N < total. A
1757
+ * continuation UTXO at vout[2] preserves the
1758
+ * covenant with amount = total - N.
1757
1759
  *
1758
- * The partial-fill branch enforces a fixed output layout so that the script
1759
- * stays compact and parseable:
1760
+ * Output layout:
1760
1761
  *
1761
1762
  * output[0] = XNA payment to seller (value >= N * unitPriceSats)
1762
1763
  * output[1] = asset to buyer (tokenId, amount == N)
1763
- * output[2] = covenant remainder (same AuthScript commitment, amount == in - N)
1764
+ * output[2] = covenant continuation (only for partial fill;
1765
+ * same AuthScript commitment,
1766
+ * amount == inputAmount - N)
1764
1767
  * output[3+] = optional buyer change (not constrained by the covenant)
1765
1768
  *
1766
- * The remainder UTXO reuses the spent covenant's AuthScript v1 commitment
1767
- * via `OP_OUTPUTAUTHCOMMITMENT(2) == OP_TXFIELD(0x02)` (NIP-023). Comparing
1768
- * commitments rather than full scriptPubKeys is mandatory here: the
1769
- * remainder output's asset wrapper (`OP_XNA_ASSET ... OP_DROP`) encodes a
1770
- * smaller `amountRaw` than the spent UTXO's wrapper, so the full-spk
1771
- * equality used by earlier drafts was vacuously unsatisfiable on any
1772
- * asset-wrapped covenant UTXO.
1769
+ * Continuity — the remainder UTXO reuses the spent covenant's AuthScript v1
1770
+ * commitment via `OP_OUTPUTAUTHCOMMITMENT(2) == OP_TXFIELD(0x02)` (NIP-023).
1771
+ * Comparing commitments rather than full scriptPubKeys is mandatory because
1772
+ * the remainder's asset wrapper carries a different `amountRaw` than the
1773
+ * spent UTXO's wrapper.
1774
+ *
1775
+ * Unlock stack shapes (scriptSig pushes, top → bottom):
1776
+ *
1777
+ * Cancel: <sig> <pubkey> <1>
1778
+ * Full fill: <1> <0> (full-flag=1, cancel-flag=0)
1779
+ * Partial fill: <N> <0> <0> (N, full-flag=0, cancel-flag=0)
1773
1780
  *
1774
1781
  * The cancel branch uses classical ECDSA (`OP_HASH160 + OP_CHECKSIG`) and
1775
- * commits to a 20-byte PKH. As a consequence this variant only accepts
1776
- * legacy P2PKH addresses as the seller destination. For AuthScript bech32m
1777
- * destinations and post-quantum signing, use `buildPartialFillScriptPQ`.
1782
+ * commits to a 20-byte PKH — this variant only accepts legacy P2PKH
1783
+ * addresses as the seller destination. For AuthScript bech32m destinations
1784
+ * and post-quantum signing, use `buildPartialFillScriptPQ`.
1778
1785
  */
1779
1786
  const ASSET_NAME_MAX$1 = 32;
1780
1787
  function decodeSellerAddress(sellerAddress) {
@@ -1810,8 +1817,6 @@ function assertPrice$1(priceSats) {
1810
1817
  if (priceSats <= 0n) {
1811
1818
  throw new Error('unitPriceSats must be > 0');
1812
1819
  }
1813
- // 8-byte signed int ceiling: values beyond this cannot be produced by OP_MUL
1814
- // inside the covenant without overflow (CScriptNum is int64).
1815
1820
  if (priceSats > 0x7fffffffffffffffn) {
1816
1821
  throw new Error('unitPriceSats exceeds int64 range');
1817
1822
  }
@@ -1828,19 +1833,28 @@ function buildPartialFillScript(params) {
1828
1833
  const sellerScriptPubKey = encodeP2PKHScriptPubKey(sellerPubKeyHash);
1829
1834
  const tokenIdBytes = new TextEncoder().encode(tokenId);
1830
1835
  const b = new ScriptBuilder();
1831
- // ───────── Cancel branch (IF) ─────────
1832
- // scriptSig expected: <sig> <pubkey> OP_1
1836
+ // ════════ Cancel branch (outer IF) ════════
1837
+ // scriptSig: <sig> <pubkey> <1>
1833
1838
  b.op(OP_IF)
1834
1839
  .op(OP_DUP, OP_HASH160)
1835
1840
  .pushBytes(sellerPubKeyHash)
1836
1841
  .op(OP_EQUALVERIFY, OP_CHECKSIG)
1837
1842
  .op(OP_ELSE);
1838
- // ───────── Partial-fill branch (ELSE) ─────────
1839
- // scriptSig expected: <N> OP_0
1843
+ // ════════ Fill branches (outer ELSE: inner IF/ELSE) ════════
1844
+ b.op(OP_IF);
1845
+ // ──────── Full-fill branch (inner IF) ────────
1846
+ // scriptSig: <1> <0> ( full-flag=1, cancel-flag=0 )
1847
+ // Stack entering: [ ]
1840
1848
  //
1841
- // Stack invariant entering the ELSE branch: [ N ]
1842
- // 1. Payment value to seller (output 0)
1843
- // require outputValue(0) >= N * unitPriceSats
1849
+ // N is derived from the spent UTXO's asset amount, so the buyer does not
1850
+ // push N. The entire covenant is drained to vout[1]; no vout[2] is
1851
+ // constrained and none is required (consensus forbids zero-amount asset
1852
+ // transfers, so the partial-fill continuity check is simply skipped).
1853
+ // 1. N = inputAmount
1854
+ b.pushInt(0)
1855
+ .pushInt(ASSETFIELD_AMOUNT)
1856
+ .op(OP_INPUTASSETFIELD); // [ N ]
1857
+ // 2. output[0].value >= N * unitPriceSats
1844
1858
  b.op(OP_DUP) // [ N, N ]
1845
1859
  .pushInt(unitPriceSats) // [ N, N, price ]
1846
1860
  .op(OP_MUL) // [ N, N*price ]
@@ -1849,52 +1863,83 @@ function buildPartialFillScript(params) {
1849
1863
  .op(OP_SWAP) // [ N, value, N*price ]
1850
1864
  .op(OP_GREATERTHANOREQUAL)
1851
1865
  .op(OP_VERIFY); // [ N ]
1852
- // 2. Payment scriptPubKey must equal Alice's (output 0)
1866
+ // 3. output[0].scriptPubKey == sellerScriptPubKey
1853
1867
  b.pushInt(0)
1854
- .op(OP_OUTPUTSCRIPT) // [ N, scriptPubKey_out0 ]
1868
+ .op(OP_OUTPUTSCRIPT) // [ N, spk_out0 ]
1855
1869
  .pushBytes(sellerScriptPubKey)
1856
1870
  .op(OP_EQUALVERIFY); // [ N ]
1857
- // 3. Asset delivered to buyer (output 1): amount == N
1871
+ // 4. output[1].asset.amount == N
1858
1872
  b.op(OP_DUP) // [ N, N ]
1859
- .pushInt(1) // [ N, N, 1 ]
1873
+ .pushInt(1)
1860
1874
  .pushInt(ASSETFIELD_AMOUNT)
1861
1875
  .op(OP_OUTPUTASSETFIELD) // [ N, N, amount_out1 ]
1862
1876
  .op(OP_EQUALVERIFY); // [ N ]
1863
- // 4. Asset delivered to buyer (output 1): name == tokenId
1877
+ // 5. output[1].asset.name == tokenId
1864
1878
  b.pushInt(1)
1865
1879
  .pushInt(ASSETFIELD_NAME)
1866
1880
  .op(OP_OUTPUTASSETFIELD) // [ N, name_out1 ]
1867
1881
  .pushBytes(tokenIdBytes)
1868
1882
  .op(OP_EQUALVERIFY); // [ N ]
1869
- // 5. Remainder covenant continuity (output 2): same AuthScript commitment
1870
- // as spent. NIP-023: comparing 32-byte commitments rather than full
1871
- // scriptPubKeys, because the remainder's asset wrapper carries a
1872
- // different `amountRaw` than the spent UTXO's wrapper.
1883
+ // 6. Drop N, leave TRUE on the stack.
1884
+ b.op(OP_DROP).pushInt(1);
1885
+ // ──────── Partial-fill branch (inner ELSE) ────────
1886
+ // scriptSig: <N> <0> <0> ( N, full-flag=0, cancel-flag=0 )
1887
+ // Stack entering: [ N ]
1888
+ b.op(OP_ELSE);
1889
+ // 1. Payment value (output 0) >= N * unitPriceSats
1890
+ b.op(OP_DUP) // [ N, N ]
1891
+ .pushInt(unitPriceSats) // [ N, N, price ]
1892
+ .op(OP_MUL) // [ N, N*price ]
1893
+ .pushInt(0) // [ N, N*price, 0 ]
1894
+ .op(OP_OUTPUTVALUE) // [ N, N*price, value ]
1895
+ .op(OP_SWAP) // [ N, value, N*price ]
1896
+ .op(OP_GREATERTHANOREQUAL)
1897
+ .op(OP_VERIFY); // [ N ]
1898
+ // 2. Payment scriptPubKey (output 0)
1899
+ b.pushInt(0)
1900
+ .op(OP_OUTPUTSCRIPT) // [ N, spk_out0 ]
1901
+ .pushBytes(sellerScriptPubKey)
1902
+ .op(OP_EQUALVERIFY); // [ N ]
1903
+ // 3. Asset to buyer (output 1) amount == N
1904
+ b.op(OP_DUP) // [ N, N ]
1905
+ .pushInt(1)
1906
+ .pushInt(ASSETFIELD_AMOUNT)
1907
+ .op(OP_OUTPUTASSETFIELD)
1908
+ .op(OP_EQUALVERIFY); // [ N ]
1909
+ // 4. Asset to buyer (output 1) name == tokenId
1910
+ b.pushInt(1)
1911
+ .pushInt(ASSETFIELD_NAME)
1912
+ .op(OP_OUTPUTASSETFIELD)
1913
+ .pushBytes(tokenIdBytes)
1914
+ .op(OP_EQUALVERIFY); // [ N ]
1915
+ // 5. Continuation (output 2): same AuthScript commitment as spent UTXO
1916
+ // (NIP-023 — see file-level comment).
1873
1917
  b.pushInt(2)
1874
- .op(OP_OUTPUTAUTHCOMMITMENT) // [ N, auth_out2 ]
1918
+ .op(OP_OUTPUTAUTHCOMMITMENT)
1875
1919
  .pushInt(TXFIELD_AUTHSCRIPT_COMMITMENT)
1876
- .op(OP_TXFIELD) // [ N, auth_out2, spent_auth ]
1920
+ .op(OP_TXFIELD)
1877
1921
  .op(OP_EQUALVERIFY); // [ N ]
1878
- // 6. Remainder output: same tokenId
1922
+ // 6. Continuation name == tokenId
1879
1923
  b.pushInt(2)
1880
1924
  .pushInt(ASSETFIELD_NAME)
1881
- .op(OP_OUTPUTASSETFIELD) // [ N, name_out2 ]
1925
+ .op(OP_OUTPUTASSETFIELD)
1882
1926
  .pushBytes(tokenIdBytes)
1883
1927
  .op(OP_EQUALVERIFY); // [ N ]
1884
- // 7. Remainder output: amount == inputAssetAmount - N
1928
+ // 7. Continuation amount == inputAmount - N
1885
1929
  b.pushInt(2)
1886
1930
  .pushInt(ASSETFIELD_AMOUNT)
1887
1931
  .op(OP_OUTPUTASSETFIELD) // [ N, rem_amount ]
1888
- .op(OP_OVER) // [ N, rem_amount, N ] -- copy N under top
1932
+ .op(OP_OVER) // [ N, rem_amount, N ]
1889
1933
  .pushInt(0) // [ N, rem_amount, N, 0 ]
1890
1934
  .pushInt(ASSETFIELD_AMOUNT)
1891
1935
  .op(OP_INPUTASSETFIELD) // [ N, rem_amount, N, in_amount ]
1892
1936
  .op(OP_SWAP) // [ N, rem_amount, in_amount, N ]
1893
1937
  .op(OP_SUB) // [ N, rem_amount, in_amount - N ]
1894
1938
  .op(OP_EQUALVERIFY); // [ N ]
1895
- // Drop N, leave TRUE on the stack so the ELSE branch evaluates as success.
1939
+ // 8. Drop N, leave TRUE on the stack.
1896
1940
  b.op(OP_DROP).pushInt(1);
1897
- b.op(OP_ENDIF);
1941
+ b.op(OP_ENDIF); // closes full/partial inner IF
1942
+ b.op(OP_ENDIF); // closes outer cancel/fill IF
1898
1943
  return b.build();
1899
1944
  }
1900
1945
  /** Hex convenience wrapper for `buildPartialFillScript`. */
@@ -1905,9 +1950,9 @@ function buildPartialFillScriptHex(params) {
1905
1950
  /**
1906
1951
  * PQ (post-quantum) variant of the Partial-Fill Sell Order covenant.
1907
1952
  *
1908
- * Identical partial-fill branch to the legacy covenant, but the **cancel**
1909
- * branch accepts an ML-DSA-44 signature instead of an ECDSA one. This
1910
- * requires:
1953
+ * Identical fill branches (full + partial) to the legacy covenant, but the
1954
+ * **cancel** branch accepts an ML-DSA-44 signature instead of an ECDSA one.
1955
+ * This requires:
1911
1956
  * - `SCRIPT_VERIFY_CHECKSIGFROMSTACK` (for OP_CSFS) active
1912
1957
  * - `SCRIPT_VERIFY_TXHASH` (for OP_TXHASH) active
1913
1958
  * - NIP-18 (`MAX_PQ_SCRIPT_ELEMENT_SIZE = 3072`) active, so the ~2.4 KB
@@ -1925,6 +1970,9 @@ function buildPartialFillScriptHex(params) {
1925
1970
  * single-SHA256s its message argument before verification, and OP_TXHASH
1926
1971
  * produces its own 32-byte hash, so the seller computes:
1927
1972
  * `sign(pqSeckey, SHA256(doubleSHA256(selected_tx_fields)))`
1973
+ *
1974
+ * Fill branches are identical in structure to the legacy variant — see
1975
+ * `./script.ts` for the three-branch layout description.
1928
1976
  */
1929
1977
  const ASSET_NAME_MAX = 32;
1930
1978
  const DEFAULT_PQ_TXHASH_SELECTOR = 0xff;
@@ -1975,29 +2023,64 @@ function buildPartialFillScriptPQ(params) {
1975
2023
  const payment = encodeSellerScriptPubKey(paymentAddress);
1976
2024
  const tokenIdBytes = new TextEncoder().encode(tokenId);
1977
2025
  const b = new ScriptBuilder();
1978
- // ───────── Cancel branch (PQ via OP_CHECKSIGFROMSTACK) ─────────
1979
- // scriptSig expected: <sigPQ> <pubKeyPQ> OP_1
2026
+ // ════════ Cancel branch (PQ via OP_CHECKSIGFROMSTACK) ════════
2027
+ // scriptSig: <sigPQ> <pubKeyPQ> <1>
1980
2028
  // After OP_IF consumes the flag: [ sig, pubKey ]
1981
2029
  //
1982
- // The selector MUST be pushed as a raw 1-byte element — consensus
1983
- // (`interpreter.cpp` OP_TXHASH case) rejects any stack item of
1984
- // size ≠ 1. Using `pushInt(selector)` would work for 1..127 but emit a
1985
- // 2-byte CScriptNum for 0x80..0xff (the sign-disambiguation pad), which
1986
- // makes OP_TXHASH fail with SCRIPT_ERR_TXHASH. See
1987
- // `memory/project_covenant_v3_findings.md` bug B for details.
2030
+ // The selector MUST be pushed as a raw 1-byte element — consensus rejects
2031
+ // any stack item of size ≠ 1. Using `pushInt(selector)` would work for
2032
+ // 1..127 but emit a 2-byte CScriptNum for 0x80..0xff (sign-disambiguation
2033
+ // pad), which makes OP_TXHASH fail with SCRIPT_ERR_TXHASH.
1988
2034
  b.op(OP_IF)
1989
2035
  .op(OP_DUP) // [ sig, pubKey, pubKey ]
1990
2036
  .op(OP_SHA256) // [ sig, pubKey, H(pubKey) ]
1991
2037
  .pushBytes(pubKeyCommitment) // [ sig, pubKey, H(pubKey), commitment ]
1992
2038
  .op(OP_EQUALVERIFY) // [ sig, pubKey ]
1993
- .pushBytes(Uint8Array.of(txHashSelector)) // [ sig, pubKey, selector ] — always 1-byte stack item
2039
+ .pushBytes(Uint8Array.of(txHashSelector)) // [ sig, pubKey, selector ]
1994
2040
  .op(OP_TXHASH) // [ sig, pubKey, txHash ]
1995
2041
  .op(OP_SWAP) // [ sig, txHash, pubKey ]
1996
2042
  .op(OP_CHECKSIGFROMSTACK) // [ 1 | 0 ]
1997
2043
  .op(OP_ELSE);
1998
- // ───────── Partial-fill branch (identical layout to legacy) ─────────
1999
- // scriptSig expected: <N> OP_0
2000
- // Stack entering ELSE: [ N ]
2044
+ // ════════ Fill branches (inner IF: full / ELSE: partial) ════════
2045
+ b.op(OP_IF);
2046
+ // ──────── Full-fill branch ────────
2047
+ // scriptSig: <1> <0>
2048
+ // Stack entering: [ ]
2049
+ // 1. N = inputAmount
2050
+ b.pushInt(0)
2051
+ .pushInt(ASSETFIELD_AMOUNT)
2052
+ .op(OP_INPUTASSETFIELD);
2053
+ // 2. Payment value (output 0) >= N * unitPriceSats
2054
+ b.op(OP_DUP)
2055
+ .pushInt(unitPriceSats)
2056
+ .op(OP_MUL)
2057
+ .pushInt(0)
2058
+ .op(OP_OUTPUTVALUE)
2059
+ .op(OP_SWAP)
2060
+ .op(OP_GREATERTHANOREQUAL)
2061
+ .op(OP_VERIFY);
2062
+ // 3. Payment scriptPubKey (output 0)
2063
+ b.pushInt(0)
2064
+ .op(OP_OUTPUTSCRIPT)
2065
+ .pushBytes(payment.bytes)
2066
+ .op(OP_EQUALVERIFY);
2067
+ // 4. Asset to buyer (output 1) amount == N
2068
+ b.op(OP_DUP)
2069
+ .pushInt(1)
2070
+ .pushInt(ASSETFIELD_AMOUNT)
2071
+ .op(OP_OUTPUTASSETFIELD)
2072
+ .op(OP_EQUALVERIFY);
2073
+ // 5. Asset to buyer (output 1) name == tokenId
2074
+ b.pushInt(1)
2075
+ .pushInt(ASSETFIELD_NAME)
2076
+ .op(OP_OUTPUTASSETFIELD)
2077
+ .pushBytes(tokenIdBytes)
2078
+ .op(OP_EQUALVERIFY);
2079
+ b.op(OP_DROP).pushInt(1);
2080
+ // ──────── Partial-fill branch ────────
2081
+ // scriptSig: <N> <0> <0>
2082
+ // Stack entering: [ N ]
2083
+ b.op(OP_ELSE);
2001
2084
  // 1. Payment value (output 0) >= N * unitPriceSats
2002
2085
  b.op(OP_DUP)
2003
2086
  .pushInt(unitPriceSats)
@@ -2007,7 +2090,7 @@ function buildPartialFillScriptPQ(params) {
2007
2090
  .op(OP_SWAP)
2008
2091
  .op(OP_GREATERTHANOREQUAL)
2009
2092
  .op(OP_VERIFY);
2010
- // 2. Payment scriptPubKey (output 0) == payment.bytes
2093
+ // 2. Payment scriptPubKey (output 0)
2011
2094
  b.pushInt(0)
2012
2095
  .op(OP_OUTPUTSCRIPT)
2013
2096
  .pushBytes(payment.bytes)
@@ -2024,21 +2107,19 @@ function buildPartialFillScriptPQ(params) {
2024
2107
  .op(OP_OUTPUTASSETFIELD)
2025
2108
  .pushBytes(tokenIdBytes)
2026
2109
  .op(OP_EQUALVERIFY);
2027
- // 5. Remainder continuity (output 2) — same AuthScript commitment as spent
2028
- // (NIP-023; see script.ts for why full-spk equality is unsatisfiable on
2029
- // asset-wrapped covenant UTXOs).
2110
+ // 5. Continuation (output 2): same AuthScript commitment as spent (NIP-023)
2030
2111
  b.pushInt(2)
2031
2112
  .op(OP_OUTPUTAUTHCOMMITMENT)
2032
2113
  .pushInt(TXFIELD_AUTHSCRIPT_COMMITMENT)
2033
2114
  .op(OP_TXFIELD)
2034
2115
  .op(OP_EQUALVERIFY);
2035
- // 6. Remainder tokenId
2116
+ // 6. Continuation name == tokenId
2036
2117
  b.pushInt(2)
2037
2118
  .pushInt(ASSETFIELD_NAME)
2038
2119
  .op(OP_OUTPUTASSETFIELD)
2039
2120
  .pushBytes(tokenIdBytes)
2040
2121
  .op(OP_EQUALVERIFY);
2041
- // 7. Remainder amount == inputAssetAmount - N
2122
+ // 7. Continuation amount == inputAmount - N
2042
2123
  b.pushInt(2)
2043
2124
  .pushInt(ASSETFIELD_AMOUNT)
2044
2125
  .op(OP_OUTPUTASSETFIELD)
@@ -2050,7 +2131,8 @@ function buildPartialFillScriptPQ(params) {
2050
2131
  .op(OP_SUB)
2051
2132
  .op(OP_EQUALVERIFY);
2052
2133
  b.op(OP_DROP).pushInt(1);
2053
- b.op(OP_ENDIF);
2134
+ b.op(OP_ENDIF); // full / partial
2135
+ b.op(OP_ENDIF); // cancel / fill
2054
2136
  return b.build();
2055
2137
  }
2056
2138
  function buildPartialFillScriptPQHex(params) {
@@ -2066,33 +2148,52 @@ function buildPartialFillScriptPQHex(params) {
2066
2148
  * with `@neuraiproject/neurai-create-transaction`.
2067
2149
  */
2068
2150
  /**
2069
- * Unlock the covenant via the public partial-fill branch.
2151
+ * Unlock the covenant via the public fill branches.
2070
2152
  *
2071
- * Layout on the stack before OP_IF executes (top → bottom):
2072
- * 0 ← selects the OP_ELSE (fill) branch
2073
- * N ← amount of asset the buyer is taking from this order
2153
+ * amount === total → full-fill branch. The entire covenant drains to
2154
+ * vout[1]; no vout[2] continuation is emitted.
2155
+ * amount < total → partial-fill branch. vout[2] re-locks the
2156
+ * continuation (`total - amount` units).
2074
2157
  *
2075
- * so the scriptSig pushes `<N>` then `<0>`.
2158
+ * Unlock stack shapes (pushed bottom → top):
2076
2159
  *
2077
- * @param amount units of the asset the buyer is taking. Must be > 0 and
2078
- * strictly less than the amount locked in the order UTXO
2079
- * (equal would leave a zero-asset remainder, which isn't a
2080
- * valid Neurai transfer output).
2160
+ * Full fill: <1> <0> ( full-flag=1, cancel-flag=0 )
2161
+ * Partial fill: <N> <0> <0> ( N, full-flag=0, cancel-flag=0 )
2162
+ *
2163
+ * @param amount units the buyer is taking. Must be > 0 and ≤ total.
2164
+ * @param total current asset amount locked in the covenant UTXO. The
2165
+ * builder reads this to decide whether to emit the full-fill
2166
+ * or partial-fill witness — consensus uses `OP_INPUTASSETFIELD`
2167
+ * inside the covenant to check it independently, so the value
2168
+ * passed here must match on-chain reality or the script fails.
2081
2169
  */
2082
- function buildFillScriptSig(amount) {
2083
- if (typeof amount !== 'bigint') {
2084
- throw new Error('amount must be a bigint');
2170
+ function buildFillScriptSig(amount, total) {
2171
+ if (typeof amount !== 'bigint' || typeof total !== 'bigint') {
2172
+ throw new Error('amount and total must be bigint');
2085
2173
  }
2086
2174
  if (amount <= 0n) {
2087
2175
  throw new Error('fill amount must be > 0');
2088
2176
  }
2089
- return new ScriptBuilder()
2090
- .pushInt(amount)
2091
- .pushInt(0)
2092
- .build();
2177
+ if (total <= 0n) {
2178
+ throw new Error('total must be > 0');
2179
+ }
2180
+ if (amount > total) {
2181
+ throw new Error('fill amount exceeds the covenant total');
2182
+ }
2183
+ const b = new ScriptBuilder();
2184
+ if (amount === total) {
2185
+ // Full fill: covenant drains entirely. Buyer does not push N — the
2186
+ // covenant reads it via OP_INPUTASSETFIELD.
2187
+ b.pushInt(1).pushInt(0);
2188
+ }
2189
+ else {
2190
+ // Partial fill: buyer pushes N, then both flag bytes.
2191
+ b.pushInt(amount).pushInt(0).pushInt(0);
2192
+ }
2193
+ return b.build();
2093
2194
  }
2094
- function buildFillScriptSigHex(amount) {
2095
- return bytesToHex(buildFillScriptSig(amount));
2195
+ function buildFillScriptSigHex(amount, total) {
2196
+ return bytesToHex(buildFillScriptSig(amount, total));
2096
2197
  }
2097
2198
  /**
2098
2199
  * Unlock the covenant via the seller's cancel branch.
@@ -2316,13 +2417,17 @@ function readPushUint8(c, label) {
2316
2417
  }
2317
2418
 
2318
2419
  /**
2319
- * Parser for the Partial-Fill Sell Order covenant.
2420
+ * Parser for the Partial-Fill Sell Order covenant (three-branch).
2320
2421
  *
2321
2422
  * Extracts `(sellerPubKeyHash, unitPriceSats, tokenId)` from a scriptPubKey
2322
- * that was produced by `buildPartialFillScript`. The parser walks the exact
2323
- * byte layout emitted by the builder and fails on any deviation — this is
2423
+ * that was produced by `buildPartialFillScript`. Walks the exact byte
2424
+ * layout emitted by the builder and fails on any deviation — this is
2324
2425
  * deliberate, so a downstream indexer can unambiguously classify a UTXO as
2325
2426
  * "partial-fill order" or "unknown script" with no false positives.
2427
+ *
2428
+ * The full-fill and partial-fill branches share `(sellerScriptPubKey,
2429
+ * unitPriceSats, tokenId)`. The parser reads both branches and verifies
2430
+ * consistency; inconsistency throws.
2326
2431
  */
2327
2432
  /**
2328
2433
  * Parse a covenant scriptPubKey and extract its parameters. Throws with a
@@ -2331,8 +2436,8 @@ function readPushUint8(c, label) {
2331
2436
  function parsePartialFillScript(script, network = 'xna-test') {
2332
2437
  const bytes = typeof script === 'string' ? hexToBytes(script) : script;
2333
2438
  const c = makeCursor(bytes);
2334
- // ───── Cancel branch prefix ─────
2335
- expectByte(c, OP_IF, 'OP_IF');
2439
+ // ═════ Outer IF — Cancel branch ═════
2440
+ expectByte(c, OP_IF, 'OP_IF (outer cancel)');
2336
2441
  expectByte(c, OP_DUP, 'OP_DUP (cancel)');
2337
2442
  expectByte(c, OP_HASH160, 'OP_HASH160');
2338
2443
  const sellerPubKeyHash = readPush(c, 'sellerPubKeyHash');
@@ -2341,86 +2446,139 @@ function parsePartialFillScript(script, network = 'xna-test') {
2341
2446
  }
2342
2447
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (cancel)');
2343
2448
  expectByte(c, OP_CHECKSIG, 'OP_CHECKSIG (cancel)');
2344
- expectByte(c, OP_ELSE, 'OP_ELSE');
2345
- // ───── Payment value check ─────
2346
- expectByte(c, OP_DUP, 'OP_DUP (price)');
2347
- const unitPriceSats = readPushPositiveInt(c, 'unitPriceSats');
2348
- expectByte(c, OP_MUL, 'OP_MUL');
2349
- expectByte(c, OP_0, 'OP_0 (payment idx)');
2350
- expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE');
2351
- expectByte(c, OP_SWAP, 'OP_SWAP');
2352
- expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GREATERTHANOREQUAL');
2353
- expectByte(c, OP_VERIFY, 'OP_VERIFY (payment)');
2354
- // ───── Payment scriptPubKey check ─────
2355
- expectByte(c, OP_0, 'OP_0 (spk idx)');
2356
- expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment)');
2357
- const sellerSpk = readPush(c, 'sellerScriptPubKey');
2358
- // Must be P2PKH with our PKH.
2449
+ expectByte(c, OP_ELSE, 'OP_ELSE (outer → fill)');
2450
+ // ═════ Inner IF — Full-fill branch ═════
2451
+ expectByte(c, OP_IF, 'OP_IF (inner full-fill)');
2452
+ // N = inputAmount
2453
+ expectByte(c, OP_0, 'OP_0 (input idx, full)');
2454
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, full)');
2455
+ expectByte(c, OP_INPUTASSETFIELD, 'OP_INPUTASSETFIELD (full)');
2456
+ // payment value check
2457
+ expectByte(c, OP_DUP, 'OP_DUP (price, full)');
2458
+ const unitPriceSatsFull = readPushPositiveInt(c, 'unitPriceSats (full)');
2459
+ expectByte(c, OP_MUL, 'OP_MUL (full)');
2460
+ expectByte(c, OP_0, 'OP_0 (payment idx, full)');
2461
+ expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE (full)');
2462
+ expectByte(c, OP_SWAP, 'OP_SWAP (full)');
2463
+ expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GREATERTHANOREQUAL (full)');
2464
+ expectByte(c, OP_VERIFY, 'OP_VERIFY (payment full)');
2465
+ // payment spk
2466
+ expectByte(c, OP_0, 'OP_0 (spk idx, full)');
2467
+ expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment full)');
2468
+ const sellerSpkFull = readPush(c, 'sellerScriptPubKey (full)');
2359
2469
  const expectedSpk = new Uint8Array([
2360
2470
  OP_DUP, OP_HASH160, 0x14, ...sellerPubKeyHash, OP_EQUALVERIFY, OP_CHECKSIG
2361
2471
  ]);
2362
- if (!bytesEqual(sellerSpk, expectedSpk)) {
2363
- throw new Error('parse: embedded seller scriptPubKey does not match the cancel PKH');
2364
- }
2365
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment spk)');
2366
- // ───── Buyer asset amount check (output 1) ─────
2367
- expectByte(c, OP_DUP, 'OP_DUP (buyer amount)');
2368
- expectByte(c, OP_1, 'OP_1 (buyer idx)');
2369
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2370
- expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount)');
2371
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount)');
2372
- // ───── Buyer asset name check (output 1) ─────
2373
- expectByte(c, OP_1, 'OP_1 (buyer idx)');
2374
- expectByte(c, OP_1, 'OP_1 (NAME selector)');
2375
- expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name)');
2376
- const tokenIdBytes1 = readPush(c, 'tokenId #1');
2377
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name)');
2378
- // ───── Remainder continuity: same AuthScript commitment (NIP-023) ─────
2472
+ if (!bytesEqual(sellerSpkFull, expectedSpk)) {
2473
+ throw new Error('parse: full-fill seller scriptPubKey does not match the cancel PKH');
2474
+ }
2475
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment spk full)');
2476
+ // buyer amount == N (full)
2477
+ expectByte(c, OP_DUP, 'OP_DUP (buyer amount, full)');
2478
+ expectByte(c, OP_1, 'OP_1 (buyer idx, full)');
2479
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, full)');
2480
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount, full)');
2481
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount, full)');
2482
+ // buyer name == tokenId (full)
2483
+ expectByte(c, OP_1, 'OP_1 (buyer idx, full)');
2484
+ expectByte(c, OP_1, 'OP_1 (NAME sel, full)');
2485
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name, full)');
2486
+ const tokenIdFull = readPush(c, 'tokenId (full)');
2487
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name, full)');
2488
+ // tail (full)
2489
+ expectByte(c, OP_DROP, 'OP_DROP (full)');
2490
+ expectByte(c, OP_1, 'OP_1 (true, full)');
2491
+ expectByte(c, OP_ELSE, 'OP_ELSE (inner → partial fill)');
2492
+ // ═════ Inner ELSE — Partial-fill branch ═════
2493
+ // Payment value
2494
+ expectByte(c, OP_DUP, 'OP_DUP (price, partial)');
2495
+ const unitPriceSatsPartial = readPushPositiveInt(c, 'unitPriceSats (partial)');
2496
+ expectByte(c, OP_MUL, 'OP_MUL (partial)');
2497
+ expectByte(c, OP_0, 'OP_0 (pay idx, partial)');
2498
+ expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE (partial)');
2499
+ expectByte(c, OP_SWAP, 'OP_SWAP (partial)');
2500
+ expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GREATERTHANOREQUAL (partial)');
2501
+ expectByte(c, OP_VERIFY, 'OP_VERIFY (payment partial)');
2502
+ // Payment spk
2503
+ expectByte(c, OP_0, 'OP_0 (spk idx, partial)');
2504
+ expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment partial)');
2505
+ const sellerSpkPartial = readPush(c, 'sellerScriptPubKey (partial)');
2506
+ if (!bytesEqual(sellerSpkPartial, expectedSpk)) {
2507
+ throw new Error('parse: partial-fill seller scriptPubKey does not match the cancel PKH');
2508
+ }
2509
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment spk partial)');
2510
+ // Buyer amount
2511
+ expectByte(c, OP_DUP, 'OP_DUP (buyer amount, partial)');
2512
+ expectByte(c, OP_1, 'OP_1 (buyer idx, partial)');
2513
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, partial)');
2514
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount, partial)');
2515
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount, partial)');
2516
+ // Buyer name
2517
+ expectByte(c, OP_1, 'OP_1 (buyer idx, partial)');
2518
+ expectByte(c, OP_1, 'OP_1 (NAME sel, partial)');
2519
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name, partial)');
2520
+ const tokenIdPartial1 = readPush(c, 'tokenId partial #1');
2521
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name, partial)');
2522
+ // Continuation commitment
2379
2523
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2380
2524
  expectByte(c, OP_OUTPUTAUTHCOMMITMENT, 'OP_OUTPUTAUTHCOMMITMENT (remainder)');
2381
- expectByte(c, OP_2, 'OP_2 (TXFIELD selector: AUTHSCRIPT_COMMITMENT)');
2525
+ expectByte(c, OP_2, 'OP_2 (TXFIELD sel: AUTHSCRIPT_COMMITMENT)');
2382
2526
  expectByte(c, OP_TXFIELD, 'OP_TXFIELD');
2383
2527
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder auth)');
2384
- // ───── Remainder tokenId check ─────
2528
+ // Continuation name
2385
2529
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2386
- expectByte(c, OP_1, 'OP_1 (NAME selector)');
2530
+ expectByte(c, OP_1, 'OP_1 (NAME sel)');
2387
2531
  expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (remainder name)');
2388
- const tokenIdBytes2 = readPush(c, 'tokenId #2');
2532
+ const tokenIdPartial2 = readPush(c, 'tokenId partial #2');
2389
2533
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder name)');
2390
- // ───── Remainder amount == input amount - N ─────
2534
+ // Continuation amount
2391
2535
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2392
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2536
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel)');
2393
2537
  expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (remainder amount)');
2394
2538
  expectByte(c, OP_OVER, 'OP_OVER');
2395
2539
  expectByte(c, OP_0, 'OP_0 (input idx)');
2396
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2540
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel)');
2397
2541
  expectByte(c, OP_INPUTASSETFIELD, 'OP_INPUTASSETFIELD');
2398
2542
  expectByte(c, OP_SWAP, 'OP_SWAP');
2399
2543
  expectByte(c, OP_SUB, 'OP_SUB');
2400
2544
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder amount)');
2401
- // ───── Tail ─────
2402
- expectByte(c, OP_DROP, 'OP_DROP');
2403
- expectByte(c, OP_1, 'OP_1 (true)');
2404
- expectByte(c, OP_ENDIF, 'OP_ENDIF');
2545
+ // Tail (partial)
2546
+ expectByte(c, OP_DROP, 'OP_DROP (partial)');
2547
+ expectByte(c, OP_1, 'OP_1 (true, partial)');
2548
+ // Close the nested structure
2549
+ expectByte(c, OP_ENDIF, 'OP_ENDIF (inner)');
2550
+ expectByte(c, OP_ENDIF, 'OP_ENDIF (outer)');
2405
2551
  assertTrailing(c);
2406
- if (!bytesEqual(tokenIdBytes1, tokenIdBytes2)) {
2407
- throw new Error('parse: tokenId bytes differ between buyer and remainder checks');
2552
+ // Cross-branch consistency: all three (full token, partial name #1,
2553
+ // partial name #2) must agree, and the two unit prices must match.
2554
+ if (!bytesEqual(tokenIdFull, tokenIdPartial1)) {
2555
+ throw new Error('parse: tokenId differs between full-fill and partial-fill branches');
2556
+ }
2557
+ if (!bytesEqual(tokenIdPartial1, tokenIdPartial2)) {
2558
+ throw new Error('parse: tokenId bytes differ between buyer and remainder partial checks');
2408
2559
  }
2409
- const tokenId = new TextDecoder('utf-8', { fatal: true }).decode(tokenIdBytes1);
2560
+ if (unitPriceSatsFull !== unitPriceSatsPartial) {
2561
+ throw new Error('parse: unitPriceSats differs between full-fill and partial-fill branches');
2562
+ }
2563
+ const tokenId = new TextDecoder('utf-8', { fatal: true }).decode(tokenIdFull);
2410
2564
  return {
2411
2565
  network,
2412
2566
  sellerPubKeyHash,
2413
- unitPriceSats,
2567
+ unitPriceSats: unitPriceSatsFull,
2414
2568
  tokenId,
2415
2569
  scriptHex: bytesToHex(bytes)
2416
2570
  };
2417
2571
  }
2418
2572
 
2419
2573
  /**
2420
- * Parser for the PQ Partial-Fill Sell Order covenant. Returns the same
2421
- * economic parameters as the legacy parser, plus the payment scriptPubKey
2422
- * bytes (which may be P2PKH or AuthScript) and the configured TXHASH
2423
- * selector.
2574
+ * Parser for the PQ Partial-Fill Sell Order covenant (three-branch).
2575
+ * Returns the same economic parameters as the legacy parser, plus the
2576
+ * payment scriptPubKey bytes (which may be P2PKH or AuthScript) and the
2577
+ * configured TXHASH selector.
2578
+ *
2579
+ * The full-fill and partial-fill branches share `(paymentScriptPubKey,
2580
+ * unitPriceSats, tokenId)`. The parser reads both branches and verifies
2581
+ * consistency; inconsistency throws.
2424
2582
  */
2425
2583
  /** Quick discriminator without throwing — useful for indexers. */
2426
2584
  function isPartialFillScriptPQ(script) {
@@ -2438,8 +2596,8 @@ function isPartialFillScriptPQ(script) {
2438
2596
  function parsePartialFillScriptPQ(script, network = 'xna-test') {
2439
2597
  const bytes = typeof script === 'string' ? hexToBytes(script) : script;
2440
2598
  const c = makeCursor(bytes);
2441
- // ───── Cancel branch (PQ) ─────
2442
- expectByte(c, OP_IF, 'OP_IF');
2599
+ // ═════ Outer IF — Cancel branch (PQ) ═════
2600
+ expectByte(c, OP_IF, 'OP_IF (outer cancel)');
2443
2601
  expectByte(c, OP_DUP, 'OP_DUP (cancel)');
2444
2602
  expectByte(c, OP_SHA256, 'OP_SHA256');
2445
2603
  const pubKeyCommitment = readPush(c, 'pubKeyCommitment');
@@ -2447,9 +2605,6 @@ function parsePartialFillScriptPQ(script, network = 'xna-test') {
2447
2605
  throw new Error(`parse-pq: pubKeyCommitment must be 32 bytes, got ${pubKeyCommitment.length}`);
2448
2606
  }
2449
2607
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (cancel)');
2450
- // Selector is read as an unsigned byte — consensus OP_TXHASH treats the
2451
- // on-stack element as uint8, and the builder emits a raw 1-byte push so
2452
- // selectors 0x80..0xff round-trip correctly (plan v3 bug B).
2453
2608
  const txHashSelector = readPushUint8(c, 'txHashSelector');
2454
2609
  if (txHashSelector < 1) {
2455
2610
  throw new Error(`parse-pq: txHashSelector 0x00 is rejected by OP_TXHASH`);
@@ -2457,66 +2612,107 @@ function parsePartialFillScriptPQ(script, network = 'xna-test') {
2457
2612
  expectByte(c, OP_TXHASH, 'OP_TXHASH');
2458
2613
  expectByte(c, OP_SWAP, 'OP_SWAP');
2459
2614
  expectByte(c, OP_CHECKSIGFROMSTACK, 'OP_CHECKSIGFROMSTACK');
2460
- expectByte(c, OP_ELSE, 'OP_ELSE');
2461
- // ───── Fill branch ─────
2462
- expectByte(c, OP_DUP, 'OP_DUP (price)');
2463
- const unitPriceSats = readPushPositiveInt(c, 'unitPriceSats');
2464
- expectByte(c, OP_MUL, 'OP_MUL');
2465
- expectByte(c, OP_0, 'OP_0 (payment idx)');
2466
- expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE');
2467
- expectByte(c, OP_SWAP, 'OP_SWAP');
2468
- expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GE');
2469
- expectByte(c, OP_VERIFY, 'OP_VERIFY');
2470
- expectByte(c, OP_0, 'OP_0 (payment spk idx)');
2471
- expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment)');
2472
- const paymentScriptPubKey = readPush(c, 'paymentScriptPubKey');
2473
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment)');
2474
- expectByte(c, OP_DUP, 'OP_DUP (buyer amount)');
2475
- expectByte(c, OP_1, 'OP_1 (buyer idx)');
2476
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2477
- expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount)');
2478
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount)');
2479
- expectByte(c, OP_1, 'OP_1 (buyer idx)');
2480
- expectByte(c, OP_1, 'OP_1 (NAME selector)');
2481
- expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name)');
2482
- const tokenIdBytes1 = readPush(c, 'tokenId #1');
2483
- expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name)');
2484
- // Remainder continuity: same AuthScript commitment (NIP-023)
2615
+ expectByte(c, OP_ELSE, 'OP_ELSE (outer → fill)');
2616
+ // ═════ Inner IF — Full-fill branch ═════
2617
+ expectByte(c, OP_IF, 'OP_IF (inner full-fill)');
2618
+ expectByte(c, OP_0, 'OP_0 (input idx, full)');
2619
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, full)');
2620
+ expectByte(c, OP_INPUTASSETFIELD, 'OP_INPUTASSETFIELD (full)');
2621
+ expectByte(c, OP_DUP, 'OP_DUP (price, full)');
2622
+ const unitPriceSatsFull = readPushPositiveInt(c, 'unitPriceSats (full)');
2623
+ expectByte(c, OP_MUL, 'OP_MUL (full)');
2624
+ expectByte(c, OP_0, 'OP_0 (payment idx, full)');
2625
+ expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE (full)');
2626
+ expectByte(c, OP_SWAP, 'OP_SWAP (full)');
2627
+ expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GE (full)');
2628
+ expectByte(c, OP_VERIFY, 'OP_VERIFY (full)');
2629
+ expectByte(c, OP_0, 'OP_0 (payment spk idx, full)');
2630
+ expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment full)');
2631
+ const paymentScriptPubKeyFull = readPush(c, 'paymentScriptPubKey (full)');
2632
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment full)');
2633
+ expectByte(c, OP_DUP, 'OP_DUP (buyer amount, full)');
2634
+ expectByte(c, OP_1, 'OP_1 (buyer idx, full)');
2635
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, full)');
2636
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount, full)');
2637
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount, full)');
2638
+ expectByte(c, OP_1, 'OP_1 (buyer idx, full)');
2639
+ expectByte(c, OP_1, 'OP_1 (NAME sel, full)');
2640
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name, full)');
2641
+ const tokenIdFull = readPush(c, 'tokenId (full)');
2642
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name, full)');
2643
+ expectByte(c, OP_DROP, 'OP_DROP (full)');
2644
+ expectByte(c, OP_1, 'OP_1 (true, full)');
2645
+ expectByte(c, OP_ELSE, 'OP_ELSE (inner → partial fill)');
2646
+ // ═════ Inner ELSE — Partial-fill branch ═════
2647
+ expectByte(c, OP_DUP, 'OP_DUP (price, partial)');
2648
+ const unitPriceSatsPartial = readPushPositiveInt(c, 'unitPriceSats (partial)');
2649
+ expectByte(c, OP_MUL, 'OP_MUL (partial)');
2650
+ expectByte(c, OP_0, 'OP_0 (payment idx, partial)');
2651
+ expectByte(c, OP_OUTPUTVALUE, 'OP_OUTPUTVALUE (partial)');
2652
+ expectByte(c, OP_SWAP, 'OP_SWAP (partial)');
2653
+ expectByte(c, OP_GREATERTHANOREQUAL, 'OP_GE (partial)');
2654
+ expectByte(c, OP_VERIFY, 'OP_VERIFY (partial)');
2655
+ expectByte(c, OP_0, 'OP_0 (payment spk idx, partial)');
2656
+ expectByte(c, OP_OUTPUTSCRIPT, 'OP_OUTPUTSCRIPT (payment partial)');
2657
+ const paymentScriptPubKeyPartial = readPush(c, 'paymentScriptPubKey (partial)');
2658
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (payment partial)');
2659
+ expectByte(c, OP_DUP, 'OP_DUP (buyer amount, partial)');
2660
+ expectByte(c, OP_1, 'OP_1 (buyer idx, partial)');
2661
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel, partial)');
2662
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer amount, partial)');
2663
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer amount, partial)');
2664
+ expectByte(c, OP_1, 'OP_1 (buyer idx, partial)');
2665
+ expectByte(c, OP_1, 'OP_1 (NAME sel, partial)');
2666
+ expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (buyer name, partial)');
2667
+ const tokenIdPartial1 = readPush(c, 'tokenId partial #1');
2668
+ expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (buyer name, partial)');
2669
+ // Continuation commitment
2485
2670
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2486
2671
  expectByte(c, OP_OUTPUTAUTHCOMMITMENT, 'OP_OUTPUTAUTHCOMMITMENT (remainder)');
2487
- expectByte(c, OP_2, 'OP_2 (TXFIELD selector: AUTHSCRIPT_COMMITMENT)');
2672
+ expectByte(c, OP_2, 'OP_2 (TXFIELD sel: AUTHSCRIPT_COMMITMENT)');
2488
2673
  expectByte(c, OP_TXFIELD, 'OP_TXFIELD');
2489
2674
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder auth)');
2490
2675
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2491
- expectByte(c, OP_1, 'OP_1 (NAME selector)');
2676
+ expectByte(c, OP_1, 'OP_1 (NAME sel)');
2492
2677
  expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (remainder name)');
2493
- const tokenIdBytes2 = readPush(c, 'tokenId #2');
2678
+ const tokenIdPartial2 = readPush(c, 'tokenId partial #2');
2494
2679
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder name)');
2495
2680
  expectByte(c, OP_2, 'OP_2 (remainder idx)');
2496
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2681
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel)');
2497
2682
  expectByte(c, OP_OUTPUTASSETFIELD, 'OP_OUTPUTASSETFIELD (remainder amount)');
2498
2683
  expectByte(c, OP_OVER, 'OP_OVER');
2499
2684
  expectByte(c, OP_0, 'OP_0 (input idx)');
2500
- expectByte(c, OP_2, 'OP_2 (AMOUNT selector)');
2685
+ expectByte(c, OP_2, 'OP_2 (AMOUNT sel)');
2501
2686
  expectByte(c, OP_INPUTASSETFIELD, 'OP_INPUTASSETFIELD');
2502
2687
  expectByte(c, OP_SWAP, 'OP_SWAP');
2503
2688
  expectByte(c, OP_SUB, 'OP_SUB');
2504
2689
  expectByte(c, OP_EQUALVERIFY, 'OP_EQUALVERIFY (remainder amount)');
2505
- expectByte(c, OP_DROP, 'OP_DROP');
2506
- expectByte(c, OP_1, 'OP_1 (true)');
2507
- expectByte(c, OP_ENDIF, 'OP_ENDIF');
2690
+ expectByte(c, OP_DROP, 'OP_DROP (partial)');
2691
+ expectByte(c, OP_1, 'OP_1 (true, partial)');
2692
+ expectByte(c, OP_ENDIF, 'OP_ENDIF (inner)');
2693
+ expectByte(c, OP_ENDIF, 'OP_ENDIF (outer)');
2508
2694
  assertTrailing(c);
2509
- if (!bytesEqual(tokenIdBytes1, tokenIdBytes2)) {
2510
- throw new Error('parse-pq: tokenId differs between buyer and remainder checks');
2695
+ // Cross-branch consistency.
2696
+ if (!bytesEqual(paymentScriptPubKeyFull, paymentScriptPubKeyPartial)) {
2697
+ throw new Error('parse-pq: paymentScriptPubKey differs between full-fill and partial-fill branches');
2698
+ }
2699
+ if (!bytesEqual(tokenIdFull, tokenIdPartial1)) {
2700
+ throw new Error('parse-pq: tokenId differs between full-fill and partial-fill branches');
2701
+ }
2702
+ if (!bytesEqual(tokenIdPartial1, tokenIdPartial2)) {
2703
+ throw new Error('parse-pq: tokenId differs between buyer and remainder partial checks');
2704
+ }
2705
+ if (unitPriceSatsFull !== unitPriceSatsPartial) {
2706
+ throw new Error('parse-pq: unitPriceSats differs between full-fill and partial-fill branches');
2511
2707
  }
2512
- const tokenId = new TextDecoder('utf-8', { fatal: true }).decode(tokenIdBytes1);
2708
+ const tokenId = new TextDecoder('utf-8', { fatal: true }).decode(tokenIdFull);
2513
2709
  return {
2514
2710
  network,
2515
2711
  pubKeyCommitment,
2516
2712
  tokenId,
2517
- unitPriceSats,
2713
+ unitPriceSats: unitPriceSatsFull,
2518
2714
  txHashSelector,
2519
- paymentScriptPubKey,
2715
+ paymentScriptPubKey: paymentScriptPubKeyFull,
2520
2716
  scriptHex: bytesToHex(bytes)
2521
2717
  };
2522
2718
  }