@neuraiproject/neurai-key 3.0.1 → 3.1.0

package/README.md

@@ -5,7 +5,7 @@ Generate Neurai addresses from a mnemonic phrase following the standards BIP32,
 That is, use your 12 words to get addresses for Neurai mainnet and testnet.
 
 **NPM**: https://www.npmjs.com/package/@neuraiproject/neurai-key   
-**CDN**: https://cdn.jsdelivr.net/npm/@neuraiproject/neurai-key@3.0.0/dist/NeuraiKey.global.js   
+**CDN**: https://cdn.jsdelivr.net/npm/@neuraiproject/neurai-key@3.1.0/dist/NeuraiKey.global.js   
 
 ## Features
 
@@ -16,7 +16,16 @@ 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
+- ✅ AuthScript witness v1 addresses with Bech32m encoding
+- ✅ `authType = 0x00` NoAuth addresses from `witnessScript` only
+- ✅ `authType = 0x01` PostQuantum ML-DSA-44 AuthScript addresses
+- ✅ `authType = 0x02` Legacy secp256k1 AuthScript addresses
+
+## Compatibility Note
+
+Starting in `3.1.0`, PQ AuthScript descriptors are computed as `0x01 || HASH160(0x05 || rawPublicKey)` to match `neurai-sign-transaction` and the node implementation.
+
+This changes PQ AuthScript addresses and commitments compared to older releases of this library. If you previously generated PQ addresses with an older version of `neurai-key`, treat them as legacy outputs and verify fund exposure before migrating.
 
 ## Network Types
 
@@ -24,7 +33,7 @@ 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`**: AuthScript witness v1 addresses (Bech32m, `nq1` / `tnq1`)
 
 The main difference is the derivation path and address encoding:
 - **XNA**: mainnet `m/44'/1900'/0'/0/0`, testnet `m/44'/1'/0'/0/0` — Base58Check (recommended for new wallets)
@@ -181,9 +190,17 @@ 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 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 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.
+Supported AuthScript variants:
+
+| `authType` | Name | Description |
+|------------|------|-------------|
+| `0x00` | NoAuth | No signature. Spend path depends only on `witnessScript` |
+| `0x01` | PQ | ML-DSA-44 post-quantum signature |
+| `0x02` | Legacy | secp256k1 signature inside the AuthScript framework |
 
 ### Generate a PQ address
 
@@ -205,11 +222,15 @@ Outputs
 
 ```
 {
-  address: 'nq1...',                    // Bech32m address
+  address: 'nq1...',                    // Bech32m AuthScript address
+  authType: 1,                         // 0x01 = PQ single-key auth
+  authDescriptor: '01...',             // 0x01 || HASH160(0x05 || 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
 }
 ```
 
@@ -229,6 +250,96 @@ 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
+```
+
+`getPQAddress()` always generates `authType = 0x01` PQ addresses. Use `getNoAuthAddress()` for `0x00` and `getLegacyAuthScriptAddress()` / `getLegacyAuthScriptAddressByWIF()` for `0x02`.
+
+### Generate a NoAuth address
+
+```javascript
+import NeuraiKey from "@neuraiproject/neurai-key";
+
+const noAuth = NeuraiKey.getNoAuthAddress("xna-pq-test");
+
+console.log(noAuth);
+```
+
+Outputs
+
+```javascript
+{
+  address: "tnq1...",
+  authType: 0,
+  commitment: "...",
+  witnessScript: "51"
+}
+```
+
+You can provide a custom `witnessScript`:
+
+```javascript
+const noAuth = NeuraiKey.getNoAuthAddress("xna-pq-test", {
+  witnessScript: "527551"
+});
+```
+
+### Generate a Legacy AuthScript address from mnemonic
+
+This derives a normal secp256k1 key using the selected legacy/current HD network, then wraps it as an AuthScript address using the PQ Bech32m network.
+
+```javascript
+import NeuraiKey from "@neuraiproject/neurai-key";
+
+const mnemonic = "result pact model attract result puzzle final boss private educate luggage era";
+
+const legacyAuth = NeuraiKey.getLegacyAuthScriptAddress(
+  "xna-pq-test",
+  "xna-test",
+  mnemonic,
+  0,
+  0
+);
+
+console.log(legacyAuth);
+```
+
+Outputs
+
+```javascript
+{
+  address: "tnq1...",
+  path: "m/44'/1'/0'/0/0",
+  publicKey: "...",                    // compressed secp256k1 pubkey
+  privateKey: "...",
+  WIF: "...",
+  authType: 2,
+  authDescriptor: "02...",
+  commitment: "...",
+  witnessScript: "51"
+}
+```
+
+### Generate a Legacy AuthScript address from WIF
+
+```javascript
+import NeuraiKey from "@neuraiproject/neurai-key";
+
+const wif = "cVP9mzcDqMzWDhekiKMWKqEy739Cp6rKDT4tbG4wXXVfopMfTiBW";
+const legacyAuth = NeuraiKey.getLegacyAuthScriptAddressByWIF("xna-pq-test", wif);
+
+console.log(legacyAuth.address);
+console.log(legacyAuth.publicKey);
+```
+
 ### Advanced: derive by path with HD key reuse
 
 ```javascript
@@ -237,20 +348,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 default/external) | `m/100'/1'/account'/0/index` |
-| Address hash | HASH160(0x05 \|\| pubkey) |
+| Auth descriptor | `0x01 \|\| HASH160(0x05 \|\| 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
 
@@ -299,7 +412,7 @@ const NeuraiKey = require("@neuraiproject/neurai-key");
 </html>
 ```
 
-## Package layout in `3.0.0`
+## Package layout in `3.1.0`
 
 - `dist/index.js`: ESM main entry
 - `dist/index.cjs`: CommonJS entry
@@ -319,7 +432,7 @@ const NeuraiKey = require("@neuraiproject/neurai-key");
 
 `npm test`
 
-The test script already builds the package before running Jest.
+The test script already builds the package before running Vitest.
 
 ## BIP32
 

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,13 @@ zurdo`.split('\n');
 
     var distExports = requireDist();
 
+    const AUTHSCRIPT_TAG = "NeuraiAuthScript";
+    const AUTHSCRIPT_VERSION = 0x01;
+    const NOAUTH_TYPE = 0x00;
+    const PQ_AUTH_TYPE = 0x01;
+    const LEGACY_AUTH_TYPE = 0x02;
+    const PQ_PUBLIC_KEY_HEADER = Uint8Array.from([0x05]);
+    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 +23777,53 @@ 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 buildAuthDescriptor(authType, publicKey) {
+        if (authType === NOAUTH_TYPE) {
+            return Uint8Array.from([NOAUTH_TYPE]);
+        }
+        if (!publicKey) {
+            throw new Error(`Auth type 0x${authType.toString(16).padStart(2, "0")} requires a public key`);
+        }
+        if (authType === PQ_AUTH_TYPE) {
+            return concatBytes(Uint8Array.from([PQ_AUTH_TYPE]), hash160(concatBytes(PQ_PUBLIC_KEY_HEADER, publicKey)));
+        }
+        if (authType === LEGACY_AUTH_TYPE) {
+            return concatBytes(Uint8Array.from([LEGACY_AUTH_TYPE]), hash160(publicKey));
+        }
+        throw new Error(`Unsupported authType: 0x${String(authType).padStart(2, "0")}`);
+    }
+    function pqPublicKeyToAuthDescriptor(publicKey) {
+        return buildAuthDescriptor(PQ_AUTH_TYPE, publicKey);
+    }
+    function pqPublicKeyToCommitment(publicKey, options = {}) {
+        return pqPublicKeyToCommitmentParts(publicKey, options).commitment;
+    }
+    function authScriptCommitmentParts(authType, publicKey, options = {}) {
+        const witnessScript = normalizeWitnessScript(options.witnessScript);
+        const authDescriptor = buildAuthDescriptor(authType, publicKey);
+        const witnessScriptHash = sha256Hash(witnessScript);
+        const commitment = taggedHash(AUTHSCRIPT_TAG, concatBytes(Uint8Array.from([AUTHSCRIPT_VERSION]), authDescriptor, witnessScriptHash));
+        return {
+            authDescriptor,
+            authType,
+            commitment,
+            witnessScript,
+        };
+    }
+    function pqPublicKeyToCommitmentParts(publicKey, options = {}) {
+        return authScriptCommitmentParts(PQ_AUTH_TYPE, publicKey, options);
+    }
+    function pqPublicKeyToAddressBytes(publicKey, network, options = {}) {
+        return bech32mEncode(network.hrp, network.witnessVersion, pqPublicKeyToCommitment(publicKey, options));
+    }
+    function noAuthToAddressBytes(network, options = {}) {
+        return bech32mEncode(network.hrp, network.witnessVersion, authScriptCommitmentParts(NOAUTH_TYPE, null, options).commitment);
+    }
+    function legacyAuthScriptToAddressBytes(publicKey, network, options = {}) {
+        return bech32mEncode(network.hrp, network.witnessVersion, authScriptCommitmentParts(LEGACY_AUTH_TYPE, publicKey, options).commitment);
     }
     function normalizePublicKey(input) {
         return ensureBytes(input);
@@ -24026,7 +24083,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 +24091,101 @@ 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: 0x01,
+            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 getNoAuthAddress(network, options = {}) {
+        const chain = getPQNetwork(network);
+        const parts = authScriptCommitmentParts(0x00, null, options);
+        return {
+            address: noAuthToAddressBytes(chain, options),
+            authType: 0x00,
+            commitment: bytesToHex(parts.commitment),
+            witnessScript: bytesToHex(parts.witnessScript),
+        };
+    }
+    function getLegacyAuthScriptAddress(network, legacyNetwork, mnemonic, account, index, passphrase = "", options = {}) {
+        const pqChain = getPQNetwork(network);
+        const legacyChain = getNetwork(legacyNetwork);
+        const coinType = legacyChain.bip44;
+        const hdKey = getHDKey(legacyNetwork, mnemonic, passphrase);
+        const path = `m/44'/${coinType}'/${account}'/0/${index}`;
+        const derived = hdKey.derive(path);
+        if (!derived.privateKey) {
+            throw new Error("Could not derive private key for path");
+        }
+        const legacyObject = privateKeyToAddressObject(derived.privateKey, legacyChain, path);
+        const publicKeyBytes = ensureBytes(legacyObject.publicKey);
+        const parts = authScriptCommitmentParts(0x02, publicKeyBytes, options);
+        return {
+            address: legacyAuthScriptToAddressBytes(publicKeyBytes, pqChain, options),
+            path,
+            publicKey: legacyObject.publicKey,
+            privateKey: legacyObject.privateKey,
+            WIF: legacyObject.WIF,
+            authType: 0x02,
+            authDescriptor: bytesToHex(parts.authDescriptor),
+            commitment: bytesToHex(parts.commitment),
+            witnessScript: bytesToHex(parts.witnessScript),
+        };
+    }
+    function getLegacyAuthScriptAddressByWIF(network, wif, options = {}) {
+        const pqChain = getPQNetwork(network);
+        const publicKeyHex = publicKeyHexFromWIF(wif);
+        const publicKeyBytes = ensureBytes(publicKeyHex);
+        const parts = authScriptCommitmentParts(0x02, publicKeyBytes, options);
+        return {
+            address: legacyAuthScriptToAddressBytes(publicKeyBytes, pqChain, options),
+            publicKey: publicKeyHex,
+            privateKey: "",
+            WIF: wif,
+            authType: 0x02,
+            authDescriptor: bytesToHex(parts.authDescriptor),
+            commitment: bytesToHex(parts.commitment),
+            witnessScript: bytesToHex(parts.witnessScript),
+        };
+    }
+    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,
@@ -24079,7 +24207,12 @@ zurdo`.split('\n');
         getPQAddress,
         getPQAddressByPath,
         getPQHDKey,
+        getNoAuthAddress,
+        getLegacyAuthScriptAddress,
+        getLegacyAuthScriptAddressByWIF,
         pqPublicKeyToAddress,
+        pqPublicKeyToAuthDescriptorHex,
+        pqPublicKeyToCommitmentHex,
         generatePQAddressObject,
     };