@btc-vision/transaction 1.7.18 → 1.7.22

package/src/transaction/offline/interfaces/ITypeSpecificData.ts

@@ -0,0 +1,172 @@
+import { TransactionType } from '../../enums/TransactionType.js';
+import { RawChallenge } from '../../../epoch/interfaces/IChallengeSolution.js';
+
+/**
+ * Discriminated union for type-specific serialized data
+ */
+export type TypeSpecificData =
+    | FundingSpecificData
+    | DeploymentSpecificData
+    | InteractionSpecificData
+    | MultiSigSpecificData
+    | CustomScriptSpecificData
+    | CancelSpecificData;
+
+/**
+ * Funding transaction specific data
+ */
+export interface FundingSpecificData {
+    readonly type: TransactionType.FUNDING;
+    /** Amount to send in satoshis */
+    readonly amount: string; // bigint as string
+    /** Number of outputs to split into */
+    readonly splitInputsInto: number;
+}
+
+/**
+ * Deployment transaction specific data
+ */
+export interface DeploymentSpecificData {
+    readonly type: TransactionType.DEPLOYMENT;
+    /** Compressed bytecode (hex) */
+    readonly bytecode: string;
+    /** Constructor calldata (hex) */
+    readonly calldata?: string;
+    /** Challenge solution for epoch */
+    readonly challenge: RawChallenge;
+    /** Reveal MLDSA public key in transaction */
+    readonly revealMLDSAPublicKey?: boolean;
+    /** Link MLDSA public key to legacy address */
+    readonly linkMLDSAPublicKeyToAddress?: boolean;
+    /** Hashed MLDSA public key (hex) */
+    readonly hashedPublicKey?: string;
+}
+
+/**
+ * Interaction transaction specific data
+ */
+export interface InteractionSpecificData {
+    readonly type: TransactionType.INTERACTION;
+    /** Compressed calldata (hex) */
+    readonly calldata: string;
+    /** Contract address/identifier */
+    readonly contract?: string;
+    /** Challenge solution for epoch */
+    readonly challenge: RawChallenge;
+    /** Loaded storage for access list */
+    readonly loadedStorage?: SerializedLoadedStorage;
+    /** Whether this is a cancellation */
+    readonly isCancellation?: boolean;
+    /** Disable auto refund */
+    readonly disableAutoRefund?: boolean;
+    /** Reveal MLDSA public key in transaction */
+    readonly revealMLDSAPublicKey?: boolean;
+    /** Link MLDSA public key to legacy address */
+    readonly linkMLDSAPublicKeyToAddress?: boolean;
+    /** Hashed MLDSA public key (hex) */
+    readonly hashedPublicKey?: string;
+}
+
+/**
+ * Loaded storage serialization format
+ */
+export interface SerializedLoadedStorage {
+    [key: string]: string[];
+}
+
+/**
+ * MultiSig transaction specific data
+ */
+export interface MultiSigSpecificData {
+    readonly type: TransactionType.MULTI_SIG;
+    /** Public keys (hex array) */
+    readonly pubkeys: string[];
+    /** M of N (minimum signatures required) */
+    readonly minimumSignatures: number;
+    /** Receiver address */
+    readonly receiver: string;
+    /** Requested amount to send */
+    readonly requestedAmount: string; // bigint as string
+    /** Refund vault address */
+    readonly refundVault: string;
+    /** Original input count (for partial signing) */
+    readonly originalInputCount: number;
+    /** Existing PSBT state (base64) if partially signed */
+    readonly existingPsbtBase64?: string;
+}
+
+/**
+ * Serialized script element for custom scripts
+ */
+export interface SerializedScriptElement {
+    /** Element type */
+    readonly elementType: 'buffer' | 'opcode';
+    /** Value as hex (buffer) or opcode number */
+    readonly value: string | number;
+}
+
+/**
+ * Custom script transaction specific data
+ */
+export interface CustomScriptSpecificData {
+    readonly type: TransactionType.CUSTOM_CODE;
+    /** Bitcoin script elements */
+    readonly scriptElements: SerializedScriptElement[];
+    /** Witnesses (hex array) */
+    readonly witnesses: string[];
+    /** Optional annex data (hex) */
+    readonly annex?: string;
+}
+
+/**
+ * Cancel transaction specific data
+ */
+export interface CancelSpecificData {
+    readonly type: TransactionType.CANCEL;
+    /** Compiled target script to cancel (hex) */
+    readonly compiledTargetScript: string;
+}
+
+/**
+ * Type guard for FundingSpecificData
+ */
+export function isFundingSpecificData(data: TypeSpecificData): data is FundingSpecificData {
+    return data.type === TransactionType.FUNDING;
+}
+
+/**
+ * Type guard for DeploymentSpecificData
+ */
+export function isDeploymentSpecificData(data: TypeSpecificData): data is DeploymentSpecificData {
+    return data.type === TransactionType.DEPLOYMENT;
+}
+
+/**
+ * Type guard for InteractionSpecificData
+ */
+export function isInteractionSpecificData(data: TypeSpecificData): data is InteractionSpecificData {
+    return data.type === TransactionType.INTERACTION;
+}
+
+/**
+ * Type guard for MultiSigSpecificData
+ */
+export function isMultiSigSpecificData(data: TypeSpecificData): data is MultiSigSpecificData {
+    return data.type === TransactionType.MULTI_SIG;
+}
+
+/**
+ * Type guard for CustomScriptSpecificData
+ */
+export function isCustomScriptSpecificData(
+    data: TypeSpecificData,
+): data is CustomScriptSpecificData {
+    return data.type === TransactionType.CUSTOM_CODE;
+}
+
+/**
+ * Type guard for CancelSpecificData
+ */
+export function isCancelSpecificData(data: TypeSpecificData): data is CancelSpecificData {
+    return data.type === TransactionType.CANCEL;
+}

package/src/transaction/offline/interfaces/index.ts

@@ -0,0 +1,2 @@
+export * from './ISerializableState.js';
+export * from './ITypeSpecificData.js';

package/src/transaction/shared/TweakedTransaction.ts

@@ -43,6 +43,7 @@ import { Buffer } from 'buffer';
 import { P2WDADetector } from '../../p2wda/P2WDADetector.js';
 import { QuantumBIP32Interface } from '@btc-vision/bip32';
 import { MessageSigner } from '../../keypair/MessageSigner.js';
+import { AddressRotationConfig, RotationSigner, SignerMap } from '../../signer/AddressRotation.js';
 
 export type SupportedTransactionVersion = 1 | 2 | 3;
 
@@ -55,6 +56,12 @@ export interface ITweakedTransactionData {
     readonly noSignatures?: boolean;
     readonly unlockScript?: Buffer[];
     readonly txVersion?: SupportedTransactionVersion;
+
+    /**
+     * Address rotation configuration for per-UTXO signing.
+     * When enabled, each UTXO can be signed by a different signer.
+     */
+    readonly addressRotation?: AddressRotationConfig;
 }
 
 /**
@@ -165,6 +172,28 @@ export abstract class TweakedTransaction extends Logger {
     protected readonly _mldsaSigner: QuantumBIP32Interface | null = null;
     protected readonly _hashedPublicKey: Buffer | null = null;
 
+    /**
+     * Whether address rotation mode is enabled.
+     * When true, each UTXO can be signed by a different signer.
+     */
+    protected readonly addressRotationEnabled: boolean = false;
+
+    /**
+     * Map of addresses to their respective signers for address rotation mode.
+     */
+    protected readonly signerMap: SignerMap = new Map();
+
+    /**
+     * Map of input indices to their signers (resolved from UTXOs or signerMap).
+     * Populated during input addition.
+     */
+    protected readonly inputSignerMap: Map<number, RotationSigner> = new Map();
+
+    /**
+     * Cache of tweaked signers per input for address rotation mode.
+     */
+    protected readonly tweakedSignerCache: Map<number, ECPairInterface | undefined> = new Map();
+
     protected constructor(data: ITweakedTransactionData) {
         super();
 
@@ -185,6 +214,12 @@ export abstract class TweakedTransaction extends Logger {
             this._mldsaSigner = data.mldsaSigner;
             this._hashedPublicKey = MessageSigner.sha256(this._mldsaSigner.publicKey);
         }
+
+        // Initialize address rotation
+        if (data.addressRotation?.enabled) {
+            this.addressRotationEnabled = true;
+            this.signerMap = data.addressRotation.signerMap;
+        }
     }
 
     /**
@@ -323,6 +358,13 @@ export abstract class TweakedTransaction extends Logger {
         return signHash || 0;
     }
 
+    /**
+     * Check if address rotation mode is enabled.
+     */
+    public isAddressRotationEnabled(): boolean {
+        return this.addressRotationEnabled;
+    }
+
     public ignoreSignatureError(): void {
         this.ignoreSignatureErrors = true;
     }
@@ -425,6 +467,93 @@ export abstract class TweakedTransaction extends Logger {
         return vSize * feeRate;
     }
 
+    /**
+     * Get the signer for a specific input index.
+     * Returns the input-specific signer if in rotation mode, otherwise the default signer.
+     * @param inputIndex - The index of the input
+     */
+    protected getSignerForInput(inputIndex: number): RotationSigner {
+        if (this.addressRotationEnabled) {
+            const inputSigner = this.inputSignerMap.get(inputIndex);
+            if (inputSigner) {
+                return inputSigner;
+            }
+        }
+        return this.signer;
+    }
+
+    /**
+     * Register a signer for a specific input index.
+     * Called during UTXO processing to map each input to its signer.
+     * @param inputIndex - The index of the input
+     * @param utxo - The UTXO being added
+     */
+    protected registerInputSigner(inputIndex: number, utxo: UTXO): void {
+        if (!this.addressRotationEnabled) {
+            return;
+        }
+
+        // Priority 1: UTXO has an explicit signer attached
+        if (utxo.signer) {
+            this.inputSignerMap.set(inputIndex, utxo.signer);
+            return;
+        }
+
+        // Priority 2: Look up signer from signerMap by address
+        const address = utxo.scriptPubKey?.address;
+        if (address && this.signerMap.has(address)) {
+            const signer = this.signerMap.get(address);
+            if (signer) {
+                this.inputSignerMap.set(inputIndex, signer);
+                return;
+            }
+        }
+
+        // Fallback: Use default signer (no entry in inputSignerMap)
+    }
+
+    /**
+     * Get the x-only public key for a specific input's signer.
+     * Used for taproot inputs in address rotation mode.
+     * @param inputIndex - The index of the input
+     */
+    protected internalPubKeyToXOnlyForInput(inputIndex: number): Buffer {
+        const signer = this.getSignerForInput(inputIndex);
+        return toXOnly(Buffer.from(signer.publicKey));
+    }
+
+    /**
+     * Get the tweaked signer for a specific input.
+     * Caches the result for efficiency.
+     * @param inputIndex - The index of the input
+     * @param useTweakedHash - Whether to use the tweaked hash
+     */
+    protected getTweakedSignerForInput(
+        inputIndex: number,
+        useTweakedHash: boolean = false,
+    ): ECPairInterface | undefined {
+        if (!this.addressRotationEnabled) {
+            // Fall back to original behavior
+            if (useTweakedHash) {
+                this.tweakSigner();
+                return this.tweakedSigner;
+            }
+            return this.getTweakedSigner(useTweakedHash);
+        }
+
+        // Check cache
+        const cacheKey = inputIndex * 2 + (useTweakedHash ? 1 : 0);
+        if (this.tweakedSignerCache.has(cacheKey)) {
+            return this.tweakedSignerCache.get(cacheKey);
+        }
+
+        const signer = this.getSignerForInput(inputIndex);
+        const tweaked = this.getTweakedSigner(useTweakedHash, signer);
+        this.tweakedSignerCache.set(cacheKey, tweaked);
+
+        return tweaked;
+    }
+
     protected generateTapData(): P2TRPayment {
         return {
             internalPubkey: this.internalPubKeyToXOnly(),
@@ -567,7 +696,9 @@ export abstract class TweakedTransaction extends Logger {
                     const input = batch[j];
 
                     try {
-                        promises.push(this.signInput(transaction, input, index, this.signer));
+                        // Use per-input signer in address rotation mode
+                        const inputSigner = this.getSignerForInput(index);
+                        promises.push(this.signInput(transaction, input, index, inputSigner));
                     } catch (e) {
                         this.log(`Failed to sign input ${index}: ${(e as Error).stack}`);
                     }
@@ -696,15 +827,24 @@ export abstract class TweakedTransaction extends Logger {
         return;
     }
 
-    protected generateP2SHP2PKHRedeemScript(inputAddr: string):
+    protected generateP2SHP2PKHRedeemScript(
+        inputAddr: string,
+        inputIndex?: number,
+    ):
         | {
               redeemScript: Buffer;
               outputScript: Buffer;
           }
         | undefined {
-        const pubkey = Buffer.isBuffer(this.signer.publicKey)
-            ? this.signer.publicKey
-            : Buffer.from(this.signer.publicKey, 'hex');
+        // Use per-input signer in address rotation mode
+        const signer =
+            this.addressRotationEnabled && inputIndex !== undefined
+                ? this.getSignerForInput(inputIndex)
+                : this.signer;
+
+        const pubkey = Buffer.isBuffer(signer.publicKey)
+            ? signer.publicKey
+            : Buffer.from(signer.publicKey, 'hex');
 
         const w = payments.p2wpkh({
             pubkey: pubkey,
@@ -798,7 +938,10 @@ export abstract class TweakedTransaction extends Logger {
                     );
                 }
 
-                const legacyScripts = this.generateP2SHP2PKHRedeemScript(utxo.scriptPubKey.address);
+                const legacyScripts = this.generateP2SHP2PKHRedeemScript(
+                    utxo.scriptPubKey.address,
+                    i,
+                );
                 if (!legacyScripts) {
                     throw new Error('Missing redeemScript for P2SH UTXO and unable to regenerate');
                 }
@@ -853,9 +996,13 @@ export abstract class TweakedTransaction extends Logger {
                 if (inputSign) input.sighashType = inputSign;
             }
 
-            // Taproot internal key
-            this.tweakSigner();
-            input.tapInternalKey = this.internalPubKeyToXOnly();
+            // Taproot internal key - use per-input signer in address rotation mode
+            if (this.addressRotationEnabled) {
+                input.tapInternalKey = this.internalPubKeyToXOnlyForInput(i);
+            } else {
+                this.tweakSigner();
+                input.tapInternalKey = this.internalPubKeyToXOnly();
+            }
         }
 
         // Handle P2A (Any SegWit version, future versions)

package/src/utxo/interfaces/IUTXO.ts

@@ -1,4 +1,5 @@
 import { ScriptPubKey } from '@btc-vision/bitcoin-rpc';
+import { RotationSigner } from '../../signer/AddressRotation.js';
 
 export interface UTXO {
     readonly transactionId: string;
@@ -9,6 +10,13 @@ export interface UTXO {
     redeemScript?: string | Buffer;
     witnessScript?: string | Buffer;
     nonWitnessUtxo?: string | Buffer;
+
+    /**
+     * Optional signer for this specific UTXO.
+     * Used in address rotation mode where each UTXO may have its own signer.
+     * If not provided, the signer will be resolved from the signerMap or the default signer.
+     */
+    signer?: RotationSigner;
 }
 
 export interface FetchUTXOParams {