@btc-vision/transaction 1.7.0 → 1.7.2

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/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@btc-vision/transaction",
     "type": "module",
-    "version": "1.7.0",
+    "version": "1.7.2",
     "author": "BlobMaster41",
     "description": "OPNet transaction library allows you to create and sign transactions for the OPNet network.",
     "engines": {

package/src/_version.ts

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

package/src/buffer/BinaryReader.ts

@@ -10,11 +10,11 @@ import {
     U64_BYTE_LENGTH,
     U8_BYTE_LENGTH,
 } from '../utils/lengths.js';
-import { BufferLike, i32, Selector, u16, u32, u8 } from '../utils/types.js';
+import { BufferLike, Selector, u16, u32, u8 } from '../utils/types.js';
 
 export class BinaryReader {
     private buffer: DataView;
-    private currentOffset: i32 = 0;
+    private currentOffset: number = 0;
 
     constructor(bytes: BufferLike) {
         this.buffer = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -342,7 +342,7 @@ export class BinaryReader {
     /**
      * Verifies we have enough bytes in the buffer to read up to `size`.
      */
-    public verifyEnd(size: i32): void {
+    public verifyEnd(size: number): void {
         if (size > this.buffer.byteLength) {
             throw new Error(
                 `Attempt to read beyond buffer length: requested up to byte offset ${size}, but buffer is only ${this.buffer.byteLength} bytes.`,

package/src/buffer/BinaryWriter.ts

@@ -11,7 +11,7 @@ import {
     U64_BYTE_LENGTH,
     U8_BYTE_LENGTH,
 } from '../utils/lengths.js';
-import { i32, Selector, u16, u32, u64, u8 } from '../utils/types.js';
+import { Selector, u16, u32, u64, u8 } from '../utils/types.js';
 import { BinaryReader } from './BinaryReader.js';
 
 export class BinaryWriter {
@@ -351,7 +351,7 @@ export class BinaryWriter {
 
     private resize(size: u32): void {
         const buf: Uint8Array = new Uint8Array(this.buffer.byteLength + size);
-        for (let i: i32 = 0; i < this.buffer.byteLength; i++) {
+        for (let i: number = 0; i < this.buffer.byteLength; i++) {
             buf[i] = this.buffer.getUint8(i);
         }
 

package/src/deterministic/AddressMap.ts

@@ -1,63 +1,90 @@
-import { i32 } from '../utils/types.js';
 import { Address } from '../keypair/Address.js';
-import { Map } from './Map.js';
 
-export class AddressMap<V> extends Map<Address, V> {
-    public set(key: Address, value: V): void {
-        const index: i32 = this.indexOf(key);
-        if (index == -1) {
-            this._keys.push(key);
-            this._values.push(value);
-        } else {
-            this._values[index] = value;
+export class AddressMap<V> {
+    private items: Map<bigint, V>;
+    private keyOrder: Address[];
+
+    constructor(iterable?: ReadonlyArray<readonly [Address, V]> | null) {
+        this.items = new Map();
+        this.keyOrder = [];
+
+        if (iterable) {
+            for (const [key, value] of iterable) {
+                this.set(key, value);
+            }
         }
     }
 
-    public indexOf(address: Address): i32 {
-        for (let i: i32 = 0; i < this._keys.length; i++) {
-            const key = this._keys[i];
+    get size(): number {
+        return this.keyOrder.length;
+    }
 
-            if (address.equals(key)) {
-                return i;
-            }
+    public set(key: Address, value: V): void {
+        const keyBigInt = key.toBigInt();
+        if (!this.items.has(keyBigInt)) {
+            this.keyOrder.push(key);
         }
+        this.items.set(keyBigInt, value);
+    }
 
-        return -1;
+    public get(key: Address): V | undefined {
+        return this.items.get(key.toBigInt());
     }
 
     public has(key: Address): boolean {
-        for (let i: i32 = 0; i < this._keys.length; i++) {
-            if (key.equals(this._keys[i])) {
-                return true;
-            }
-        }
+        return this.items.has(key.toBigInt());
+    }
 
+    public delete(key: Address): boolean {
+        const keyBigInt = key.toBigInt();
+        if (this.items.delete(keyBigInt)) {
+            this.keyOrder = this.keyOrder.filter((k) => k.toBigInt() !== keyBigInt);
+            return true;
+        }
         return false;
     }
 
-    public get(key: Address): V | undefined {
-        const index: i32 = this.indexOf(key);
-        if (index == -1) {
-            return;
+    public clear(): void {
+        this.items.clear();
+        this.keyOrder = [];
+    }
+
+    public indexOf(address: Address): number {
+        const addressBigInt = address.toBigInt();
+        for (let i: number = 0; i < this.keyOrder.length; i++) {
+            if (this.keyOrder[i].toBigInt() === addressBigInt) {
+                return i;
+            }
         }
-        return this._values[index];
+        return -1;
     }
 
-    public delete(key: Address): boolean {
-        const index: i32 = this.indexOf(key);
-        if (index == -1) {
-            return false;
+    *entries(): IterableIterator<[Address, V]> {
+        for (const key of this.keyOrder) {
+            yield [key, this.items.get(key.toBigInt()) as V];
         }
+    }
 
-        this._keys.splice(index, 1);
-        this._values.splice(index, 1);
+    *keys(): IterableIterator<Address> {
+        yield* this.keyOrder;
+    }
 
-        return true;
+    *values(): IterableIterator<V> {
+        for (const key of this.keyOrder) {
+            yield this.items.get(key.toBigInt()) as V;
+        }
     }
 
-    *[Symbol.iterator](): IterableIterator<[Address, V]> {
-        for (const key of this._keys) {
-            yield [key, this.get(key) as V];
+    forEach(
+        callback: (value: V, key: Address, map: AddressMap<V>) => void,
+        thisArg?: unknown,
+    ): void {
+        for (const key of this.keyOrder) {
+            callback.call(thisArg, this.items.get(key.toBigInt()) as V, key, this);
         }
     }
+
+    [Symbol.iterator](): IterableIterator<[Address, V]> {
+        return this.entries();
+    }
 }

package/src/deterministic/AddressSet.ts

@@ -1,10 +1,16 @@
 import { Address } from '../keypair/Address.js';
 
 export class AddressSet {
+    private items: Set<bigint>;
     private keys: Address[];
 
     public constructor(keys: Address[] = []) {
-        this.keys = keys;
+        this.items = new Set();
+        this.keys = [];
+
+        for (const key of keys) {
+            this.add(key);
+        }
     }
 
     public get size(): number {
@@ -12,56 +18,44 @@ export class AddressSet {
     }
 
     public add(address: Address): void {
-        if (!this.has(address)) {
+        const addressBigInt = address.toBigInt();
+        if (!this.items.has(addressBigInt)) {
+            this.items.add(addressBigInt);
             this.keys.push(address);
         }
     }
 
     public has(address: Address): boolean {
-        for (let i = 0; i < this.keys.length; i++) {
-            if (this.keys[i].equals(address)) {
-                return true;
-            }
-        }
-
-        return false;
+        return this.items.has(address.toBigInt());
     }
 
     public remove(address: Address): void {
-        const index = this.keys.findIndex((key) => key.equals(address));
-
-        if (index !== -1) {
-            this.keys.splice(index, 1);
+        const addressBigInt = address.toBigInt();
+        if (this.items.delete(addressBigInt)) {
+            this.keys = this.keys.filter((k) => k.toBigInt() !== addressBigInt);
         }
     }
 
     public clone(): AddressSet {
-        const clone = new AddressSet();
-
-        for (let i = 0; i < this.keys.length; i++) {
-            clone.add(this.keys[i]);
-        }
-
-        return clone;
+        return new AddressSet(this.keys);
     }
 
     public clear(): void {
+        this.items.clear();
         this.keys = [];
     }
 
     public combine(set: AddressSet): AddressSet {
         const clone = this.clone();
 
-        for (let i = 0; i < set.keys.length; i++) {
-            clone.add(set.keys[i]);
+        for (const key of set.keys) {
+            clone.add(key);
         }
 
         return clone;
     }
 
-    *[Symbol.iterator]() {
-        for (let i = 0; i < this.keys.length; i++) {
-            yield this.keys[i];
-        }
+    *[Symbol.iterator](): IterableIterator<Address> {
+        yield* this.keys;
     }
 }