@btc-vision/transaction 1.7.18 → 1.7.22

package/src/keypair/Address.ts

@@ -36,7 +36,12 @@ export class Address extends Uint8Array {
     #originalMDLSAPublicKey: Uint8Array | undefined;
     #mldsaLevel: MLDSASecurityLevel | undefined;
 
-    private legacyPublicKey: Uint8Array | undefined;
+    // Lazy loading state - defers expensive EC operations until actually needed
+    #pendingLegacyKey: Uint8Array | undefined;
+    #legacyProcessed: boolean = false;
+
+    // After processing, this is 32-byte tweaked x-only (same as original behavior)
+    #legacyPublicKey: Uint8Array | undefined;
 
     public constructor(mldsaPublicKey?: ArrayLike<number>, publicKeyOrTweak?: ArrayLike<number>) {
         super(ADDRESS_BYTE_LENGTH);
@@ -46,11 +51,12 @@ export class Address extends Uint8Array {
         }
 
         if (publicKeyOrTweak) {
-            this.legacyPublicKey = new Uint8Array(publicKeyOrTweak.length);
-            this.legacyPublicKey.set(publicKeyOrTweak);
+            // Store but don't process yet - defer EC operations
+            this.#pendingLegacyKey = new Uint8Array(publicKeyOrTweak.length);
+            this.#pendingLegacyKey.set(publicKeyOrTweak);
         }
 
-        this.set(mldsaPublicKey);
+        this.setMldsaKey(mldsaPublicKey);
     }
 
     public get mldsaLevel(): MLDSASecurityLevel | undefined {
@@ -74,6 +80,7 @@ export class Address extends Uint8Array {
      * @returns {Uint8Array} The original public key used to create the address.
      */
     public get originalPublicKey(): Uint8Array | undefined {
+        this.ensureLegacyProcessed();
         return this.#originalPublicKey;
     }
 
@@ -81,11 +88,21 @@ export class Address extends Uint8Array {
         return this.#mldsaPublicKey;
     }
 
+    /**
+     * Get the legacy public key (32-byte tweaked x-only after processing).
+     * Triggers lazy processing if not yet done.
+     */
+    private get legacyPublicKey(): Uint8Array | undefined {
+        this.ensureLegacyProcessed();
+        return this.#legacyPublicKey;
+    }
+
     /**
      * Get the key pair for the address
      * @description This is only for internal use. Please use address.tweakedBytes instead.
      */
     private get keyPair(): ECPairInterface {
+        this.ensureLegacyProcessed();
         if (!this.#keyPair) {
             throw new Error('Legacy public key not set for address');
         }
@@ -291,11 +308,12 @@ export class Address extends Uint8Array {
      * @returns {string} The hex string
      */
     public tweakedToHex(): string {
-        if (!this.legacyPublicKey) {
+        const key = this.legacyPublicKey;
+        if (!key) {
             throw new Error('Legacy public key not set');
         }
 
-        return '0x' + Buffer.from(this.legacyPublicKey).toString('hex');
+        return '0x' + Buffer.from(key).toString('hex');
     }
 
     /**
@@ -311,14 +329,16 @@ export class Address extends Uint8Array {
      * @returns {Buffer} The buffer
      */
     public tweakedPublicKeyToBuffer(): Buffer {
-        if (!this.legacyPublicKey) {
+        const key = this.legacyPublicKey;
+        if (!key) {
             throw new Error('Legacy public key not set');
         }
 
-        return Buffer.from(this.legacyPublicKey);
+        return Buffer.from(key);
     }
 
     public toUncompressedHex(): string {
+        this.ensureLegacyProcessed();
         if (!this.#uncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -327,6 +347,7 @@ export class Address extends Uint8Array {
     }
 
     public toUncompressedBuffer(): Buffer {
+        this.ensureLegacyProcessed();
         if (!this.#uncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -335,6 +356,7 @@ export class Address extends Uint8Array {
     }
 
     public toHybridPublicKeyHex(): string {
+        this.ensureLegacyProcessed();
         if (!this.#uncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -343,6 +365,7 @@ export class Address extends Uint8Array {
     }
 
     public toHybridPublicKeyBuffer(): Buffer {
+        this.ensureLegacyProcessed();
         if (!this.#uncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -351,6 +374,7 @@ export class Address extends Uint8Array {
     }
 
     public originalPublicKeyBuffer(): Buffer {
+        this.ensureLegacyProcessed();
         if (!this.#originalPublicKey) {
             throw new Error('Legacy public key not set');
         }
@@ -454,53 +478,8 @@ export class Address extends Uint8Array {
      * @returns {void}
      */
     public override set(mldsaPublicKey: ArrayLike<number>): void {
-        if (this.legacyPublicKey) {
-            const validLengths = [ADDRESS_BYTE_LENGTH, 33, 65];
-            if (!validLengths.includes(this.legacyPublicKey.length)) {
-                throw new Error(`Invalid public key length ${this.legacyPublicKey.length}`);
-            }
-
-            if (this.legacyPublicKey.length === ADDRESS_BYTE_LENGTH) {
-                const buf = Buffer.alloc(ADDRESS_BYTE_LENGTH);
-                buf.set(this.legacyPublicKey);
-
-                this.#tweakedUncompressed = ContractAddress.generateHybridKeyFromHash(buf);
-            } else {
-                this.autoFormat(this.legacyPublicKey);
-            }
-        }
-
-        // THIS is the SHA256(ORIGINAL_ML_DSA_PUBLIC_KEY)
-        if (mldsaPublicKey.length === ADDRESS_BYTE_LENGTH) {
-            const buf = new Uint8Array(ADDRESS_BYTE_LENGTH);
-            buf.set(mldsaPublicKey);
-
-            super.set(buf);
-        } else {
-            // Validate ML-DSA public key lengths according to BIP360 and FIPS 204
-            // ML-DSA-44 (Level 2): 1312 bytes public key
-            // ML-DSA-65 (Level 3): 1952 bytes public key
-            // ML-DSA-87 (Level 5): 2592 bytes public key
-            const validMLDSALengths = [1312, 1952, 2592];
-
-            if (!validMLDSALengths.includes(mldsaPublicKey.length)) {
-                throw new Error(
-                    `Invalid ML-DSA public key length: ${mldsaPublicKey.length}. ` +
-                        `Expected 1312 (ML-DSA-44/LEVEL2), 1952 (ML-DSA-65/LEVEL3), or 2592 (ML-DSA-87/LEVEL5) bytes.`,
-                );
-            }
-
-            // Store the original ML-DSA public key
-            this.#mldsaPublicKey = new Uint8Array(mldsaPublicKey.length);
-            this.#mldsaPublicKey.set(mldsaPublicKey);
-
-            // Hash the ML-DSA public key to get the 32-byte address
-            const hashedPublicKey = sha256(new Uint8Array(mldsaPublicKey));
-            const buf = new Uint8Array(ADDRESS_BYTE_LENGTH);
-            buf.set(hashedPublicKey);
-
-            super.set(buf);
-        }
+        // Legacy key processing is now deferred via ensureLegacyProcessed()
+        this.setMldsaKey(mldsaPublicKey);
     }
 
     /**
@@ -509,14 +488,12 @@ export class Address extends Uint8Array {
      * @returns {boolean} If the public key is valid
      */
     public isValidLegacyPublicKey(network: Network): boolean {
-        if (!this.legacyPublicKey) {
+        const key = this.legacyPublicKey;
+        if (!key) {
             throw new Error(`Legacy key not set.`);
         }
 
-        return AddressVerificator.isValidPublicKey(
-            Buffer.from(this.legacyPublicKey).toString('hex'),
-            network,
-        );
+        return AddressVerificator.isValidPublicKey(Buffer.from(key).toString('hex'), network);
     }
 
     /**
@@ -569,18 +546,16 @@ export class Address extends Uint8Array {
      * @param {Network} network The network
      */
     public p2tr(network: Network): string {
-        if (!this.legacyPublicKey) {
-            throw new Error('Legacy public key not set');
-        }
-
         if (this.#p2tr && this.#network === network) {
             return this.#p2tr;
         }
 
-        const p2trAddy: string | undefined = EcKeyPair.tweakedPubKeyBufferToAddress(
-            this.legacyPublicKey,
-            network,
-        );
+        const key = this.legacyPublicKey;
+        if (!key) {
+            throw new Error('Legacy public key not set');
+        }
+
+        const p2trAddy: string | undefined = EcKeyPair.tweakedPubKeyBufferToAddress(key, network);
 
         if (p2trAddy) {
             this.#network = network;
@@ -619,6 +594,7 @@ export class Address extends Uint8Array {
             return this.#p2wda;
         }
 
+        this.ensureLegacyProcessed();
         if (!this.#originalPublicKey) {
             throw new Error('Cannot create P2WDA address: public key not set');
         }
@@ -665,6 +641,7 @@ export class Address extends Uint8Array {
 
         // We need the original public key in compressed format for the script
         // Your class stores this in #originalPublicKey when a key is set
+        this.ensureLegacyProcessed();
         if (!this.#originalPublicKey) {
             throw new Error('Cannot create CSV address: public key not set');
         }
@@ -698,6 +675,7 @@ export class Address extends Uint8Array {
 
         // We need the original public key in compressed format for the script
         // Your class stores this in #originalPublicKey when a key is set
+        this.ensureLegacyProcessed();
         if (!this.#originalPublicKey) {
             throw new Error('Cannot create CSV address: public key not set');
         }
@@ -726,6 +704,8 @@ export class Address extends Uint8Array {
             return this.#p2op;
         }
 
+        // p2op only uses the MLDSA hash (this Uint8Array), no legacy key processing needed.
+        // This is the HOT PATH for parsing - stays fast without triggering EC operations.
         const p2opAddy: string | undefined = EcKeyPair.p2op(this, network);
         if (p2opAddy) {
             this.#network = network;
@@ -738,6 +718,7 @@ export class Address extends Uint8Array {
     }
 
     public toTweakedHybridPublicKeyHex(): string {
+        this.ensureLegacyProcessed();
         if (!this.#tweakedUncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -746,6 +727,7 @@ export class Address extends Uint8Array {
     }
 
     public toTweakedHybridPublicKeyBuffer(): Buffer {
+        this.ensureLegacyProcessed();
         if (!this.#tweakedUncompressed) {
             throw new Error('Legacy public key not set');
         }
@@ -753,6 +735,77 @@ export class Address extends Uint8Array {
         return this.#tweakedUncompressed;
     }
 
+    /**
+     * Sets the MLDSA key portion of the address.
+     * @param {ArrayLike<number>} mldsaPublicKey - The MLDSA public key or its hash
+     */
+    private setMldsaKey(mldsaPublicKey: ArrayLike<number>): void {
+        // THIS is the SHA256(ORIGINAL_ML_DSA_PUBLIC_KEY)
+        if (mldsaPublicKey.length === ADDRESS_BYTE_LENGTH) {
+            const buf = new Uint8Array(ADDRESS_BYTE_LENGTH);
+            buf.set(mldsaPublicKey);
+
+            super.set(buf);
+        } else {
+            // Validate ML-DSA public key lengths according to BIP360 and FIPS 204
+            // ML-DSA-44 (Level 2): 1312 bytes public key
+            // ML-DSA-65 (Level 3): 1952 bytes public key
+            // ML-DSA-87 (Level 5): 2592 bytes public key
+            const validMLDSALengths = [1312, 1952, 2592];
+
+            if (!validMLDSALengths.includes(mldsaPublicKey.length)) {
+                throw new Error(
+                    `Invalid ML-DSA public key length: ${mldsaPublicKey.length}. ` +
+                        `Expected 1312 (ML-DSA-44/LEVEL2), 1952 (ML-DSA-65/LEVEL3), or 2592 (ML-DSA-87/LEVEL5) bytes.`,
+                );
+            }
+
+            // Store the original ML-DSA public key
+            this.#mldsaPublicKey = new Uint8Array(mldsaPublicKey.length);
+            this.#mldsaPublicKey.set(mldsaPublicKey);
+
+            // Hash the ML-DSA public key to get the 32-byte address
+            const hashedPublicKey = sha256(new Uint8Array(mldsaPublicKey));
+            const buf = new Uint8Array(ADDRESS_BYTE_LENGTH);
+            buf.set(hashedPublicKey);
+
+            super.set(buf);
+        }
+    }
+
+    /**
+     * Lazy processing of legacy key - defers expensive EC operations until actually needed.
+     * Does the EXACT same logic as the original set() method did for legacy keys.
+     */
+    private ensureLegacyProcessed(): void {
+        if (this.#legacyProcessed) return;
+        this.#legacyProcessed = true;
+
+        const pending = this.#pendingLegacyKey;
+        if (!pending) return;
+
+        const validLengths = [ADDRESS_BYTE_LENGTH, 33, 65];
+        if (!validLengths.includes(pending.length)) {
+            throw new Error(`Invalid public key length ${pending.length}`);
+        }
+
+        if (pending.length === ADDRESS_BYTE_LENGTH) {
+            // 32-byte input: already tweaked x-only, just generate hybrid
+            const buf = Buffer.alloc(ADDRESS_BYTE_LENGTH);
+            buf.set(pending);
+
+            this.#tweakedUncompressed = ContractAddress.generateHybridKeyFromHash(buf);
+            this.#legacyPublicKey = pending;
+        } else {
+            // 33 or 65 bytes: full autoFormat processing with EC operations
+            this.autoFormat(pending);
+        }
+    }
+
+    /**
+     * Processes a 33 or 65 byte public key, performing EC operations.
+     * Sets #legacyPublicKey to 32-byte tweaked x-only (same as original behavior).
+     */
     private autoFormat(publicKey: ArrayLike<number>): void {
         const firstByte = publicKey[0];
 
@@ -773,7 +826,7 @@ export class Address extends Uint8Array {
 
         this.#tweakedUncompressed = ContractAddress.generateHybridKeyFromHash(tweakedBytes);
 
-        this.legacyPublicKey = new Uint8Array(ADDRESS_BYTE_LENGTH);
-        this.legacyPublicKey.set(tweakedBytes);
+        this.#legacyPublicKey = new Uint8Array(ADDRESS_BYTE_LENGTH);
+        this.#legacyPublicKey.set(tweakedBytes);
     }
 }

package/src/opnet.ts

@@ -9,6 +9,7 @@ export * from './bytecode/Compressor.js';
 export * from './generators/builders/CalldataGenerator.js';
 export * from './generators/builders/CustomGenerator.js';
 export * from './generators/builders/DeploymentGenerator.js';
+export * from './generators/builders/HashCommitmentGenerator.js';
 export * from './generators/builders/LegacyCalldataGenerator.js';
 export * from './generators/builders/MultiSignGenerator.js';
 export * from './generators/builders/P2WDAGenerator.js';
@@ -54,14 +55,18 @@ export * from './network/ChainId.js';
 
 /** Signer */
 export * from './signer/TweakedSigner.js';
+export * from './signer/AddressRotation.js';
 
 /** Transaction */
 export * from './transaction/enums/TransactionType.js';
 export * from './transaction/interfaces/ITransactionParameters.js';
+export * from './transaction/interfaces/IConsolidatedTransactionParameters.js';
 export * from './transaction/interfaces/Tap.js';
 export * from './transaction/TransactionFactory.js';
 
 /** Builders */
+export * from './transaction/builders/CancelTransaction.js';
+export * from './transaction/builders/ConsolidatedInteractionTransaction.js';
 export * from './transaction/builders/CustomScriptTransaction.js';
 export * from './transaction/builders/DeploymentTransaction.js';
 export * from './transaction/builders/FundingTransaction.js';
@@ -70,7 +75,9 @@ export * from './transaction/builders/InteractionTransactionP2WDA.js';
 export * from './transaction/builders/MultiSignTransaction.js';
 export * from './transaction/builders/SharedInteractionTransaction.js';
 export * from './transaction/builders/TransactionBuilder.js';
-export * from './transaction/builders/CancelTransaction.js';
+
+/** Offline Transaction Signing */
+export * from './transaction/offline/index.js';
 
 /** Epoch */
 export * from './epoch/interfaces/IChallengeSolution.js';

package/src/signer/AddressRotation.ts

@@ -0,0 +1,72 @@
+import { Signer } from '@btc-vision/bitcoin';
+import { ECPairInterface } from 'ecpair';
+import { UnisatSigner } from '../transaction/browser/extensions/UnisatSigner.js';
+
+/**
+ * Supported signer types for address rotation
+ */
+export type RotationSigner = Signer | ECPairInterface | UnisatSigner;
+
+/**
+ * Map of addresses to their respective signers for address rotation mode.
+ * Each UTXO address can have its own dedicated signer.
+ */
+export type SignerMap = Map<string, RotationSigner>;
+
+/**
+ * Configuration for address rotation mode.
+ * When enabled, each UTXO can be signed by a different signer based on its address.
+ */
+export interface AddressRotationConfig {
+    /**
+     * Whether address rotation mode is enabled.
+     * When true, the signerMap will be used to find the appropriate signer for each UTXO.
+     * When false, the default single signer will be used for all inputs.
+     */
+    readonly enabled: boolean;
+
+    /**
+     * Map of addresses to their respective signers.
+     * The key is the address (from UTXO.scriptPubKey.address).
+     * The value is the signer that controls that address.
+     */
+    readonly signerMap: SignerMap;
+}
+
+/**
+ * Creates a new SignerMap from an array of address-signer pairs.
+ * @param pairs - Array of [address, signer] tuples
+ * @returns A SignerMap ready for use with address rotation
+ */
+export function createSignerMap(
+    pairs: ReadonlyArray<readonly [string, RotationSigner]>,
+): SignerMap {
+    return new Map(pairs);
+}
+
+/**
+ * Creates an AddressRotationConfig with the given signers.
+ * @param signers - Map or array of address-signer pairs
+ * @returns AddressRotationConfig ready for use
+ */
+export function createAddressRotation(
+    signers: SignerMap | ReadonlyArray<readonly [string, RotationSigner]>,
+): AddressRotationConfig {
+    const signerMap = signers instanceof Map ? signers : createSignerMap(signers);
+
+    return {
+        enabled: true,
+        signerMap,
+    };
+}
+
+/**
+ * Creates a disabled address rotation config (single signer mode).
+ * @returns AddressRotationConfig with rotation disabled
+ */
+export function disabledAddressRotation(): AddressRotationConfig {
+    return {
+        enabled: false,
+        signerMap: new Map(),
+    };
+}

package/src/transaction/TransactionFactory.ts

@@ -1,7 +1,10 @@
 import { Transaction, TxOutput } from '@btc-vision/bitcoin';
 import { currentConsensus } from '../consensus/ConsensusConfig.js';
 import { UTXO } from '../utxo/interfaces/IUTXO.js';
-import { CustomScriptTransaction, ICustomTransactionParameters, } from './builders/CustomScriptTransaction.js';
+import {
+    CustomScriptTransaction,
+    ICustomTransactionParameters,
+} from './builders/CustomScriptTransaction.js';
 import { DeploymentTransaction } from './builders/DeploymentTransaction.js';
 import { FundingTransaction } from './builders/FundingTransaction.js';
 import { InteractionTransaction } from './builders/InteractionTransaction.js';
@@ -28,6 +31,11 @@ import { ChallengeSolution } from '../epoch/ChallengeSolution.js';
 import { Address } from '../keypair/Address.js';
 import { BitcoinUtils } from '../utils/BitcoinUtils.js';
 import { CancelTransaction, ICancelTransactionParameters } from './builders/CancelTransaction.js';
+import { ConsolidatedInteractionTransaction } from './builders/ConsolidatedInteractionTransaction.js';
+import {
+    IConsolidatedInteractionParameters,
+    IConsolidatedInteractionResult,
+} from './interfaces/IConsolidatedTransactionParameters.js';
 
 export interface DeploymentResult {
     readonly transaction: [string, string];
@@ -75,6 +83,33 @@ export interface CancelledTransaction {
     readonly inputUtxos: UTXO[];
 }
 
+/**
+ * Response from signConsolidatedInteraction.
+ * Contains both setup and reveal transactions for the CHCT system.
+ */
+export interface ConsolidatedInteractionResponse {
+    /** Setup transaction hex - creates P2WSH commitment outputs */
+    readonly setupTransaction: string;
+    /** Reveal transaction hex - spends commitments, reveals data in witnesses */
+    readonly revealTransaction: string;
+    /** Setup transaction ID */
+    readonly setupTxId: string;
+    /** Reveal transaction ID */
+    readonly revealTxId: string;
+    /** Total fees across both transactions in satoshis */
+    readonly totalFees: bigint;
+    /** Number of data chunks */
+    readonly chunkCount: number;
+    /** Total compiled data size in bytes */
+    readonly dataSize: number;
+    /** Challenge for the interaction */
+    readonly challenge: RawChallenge;
+    /** Input UTXOs used */
+    readonly inputUtxos: UTXO[];
+    /** Compiled target script (same as InteractionTransaction) */
+    readonly compiledTargetScript: string;
+}
+
 export class TransactionFactory {
     public debug: boolean = false;
 
@@ -318,6 +353,64 @@ export class TransactionFactory {
         };
     }
 
+    /**
+     * @description Generates a consolidated interaction transaction (CHCT system).
+     *
+     * Drop-in replacement for signInteraction that bypasses BIP110/Bitcoin Knots censorship.
+     * Uses P2WSH with HASH160 commitments instead of Tapscript (which uses OP_IF and gets censored).
+     *
+     * Returns two transactions:
+     * - Setup: Creates P2WSH outputs with hash commitments to data chunks
+     * - Reveal: Spends those outputs, revealing data in witnesses
+     *
+     * Data integrity is consensus-enforced - if data is stripped/modified,
+     * HASH160(data) != committed_hash and the transaction is INVALID.
+     *
+     * @param {IConsolidatedInteractionParameters} interactionParameters - Same parameters as signInteraction
+     * @returns {Promise<ConsolidatedInteractionResponse>} - Both setup and reveal transactions
+     */
+    public async signConsolidatedInteraction(
+        interactionParameters: IConsolidatedInteractionParameters,
+    ): Promise<ConsolidatedInteractionResponse> {
+        if (!interactionParameters.to) {
+            throw new Error('Field "to" not provided.');
+        }
+        if (!interactionParameters.from) {
+            throw new Error('Field "from" not provided.');
+        }
+        if (!interactionParameters.utxos[0]) {
+            throw new Error('Missing at least one UTXO.');
+        }
+        if (!('signer' in interactionParameters)) {
+            throw new Error('Field "signer" not provided.');
+        }
+        if (!interactionParameters.challenge) {
+            throw new Error('Field "challenge" not provided.');
+        }
+
+        const inputs = this.parseOptionalInputs(interactionParameters.optionalInputs);
+
+        const consolidatedTx = new ConsolidatedInteractionTransaction({
+            ...interactionParameters,
+            optionalInputs: inputs,
+        });
+
+        const result = await consolidatedTx.build();
+
+        return {
+            setupTransaction: result.setup.txHex,
+            revealTransaction: result.reveal.txHex,
+            setupTxId: result.setup.txId,
+            revealTxId: result.reveal.txId,
+            totalFees: result.totalFees,
+            chunkCount: result.setup.chunkCount,
+            dataSize: result.setup.totalDataSize,
+            challenge: consolidatedTx.getChallenge().toRaw(),
+            inputUtxos: interactionParameters.utxos,
+            compiledTargetScript: consolidatedTx.exportCompiledTargetScript().toString('hex'),
+        };
+    }
+
     /**
      * @description Generates the required transactions.
      * @param {IDeploymentParameters} deploymentParameters - The deployment parameters

package/src/transaction/builders/CancelTransaction.ts

@@ -8,8 +8,10 @@ import {
 } from '../interfaces/ITransactionParameters.js';
 import { UnisatSigner } from '../browser/extensions/UnisatSigner.js';
 
-export interface ICancelTransactionParameters
-    extends Omit<ITransactionParameters, 'priorityFee' | 'gasSatFee'> {
+export interface ICancelTransactionParameters extends Omit<
+    ITransactionParameters,
+    'priorityFee' | 'gasSatFee'
+> {
     readonly compiledTargetScript: string | Buffer;
 }