@btc-vision/transaction 1.7.0 → 1.7.1

package/browser/src/_version.d.ts

@@ -1 +1 @@
-export declare const version = "1.7.0";
+export declare const version = "1.7.1";

package/browser/src/mnemonic/BIPStandard.d.ts

@@ -0,0 +1,8 @@
+export declare enum BIPStandard {
+    BIP44 = 44,
+    BIP49 = 49,
+    BIP84 = 84,
+    BIP86 = 86
+}
+export declare function getBIPDescription(standard: BIPStandard): string;
+export declare function buildBIPPath(standard: BIPStandard, coinType: number, account: number, change: number, addressIndex: number): string;

package/browser/src/mnemonic/Mnemonic.d.ts

@@ -2,6 +2,9 @@ import { BIP32Interface, MLDSASecurityLevel, QuantumBIP32Interface } from '@btc-
 import { Network } from '@btc-vision/bitcoin';
 import { Wallet } from '../keypair/Wallet.js';
 import { MnemonicStrength } from './MnemonicStrength.js';
+import { BIPStandard } from './BIPStandard.js';
+import { AddressTypes } from '../keypair/AddressVerificator.js';
+export { BIPStandard, getBIPDescription } from './BIPStandard.js';
 export declare class Mnemonic {
     private readonly _phrase;
     private readonly _passphrase;
@@ -18,8 +21,10 @@ export declare class Mnemonic {
     static generatePhrase(strength?: MnemonicStrength): string;
     static generate(strength?: MnemonicStrength, passphrase?: string, network?: Network, securityLevel?: MLDSASecurityLevel): Mnemonic;
     static validate(phrase: string): boolean;
-    derive(index?: number, account?: number, isChange?: boolean): Wallet;
-    deriveMultiple(count: number, startIndex?: number, account?: number, isChange?: boolean): Wallet[];
+    derive(index?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): Wallet;
+    deriveUnisat(addressType?: AddressTypes, index?: number, account?: number, isChange?: boolean): Wallet;
+    deriveMultipleUnisat(addressType?: AddressTypes, count?: number, startIndex?: number, account?: number, isChange?: boolean): Wallet[];
+    deriveMultiple(count: number, startIndex?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): Wallet[];
     deriveCustomPath(classicalPath: string, quantumPath: string): Wallet;
     getClassicalRoot(): BIP32Interface;
     getQuantumRoot(): QuantumBIP32Interface;

package/browser/src/opnet.d.ts

@@ -21,6 +21,7 @@ export * from './keypair/MessageSigner.js';
 export * from './keypair/Wallet.js';
 export * from './mnemonic/Mnemonic.js';
 export * from './mnemonic/MnemonicStrength.js';
+export * from './mnemonic/BIPStandard.js';
 export { MLDSASecurityLevel, MLDSAKeyPair, QuantumBIP32Interface, QuantumBIP32API, QuantumSigner, QuantumBIP32Factory, QuantumDerivationPath, } from '@btc-vision/bip32';
 export * from './metadata/ContractBaseMetadata.js';
 export * from './network/ChainId.js';

package/build/_version.d.ts

@@ -1 +1 @@
-export declare const version = "1.7.0";
+export declare const version = "1.7.1";

package/build/_version.js

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

package/build/mnemonic/BIPStandard.d.ts

@@ -0,0 +1,8 @@
+export declare enum BIPStandard {
+    BIP44 = 44,
+    BIP49 = 49,
+    BIP84 = 84,
+    BIP86 = 86
+}
+export declare function getBIPDescription(standard: BIPStandard): string;
+export declare function buildBIPPath(standard: BIPStandard, coinType: number, account: number, change: number, addressIndex: number): string;

package/build/mnemonic/BIPStandard.js

@@ -0,0 +1,24 @@
+export var BIPStandard;
+(function (BIPStandard) {
+    BIPStandard[BIPStandard["BIP44"] = 44] = "BIP44";
+    BIPStandard[BIPStandard["BIP49"] = 49] = "BIP49";
+    BIPStandard[BIPStandard["BIP84"] = 84] = "BIP84";
+    BIPStandard[BIPStandard["BIP86"] = 86] = "BIP86";
+})(BIPStandard || (BIPStandard = {}));
+export function getBIPDescription(standard) {
+    switch (standard) {
+        case BIPStandard.BIP44:
+            return 'BIP44: Legacy addresses (P2PKH), widely used by Unisat and other wallets';
+        case BIPStandard.BIP49:
+            return 'BIP49: Wrapped SegWit addresses (P2SH-P2WPKH)';
+        case BIPStandard.BIP84:
+            return 'BIP84: Native SegWit addresses (P2WPKH) - DEFAULT';
+        case BIPStandard.BIP86:
+            return 'BIP86: Taproot addresses (P2TR)';
+        default:
+            return 'Unknown BIP standard';
+    }
+}
+export function buildBIPPath(standard, coinType, account, change, addressIndex) {
+    return `m/${standard}'/${coinType}'/${account}'/${change}/${addressIndex}`;
+}

package/build/mnemonic/Mnemonic.d.ts

@@ -2,6 +2,9 @@ import { BIP32Interface, MLDSASecurityLevel, QuantumBIP32Interface } from '@btc-
 import { Network } from '@btc-vision/bitcoin';
 import { Wallet } from '../keypair/Wallet.js';
 import { MnemonicStrength } from './MnemonicStrength.js';
+import { BIPStandard } from './BIPStandard.js';
+import { AddressTypes } from '../keypair/AddressVerificator.js';
+export { BIPStandard, getBIPDescription } from './BIPStandard.js';
 export declare class Mnemonic {
     private readonly _phrase;
     private readonly _passphrase;
@@ -18,8 +21,10 @@ export declare class Mnemonic {
     static generatePhrase(strength?: MnemonicStrength): string;
     static generate(strength?: MnemonicStrength, passphrase?: string, network?: Network, securityLevel?: MLDSASecurityLevel): Mnemonic;
     static validate(phrase: string): boolean;
-    derive(index?: number, account?: number, isChange?: boolean): Wallet;
-    deriveMultiple(count: number, startIndex?: number, account?: number, isChange?: boolean): Wallet[];
+    derive(index?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): Wallet;
+    deriveUnisat(addressType?: AddressTypes, index?: number, account?: number, isChange?: boolean): Wallet;
+    deriveMultipleUnisat(addressType?: AddressTypes, count?: number, startIndex?: number, account?: number, isChange?: boolean): Wallet[];
+    deriveMultiple(count: number, startIndex?: number, account?: number, isChange?: boolean, bipStandard?: BIPStandard): Wallet[];
     deriveCustomPath(classicalPath: string, quantumPath: string): Wallet;
     getClassicalRoot(): BIP32Interface;
     getQuantumRoot(): QuantumBIP32Interface;

package/build/mnemonic/Mnemonic.js

@@ -4,8 +4,11 @@ import * as ecc from '@bitcoinerlab/secp256k1';
 import { initEccLib, networks } from '@btc-vision/bitcoin';
 import { Wallet } from '../keypair/Wallet.js';
 import { MnemonicStrength } from './MnemonicStrength.js';
+import { BIPStandard, buildBIPPath } from './BIPStandard.js';
+import { AddressTypes } from '../keypair/AddressVerificator.js';
 initEccLib(ecc);
 const bip32 = BIP32Factory(ecc);
+export { BIPStandard, getBIPDescription } from './BIPStandard.js';
 export class Mnemonic {
     constructor(phrase, passphrase = '', network = networks.bitcoin, securityLevel = MLDSASecurityLevel.LEVEL2) {
         if (!bip39.validateMnemonic(phrase)) {
@@ -41,8 +44,8 @@ export class Mnemonic {
     static validate(phrase) {
         return bip39.validateMnemonic(phrase);
     }
-    derive(index = 0, account = 0, isChange = false) {
-        const classicalPath = this.buildClassicalPath(account, index, isChange);
+    derive(index = 0, account = 0, isChange = false, bipStandard = BIPStandard.BIP84) {
+        const classicalPath = this.buildClassicalPath(account, index, isChange, bipStandard);
         const classicalChild = this._classicalRoot.derivePath(classicalPath);
         if (!classicalChild.privateKey) {
             throw new Error(`Failed to derive classical private key at index ${index}`);
@@ -54,10 +57,49 @@ export class Mnemonic {
         }
         return new Wallet(Buffer.from(classicalChild.privateKey).toString('hex'), Buffer.from(quantumChild.privateKey).toString('hex'), this._network, this._securityLevel);
     }
-    deriveMultiple(count, startIndex = 0, account = 0, isChange = false) {
+    deriveUnisat(addressType = AddressTypes.P2TR, index = 0, account = 0, isChange = false) {
+        let purpose;
+        switch (addressType) {
+            case AddressTypes.P2PKH:
+                purpose = 44;
+                break;
+            case AddressTypes.P2SH_OR_P2SH_P2WPKH:
+                purpose = 49;
+                break;
+            case AddressTypes.P2WPKH:
+                purpose = 84;
+                break;
+            case AddressTypes.P2TR:
+                purpose = 86;
+                break;
+            default:
+                throw new Error(`Unsupported address type: ${addressType}`);
+        }
+        const coinType = this.getCoinType();
+        const change = isChange ? 1 : 0;
+        const classicalPath = `m/${purpose}'/0'/${account}'/${change}/${index}`;
+        const classicalChild = this._classicalRoot.derivePath(classicalPath);
+        if (!classicalChild.privateKey) {
+            throw new Error(`Failed to derive classical private key at path ${classicalPath}`);
+        }
+        const quantumPath = `m/360'/${coinType}'/${account}'/${change}/${index}`;
+        const quantumChild = this._quantumRoot.derivePath(quantumPath);
+        if (!quantumChild.privateKey) {
+            throw new Error(`Failed to derive quantum private key at path ${quantumPath}`);
+        }
+        return new Wallet(Buffer.from(classicalChild.privateKey).toString('hex'), Buffer.from(quantumChild.privateKey).toString('hex'), this._network, this._securityLevel);
+    }
+    deriveMultipleUnisat(addressType = AddressTypes.P2TR, count = 5, startIndex = 0, account = 0, isChange = false) {
+        const wallets = [];
+        for (let i = 0; i < count; i++) {
+            wallets.push(this.deriveUnisat(addressType, startIndex + i, account, isChange));
+        }
+        return wallets;
+    }
+    deriveMultiple(count, startIndex = 0, account = 0, isChange = false, bipStandard = BIPStandard.BIP84) {
         const wallets = [];
         for (let i = 0; i < count; i++) {
-            wallets.push(this.derive(startIndex + i, account, isChange));
+            wallets.push(this.derive(startIndex + i, account, isChange, bipStandard));
         }
         return wallets;
     }
@@ -78,10 +120,10 @@ export class Mnemonic {
     getQuantumRoot() {
         return this._quantumRoot;
     }
-    buildClassicalPath(account, index, isChange) {
+    buildClassicalPath(account, index, isChange, bipStandard = BIPStandard.BIP84) {
         const coinType = this.getCoinType();
         const change = isChange ? 1 : 0;
-        return `m/84'/${coinType}'/${account}'/${change}/${index}`;
+        return buildBIPPath(bipStandard, coinType, account, change, index);
     }
     buildQuantumPath(account, index, isChange) {
         const coinType = this.getCoinType();

package/build/opnet.d.ts

@@ -21,6 +21,7 @@ export * from './keypair/MessageSigner.js';
 export * from './keypair/Wallet.js';
 export * from './mnemonic/Mnemonic.js';
 export * from './mnemonic/MnemonicStrength.js';
+export * from './mnemonic/BIPStandard.js';
 export { MLDSASecurityLevel, MLDSAKeyPair, QuantumBIP32Interface, QuantumBIP32API, QuantumSigner, QuantumBIP32Factory, QuantumDerivationPath, } from '@btc-vision/bip32';
 export * from './metadata/ContractBaseMetadata.js';
 export * from './network/ChainId.js';

package/build/opnet.js

@@ -20,6 +20,7 @@ export * from './keypair/MessageSigner.js';
 export * from './keypair/Wallet.js';
 export * from './mnemonic/Mnemonic.js';
 export * from './mnemonic/MnemonicStrength.js';
+export * from './mnemonic/BIPStandard.js';
 export { MLDSASecurityLevel, QuantumBIP32Factory, QuantumDerivationPath, } from '@btc-vision/bip32';
 export * from './metadata/ContractBaseMetadata.js';
 export * from './network/ChainId.js';

package/documentation/README.md

@@ -0,0 +1,32 @@
+# OPNet Transaction Library Documentation
+
+Complete documentation for the OPNet Transaction Library - Bitcoin transaction building with quantum-resistant cryptography support.
+
+## Documentation Index
+
+### Core Concepts
+
+#### Address Types
+- **[P2OP](./addresses/P2OP.md)** - Pay-to-OPNet contract addresses (witness v16, quantum support for contracts only)
+- **P2QRH** - Pay-to-Quantum-Resistant-Hash user addresses (NOT IMPLEMENTED)
+- **P2WDA** - Pay-to-Witness-Data-Authentication addresses
+- **P2TR** - Pay-to-Taproot addresses (witness v1)
+- **P2WPKH** - Pay-to-Witness-PubKey-Hash (SegWit v0)
+- **P2PKH** - Pay-to-PubKey-Hash (legacy)
+- **P2SH** - Pay-to-Script-Hash
+
+#### Quantum Address
+- **Universal Public Key** - `address.toHex()` returns the SHA256 hash of ML-DSA public key (32 bytes)
+- This is the user's universal identifier across the OPNet protocol
+
+### Quantum Support (ML-DSA)
+
+**[Complete Quantum Support Guide](./quantum-support/README.md)**
+
+- [Introduction to ML-DSA](./quantum-support/01-introduction.md) - Post-quantum cryptography overview
+- [Mnemonic & Wallet Management](./quantum-support/02-mnemonic-and-wallet.md) - BIP39 + BIP360 quantum wallets
+- [Address Generation](./quantum-support/03-address-generation.md) - All address types
+- [Message Signing](./quantum-support/04-message-signing.md) - ML-DSA and Schnorr signatures
+- [Address Verification](./quantum-support/05-address-verification.md) - Validation and type detection
+- [Complete Examples](./quantum-support/06-complete-examples.md) - Production-ready code
+- [Complete Message Signing Example](./quantum-support/complete-message-signing-example.md) - Full working example with proper typings

package/documentation/quantum-support/01-introduction.md

@@ -0,0 +1,88 @@
+# ML-DSA Quantum Support - Introduction
+
+## Overview
+
+OPNet now supports **ML-DSA (Module-Lattice-Based Digital Signature Algorithm)**, also known as FIPS 204, providing quantum-resistant cryptography alongside traditional ECDSA/Schnorr signatures. This hybrid approach ensures your transactions and signatures remain secure even when quantum computers become capable of breaking classical cryptographic schemes.
+
+## What is ML-DSA?
+
+ML-DSA is a **post-quantum cryptographic algorithm** standardized by NIST as FIPS 204. It uses lattice-based mathematics that are believed to be resistant to attacks by both classical and quantum computers.
+
+## Security Levels
+
+ML-DSA offers three security levels with different key sizes and security guarantees:
+
+| Level | Name | Public Key Size | Signature Size | Security Equivalent | Status |
+|-------|------|----------------|----------------|-------------------|--------|
+| **LEVEL2** | ML-DSA-44 | 1,312 bytes | 2,420 bytes | AES-128 | ✅ **RECOMMENDED DEFAULT (BIP360)** |
+| **LEVEL3** | ML-DSA-65 | 1,952 bytes | 3,309 bytes | AES-192 | Optional |
+| **LEVEL5** | ML-DSA-87 | 2,592 bytes | 4,627 bytes | AES-256 | Optional (maximum security) |
+
+**Recommendation**: Use **LEVEL2** (ML-DSA-44) - this is the **BIP360 default** and provides strong quantum resistance with reasonable key sizes. Use LEVEL3 or LEVEL5 only if you need higher security for specific high-value applications.
+
+## Hybrid Architecture
+
+OPNet uses a **dual-key system** for maximum compatibility and security:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    OPNet Wallet                         │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Classical Keys (ECDSA/Schnorr)    Quantum Keys (ML-DSA)│
+│  ├─ 32-byte private key            ├─ Private key       │
+│  ├─ 33-byte public key              ├─ 1312-2592 byte   │
+│  ├─ Bitcoin script execution        │   public key      │
+│  └─ P2TR, P2WPKH addresses          └─ Quantum address  │
+│                                                         │
+│  SHA256 Hash of ML-DSA Public Key → Universal Public Key│
+│         (address.toHex() - 32 bytes)                    │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### How It Works
+
+1. **Universal Public Key**: ML-DSA public keys are **SHA256-hashed to 32 bytes** via `address.toHex()` - this is the user's universal identifier
+2. **Classical Keys**: Maintained separately for Bitcoin transaction signing (P2TR, P2WPKH, etc.)
+3. **Quantum Keys**: Provide quantum-resistant authentication and signatures
+4. **P2OP Addresses**: Contract address format (witness version 16) - for OPNet contracts ONLY, not for user addresses
+
+## Quick Start
+
+```typescript
+import { Mnemonic, MessageSigner, MLDSASecurityLevel } from '@btc-vision/transaction';
+import { networks } from '@btc-vision/bitcoin';
+
+// Generate a new quantum-resistant wallet
+const mnemonic = Mnemonic.generate(undefined, '', networks.bitcoin, MLDSASecurityLevel.LEVEL2);
+
+// Derive a wallet
+const wallet = mnemonic.derive(0);
+
+// Get quantum address (universal public key)
+const quantumAddress = wallet.address.toHex();
+console.log('Quantum Address:', quantumAddress);
+
+// Sign a message with ML-DSA
+const message = 'Hello, Quantum World!';
+const signature = MessageSigner.signMLDSAMessage(wallet.mldsaKeypair, message);
+console.log('ML-DSA Signature:', Buffer.from(signature.signature).toString('hex'));
+```
+
+## What's New
+
+This implementation adds:
+
+1. **Mnemonic Support** - BIP39 + BIP360 for quantum key derivation
+2. **Wallet Management** - Hybrid classical + quantum key management
+3. **Universal Public Key** - `address.toHex()` provides the user's quantum address (SHA256 of ML-DSA public key)
+4. **Message Signing** - ML-DSA and Schnorr signature support
+5. **Address Verification** - Validation for ML-DSA public keys and classical address types
+6. **Security Levels** - Three levels of quantum resistance (LEVEL2, LEVEL3, LEVEL5)
+
+## Next Steps
+
+- [Mnemonic & Wallet Guide](./02-mnemonic-and-wallet.md) - Learn to generate and manage quantum wallets
+- [Address Generation](./03-address-generation.md) - Generate P2OP and other addresses
+- [Message Signing](./04-message-signing.md) - Sign and verify messages