@btc-vision/transaction 1.6.19 → 1.7.1

package/documentation/quantum-support/05-address-verification.md

@@ -0,0 +1,307 @@
+# Address Verification Guide
+
+## Table of Contents
+- [ML-DSA Public Key Validation](#ml-dsa-public-key-validation)
+- [Address Type Detection](#address-type-detection)
+- [Classical Address Validation](#classical-address-validation)
+- [Complete Validation Example](#complete-validation-example)
+
+## ML-DSA Public Key Validation
+
+### Validating ML-DSA Public Keys
+
+The `AddressVerificator` provides methods to validate ML-DSA public keys and determine their security level:
+
+```typescript
+import { AddressVerificator, MLDSASecurityLevel } from '@btc-vision/transaction';
+
+// Valid ML-DSA-44 public key (1312 bytes)
+const level2Key = Buffer.alloc(1312);
+const level2Check = AddressVerificator.isValidMLDSAPublicKey(level2Key);
+console.log('LEVEL2 valid:', level2Check);  // MLDSASecurityLevel.LEVEL2
+
+// Valid ML-DSA-65 public key (1952 bytes)
+const level3Key = Buffer.alloc(1952);
+const level3Check = AddressVerificator.isValidMLDSAPublicKey(level3Key);
+console.log('LEVEL3 valid:', level3Check);  // MLDSASecurityLevel.LEVEL3
+
+// Valid ML-DSA-87 public key (2592 bytes)
+const level5Key = Buffer.alloc(2592);
+const level5Check = AddressVerificator.isValidMLDSAPublicKey(level5Key);
+console.log('LEVEL5 valid:', level5Check);  // MLDSASecurityLevel.LEVEL5
+
+// Invalid length
+const invalidKey = Buffer.alloc(1000);
+const invalidCheck = AddressVerificator.isValidMLDSAPublicKey(invalidKey);
+console.log('Invalid:', invalidCheck);  // null
+```
+
+### Input Format Support
+
+Validation supports multiple input formats:
+
+```typescript
+import { AddressVerificator, MLDSASecurityLevel } from '@btc-vision/transaction';
+
+// Hex string (with 0x prefix)
+const hexWith0x = '0x' + 'a'.repeat(2624);  // 1312 bytes in hex
+const check1 = AddressVerificator.isValidMLDSAPublicKey(hexWith0x);
+console.log('Hex with 0x:', check1);  // MLDSASecurityLevel.LEVEL2
+
+// Hex string (without 0x prefix)
+const hexWithout0x = 'a'.repeat(2624);
+const check2 = AddressVerificator.isValidMLDSAPublicKey(hexWithout0x);
+console.log('Hex without 0x:', check2);  // MLDSASecurityLevel.LEVEL2
+
+// Buffer
+const buffer = Buffer.alloc(1312);
+const check3 = AddressVerificator.isValidMLDSAPublicKey(buffer);
+console.log('Buffer:', check3);  // MLDSASecurityLevel.LEVEL2
+
+// Uint8Array
+const uint8Array = new Uint8Array(1312);
+const check4 = AddressVerificator.isValidMLDSAPublicKey(uint8Array);
+console.log('Uint8Array:', check4);  // MLDSASecurityLevel.LEVEL2
+```
+
+### Validating Wallet Keys
+
+```typescript
+import { Mnemonic, AddressVerificator, MLDSASecurityLevel } from '@btc-vision/transaction';
+import { networks } from '@btc-vision/bitcoin';
+
+// Generate wallet
+const mnemonic = Mnemonic.generate(undefined, '', networks.bitcoin, MLDSASecurityLevel.LEVEL2);
+const wallet = mnemonic.derive(0);
+
+// Validate quantum public key
+const quantumKeyHex = wallet.quantumPublicKeyHex;
+const securityLevel = AddressVerificator.isValidMLDSAPublicKey(quantumKeyHex);
+
+console.log('Quantum key valid:', securityLevel !== null);
+console.log('Security level:', securityLevel);  // MLDSASecurityLevel.LEVEL2
+console.log('Expected:', wallet.securityLevel);  // MLDSASecurityLevel.LEVEL2
+console.log('Match:', securityLevel === wallet.securityLevel);  // true
+```
+
+### Error Cases
+
+```typescript
+// Empty string
+console.log(AddressVerificator.isValidMLDSAPublicKey(''));  // null
+
+// Empty Buffer
+console.log(AddressVerificator.isValidMLDSAPublicKey(Buffer.alloc(0)));  // null
+
+// Invalid hex
+console.log(AddressVerificator.isValidMLDSAPublicKey('not hex'));  // null
+
+// Wrong length (classical key size)
+const classicalKey = Buffer.alloc(33);
+console.log(AddressVerificator.isValidMLDSAPublicKey(classicalKey));  // null
+
+// Wrong length (arbitrary size)
+const wrongSize = Buffer.alloc(1500);
+console.log(AddressVerificator.isValidMLDSAPublicKey(wrongSize));  // null
+```
+
+## Address Type Detection
+
+### Detecting Address Types
+
+```typescript
+import { AddressVerificator, AddressTypes } from '@btc-vision/transaction';
+import { networks } from '@btc-vision/bitcoin';
+
+const wallet = mnemonic.derive(0);
+
+// P2TR Detection
+const p2tr = wallet.p2tr;
+const p2trType = AddressVerificator.detectAddressType(p2tr, networks.bitcoin);
+console.log('P2TR type:', p2trType);  // AddressTypes.P2TR
+
+// P2WPKH Detection
+const p2wpkh = wallet.p2wpkh;
+const p2wpkhType = AddressVerificator.detectAddressType(p2wpkh, networks.bitcoin);
+console.log('P2WPKH type:', p2wpkhType);  // AddressTypes.P2WPKH
+
+// P2PKH Detection
+const p2pkh = wallet.p2pkh;
+const p2pkhType = AddressVerificator.detectAddressType(p2pkh, networks.bitcoin);
+console.log('P2PKH type:', p2pkhType);  // AddressTypes.P2PKH
+```
+
+### Available Address Types
+
+```typescript
+enum AddressTypes {
+    P2PKH = 'P2PKH',                      // Legacy (1...)
+    P2SH_OR_P2SH_P2WPKH = 'P2SH_OR_P2SH-P2WPKH',  // Script hash (3...)
+    P2PK = 'P2PK',                        // Public key
+    P2TR = 'P2TR',                        // Taproot (bc1p...)
+    P2WPKH = 'P2WPKH',                    // SegWit (bc1q...)
+    P2WSH = 'P2WSH',                      // SegWit script (bc1q...)
+    P2WDA = 'P2WDA',                      // Witness data auth
+}
+```
+
+### Distinguishing Similar Addresses
+
+```typescript
+const wallet = mnemonic.derive(0);
+
+// P2TR vs P2WPKH (both Bech32 formats)
+const p2tr = wallet.p2tr;
+const p2wpkh = wallet.p2wpkh;
+
+const p2trType = AddressVerificator.detectAddressType(p2tr, networks.bitcoin);
+const p2wpkhType = AddressVerificator.detectAddressType(p2wpkh, networks.bitcoin);
+
+console.log('P2TR detected as:', p2trType);  // AddressTypes.P2TR
+console.log('P2WPKH detected as:', p2wpkhType);  // AddressTypes.P2WPKH
+console.log('Different types:', p2trType !== p2wpkhType);  // true
+```
+
+### Network-Specific Detection
+
+```typescript
+// Mainnet address on mainnet
+const mainnetAddr = wallet.p2tr;
+const mainnetDetect = AddressVerificator.detectAddressType(mainnetAddr, networks.bitcoin);
+console.log('Mainnet on mainnet:', mainnetDetect);  // AddressTypes.P2TR
+
+// Mainnet address on wrong network
+const wrongNetwork = AddressVerificator.detectAddressType(mainnetAddr, networks.testnet);
+console.log('Mainnet on testnet:', wrongNetwork);  // null
+```
+
+## Classical Address Validation
+
+### Validating Classical Public Keys
+
+```typescript
+import { AddressVerificator } from '@btc-vision/transaction';
+import { networks } from '@btc-vision/bitcoin';
+
+const wallet = mnemonic.derive(0);
+
+// Validate compressed public key (33 bytes)
+const compressedKey = wallet.toPublicKeyHex();
+const isValid = AddressVerificator.isValidPublicKey(compressedKey, networks.bitcoin);
+console.log('Compressed key valid:', isValid);  // true
+
+// Validate uncompressed public key (65 bytes)
+const uncompressedKey = wallet.toUncompressedPublicKey().toString('hex');
+const isUncompressedValid = AddressVerificator.isValidPublicKey(uncompressedKey, networks.bitcoin);
+console.log('Uncompressed key valid:', isUncompressedValid);  // true
+```
+
+### Validating Other Address Types
+
+```typescript
+// P2TR validation
+const p2tr = wallet.p2tr;
+const isP2TRValid = AddressVerificator.isValidP2TRAddress(p2tr, networks.bitcoin);
+console.log('P2TR valid:', isP2TRValid);  // true
+
+// P2WPKH validation
+const p2wpkh = wallet.p2wpkh;
+const isP2WPKHValid = AddressVerificator.isP2WPKHAddress(p2wpkh, networks.bitcoin);
+console.log('P2WPKH valid:', isP2WPKHValid);  // true
+
+// P2PKH or P2SH validation
+const p2pkh = wallet.p2pkh;
+const isLegacyValid = AddressVerificator.isP2PKHOrP2SH(p2pkh, networks.bitcoin);
+console.log('Legacy valid:', isLegacyValid);  // true
+```
+
+## Complete Validation Example
+
+```typescript
+import {
+    Mnemonic,
+    AddressVerificator,
+    AddressTypes,
+    MLDSASecurityLevel,
+} from '@btc-vision/transaction';
+import { networks } from '@btc-vision/bitcoin';
+
+// Generate wallet
+const mnemonic = Mnemonic.generate(undefined, '', networks.bitcoin, MLDSASecurityLevel.LEVEL2);
+const wallet = mnemonic.derive(0);
+
+console.log('=== ML-DSA Public Key Validation ===');
+
+// Validate quantum public key
+const quantumKeyHex = wallet.quantumPublicKeyHex;
+const quantumKeyBuffer = wallet.quantumPublicKey;
+
+const securityLevelFromHex = AddressVerificator.isValidMLDSAPublicKey(quantumKeyHex);
+const securityLevelFromBuffer = AddressVerificator.isValidMLDSAPublicKey(quantumKeyBuffer);
+
+console.log('Hex validation:', securityLevelFromHex);  // MLDSASecurityLevel.LEVEL2
+console.log('Buffer validation:', securityLevelFromBuffer);  // MLDSASecurityLevel.LEVEL2
+console.log('Matches wallet:', securityLevelFromHex === wallet.securityLevel);  // true
+
+console.log('\n=== Address Type Detection ===');
+
+// Detect all address types
+const addresses = {
+    p2tr: wallet.p2tr,
+    p2wpkh: wallet.p2wpkh,
+    p2pkh: wallet.p2pkh,
+};
+
+for (const [name, addr] of Object.entries(addresses)) {
+    const type = AddressVerificator.detectAddressType(addr, networks.bitcoin);
+    console.log(`${name}: ${type}`);
+}
+
+console.log('\n=== Classical Key Validation ===');
+
+// Validate classical public key
+const classicalKey = wallet.toPublicKeyHex();
+const isClassicalValid = AddressVerificator.isValidPublicKey(classicalKey, networks.bitcoin);
+
+console.log('Classical key:', classicalKey);
+console.log('Classical valid:', isClassicalValid);  // true
+
+console.log('\n=== Cross-Network Validation ===');
+
+// Test network mismatch
+const mainnetP2TR = wallet.p2tr;
+const testnetMnemonic = Mnemonic.generate(undefined, '', networks.testnet, MLDSASecurityLevel.LEVEL2);
+const testnetWallet = testnetMnemonic.derive(0);
+const testnetP2TR = testnetWallet.p2tr;
+
+const mainnetType = AddressVerificator.detectAddressType(mainnetP2TR, networks.bitcoin);
+const wrongNetworkType = AddressVerificator.detectAddressType(mainnetP2TR, networks.testnet);
+
+console.log('Mainnet P2TR on mainnet:', mainnetType);  // AddressTypes.P2TR
+console.log('Mainnet P2TR on testnet:', wrongNetworkType);  // null
+
+console.log('\n=== Complete Wallet Validation ===');
+
+function validateWallet(wallet: any, network: any): boolean {
+    // Validate quantum key
+    const quantumValid = AddressVerificator.isValidMLDSAPublicKey(
+        wallet.quantumPublicKey
+    ) !== null;
+
+    // Validate classical key
+    const classicalValid = AddressVerificator.isValidPublicKey(
+        wallet.toPublicKeyHex(),
+        network
+    );
+
+    return quantumValid && classicalValid;
+}
+
+const isWalletValid = validateWallet(wallet, networks.bitcoin);
+console.log('Complete wallet validation:', isWalletValid);  // true
+```
+
+## Next Steps
+
+- [Message Signing](./04-message-signing.md) - Sign and verify messages
+- [Introduction](./01-introduction.md) - Back to overview

package/documentation/quantum-support/README.md

@@ -0,0 +1,65 @@
+# OPNet ML-DSA Quantum Support Documentation
+
+Welcome to the OPNet ML-DSA (Post-Quantum Cryptography) documentation! This guide will help you integrate quantum-resistant signatures and addresses into your OPNet applications.
+
+## Documentation Index
+
+### [1. Introduction to ML-DSA](./01-introduction.md)
+Learn about ML-DSA (Module-Lattice-Based Digital Signature Algorithm), the hybrid quantum-classical architecture, and when to use quantum-resistant cryptography.
+
+**Topics covered:**
+- What is ML-DSA and post-quantum cryptography
+- Three security levels: **LEVEL2 (BIP360 RECOMMENDED DEFAULT)**, LEVEL3, LEVEL5
+- Hybrid classical + quantum architecture
+- Quick start guide
+- When to use ML-DSA vs classical crypto
+
+### [2. Mnemonic & Wallet Management](./02-mnemonic-and-wallet.md)
+Complete guide to generating and managing quantum-resistant wallets using BIP39 mnemonics and BIP360 quantum key derivation.
+
+**Topics covered:**
+- Generating new mnemonics with quantum support
+- Loading existing mnemonics
+- Deriving wallets (single and multiple)
+- Wallet properties (classical and quantum keys)
+- Security best practices
+- Network awareness
+- Advanced usage
+
+### [3. Address Generation](./03-address-generation.md)
+Learn to generate P2OP and classical Bitcoin addresses for all networks.
+
+**Topics covered:**
+- P2OP addresses (Pay-to-OPNet, for contract addresses)
+- Classical addresses (P2TR, P2WPKH, P2PKH, P2SH)
+- P2WDA (Witness Data Authentication)
+- Network support (mainnet, testnet, regtest)
+- Address comparison and ordering
+- Time-locked addresses (CSV)
+- Address caching
+
+### [4. Message Signing](./04-message-signing.md)
+Sign and verify messages using ML-DSA (quantum) and Schnorr (classical) signatures. Includes detailed explanation of `QuantumBIP32Factory.fromPublicKey()` usage for signature verification.
+
+**Topics covered:**
+- ML-DSA message signing and verification
+- Schnorr message signing
+- Multiple input formats (string, Buffer, Uint8Array, hex)
+- Cross-format verification
+- Tweaked signatures for Taproot
+- Message hashing (SHA-256)
+- Best practices
+
+### [5. Address Verification](./05-address-verification.md)
+Validate ML-DSA public keys and detect classical address types.
+
+**Topics covered:**
+- ML-DSA public key validation
+- Address type detection
+- Classical address validation
+- Network-specific validation
+- Complete validation examples
+
+---
+
+**Ready to get started?** Begin with the [Introduction](./01-introduction.md)!

package/gulpfile.js

@@ -13,8 +13,8 @@ process.on('uncaughtException', function (err) {
 const tsProject = ts.createProject('tsconfig.json');
 
 function buildESM() {
-    return tsProject
-        .src()
+    return gulp
+        .src(['src/**/*.ts', 'src/**/*.js', '!test/**/*'])
         .pipe(gulpcache('ts-esm'))
         .pipe(
             logger({

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@btc-vision/transaction",
     "type": "module",
-    "version": "1.6.19",
+    "version": "1.7.1",
     "author": "BlobMaster41",
     "description": "OPNet transaction library allows you to create and sign transactions for the OPNet network.",
     "engines": {
@@ -61,19 +61,24 @@
         "build": "gulp build",
         "setup": "npm i && npm run build",
         "browserBuild": "webpack --mode production",
-        "docs": "typedoc --out docs --exclude 'src/tests/*.ts' --tsconfig tsconfig.json --readme README.md --name OPNet --plugin typedoc-material-theme --themeColor '#cb9820' --exclude src/tests/test.ts --exclude src/index.ts src"
+        "docs": "typedoc --out docs --exclude 'src/tests/*.ts' --tsconfig tsconfig.json --readme README.md --name OPNet --plugin typedoc-material-theme --themeColor '#cb9820' --exclude src/tests/test.ts --exclude src/index.ts src",
+        "test": "npm run build && vitest run",
+        "test:watch": "npm run build && vitest",
+        "test:ui": "npm run build && vitest --ui",
+        "test:coverage": "npm run build && vitest run --coverage"
     },
     "devDependencies": {
-        "@babel/core": "^7.28.0",
+        "@babel/core": "^7.28.5",
         "@babel/plugin-proposal-class-properties": "^7.18.6",
-        "@babel/plugin-transform-runtime": "^7.28.0",
-        "@babel/preset-env": "^7.28.0",
+        "@babel/plugin-transform-runtime": "^7.28.5",
+        "@babel/preset-env": "^7.28.5",
         "@babel/preset-flow": "^7.27.1",
-        "@babel/preset-react": "^7.27.1",
-        "@babel/preset-typescript": "^7.27.1",
-        "@types/node": "^24.2.1",
+        "@babel/preset-react": "^7.28.5",
+        "@babel/preset-typescript": "^7.28.5",
+        "@types/node": "^24.10.0",
         "@types/sha.js": "^2.4.4",
-        "eslint": "9.38.0",
+        "@vitest/ui": "^4.0.8",
+        "eslint": "^9.39.1",
         "gulp": "^5.0.1",
         "gulp-cached": "^1.1.1",
         "gulp-typescript": "^6.0.0-alpha.1",
@@ -82,18 +87,21 @@
         "prettier": "^3.6.2",
         "stream-browserify": "^3.0.0",
         "stream-http": "^3.2.0",
-        "typedoc": "^0.28.10",
-        "typescript-eslint": "^8.39.1",
+        "typedoc": "^0.28.14",
+        "typescript-eslint": "^8.46.3",
+        "vitest": "^4.0.8",
         "webpack-cli": "^6.0.1"
     },
     "dependencies": {
         "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
         "@bitcoinerlab/secp256k1": "^1.2.0",
+        "@btc-vision/bip32": "^6.0.3",
         "@btc-vision/bitcoin": "^6.4.11",
         "@btc-vision/bitcoin-rpc": "^1.0.5",
         "@btc-vision/logger": "^1.0.7",
-        "@eslint/js": "9.38.0",
-        "@noble/secp256k1": "^2.3.0",
+        "@btc-vision/post-quantum": "^0.5.3",
+        "@eslint/js": "^9.39.1",
+        "@noble/secp256k1": "^3.0.0",
         "assert": "^2.1.0",
         "babel-loader": "^10.0.0",
         "babel-plugin-transform-import-meta": "^2.3.3",
@@ -101,7 +109,7 @@
         "babelify": "^10.0.0",
         "bech32": "^2.0.0",
         "bip174": "^2.1.1",
-        "bip32": "^5.0.0-rc.0",
+        "bip39": "^3.1.0",
         "browserify-zlib": "^0.2.0",
         "buffer": "^6.0.3",
         "ecpair": "^2.1.0",
@@ -110,9 +118,9 @@
         "gulp-logger-new": "^1.0.1",
         "process": "^0.11.10",
         "sha.js": "^2.4.12",
-        "ts-loader": "^9.5.2",
+        "ts-loader": "^9.5.4",
         "ts-node": "^10.9.2",
-        "typescript": "^5.9.2",
-        "webpack": "^5.101.0"
+        "typescript": "^5.9.3",
+        "webpack": "^5.102.1"
     }
 }

package/src/_version.ts

@@ -1 +1 @@
-export const version = '1.6.19';
+export const version = '1.7.1';

package/src/epoch/ChallengeSolution.ts

@@ -42,7 +42,7 @@ export class ChallengeSubmission implements IChallengeSubmission {
         data: RawChallengeSubmission,
         public readonly epochNumber: bigint,
     ) {
-        this.publicKey = Address.fromString(data.publicKey);
+        this.publicKey = Address.fromString(data.publicKey, data.classicPublicKey);
         this.solution = stringToBuffer(data.solution);
         this.graffiti = data.graffiti ? stringToBuffer(data.graffiti) : undefined;
         this.signature = stringToBuffer(data.signature);
@@ -76,7 +76,7 @@ export class ChallengeSolution implements IChallengeSolution {
 
     constructor(data: RawChallenge) {
         this.epochNumber = BigInt(data.epochNumber);
-        this.publicKey = Address.fromString(data.publicKey);
+        this.publicKey = Address.fromString(data.publicKey, data.classicPublicKey);
         this.solution = stringToBuffer(data.solution);
         this.salt = stringToBuffer(data.salt);
         this.graffiti = stringToBuffer(data.graffiti);
@@ -145,6 +145,7 @@ export class ChallengeSolution implements IChallengeSolution {
         return {
             epochNumber: this.epochNumber.toString(),
             publicKey: this.publicKey.toHex(),
+            classicPublicKey: this.publicKey.tweakedToHex(),
             solution: this.toHex(),
             salt: '0x' + this.salt.toString('hex'),
             graffiti: '0x' + this.graffiti.toString('hex'),

package/src/epoch/interfaces/IChallengeSolution.ts

@@ -31,6 +31,7 @@ export interface RawChallengeVerification {
 }
 
 export interface RawChallengeSubmission {
+    readonly classicPublicKey: string;
     readonly publicKey: string;
     readonly solution: string;
     readonly graffiti?: string;
@@ -46,6 +47,7 @@ export interface IChallengeSubmission {
 
 export interface RawChallenge {
     readonly epochNumber: string;
+    readonly classicPublicKey: string;
     readonly publicKey: string;
     readonly solution: string;
     readonly salt: string;