@neuraiproject/neurai-scripts 0.8.1 → 0.9.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/README.md CHANGED
@@ -22,7 +22,9 @@ and sign with
22
22
  > are gated by consensus flags active in **testnet / regtest** today.
23
23
  > Mainnet activation follows the fork process described in the NIPs. The
24
24
  > library accepts both `xna-test` and `xna` networks so the same call sites
25
- > work once mainnet activates.
25
+ > work once mainnet activates. Here those labels only name the chain
26
+ > (mainnet / testnet-regtest); in neurai-key 5 `xna` also names the ECDSA
27
+ > witness v3 address type.
26
28
 
27
29
  ---
28
30
 
@@ -211,9 +213,24 @@ const spk = encodeP2WPKHScriptPubKey(pubKeyHash20);
211
213
  const spk = encodeP2WSHScriptPubKey(sha256(witnessScript));
212
214
  ```
213
215
 
214
- ### AuthScript — `encodeAuthScriptScriptPubKey(program32)` + witness builders
216
+ ### AuthScript — `encodeAuthScriptScriptPubKey(program32, witnessVersion?)` + witness builders
215
217
 
216
- `scriptPubKey` layout: `OP_1 0x20 <32-byte program>`.
218
+ `scriptPubKey` layout: `OP_n 0x20 <32-byte program>`, with the witness
219
+ version of the address family:
220
+
221
+ | Witness | Opcode | Address | Spend |
222
+ |---|---|---|---|
223
+ | v1 (default) | `OP_1` | `nc1p…` / `tnc1p…` | generic: any auth type, any witnessScript (covenants) |
224
+ | v2 | `OP_2` | `pq1z…` / `tpq1z…` | strict PQ: exactly `[0x01, sig, pubKey, OP_TRUE]` |
225
+ | v3 | `OP_3` | `nq1r…` / `tnq1r…` | strict ECDSA: exactly `[0x02, sig, pubKey33, OP_TRUE]` |
226
+
227
+ `buildStrictWitnessPQ({ signature, pubKey })` and
228
+ `buildStrictWitnessECDSA({ signature, pubKey })` build the fixed 4-item stacks
229
+ of the strict families (the PQ key must be the 1313-byte `0x05`-prefixed key,
230
+ the ECDSA key must be compressed). Strict v2 / v3 are active on regtest only
231
+ today; generic v1 on testnet and regtest.
232
+
233
+ Generic AuthScript v1 spend modes, selected by a 1-byte `auth_type` in the witness stack:
217
234
 
218
235
  Four spend modes, selected by a 1-byte `auth_type` in the witness stack:
219
236
 
@@ -503,7 +520,7 @@ are active on DePIN-Test testnet.
503
520
  | Cancel sig scheme | ECDSA secp256k1 | ML-DSA-44 (~2421 B sig, ~1313 B pubkey) |
504
521
  | Cancel verifier | `OP_DUP OP_HASH160 <PKH> OP_EQUALVERIFY OP_CHECKSIG` | `OP_DUP OP_SHA256 <commitment> OP_EQUALVERIFY <selector> OP_TXHASH OP_SWAP OP_CHECKSIGFROMSTACK` |
505
522
  | What Alice signs | tx sighash (standard) | `SHA256(OP_TXHASH(selector))` — CSFS single-SHA256s the message |
506
- | Payment destination | P2PKH only | P2PKH **or** AuthScript bech32m (scriptPubKey bytes hardcoded) |
523
+ | Payment destination | P2PKH only | P2PKH **or** any AuthScript bech32m address — `nc1p` v1, `pq1z` v2, `nq1r` v3 (scriptPubKey bytes hardcoded, `OP_1`/`OP_2`/`OP_3` included) |
507
524
 
508
525
  ```ts
509
526
  import {
@@ -516,7 +533,7 @@ import {
516
533
 
517
534
  const scriptPubKeyHex = buildPartialFillScriptPQHex({
518
535
  network: 'xna-test',
519
- paymentAddress: 'tnq1...', // AuthScript bech32m, or legacy "t..." P2PKH
536
+ paymentAddress: 'tpq1z...', // tnc1p… / tpq1z… / tnq1r… bech32m, or legacy "t..." P2PKH
520
537
  pubKeyCommitment: sha256(alicePQPubKey), // 32 bytes
521
538
  tokenId: 'CAT',
522
539
  unitPriceSats: 100_000_000n,
@@ -552,7 +569,8 @@ OP_ENDIF
552
569
  ## Network handling
553
570
 
554
571
  Builders take address strings (whose prefix already encodes the network:
555
- `t.../N...` for P2PKH, `tnq1.../nq1...` for AuthScript bech32m) and
572
+ `t.../N...` for P2PKH; `tnc1p/nc1p` (v1), `tpq1z/pq1z` (v2) and
573
+ `tnq1r/nq1r` (v3) for AuthScript bech32m) and
556
574
  validate them via `decodeAddress` from `neurai-create-transaction`. No
557
575
  builder accepts a separate `network` parameter — it would be redundant
558
576
  with the address and invite silent mismatches.
@@ -563,7 +581,8 @@ network*: a legacy covenant is opcodes plus a 20-byte PKH, a PQ covenant
563
581
  is opcodes plus a 32-byte commitment and raw payment-scriptPubKey bytes,
564
582
  and neither payload differs between mainnet and testnet. The parser
565
583
  receives `network` purely so the caller can later base58-encode
566
- `sellerPubKeyHash` against the right version byte, or interpret
584
+ `sellerPubKeyHash` against the right version byte (a Legacy address,
585
+ neurai-key `xna-legacy` / `xna-legacy-test`), or interpret
567
586
  `paymentScriptPubKey` in the correct bech32m/base58 context.
568
587
 
569
588
  Keep this split intact when adding new covenants: builders reject a
@@ -587,7 +606,7 @@ Keep this split intact when adding new covenants: builders reject a
587
606
  testnet today — no `-acceptnonstdtxn=1` required. The legacy 80 B cap
588
607
  only applies when CSFS is off.
589
608
  - **Commitment choice (PQ).** The PQ covenant commits to
590
- `SHA256(pubKey)`, not the witness-v1 bech32m program. That keeps the
609
+ `SHA256(pubKey)`, not the bech32m AuthScript program. That keeps the
591
610
  covenant decoupled from AuthScript address derivation and lets the
592
611
  caller use any PQ key whose SHA256 they can compute.
593
612
 
@@ -613,6 +632,34 @@ consumable; callers import directly from the package root.
613
632
 
614
633
  ---
615
634
 
635
+ ## Version notes
636
+
637
+ ### 0.9.0
638
+
639
+ Address types of neurai-key 5 / neurai-create-transaction 0.9.0.
640
+
641
+ - `encodeSellerScriptPubKey` keeps the witness version of the address:
642
+ `pq1z…` payment addresses are hardcoded as `OP_2 <32B>` and `nq1r…` as
643
+ `OP_3 <32B>` (a same-program `OP_1` script would be another destination).
644
+ `SellerAddressKind` gains `'pq'` and `'ecdsa'`, and the result carries
645
+ `witnessVersion`. Code that switched on `kind === 'authscript'` to mean
646
+ "any bech32m destination" must handle the new kinds.
647
+ - Generic AuthScript v1 addresses are `nc1p…` / `tnc1p…`. The pre-5.0
648
+ `nq1p…` / `tnq1p…` strings are rejected (by create-transaction's
649
+ `decodeAddress`), like in the node.
650
+ - `encodeAuthScriptScriptPubKey(program, witnessVersion = 1)`; new
651
+ `buildStrictWitnessPQ` / `buildStrictWitnessECDSA` for the strict families.
652
+ - Requires `@neuraiproject/neurai-create-transaction` `^0.9.0` (breaking
653
+ release, not matched by the previous `^0.8.1` range).
654
+
616
655
  ## License
617
656
 
618
657
  MIT — same terms as the rest of the `@neuraiproject/*` libraries.
658
+
659
+ ### Large numeric script values
660
+
661
+ Use bigint for ScriptNum values above Number.MAX_SAFE_INTEGER. Numeric inputs
662
+ must be safe integers; unsafe numbers are rejected before encoding. Covenant
663
+ amounts and prices remain bigint. The script interpreter's own size and
664
+ arithmetic limits still apply; encoding an integer does not guarantee a script
665
+ will pass consensus checks.
@@ -44,6 +44,18 @@ var NeuraiScriptsBundle = (function (exports) {
44
44
  return true;
45
45
  }
46
46
 
47
+ /** Exact monetary primitives. This module has no runtime dependencies. */
48
+ /** Normalize a raw integer without preserving an already rounded number. */
49
+ function toRawInteger(value, label = 'amount') {
50
+ if (typeof value === 'bigint')
51
+ return value;
52
+ if (typeof value === 'number' && Number.isSafeInteger(value))
53
+ return BigInt(value);
54
+ if (typeof value === 'string' && /^-?\d+$/.test(value) && value.length <= 100)
55
+ return BigInt(value);
56
+ throw new Error(`${label}: expected an exact integer; use bigint or an integer string for large values`);
57
+ }
58
+
47
59
  /**
48
60
  * Opcode constants for Neurai Script.
49
61
  *
@@ -415,12 +427,6 @@ var NeuraiScriptsBundle = (function (exports) {
415
427
  TXHASH_VERSION: TXHASH_VERSION
416
428
  });
417
429
 
418
- /**
419
- * Low-level Script assembler. Emits the exact byte layout expected by the
420
- * Neurai interpreter: pushdata prefixes follow the same rules as Bitcoin
421
- * (direct push for 1..75 bytes, OP_PUSHDATA1/2/4 otherwise), and integers
422
- * are minimally-encoded as CScriptNum.
423
- */
424
430
  /**
425
431
  * Minimal CScriptNum encoding (Bitcoin consensus rules).
426
432
  *
@@ -430,7 +436,7 @@ var NeuraiScriptsBundle = (function (exports) {
430
436
  * - otherwise: sign-magnitude little-endian, with a sign bit on the last byte
431
437
  */
432
438
  function encodeScriptNum(value) {
433
- let n = typeof value === 'bigint' ? value : BigInt(value);
439
+ let n = toRawInteger(value, 'ScriptNum');
434
440
  if (n === 0n)
435
441
  return new Uint8Array();
436
442
  const negative = n < 0n;
@@ -484,7 +490,7 @@ var NeuraiScriptsBundle = (function (exports) {
484
490
  * when available to match how the node's own templates look on the wire.
485
491
  */
486
492
  function pushInt(value) {
487
- const n = typeof value === 'bigint' ? value : BigInt(value);
493
+ const n = toRawInteger(value, 'ScriptNum');
488
494
  if (n === -1n)
489
495
  return Uint8Array.of(OP_1NEGATE);
490
496
  if (n === 0n)
@@ -574,10 +580,17 @@ var NeuraiScriptsBundle = (function (exports) {
574
580
  }
575
581
 
576
582
  /**
577
- * AuthScript (witness v1) scriptPubKey + witness-stack builders.
583
+ * AuthScript scriptPubKey + witness-stack builders.
578
584
  *
579
- * AuthScript outputs encode a 32-byte commitment in a witness v1 program:
580
- * scriptPubKey = OP_1 0x20 <32-byte program>
585
+ * AuthScript outputs encode a 32-byte commitment in a witness program:
586
+ * scriptPubKey = OP_n 0x20 <32-byte program>
587
+ *
588
+ * OP_1 generic AuthScript v1 (nc1p… / tnc1p…): any auth type, any witnessScript
589
+ * OP_2 strict PQ v2 (pq1z… / tpq1z…): auth type 0x01, witnessScript OP_TRUE
590
+ * OP_3 strict ECDSA v3 (nq1r… / tnq1r…): auth type 0x02, witnessScript OP_TRUE
591
+ *
592
+ * The witness version is also the first byte of the commitment preimage:
593
+ * tagged_hash("NeuraiAuthScript", version || auth_descriptor || SHA256(witnessScript))
581
594
  *
582
595
  * The program is `HASH160`/`SHA256` over a descriptor that depends on the
583
596
  * `auth_type` byte carried as the first witness-stack element at spend time.
@@ -604,11 +617,24 @@ var NeuraiScriptsBundle = (function (exports) {
604
617
  const AUTHSCRIPT_REF = 0x03;
605
618
  /** Cap for PQ signature / pubkey pushes under NIP-018 (3072 B). */
606
619
  const MAX_PQ_PUSH = 3072;
607
- function encodeAuthScriptScriptPubKey(program) {
620
+ const WITNESS_VERSION_OPCODE = {
621
+ 1: OP_1,
622
+ 2: OP_2,
623
+ 3: OP_3
624
+ };
625
+ /**
626
+ * `OP_n 0x20 <program>` for witness version `n`. Defaults to the generic
627
+ * AuthScript v1 (`OP_1`), which is what every covenant commits to.
628
+ */
629
+ function encodeAuthScriptScriptPubKey(program, witnessVersion = 1) {
608
630
  if (!(program instanceof Uint8Array) || program.length !== 32) {
609
631
  throw new Error('AuthScript program must be a 32-byte Uint8Array');
610
632
  }
611
- return concatBytes(Uint8Array.of(OP_1, 0x20), program);
633
+ const opcode = WITNESS_VERSION_OPCODE[witnessVersion];
634
+ if (opcode === undefined) {
635
+ throw new Error(`AuthScript witness version must be 1, 2 or 3, got ${String(witnessVersion)}`);
636
+ }
637
+ return concatBytes(Uint8Array.of(opcode, 0x20), program);
612
638
  }
613
639
  function assertWitnessScript(ws) {
614
640
  if (!(ws instanceof Uint8Array) || ws.length === 0) {
@@ -680,6 +706,45 @@ var NeuraiScriptsBundle = (function (exports) {
680
706
  input.witnessScript
681
707
  ];
682
708
  }
709
+ /** Length of the versioned ML-DSA-44 pubkey the node expects (0x05 prefix + 1312 B). */
710
+ const STRICT_PQ_PUBKEY_LENGTH = 1313;
711
+ /** Version prefix of an ML-DSA-44 pubkey on the witness stack. */
712
+ const PQ_PUBKEY_PREFIX = 0x05;
713
+ /**
714
+ * Witness stack for spending a strict PQ witness v2 output (`pq1z…`):
715
+ * exactly `[0x01, sig, pubKey, OP_TRUE]`. The node rejects any other
716
+ * shape (extra arguments, another witnessScript) for the strict families.
717
+ */
718
+ function buildStrictWitnessPQ(input) {
719
+ if (!(input.signature instanceof Uint8Array) || input.signature.length === 0) {
720
+ throw new Error('signature must be a non-empty Uint8Array');
721
+ }
722
+ if (input.signature.length > MAX_PQ_PUSH) {
723
+ throw new Error(`signature of ${input.signature.length} bytes exceeds MAX_PQ_SCRIPT_ELEMENT_SIZE (${MAX_PQ_PUSH})`);
724
+ }
725
+ if (!(input.pubKey instanceof Uint8Array) ||
726
+ input.pubKey.length !== STRICT_PQ_PUBKEY_LENGTH ||
727
+ input.pubKey[0] !== PQ_PUBKEY_PREFIX) {
728
+ throw new Error(`pubKey must be the ${STRICT_PQ_PUBKEY_LENGTH}-byte versioned ML-DSA-44 key (0x05 prefix)`);
729
+ }
730
+ return [Uint8Array.of(AUTHSCRIPT_PQ), input.signature, input.pubKey, Uint8Array.of(OP_TRUE)];
731
+ }
732
+ /**
733
+ * Witness stack for spending a strict ECDSA witness v3 output (`nq1r…`):
734
+ * exactly `[0x02, sig, pubKey33, OP_TRUE]`. The node rejects uncompressed
735
+ * keys for this family.
736
+ */
737
+ function buildStrictWitnessECDSA(input) {
738
+ if (!(input.signature instanceof Uint8Array) || input.signature.length === 0) {
739
+ throw new Error('signature must be a non-empty Uint8Array');
740
+ }
741
+ if (!(input.pubKey instanceof Uint8Array) ||
742
+ input.pubKey.length !== 33 ||
743
+ (input.pubKey[0] !== 0x02 && input.pubKey[0] !== 0x03)) {
744
+ throw new Error('pubKey must be a compressed (33B) secp256k1 key for strict ECDSA witness v3');
745
+ }
746
+ return [Uint8Array.of(AUTHSCRIPT_LEGACY), input.signature, input.pubKey, Uint8Array.of(OP_TRUE)];
747
+ }
683
748
  /**
684
749
  * Build the witness stack for a NoAuth AuthScript spend. The spend is gated
685
750
  * by the witnessScript alone (covenants, hash-locks, time-locks, ...); no
@@ -801,6 +866,8 @@ var NeuraiScriptsBundle = (function (exports) {
801
866
  return concatBytes(Uint8Array.of(OP_HASH160, 0x14), redeemScriptHash160, Uint8Array.of(OP_EQUAL));
802
867
  }
803
868
 
869
+ /** Exact monetary primitives. This module has no runtime dependencies. */
870
+
804
871
  // base-x encoding / decoding
805
872
  // Copyright (c) 2018 base-x contributors
806
873
  // Copyright (c) 2014-2018 The Bitcoin Core developers (base58.cpp)
@@ -1516,37 +1583,96 @@ var NeuraiScriptsBundle = (function (exports) {
1516
1583
 
1517
1584
  const LEGACY_MAINNET_PREFIX = 53;
1518
1585
  const LEGACY_TESTNET_PREFIX = 127;
1519
- const PQ_MAINNET_HRP = 'nq';
1520
- const PQ_TESTNET_HRP = 'tnq';
1521
- function inferNetworkFromAddress(address) {
1522
- const normalized = resolveAddressInput(address).toLowerCase();
1523
- if (normalized.startsWith(PQ_MAINNET_HRP + '1'))
1524
- return 'xna-pq';
1525
- if (normalized.startsWith(PQ_TESTNET_HRP + '1'))
1526
- return 'xna-pq-test';
1527
- if (normalized.startsWith('n'))
1528
- return 'xna';
1529
- if (normalized.startsWith('t'))
1530
- return 'xna-test';
1531
- throw new Error(`Unsupported Neurai address: ${address}`);
1586
+ const WITNESS_FAMILIES = [
1587
+ {
1588
+ type: 'authscript',
1589
+ witnessVersion: 1,
1590
+ hrp: { mainnet: 'nc', testnet: 'tnc' },
1591
+ network: { mainnet: 'xna-authscript', testnet: 'xna-authscript-test' }
1592
+ },
1593
+ {
1594
+ type: 'pq',
1595
+ witnessVersion: 2,
1596
+ hrp: { mainnet: 'pq', testnet: 'tpq' },
1597
+ network: { mainnet: 'xna-pq', testnet: 'xna-pq-test' }
1598
+ },
1599
+ {
1600
+ type: 'ecdsa',
1601
+ witnessVersion: 3,
1602
+ hrp: { mainnet: 'nq', testnet: 'tnq' },
1603
+ network: { mainnet: 'xna', testnet: 'xna-test' }
1604
+ }
1605
+ ];
1606
+ /** The family that owns `hrp` (lowercase), with the chain it encodes. */
1607
+ function witnessFamilyByHrp(hrp) {
1608
+ for (const family of WITNESS_FAMILIES) {
1609
+ if (family.hrp.mainnet === hrp)
1610
+ return { family, chain: 'mainnet' };
1611
+ if (family.hrp.testnet === hrp)
1612
+ return { family, chain: 'testnet' };
1613
+ }
1614
+ return undefined;
1615
+ }
1616
+ /** The family encoded by `witnessVersion`, or undefined for any other version. */
1617
+ function witnessFamilyByVersion(witnessVersion) {
1618
+ return WITNESS_FAMILIES.find((family) => family.witnessVersion === witnessVersion);
1532
1619
  }
1533
1620
 
1534
- function decodeAddress(address) {
1535
- const normalized = resolveAddressInput(address);
1536
- const lowered = normalized.toLowerCase();
1537
- if (!normalized)
1538
- throw new Error('Address is required');
1539
- if (lowered.startsWith(PQ_MAINNET_HRP + '1') || lowered.startsWith(PQ_TESTNET_HRP + '1')) {
1540
- const decoded = distExports.bech32m.decode(normalized);
1541
- const version = decoded.words[0];
1542
- const program = Uint8Array.from(distExports.bech32m.fromWords(decoded.words.slice(1)));
1543
- if (version !== 1 || program.length !== 32) {
1544
- throw new Error(`Unsupported AuthScript address program for ${address}`);
1545
- }
1546
- const network = lowered.startsWith(PQ_TESTNET_HRP + '1') ? 'xna-pq-test' : 'xna-pq';
1547
- return { address: normalized, type: 'authscript', network, program, commitment: program };
1621
+ // Longest Bech32m string the node's decoder accepts (bech32.cpp).
1622
+ const BECH32M_MAX_LENGTH = 90;
1623
+ const AUTHSCRIPT_PROGRAM_LENGTH = 32;
1624
+ function tryBech32mDecode(address) {
1625
+ try {
1626
+ const { prefix, words } = distExports.bech32m.decode(address, BECH32M_MAX_LENGTH);
1627
+ return { hrp: prefix.toLowerCase(), words };
1628
+ }
1629
+ catch {
1630
+ return null;
1631
+ }
1632
+ }
1633
+ function decodeWitnessAddress(address, parts) {
1634
+ const owner = witnessFamilyByHrp(parts.hrp);
1635
+ if (!owner) {
1636
+ throw new Error(`Unsupported Bech32m prefix "${parts.hrp}" for ${address}`);
1637
+ }
1638
+ if (parts.words.length === 0) {
1639
+ throw new Error(`Empty witness program in ${address}`);
1640
+ }
1641
+ const version = parts.words[0];
1642
+ const { family, chain } = owner;
1643
+ if (version !== family.witnessVersion) {
1644
+ const actual = witnessFamilyByVersion(version);
1645
+ const hint = actual
1646
+ ? `; witness v${version} addresses use the "${actual.hrp[chain]}" prefix`
1647
+ : '';
1648
+ const legacyHint = family.type === 'ecdsa' && version === 1
1649
+ ? ' Generic AuthScript v1 addresses are now encoded as nc1p… / tnc1p… ' +
1650
+ '(same scriptPubKey): regenerate the address (neurai-key xna-authscript networks).'
1651
+ : '';
1652
+ throw new Error(`Address ${address}: the "${parts.hrp}" prefix only encodes witness v${family.witnessVersion}, ` +
1653
+ `not v${version}${hint}.${legacyHint}`);
1654
+ }
1655
+ let program;
1656
+ try {
1657
+ program = Uint8Array.from(distExports.bech32m.fromWords(parts.words.slice(1)));
1658
+ }
1659
+ catch {
1660
+ throw new Error(`Invalid witness program padding in ${address}`);
1661
+ }
1662
+ if (program.length !== AUTHSCRIPT_PROGRAM_LENGTH) {
1663
+ throw new Error(`Unsupported AuthScript program length ${program.length} for ${address} (expected ${AUTHSCRIPT_PROGRAM_LENGTH})`);
1548
1664
  }
1549
- const payload = Uint8Array.from(bs58check.decode(normalized));
1665
+ return {
1666
+ address,
1667
+ type: family.type,
1668
+ witnessVersion: family.witnessVersion,
1669
+ network: family.network[chain],
1670
+ program,
1671
+ commitment: program
1672
+ };
1673
+ }
1674
+ function decodeLegacyAddress(address) {
1675
+ const payload = Uint8Array.from(bs58check.decode(address));
1550
1676
  if (payload.length !== 21) {
1551
1677
  throw new Error(`Unsupported legacy address payload length for ${address}`);
1552
1678
  }
@@ -1555,13 +1681,51 @@ var NeuraiScriptsBundle = (function (exports) {
1555
1681
  throw new Error(`Unsupported legacy address prefix ${prefix} for ${address}`);
1556
1682
  }
1557
1683
  return {
1558
- address: normalized,
1684
+ address,
1559
1685
  type: 'p2pkh',
1560
- network: inferNetworkFromAddress(normalized),
1686
+ network: prefix === LEGACY_MAINNET_PREFIX ? 'xna-legacy' : 'xna-legacy-test',
1561
1687
  program: payload.slice(1),
1562
1688
  hash: payload.slice(1)
1563
1689
  };
1564
1690
  }
1691
+ /**
1692
+ * Decode a Neurai address the way the node does (base58.cpp
1693
+ * `DecodeDestination`): Bech32m first, Base58Check otherwise.
1694
+ *
1695
+ * - Base58 P2PKH → `type: 'p2pkh'`, network `xna-legacy` / `xna-legacy-test`
1696
+ * (an `xna-old-legacy` address is indistinguishable and reports
1697
+ * `xna-legacy`).
1698
+ * - Bech32m → `authscript` (v1, `nc`/`tnc`), `pq` (v2, `pq`/`tpq`) or
1699
+ * `ecdsa` (v3, `nq`/`tnq`), with `witnessVersion` and the 32-byte
1700
+ * commitment. Any other HRP/version pair is rejected, including the old
1701
+ * `nq1p…` / `tnq1p…` encoding of generic AuthScript v1.
1702
+ *
1703
+ * The decoder does not know whether a witness family is active on the
1704
+ * target chain: before activation the node refuses v2/v3 addresses and a
1705
+ * witness output is anyone-can-spend.
1706
+ */
1707
+ function decodeAddress(address) {
1708
+ const normalized = resolveAddressInput(address);
1709
+ if (!normalized)
1710
+ throw new Error('Address is required');
1711
+ const bech32mParts = tryBech32mDecode(normalized);
1712
+ if (bech32mParts) {
1713
+ return decodeWitnessAddress(normalized, bech32mParts);
1714
+ }
1715
+ try {
1716
+ return decodeLegacyAddress(normalized);
1717
+ }
1718
+ catch (legacyError) {
1719
+ // Not Base58 either. When the string carries a known Bech32m prefix the
1720
+ // Bech32m failure (bad checksum, mixed case…) is the useful diagnosis.
1721
+ const separator = normalized.lastIndexOf('1');
1722
+ const hrp = separator > 0 ? normalized.slice(0, separator).toLowerCase() : '';
1723
+ if (witnessFamilyByHrp(hrp)) {
1724
+ throw new Error(`Invalid Bech32m address ${normalized} (checksum, case or character error)`);
1725
+ }
1726
+ throw legacyError;
1727
+ }
1728
+ }
1565
1729
 
1566
1730
  /**
1567
1731
  * Address helpers. Wraps `decodeAddress` from
@@ -1569,9 +1733,12 @@ var NeuraiScriptsBundle = (function (exports) {
1569
1733
  * scriptPubKey bytes a covenant needs to hardcode. The actual
1570
1734
  * scriptPubKey encoders live in `./standard/*`; this module delegates.
1571
1735
  *
1572
- * Two destination types are supported for the payment output (output[0]):
1573
- * - Legacy P2PKH (base58check)
1574
- * - AuthScript witness v1 (bech32m)
1736
+ * Every Neurai destination type is supported for the payment output
1737
+ * (output[0]):
1738
+ * - Legacy P2PKH (base58check) → `76a914<20>88ac`
1739
+ * - Generic AuthScript witness v1 (nc1p… / tnc1p…) → `5120<32>`
1740
+ * - Strict PQ witness v2 (pq1z… / tpq1z…) → `5220<32>`
1741
+ * - Strict ECDSA witness v3 (nq1r… / tnq1r…) → `5320<32>`
1575
1742
  */
1576
1743
  /**
1577
1744
  * Resolve any accepted seller address string into its scriptPubKey.
@@ -1588,11 +1755,14 @@ var NeuraiScriptsBundle = (function (exports) {
1588
1755
  hash
1589
1756
  };
1590
1757
  }
1591
- if (decoded.type === 'authscript') {
1758
+ if (decoded.type === 'authscript' || decoded.type === 'pq' || decoded.type === 'ecdsa') {
1759
+ // The witness version is part of the destination: a pq1z… / nq1r…
1760
+ // payment must be hardcoded with OP_2 / OP_3, never with OP_1.
1592
1761
  const program = Uint8Array.from(decoded.program);
1593
1762
  return {
1594
- kind: 'authscript',
1595
- bytes: encodeAuthScriptScriptPubKey(program),
1763
+ kind: decoded.type,
1764
+ witnessVersion: decoded.witnessVersion,
1765
+ bytes: encodeAuthScriptScriptPubKey(program, decoded.witnessVersion),
1596
1766
  hash: program
1597
1767
  };
1598
1768
  }
@@ -1607,8 +1777,8 @@ var NeuraiScriptsBundle = (function (exports) {
1607
1777
  * <prefix scriptPubKey bytes> OP_XNA_ASSET <pushdata(payload)> OP_DROP
1608
1778
  *
1609
1779
  * where `prefix` is the recipient's standard script (typically a P2PKH, an
1610
- * AuthScript witness v1, or a bare covenant such as the partial-fill sell
1611
- * order), and `payload` serializes a `CAssetTransfer`:
1780
+ * AuthScript `OP_1`/`OP_2`/`OP_3` witness program, or a bare covenant such
1781
+ * as the partial-fill sell order), and `payload` serializes a `CAssetTransfer`:
1612
1782
  *
1613
1783
  * payload = marker ("rvn" 0x72 0x76 0x6e | "xna" 0x78 0x6e 0x61)
1614
1784
  * || type_marker (0x74 transfer)
@@ -2958,6 +3128,8 @@ var NeuraiScriptsBundle = (function (exports) {
2958
3128
  DEFAULT_PQ_TXHASH_SELECTOR: DEFAULT_PQ_TXHASH_SELECTOR,
2959
3129
  MULTISIG_MAX_PUBKEYS: MULTISIG_MAX_PUBKEYS,
2960
3130
  NULLDATA_STANDARD_MAX_SIZE: NULLDATA_STANDARD_MAX_SIZE,
3131
+ PQ_PUBKEY_PREFIX: PQ_PUBKEY_PREFIX,
3132
+ STRICT_PQ_PUBKEY_LENGTH: STRICT_PQ_PUBKEY_LENGTH,
2961
3133
  ScriptBuilder: ScriptBuilder,
2962
3134
  buildAuthScriptWitnessLegacy: buildAuthScriptWitnessLegacy,
2963
3135
  buildAuthScriptWitnessNoAuth: buildAuthScriptWitnessNoAuth,
@@ -2976,6 +3148,8 @@ var NeuraiScriptsBundle = (function (exports) {
2976
3148
  buildPartialFillScriptHex: buildPartialFillScriptHex,
2977
3149
  buildPartialFillScriptPQ: buildPartialFillScriptPQ,
2978
3150
  buildPartialFillScriptPQHex: buildPartialFillScriptPQHex,
3151
+ buildStrictWitnessECDSA: buildStrictWitnessECDSA,
3152
+ buildStrictWitnessPQ: buildStrictWitnessPQ,
2979
3153
  bytesEqual: bytesEqual,
2980
3154
  bytesToHex: bytesToHex,
2981
3155
  concatBytes: concatBytes,