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