@btc-vision/transaction 1.6.19 → 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

@@ -0,0 +1,34 @@
+import { BIP32Interface, MLDSASecurityLevel, QuantumBIP32Interface } from '@btc-vision/bip32';
+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;
+    private readonly _network;
+    private readonly _securityLevel;
+    private readonly _seed;
+    private readonly _classicalRoot;
+    private readonly _quantumRoot;
+    constructor(phrase: string, passphrase?: string, network?: Network, securityLevel?: MLDSASecurityLevel);
+    get phrase(): string;
+    get network(): Network;
+    get securityLevel(): MLDSASecurityLevel;
+    get seed(): Buffer;
+    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, 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;
+    private buildClassicalPath;
+    private buildQuantumPath;
+    private getCoinType;
+}

package/build/mnemonic/Mnemonic.js

@@ -0,0 +1,140 @@
+import * as bip39 from 'bip39';
+import { BIP32Factory, MLDSASecurityLevel, QuantumBIP32Factory, } from '@btc-vision/bip32';
+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)) {
+            throw new Error('Invalid mnemonic phrase');
+        }
+        this._phrase = phrase;
+        this._passphrase = passphrase;
+        this._network = network;
+        this._securityLevel = securityLevel;
+        this._seed = bip39.mnemonicToSeedSync(this._phrase, this._passphrase);
+        this._classicalRoot = bip32.fromSeed(this._seed, this._network);
+        this._quantumRoot = QuantumBIP32Factory.fromSeed(this._seed, this._network, this._securityLevel);
+    }
+    get phrase() {
+        return this._phrase;
+    }
+    get network() {
+        return this._network;
+    }
+    get securityLevel() {
+        return this._securityLevel;
+    }
+    get seed() {
+        return Buffer.from(this._seed);
+    }
+    static generatePhrase(strength = MnemonicStrength.MAXIMUM) {
+        return bip39.generateMnemonic(strength);
+    }
+    static generate(strength = MnemonicStrength.MAXIMUM, passphrase = '', network = networks.bitcoin, securityLevel = MLDSASecurityLevel.LEVEL2) {
+        const phrase = bip39.generateMnemonic(strength);
+        return new Mnemonic(phrase, passphrase, network, securityLevel);
+    }
+    static validate(phrase) {
+        return bip39.validateMnemonic(phrase);
+    }
+    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}`);
+        }
+        const quantumPath = this.buildQuantumPath(account, index, isChange);
+        const quantumChild = this._quantumRoot.derivePath(quantumPath);
+        if (!quantumChild.privateKey) {
+            throw new Error(`Failed to derive quantum private key at index ${index}`);
+        }
+        return new Wallet(Buffer.from(classicalChild.privateKey).toString('hex'), Buffer.from(quantumChild.privateKey).toString('hex'), this._network, this._securityLevel);
+    }
+    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, bipStandard));
+        }
+        return wallets;
+    }
+    deriveCustomPath(classicalPath, quantumPath) {
+        const classicalChild = this._classicalRoot.derivePath(classicalPath);
+        const quantumChild = this._quantumRoot.derivePath(quantumPath);
+        if (!classicalChild.privateKey) {
+            throw new Error(`Failed to derive classical private key at path ${classicalPath}`);
+        }
+        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);
+    }
+    getClassicalRoot() {
+        return this._classicalRoot;
+    }
+    getQuantumRoot() {
+        return this._quantumRoot;
+    }
+    buildClassicalPath(account, index, isChange, bipStandard = BIPStandard.BIP84) {
+        const coinType = this.getCoinType();
+        const change = isChange ? 1 : 0;
+        return buildBIPPath(bipStandard, coinType, account, change, index);
+    }
+    buildQuantumPath(account, index, isChange) {
+        const coinType = this.getCoinType();
+        const change = isChange ? 1 : 0;
+        return `m/360'/${coinType}'/${account}'/${change}/${index}`;
+    }
+    getCoinType() {
+        if (this._network.bech32 === networks.testnet.bech32 ||
+            this._network.bech32 === networks.regtest.bech32) {
+            return 1;
+        }
+        return 0;
+    }
+}

package/build/mnemonic/MnemonicStrength.d.ts

@@ -0,0 +1,7 @@
+export declare enum MnemonicStrength {
+    MINIMUM = 128,
+    LOW = 160,
+    MEDIUM = 192,
+    HIGH = 224,
+    MAXIMUM = 256
+}

package/build/mnemonic/MnemonicStrength.js

@@ -0,0 +1,8 @@
+export var MnemonicStrength;
+(function (MnemonicStrength) {
+    MnemonicStrength[MnemonicStrength["MINIMUM"] = 128] = "MINIMUM";
+    MnemonicStrength[MnemonicStrength["LOW"] = 160] = "LOW";
+    MnemonicStrength[MnemonicStrength["MEDIUM"] = 192] = "MEDIUM";
+    MnemonicStrength[MnemonicStrength["HIGH"] = 224] = "HIGH";
+    MnemonicStrength[MnemonicStrength["MAXIMUM"] = 256] = "MAXIMUM";
+})(MnemonicStrength || (MnemonicStrength = {}));

package/build/opnet.d.ts

@@ -19,6 +19,10 @@ export * from './keypair/EcKeyPair.js';
 export * from './keypair/interfaces/IWallet.js';
 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';
 export * from './signer/TweakedSigner.js';
@@ -66,6 +70,7 @@ export * from './transaction/browser/extensions/UnisatSigner.js';
 export * from './transaction/browser/extensions/XverseSigner.js';
 export * from './transaction/browser/types/Unisat.js';
 export * from './transaction/browser/types/Xverse.js';
+export * from './transaction/browser/types/OPWallet.js';
 export * from './metadata/tokens.js';
 export * from './transaction/browser/Web3Provider.js';
 export * from './keypair/Secp256k1PointDeriver.js';

package/build/opnet.js

@@ -18,6 +18,10 @@ export * from './keypair/EcKeyPair.js';
 export * from './keypair/interfaces/IWallet.js';
 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';
 export * from './signer/TweakedSigner.js';
@@ -65,6 +69,7 @@ export * from './transaction/browser/extensions/UnisatSigner.js';
 export * from './transaction/browser/extensions/XverseSigner.js';
 export * from './transaction/browser/types/Unisat.js';
 export * from './transaction/browser/types/Xverse.js';
+export * from './transaction/browser/types/OPWallet.js';
 export * from './metadata/tokens.js';
 export * from './transaction/browser/Web3Provider.js';
 export * from './keypair/Secp256k1PointDeriver.js';

package/build/transaction/browser/types/OPWallet.d.ts

@@ -0,0 +1,14 @@
+import { Unisat } from './Unisat.js';
+import { MLDSASecurityLevel } from '@btc-vision/bip32';
+export interface MLDSASignature {
+    readonly signature: string;
+    readonly publicKey: string;
+    readonly securityLevel: MLDSASecurityLevel;
+    readonly messageHash: string;
+}
+export interface OPWallet extends Unisat {
+    getMLDSAPublicKey(): Promise<string>;
+    signMLDSAMessage(message: string): Promise<MLDSASignature>;
+    verifyMLDSASignature(message: string, signature: MLDSASignature): Promise<boolean>;
+}
+export declare function isOPWallet(wallet: unknown): wallet is OPWallet;

package/build/transaction/browser/types/OPWallet.js

@@ -0,0 +1,6 @@
+export function isOPWallet(wallet) {
+    return (typeof wallet === 'object' &&
+        wallet !== null &&
+        'getMLDSAPublicKey' in wallet &&
+        'signMLDSAMessage' in wallet);
+}

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