@neuraiproject/neurai-key 3.0.0 → 3.0.2

package/README.md

@@ -16,7 +16,7 @@ That is, use your 12 words to get addresses for Neurai mainnet and testnet.
 - ✅ Mainnet and Testnet support for Neurai (XNA)
 - ✅ Support for both XNA (BIP44: 1900) and XNA Legacy (BIP44: 0) networks
 - ✅ Convert raw public keys into Neurai mainnet or testnet addresses
-- ✅ PostQuantum addresses using ML-DSA-44 (FIPS 204) with Bech32m encoding
+- ✅ PostQuantum AuthScript addresses using ML-DSA-44 (FIPS 204) with Bech32m encoding
 
 ## Network Types
 
@@ -24,12 +24,12 @@ This library supports three Neurai network configurations:
 
 - **`xna` / `xna-test`**: Current Neurai standard (BIP44 coin type: 1900)
 - **`xna-legacy` / `xna-legacy-test`**: Legacy Neurai addresses (BIP44 coin type: 0)
-- **`xna-pq` / `xna-pq-test`**: PostQuantum ML-DSA-44 addresses (Bech32m, witness v1)
+- **`xna-pq` / `xna-pq-test`**: PostQuantum ML-DSA-44 AuthScript addresses (Bech32m, witness v1)
 
 The main difference is the derivation path and address encoding:
-- **XNA**: `m/44'/1900'/0'/0/0` — Base58Check, prefix `N` (recommended for new wallets)
-- **XNA Legacy**: `m/44'/0'/0'/0/0` — Base58Check, prefix `N` (for compatibility with older wallets)
-- **XNA PostQuantum**: `m/100'/1900'/0'/0/0` — Bech32m, prefix `nq1` (for future quantum-resistant fork)
+- **XNA**: mainnet `m/44'/1900'/0'/0/0`, testnet `m/44'/1'/0'/0/0` — Base58Check (recommended for new wallets)
+- **XNA Legacy**: mainnet `m/44'/0'/0'/0/0`, testnet `m/44'/1'/0'/0/0` — Base58Check (for compatibility with older wallets)
+- **XNA PostQuantum**: mainnet `m/100'/1900'/0'/0/0`, testnet default/external `m/100'/1'/0'/0/0` — Bech32m (`nq1` / `tnq1`)
 
 **Note**: Using different network types will generate completely different addresses from the same mnemonic.
 
@@ -181,9 +181,9 @@ console.log(testAddress); // tPXGaMRNwZuV1UKSrD9gABPscrJWUmedQ9
 
 `publicKeyToAddress` throws if the key length is not 33 or 65 bytes so invalid inputs are surfaced immediately.
 
-## PostQuantum (ML-DSA-44) Addresses
+## PostQuantum (ML-DSA-44) AuthScript Addresses
 
-Generate quantum-resistant addresses using the ML-DSA-44 signature scheme (FIPS 204). These addresses use Bech32m encoding with witness version 1, preparing for a future post-quantum fork.
+Generate quantum-resistant AuthScript addresses using the ML-DSA-44 signature scheme (FIPS 204). The library now follows the migrated `witness v1 = AuthScript` layout, so the Bech32m program is a 32-byte commitment instead of the old 20-byte PQ keyhash.
 
 ### Generate a PQ address
 
@@ -199,15 +199,21 @@ const pqAddress = NeuraiKey.getPQAddress(network, mnemonic, ACCOUNT, INDEX);
 console.log(pqAddress);
 ```
 
+`getPQAddress()` returns the external branch by default.
+
 Outputs
 
 ```
 {
-  address: 'nq1...',                    // Bech32m address
+  address: 'nq1...',                    // Bech32m AuthScript address
+  authType: 1,                         // 0x01 = PQ single-key auth
+  authDescriptor: '01...',             // 0x01 || HASH160(pq_pubkey)
+  commitment: '...',                   // tagged_hash("NeuraiAuthScript", ...)
   path: "m/100'/1900'/0'/0/0",          // PQ derivation path
   publicKey: '...',                     // ML-DSA-44 public key (2624 hex chars = 1312 bytes)
   privateKey: '...',                    // ML-DSA-44 private key (5120 hex chars = 2560 bytes)
-  seedKey: '...'                        // 32-byte BIP32 seed used for ML-DSA keygen (64 hex chars)
+  seedKey: '...',                       // 32-byte BIP32 seed used for ML-DSA keygen (64 hex chars)
+  witnessScript: '51'                   // default OP_TRUE script for simple PQ auth
 }
 ```
 
@@ -227,6 +233,19 @@ const reconstructed = NeuraiKey.pqPublicKeyToAddress("xna-pq", pqAddress.publicK
 // reconstructed === pqAddress.address
 ```
 
+### Custom AuthScript witnessScript
+
+```javascript
+const pqAddress = NeuraiKey.getPQAddress("xna-pq", mnemonic, 0, 0, "", {
+  witnessScript: "5151"
+});
+
+console.log(pqAddress.witnessScript); // 5151
+console.log(pqAddress.commitment);    // new 32-byte commitment
+```
+
+`authType` no es configurable en la API pública. Esta librería genera únicamente direcciones PQ simples con `authType = 0x01`.
+
 ### Advanced: derive by path with HD key reuse
 
 ```javascript
@@ -235,20 +254,22 @@ const addr0 = NeuraiKey.getPQAddressByPath("xna-pq", hdKey, "m/100'/1900'/0'/0/0
 const addr1 = NeuraiKey.getPQAddressByPath("xna-pq", hdKey, "m/100'/1900'/0'/0/1");
 ```
 
-### PQ Address Details
+### PQ AuthScript Details
 
 | Property | Value |
 |----------|-------|
 | Signature algorithm | ML-DSA-44 (FIPS 204) |
-| Address encoding | Bech32m (witness version 1) |
+| Address encoding | Bech32m (`witness v1` AuthScript) |
 | Mainnet HRP / prefix | `nq` / `nq1...` |
 | Testnet HRP / prefix | `tnq` / `tnq1...` |
 | Public key size | 1312 bytes |
 | Derivation path (mainnet) | `m/100'/1900'/0'/0/index` |
-| Derivation path (testnet) | `m/100'/1900'/0'/1/index` |
-| Address hash | HASH160(0x05 \|\| pubkey) |
+| Derivation path (testnet default/external) | `m/100'/1'/account'/0/index` |
+| Auth descriptor | `0x01 \|\| HASH160(pq_pubkey)` |
+| Commitment | `tagged_hash("NeuraiAuthScript", 0x01 \|\| auth_descriptor \|\| SHA256(witnessScript))` |
+| Default witnessScript | `OP_TRUE` (`51` in hex) |
 
-**Note**: PQ addresses do not have a WIF (Wallet Import Format) field since WIF is specific to secp256k1 keys. The `seedKey` field contains the 32-byte BIP32-derived seed used for deterministic ML-DSA-44 key generation, useful for cross-implementation verification.
+**Note**: PQ AuthScript addresses do not have a WIF (Wallet Import Format) field since WIF is specific to secp256k1 keys. The `seedKey` field contains the 32-byte BIP32-derived seed used for deterministic ML-DSA-44 key generation, useful for cross-implementation verification.
 
 ## Get public key from WIF
 

package/dist/NeuraiKey.global.js

@@ -21503,6 +21503,13 @@ zurdo`.split('\n');
     function hash160(data) {
         return ripemd160(sha256(data));
     }
+    function sha256Hash(data) {
+        return sha256(data);
+    }
+    function taggedHash(tag, data) {
+        const tagHash = sha256(utf8ToBytes(tag));
+        return sha256(concatBytes(tagHash, tagHash, data));
+    }
     function doubleSha256(data) {
         return sha256(sha256(data));
     }
@@ -21543,7 +21550,6 @@ zurdo`.split('\n');
         return Uint8Array.from(mnemonicToSeedSync(mnemonic, passphrase));
     }
     const BITCOIN_SEED_KEY = utf8ToBytes("Bitcoin seed");
-    const HASH160_PREFIX = Uint8Array.from([0x05]);
 
     /**
      * Utils for modular division and fields.
@@ -23708,6 +23714,10 @@ zurdo`.split('\n');
 
     var distExports = requireDist();
 
+    const AUTHSCRIPT_TAG = "NeuraiAuthScript";
+    const AUTHSCRIPT_VERSION = 0x01;
+    const PQ_AUTH_TYPE = 0x01;
+    const DEFAULT_WITNESS_SCRIPT = Uint8Array.from([0x51]);
     function encodeWIF(privateKey, version, compressed = true) {
         const payload = compressed
             ? concatBytes(Uint8Array.from([version]), privateKey, Uint8Array.from([0x01]))
@@ -23764,9 +23774,29 @@ zurdo`.split('\n');
     function bech32mEncode(hrp, witnessVersion, hash) {
         return distExports.bech32m.encode(hrp, [witnessVersion, ...distExports.bech32m.toWords(hash)]);
     }
-    function pqPublicKeyToAddressBytes(publicKey, network) {
-        const serialized = concatBytes(HASH160_PREFIX, publicKey);
-        return bech32mEncode(network.hrp, network.witnessVersion, hash160(serialized));
+    function normalizeWitnessScript(input) {
+        return input ? ensureBytes(input) : Uint8Array.from(DEFAULT_WITNESS_SCRIPT);
+    }
+    function pqPublicKeyToAuthDescriptor(publicKey) {
+        return concatBytes(Uint8Array.from([PQ_AUTH_TYPE]), hash160(publicKey));
+    }
+    function pqPublicKeyToCommitment(publicKey, options = {}) {
+        return pqPublicKeyToCommitmentParts(publicKey, options).commitment;
+    }
+    function pqPublicKeyToCommitmentParts(publicKey, options = {}) {
+        const witnessScript = normalizeWitnessScript(options.witnessScript);
+        const authDescriptor = pqPublicKeyToAuthDescriptor(publicKey);
+        const witnessScriptHash = sha256Hash(witnessScript);
+        const commitment = taggedHash(AUTHSCRIPT_TAG, concatBytes(Uint8Array.from([AUTHSCRIPT_VERSION]), authDescriptor, witnessScriptHash));
+        return {
+            authDescriptor,
+            authType: PQ_AUTH_TYPE,
+            commitment,
+            witnessScript,
+        };
+    }
+    function pqPublicKeyToAddressBytes(publicKey, network, options = {}) {
+        return bech32mEncode(network.hrp, network.witnessVersion, pqPublicKeyToCommitment(publicKey, options));
     }
     function normalizePublicKey(input) {
         return ensureBytes(input);
@@ -23928,8 +23958,8 @@ zurdo`.split('\n');
             hrp: "tnq",
             witnessVersion: 1,
             purpose: 100,
-            coinType: 1900,
-            changeIndex: 1,
+            coinType: 1,
+            changeIndex: 0,
             bip32: { private: 70615956, public: 70617039 },
         },
     };
@@ -24026,7 +24056,7 @@ zurdo`.split('\n');
         const seed = mnemonicToSeedBytes(mnemonicToSeedSync, mnemonic, passphrase);
         return HDKey.fromMasterSeed(seed, chain.bip32);
     }
-    function getPQAddressByPath(network, hdKey, path) {
+    function getPQAddressByPath(network, hdKey, path, options = {}) {
         const chain = getPQNetwork(network);
         const derived = hdKey.derive(path);
         if (!derived.privateKey) {
@@ -24034,30 +24064,50 @@ zurdo`.split('\n');
         }
         const seed32 = Uint8Array.from(derived.privateKey);
         const { publicKey, secretKey } = ml_dsa44.keygen(seed32);
+        const authScript = pqPublicKeyToCommitmentParts(publicKey, options);
         return {
-            address: pqPublicKeyToAddressBytes(publicKey, chain),
+            address: pqPublicKeyToAddressBytes(publicKey, chain, options),
+            authType: authScript.authType,
+            authDescriptor: bytesToHex(authScript.authDescriptor),
+            commitment: bytesToHex(authScript.commitment),
             path,
             publicKey: bytesToHex(publicKey),
             privateKey: bytesToHex(secretKey),
             seedKey: bytesToHex(seed32),
+            witnessScript: bytesToHex(authScript.witnessScript),
         };
     }
-    function getPQAddress(network, mnemonic, account, index, passphrase = "") {
+    function getPQAddress(network, mnemonic, account, index, passphrase = "", options = {}) {
         const chain = getPQNetwork(network);
         const hdKey = getPQHDKey(network, mnemonic, passphrase);
         const path = `m/${chain.purpose}'/${chain.coinType}'/${account}'/${chain.changeIndex}/${index}`;
-        return getPQAddressByPath(network, hdKey, path);
+        return getPQAddressByPath(network, hdKey, path, options);
+    }
+    function pqPublicKeyToAddress(network, publicKey, options = {}) {
+        const keyBytes = ensureBytes(publicKey);
+        if (keyBytes.length !== 1312) {
+            throw new Error("ML-DSA-44 public key must be 1312 bytes");
+        }
+        normalizeWitnessScript(options.witnessScript);
+        return pqPublicKeyToAddressBytes(keyBytes, getPQNetwork(network), options);
+    }
+    function pqPublicKeyToCommitmentHex(publicKey, options = {}) {
+        const keyBytes = ensureBytes(publicKey);
+        if (keyBytes.length !== 1312) {
+            throw new Error("ML-DSA-44 public key must be 1312 bytes");
+        }
+        return bytesToHex(pqPublicKeyToCommitment(keyBytes, options));
     }
-    function pqPublicKeyToAddress(network, publicKey) {
+    function pqPublicKeyToAuthDescriptorHex(publicKey) {
         const keyBytes = ensureBytes(publicKey);
         if (keyBytes.length !== 1312) {
             throw new Error("ML-DSA-44 public key must be 1312 bytes");
         }
-        return pqPublicKeyToAddressBytes(keyBytes, getPQNetwork(network));
+        return bytesToHex(pqPublicKeyToAuthDescriptor(keyBytes));
     }
-    function generatePQAddressObject(network = "xna-pq", passphrase = "") {
+    function generatePQAddressObject(network = "xna-pq", passphrase = "", options = {}) {
         const mnemonic = generateMnemonic();
-        const addressObj = getPQAddress(network, mnemonic, 0, 0, passphrase);
+        const addressObj = getPQAddress(network, mnemonic, 0, 0, passphrase, options);
         return {
             ...addressObj,
             mnemonic,
@@ -24080,6 +24130,8 @@ zurdo`.split('\n');
         getPQAddressByPath,
         getPQHDKey,
         pqPublicKeyToAddress,
+        pqPublicKeyToAuthDescriptorHex,
+        pqPublicKeyToCommitmentHex,
         generatePQAddressObject,
     };