@neuraiproject/neurai-key 3.0.2 → 4.0.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@4.0.0/dist/NeuraiKey.global.js   
 
 ## Features
 
@@ -16,7 +16,22 @@ 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 AuthScript 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 `4.0.0`, PQ HD derivation uses a native PQ tree (HMAC-SHA512 with `"Neurai PQ seed"`, all derivation levels hardened, path `m_pq/100'/coin'/0'/0'/index'`). The extended private key format is also updated (prefix `xpqp...` mainnet / `tpqp...` testnet, 74-byte padded layout matching BIP32 xprv length).
+
+These are breaking changes versus `3.x`:
+- PQ addresses produced from the same mnemonic will differ between `3.x` and `4.x`.
+- PQ extended private keys exported by `3.x` (leading `DeG1...` / `Ck5n...`) are not readable by `4.x`.
+
+If you have mnemonics from `3.x`, keep them — the mnemonic is the authoritative backup. Any funds on `3.x` PQ addresses should be moved before upgrading.
+
+Since `3.1.0`, PQ AuthScript descriptors are computed as `0x01 || HASH160(0x05 || rawPublicKey)` to match `neurai-sign-transaction` and the node implementation.
 
 ## Network Types
 
@@ -24,12 +39,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 AuthScript 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)
 - **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`)
+- **XNA PostQuantum**: mainnet `m_pq/100'/1900'/0'/0'/0'`, testnet default/external `m_pq/100'/1'/0'/0'/0'` — Bech32m (`nq1` / `tnq1`), native PQ HD tree with hardened-only derivation
 
 **Note**: Using different network types will generate completely different addresses from the same mnemonic.
 
@@ -185,6 +200,14 @@ console.log(testAddress); // tPXGaMRNwZuV1UKSrD9gABPscrJWUmedQ9
 
 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.
 
+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
 
 ```javascript
@@ -207,12 +230,12 @@ Outputs
 {
   address: 'nq1...',                    // Bech32m AuthScript address
   authType: 1,                         // 0x01 = PQ single-key auth
-  authDescriptor: '01...',             // 0x01 || HASH160(pq_pubkey)
+  authDescriptor: '01...',             // 0x01 || HASH160(0x05 || pq_pubkey)
   commitment: '...',                   // tagged_hash("NeuraiAuthScript", ...)
-  path: "m/100'/1900'/0'/0/0",          // PQ derivation path
+  path: "m_pq/100'/1900'/0'/0'/0'",     // PQ derivation path (native PQ tree, all hardened)
   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 native PQ seed used for ML-DSA keygen (64 hex chars)
   witnessScript: '51'                   // default OP_TRUE script for simple PQ auth
 }
 ```
@@ -244,16 +267,111 @@ 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`.
+`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
 const hdKey = NeuraiKey.getPQHDKey("xna-pq", mnemonic);
-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");
+const addr0 = NeuraiKey.getPQAddressByPath("xna-pq", hdKey, "m_pq/100'/1900'/0'/0'/0'");
+const addr1 = NeuraiKey.getPQAddressByPath("xna-pq", hdKey, "m_pq/100'/1900'/0'/0'/1'");
 ```
 
+All PQ derivation levels are hardened; a non-hardened segment (`.../0/0`) throws.
+
+### Export / import a PQ extended private key
+
+```javascript
+const hdKey = NeuraiKey.getPQHDKey("xna-pq", mnemonic);
+
+// Serialize master (or any subtree) as xpqpriv / tpqpriv
+const xpqpriv = NeuraiKey.pqExtendedPrivateKey("xna-pq", hdKey);
+// xpqpriv starts with "xpqp..." (mainnet) or "tpqp..." (testnet), 111 chars
+
+// Restore from the serialized form and keep deriving
+const restored = NeuraiKey.pqHDKeyFromExtended("xna-pq", xpqpriv);
+const addr = NeuraiKey.getPQAddressByPath("xna-pq", restored, "m_pq/100'/1900'/0'/0'/0'");
+```
+
+The binary layout (74 bytes: `depth + fingerprint + child + chainCode + 0x00 + pq_seed`) and version bytes (`0x0488AC24` mainnet, `0x043581D5` testnet) match the Neurai node's `CNeuraiExtKeyPQ` serialization.
+
 ### PQ AuthScript Details
 
 | Property | Value |
@@ -263,13 +381,15 @@ const addr1 = NeuraiKey.getPQAddressByPath("xna-pq", hdKey, "m/100'/1900'/0'/0/1
 | 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` |
-| Auth descriptor | `0x01 \|\| HASH160(pq_pubkey)` |
+| HD tree | Native PQ, HMAC-SHA512 with key `"Neurai PQ seed"`, hardened-only |
+| Derivation path (mainnet) | `m_pq/100'/1900'/0'/0'/index'` |
+| Derivation path (testnet default/external) | `m_pq/100'/1'/0'/0'/index'` |
+| Extended privkey prefix | `xpqp...` (mainnet) / `tpqp...` (testnet), 111 base58 chars |
+| 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 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.
+**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 native PQ seed used for deterministic ML-DSA-44 key generation, useful for cross-implementation verification.
 
 ## Get public key from WIF
 
@@ -318,7 +438,7 @@ const NeuraiKey = require("@neuraiproject/neurai-key");
 </html>
 ```
 
-## Package layout in `3.0.0`
+## Package layout in `4.0.0`
 
 - `dist/index.js`: ESM main entry
 - `dist/index.cjs`: CommonJS entry
@@ -338,7 +458,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