@btc-vision/transaction 1.7.1 → 1.7.3

package/documentation/quantum-support/02-mnemonic-and-wallet.md

@@ -404,16 +404,21 @@ console.log(wallet1.p2tr === wallet2.p2tr);  // true - deterministic!
 ## Complete Example
 
 ```typescript
-import { Mnemonic, MnemonicStrength, MLDSASecurityLevel } from '@btc-vision/transaction';
+import {
+    AddressTypes,
+    MLDSASecurityLevel,
+    Mnemonic,
+    MnemonicStrength,
+} from '@btc-vision/transaction';
 import { networks } from '@btc-vision/bitcoin';
 
 // Step 1: Generate mnemonic
 console.log('Generating quantum-resistant wallet...');
 const mnemonic = Mnemonic.generate(
-    MnemonicStrength.MAXIMUM,            // 24 words
-    'optional-passphrase',               // BIP39 passphrase
-    networks.bitcoin,                     // Network
-    MLDSASecurityLevel.LEVEL2            // Security level
+    MnemonicStrength.MAXIMUM, // 24 words
+    '', // BIP39 passphrase
+    networks.regtest, // Network
+    MLDSASecurityLevel.LEVEL2, // Security level
 );
 
 // Step 2: Securely store mnemonic phrase
@@ -423,11 +428,12 @@ console.log(phrase);
 
 // Step 3: Derive wallets
 const wallet = mnemonic.derive(0);
+const walletUnisat = mnemonic.deriveUnisat(AddressTypes.P2TR, 0);
 
-// Step 4: Get addresses
-console.log('\nClassical Addresses:');
-console.log('P2TR:', wallet.p2tr);
-console.log('P2WPKH:', wallet.p2wpkh);
+console.log('\nDerived Wallets:');
+console.log('Classical Wallet (Unisat):');
+console.log('  P2TR Address:', walletUnisat.p2tr);
+console.log('  P2WPKH Address:', walletUnisat.p2wpkh);
 
 console.log('\nQuantum Address:');
 console.log('Public Key:', wallet.address.toHex());
@@ -435,8 +441,14 @@ console.log('Public Key:', wallet.address.toHex());
 // Step 5: Display keys (for demonstration only!)
 console.log('\nKey Information:');
 console.log('Classical Public Key:', wallet.toPublicKeyHex());
-console.log('Quantum Public Key Length:', wallet.quantumPublicKey.length, 'bytes');
+console.log('Quantum Public Key:', wallet.quantumPublicKeyHex);
 console.log('Security Level:', wallet.securityLevel);
+
+// Step 4: Get addresses
+console.log('\nClassical Addresses:');
+console.log('P2TR:', wallet.p2tr);
+console.log('P2WPKH:', wallet.p2wpkh);
+
 ```
 
 ## Next Steps

package/package.json

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

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,94 @@
-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];
+    public 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;
+        }
+    }
+
+    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]> {
-        for (const key of this._keys) {
-            yield [key, this.get(key) as V];
+        for (let i = 0; i < this.keyOrder.length; i++) {
+            const key = this.keyOrder[i];
+            yield [key, this.items.get(key.toBigInt()) as V];
         }
     }
 }

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;
     }
 }

package/src/deterministic/DeterministicMap.ts

@@ -1,3 +1,5 @@
+import { Map } from './Map.js';
+
 export class DeterministicMap<K, V> {
     private map: Map<K, V>;
     #keys: K[];
@@ -34,25 +36,25 @@ export class DeterministicMap<K, V> {
         return this.map.get(key);
     }
 
-    public keys(): IterableIterator<K> {
-        return this.#keys.values();
+    public *entries(): IterableIterator<[K, V]> {
+        for (const key of this.#keys) {
+            yield [key, this.map.get(key) as V];
+        }
     }
 
-    public values(): IterableIterator<V> {
-        const values: V[] = [];
+    public *keys(): IterableIterator<K> {
+        yield* this.#keys;
+    }
 
-        for (let i = 0; i < this.#keys.length; i++) {
-            const key = this.#keys[i];
+    public *values(): IterableIterator<V> {
+        for (const key of this.#keys) {
             const value = this.map.get(key);
-
-            if (value) {
-                values.push(value);
-            } else {
+            if (value === undefined && !this.map.has(key)) {
                 throw new Error('Value not found');
             }
-        }
 
-        return values.values();
+            yield value as V;
+        }
     }
 
     public has(key: K): boolean {

package/src/deterministic/Map.ts

@@ -8,20 +8,18 @@ export class Map<K, V> {
         return this._keys.length;
     }
 
-    public keys(): K[] {
-        return this._keys;
+    public *keys(): IterableIterator<K> {
+        yield* this._keys;
     }
 
-    public values(): V[] {
-        return this._values;
+    public *values(): IterableIterator<V> {
+        yield* this._values;
     }
 
-    public entries(): [K, V][] {
-        const result: [K, V][] = [];
+    public *entries(): IterableIterator<[K, V]> {
         for (let i: i32 = 0; i < this._keys.length; i++) {
-            result.push([this._keys[i], this._values[i]]);
+            yield [this._keys[i], this._values[i]];
         }
-        return result;
     }
 
     public set(key: K, value: V): void {
@@ -71,4 +69,10 @@ export class Map<K, V> {
         this._keys = [];
         this._values = [];
     }
+
+    *[Symbol.iterator](): IterableIterator<[K, V]> {
+        for (let i: i32 = 0; i < this._keys.length; i++) {
+            yield [this._keys[i], this._values[i]];
+        }
+    }
 }

package/src/keypair/Address.ts

@@ -30,6 +30,8 @@ export class Address extends Uint8Array {
     #tweakedUncompressed: Buffer | undefined;
     #p2wda: IP2WSHAddress | undefined;
     #mldsaPublicKey: Uint8Array | undefined;
+    #cachedBigInt: bigint | undefined;
+    #cachedUint64Array: [bigint, bigint, bigint, bigint] | undefined;
 
     private classicPublicKey: Uint8Array | undefined;
 
@@ -140,6 +142,109 @@ export class Address extends Uint8Array {
         return compressed;
     }
 
+    /**
+     * Creates an Address instance from a BigInt value.
+     *
+     * Converts a 256-bit unsigned integer into a 32-byte address by splitting it
+     * into four 64-bit chunks and writing them in big-endian format using DataView.
+     * This is the inverse operation of toBigInt().
+     *
+     * @param {bigint} value - The 256-bit unsigned integer to convert (0 to 2^256-1)
+     * @returns {Address} A new Address instance containing the converted value
+     *
+     * @throws {RangeError} If the value is negative or exceeds 2^256-1
+     *
+     * @example
+     * ```typescript
+     * const bigIntValue = 12345678901234567890n;
+     * const address = Address.fromBigInt(bigIntValue);
+     * console.log(address.toHex()); // 0x0000000000000000000000000000000000000000000000000000abc123...
+     * ```
+     */
+    public static fromBigInt(value: bigint): Address {
+        const buffer = new Uint8Array(32);
+        const view = new DataView(buffer.buffer);
+
+        view.setBigUint64(0, (value >> 192n) & 0xffffffffffffffffn, false);
+        view.setBigUint64(8, (value >> 128n) & 0xffffffffffffffffn, false);
+        view.setBigUint64(16, (value >> 64n) & 0xffffffffffffffffn, false);
+        view.setBigUint64(24, value & 0xffffffffffffffffn, false);
+
+        return new Address(buffer);
+    }
+
+    /**
+     * Creates an Address instance from four 64-bit unsigned integers.
+     *
+     * Constructs a 32-byte address by combining four 64-bit big-endian unsigned integers.
+     * This is the inverse operation of toUint64Array() and provides an efficient way
+     * to create addresses from word-aligned data.
+     *
+     * @param {bigint} w0 - Most significant 64 bits (bytes 0-7)
+     * @param {bigint} w1 - Second 64 bits (bytes 8-15)
+     * @param {bigint} w2 - Third 64 bits (bytes 16-23)
+     * @param {bigint} w3 - Least significant 64 bits (bytes 24-31)
+     * @returns {Address} A new Address instance containing the combined value
+     *
+     * @throws {RangeError} If any value exceeds 64 bits (2^64-1)
+     *
+     * @example
+     * ```typescript
+     * const address = Address.fromUint64Array(
+     *     0x0123456789abcdefn,
+     *     0xfedcba9876543210n,
+     *     0x1111222233334444n,
+     *     0x5555666677778888n
+     * );
+     * console.log(address.toHex());
+     * ```
+     */
+    public static fromUint64Array(w0: bigint, w1: bigint, w2: bigint, w3: bigint): Address {
+        const buffer = new Uint8Array(32);
+        const view = new DataView(buffer.buffer);
+
+        view.setBigUint64(0, w0, false);
+        view.setBigUint64(8, w1, false);
+        view.setBigUint64(16, w2, false);
+        view.setBigUint64(24, w3, false);
+
+        return new Address(buffer);
+    }
+
+    /**
+     * Converts the address to four 64-bit unsigned integers.
+     *
+     * Splits the 32-byte (256-bit) address into four 64-bit big-endian unsigned integers.
+     * This representation is useful for efficient storage, comparison operations, or
+     * interfacing with systems that work with 64-bit word sizes.
+     *
+     * @returns {[bigint, bigint, bigint, bigint]} An array of four 64-bit unsigned integers
+     *          representing the address from most significant to least significant bits
+     *
+     * @example
+     * ```typescript
+     * const address = Address.fromString('0x0123456789abcdef...');
+     * const [w0, w1, w2, w3] = address.toUint64Array();
+     * console.log(w0); // Most significant 64 bits
+     * console.log(w3); // Least significant 64 bits
+     * ```
+     */
+    public toUint64Array(): [bigint, bigint, bigint, bigint] {
+        if (this.#cachedUint64Array !== undefined) {
+            return this.#cachedUint64Array;
+        }
+
+        const view = new DataView(this.buffer, this.byteOffset, 32);
+        this.#cachedUint64Array = [
+            view.getBigUint64(0, false),
+            view.getBigUint64(8, false),
+            view.getBigUint64(16, false),
+            view.getBigUint64(24, false),
+        ];
+
+        return this.#cachedUint64Array;
+    }
+
     /**
      * Converts the address to a hex string
      * @returns {string} The hex string
@@ -220,6 +325,37 @@ export class Address extends Uint8Array {
         return Buffer.from(this.#originalPublicKey);
     }
 
+    /**
+     * Converts the address to a BigInt representation.
+     *
+     * This method uses an optimized DataView approach to read the 32-byte address
+     * as four 64-bit big-endian unsigned integers, then combines them using bitwise
+     * operations. This is approximately 10-20x faster than string-based conversion.
+     *
+     * @returns {bigint} The address as a 256-bit unsigned integer
+     *
+     * @example
+     * ```typescript
+     * const address = Address.fromString('0x0123456789abcdef...');
+     * const bigIntValue = address.toBigInt();
+     * console.log(bigIntValue); // 123456789...n
+     * ```
+     */
+    public toBigInt(): bigint {
+        if (this.#cachedBigInt !== undefined) {
+            return this.#cachedBigInt;
+        }
+
+        const view = new DataView(this.buffer, this.byteOffset, 32);
+        this.#cachedBigInt =
+            (view.getBigUint64(0, false) << 192n) |
+            (view.getBigUint64(8, false) << 128n) |
+            (view.getBigUint64(16, false) << 64n) |
+            view.getBigUint64(24, false);
+
+        return this.#cachedBigInt;
+    }
+
     public equals(a: Address): boolean {
         const b: Address = this as Address;
 

package/src/opnet.ts

@@ -125,6 +125,8 @@ export * from './transaction/browser/Web3Provider.js';
 export * from './keypair/Secp256k1PointDeriver.js';
 export * from './transaction/ContractAddress.js';
 
+export * from './deterministic/Map.js';
+
 declare global {
     interface Window {
         unisat?: Unisat;

package/src/utils/lengths.ts

@@ -1,20 +1,18 @@
-import { i32 } from './types';
+export const ADDRESS_BYTE_LENGTH: number = 32;
+export const SELECTOR_BYTE_LENGTH: number = 4;
 
-export const ADDRESS_BYTE_LENGTH: i32 = 32;
-export const SELECTOR_BYTE_LENGTH: i32 = 4;
+export const U256_BYTE_LENGTH: number = 32;
+export const U128_BYTE_LENGTH: number = 16;
+export const U64_BYTE_LENGTH: number = 8;
+export const U32_BYTE_LENGTH: number = 4;
+export const U16_BYTE_LENGTH: number = 2;
+export const U8_BYTE_LENGTH: number = 1;
 
-export const U256_BYTE_LENGTH: i32 = 32;
-export const U128_BYTE_LENGTH: i32 = 16;
-export const U64_BYTE_LENGTH: i32 = 8;
-export const U32_BYTE_LENGTH: i32 = 4;
-export const U16_BYTE_LENGTH: i32 = 2;
-export const U8_BYTE_LENGTH: i32 = 1;
+export const I256_BYTE_LENGTH: number = 32;
+export const I128_BYTE_LENGTH: number = 16;
+export const I64_BYTE_LENGTH: number = 8;
+export const number_BYTE_LENGTH: number = 4;
+export const I16_BYTE_LENGTH: number = 2;
+export const I8_BYTE_LENGTH: number = 1;
 
-export const I256_BYTE_LENGTH: i32 = 32;
-export const I128_BYTE_LENGTH: i32 = 16;
-export const I64_BYTE_LENGTH: i32 = 8;
-export const I32_BYTE_LENGTH: i32 = 4;
-export const I16_BYTE_LENGTH: i32 = 2;
-export const I8_BYTE_LENGTH: i32 = 1;
-
-export const BOOLEAN_BYTE_LENGTH: i32 = 1;
+export const BOOLEAN_BYTE_LENGTH: number = 1;