@arkade-os/sdk 0.4.26 → 0.4.27

package/dist/esm/wallet/wallet.js

@@ -10,12 +10,11 @@ import { RestArkProvider, } from "../providers/ark.js";
 import { buildForfeitTx } from "../forfeit.js";
 import { validateConnectorsTxGraph, validateVtxoTxGraph, } from "../tree/validation.js";
 import { validateBatchRecipients } from "./validation.js";
-import { isBatchSignable } from "../identity/index.js";
 import { DEFAULT_ARKADE_SERVER_URL, isExpired, isRecoverable, isSpendable, isSubdust, TxType, } from "./index.js";
 import { createAssetPacket, selectCoinsWithAsset, selectedCoinsToAssetInputs, } from "./asset.js";
 import { VtxoScript } from "../script/base.js";
 import { CSVMultisigTapscript } from "../script/tapscript.js";
-import { buildOffchainTx, combineTapscriptSigs, hasBoardingTxExpired, isValidArkAddress, } from "../utils/arkTransaction.js";
+import { buildOffchainTx, hasBoardingTxExpired, isValidArkAddress, } from "../utils/arkTransaction.js";
 import { DEFAULT_RENEWAL_CONFIG, DEFAULT_SETTLEMENT_CONFIG, VtxoManager, } from "./vtxo-manager.js";
 import { ArkNote } from "../arknote/index.js";
 import { Intent } from "../intent/index.js";
@@ -35,7 +34,32 @@ import { contractHandlers } from "../contracts/handlers/index.js";
 import { timelockToSequence } from "../utils/timelock.js";
 import { clearSyncCursor, updateWalletState } from "../utils/syncCursors.js";
 import { validateVtxosForScript, saveVtxosForContract, } from "../contracts/vtxoOwnership.js";
+import { WalletReceiveRotator } from "./walletReceiveRotator.js";
+import { InputSignerRouter } from "./inputSignerRouter.js";
+import { DescriptorSigningProviderMissingError, MissingSigningDescriptorError, } from "./signingErrors.js";
 export const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || DEFAULT_ARKADE_SERVER_URL;
+// Build per-input jobs for an intent proof. Index 0 of the proof is a
+// synthetic BIP-322 toSpend reference whose witnessUtxo.script mirrors
+// coin[0]'s pkScript, so we map it to the same source contract as
+// coin[0]; coins 0..N-1 then map to proof inputs 1..N.
+function intentProofJobs(coins) {
+    if (coins.length === 0)
+        return [];
+    const coinJobs = coins.map((coin, i) => ({
+        index: i + 1,
+        lookupScript: VtxoScript.decode(coin.tapTree).pkScript,
+    }));
+    return [{ index: 0, lookupScript: coinJobs[0].lookupScript }, ...coinJobs];
+}
+// Built-in ArkProvider implementations (Rest/Expo) expose `serverUrl`,
+// but the interface itself does not declare a URL accessor — so this is a
+// structural read that returns undefined for custom implementations.
+function extractArkProviderUrl(provider) {
+    const serverUrl = provider.serverUrl;
+    return typeof serverUrl === "string" && serverUrl.length > 0
+        ? serverUrl
+        : undefined;
+}
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
 // Kept so existing wallets can still discover and spend VTXOs sent to the
 // legacy address after arkd starts advertising a different delay.
@@ -67,6 +91,7 @@ function hasToReadonly(identity) {
         "toReadonly" in identity &&
         typeof identity.toReadonly === "function");
 }
+export { DescriptorSigningProviderMissingError, MissingSigningDescriptorError };
 export class ReadonlyWallet {
     get assetManager() {
         return this._assetManager;
@@ -77,7 +102,6 @@ export class ReadonlyWallet {
         this.onchainProvider = onchainProvider;
         this.indexerProvider = indexerProvider;
         this.arkServerPublicKey = arkServerPublicKey;
-        this.offchainTapscript = offchainTapscript;
         this.boardingTapscript = boardingTapscript;
         this.dustAmount = dustAmount;
         this.walletRepository = walletRepository;
@@ -102,6 +126,7 @@ export class ReadonlyWallet {
                     `Create identity with { isMainnet: ${serverIsMainnet} } to match.`);
             }
         }
+        this._offchainTapscript = offchainTapscript;
         this.watcherConfig = watcherConfig;
         this._assetManager = new ReadonlyAssetManager(this.indexerProvider);
         // Defensive for direct-construction callers; setupWalletConfig already
@@ -114,25 +139,45 @@ export class ReadonlyWallet {
                         DefaultVtxo.Script.DEFAULT_TIMELOCK,
                 ];
     }
+    /**
+     * Currently-active receive tapscript. Read-only from the outside;
+     * mutated only via {@link Wallet.setOffchainTapscriptForRotation}
+     * by {@link WalletReceiveRotator.rotate}.
+     */
+    get offchainTapscript() {
+        return this._offchainTapscript;
+    }
     /**
      * Protected helper to set up shared wallet configuration.
      * Extracts common logic used by both ReadonlyWallet.create() and Wallet.create().
      */
     static async setupWalletConfig(config, pubKey) {
+        const arkadeServerUrl = getArkadeServerUrl(config);
         // Use provided arkProvider instance or create a new one from arkServerUrl
-        const arkProvider = config.arkProvider ||
-            (() => {
-                return new RestArkProvider(getArkadeServerUrl(config));
-            })();
-        // Extract arkServerUrl from provider if not explicitly provided
-        const arkServerUrl = config.arkServerUrl || arkProvider.serverUrl;
-        if (!arkServerUrl) {
-            throw new Error("Could not determine arkServerUrl from provider");
-        }
-        // Use provided indexerProvider instance or create a new one
-        // indexerUrl defaults to arkServerUrl if not provided
-        const indexerUrl = config.indexerUrl || arkServerUrl;
-        const indexerProvider = config.indexerProvider || new RestIndexerProvider(indexerUrl);
+        const arkProvider = config.arkProvider ?? new RestArkProvider(arkadeServerUrl);
+        // Resolve the indexer provider. If a full instance is supplied, use it
+        // directly. Otherwise pick a URL with priority:
+        //   1. explicit config.indexerUrl
+        //   2. URL derived from the injected arkProvider (so a custom
+        //      arkProvider does not silently pair with the public default)
+        //   3. arkadeServerUrl (only when no custom arkProvider was injected)
+        let indexerProvider = config.indexerProvider;
+        if (!indexerProvider) {
+            let indexerUrl = config.indexerUrl;
+            if (!indexerUrl) {
+                if (config.arkProvider) {
+                    const derived = extractArkProviderUrl(config.arkProvider);
+                    if (!derived) {
+                        throw new Error("indexerUrl is required when arkProvider is provided without a discoverable serverUrl");
+                    }
+                    indexerUrl = derived;
+                }
+                else {
+                    indexerUrl = arkadeServerUrl;
+                }
+            }
+            indexerProvider = new RestIndexerProvider(indexerUrl);
+        }
         const info = await arkProvider.getInfo();
         const network = getNetwork(info.network);
         // Guard: detect identity/server network mismatch for seed-based identities.
@@ -642,13 +687,28 @@ export class ReadonlyWallet {
             walletRepository: this.walletRepository,
             watcherConfig: this.watcherConfig,
         });
+        // Register the wallet's baseline always-active contracts: every
+        // `walletContractTimelocks` entry × {default, delegate-if-enabled}.
+        // This matrix is bound to INDEX 0 — the identity's x-only pubkey
+        // — by design: it's the permanent fallback set the wallet wants
+        // active forever, independent of any HD rotation. Rotated
+        // display contracts (registered separately by
+        // {@link WalletReceiveRotator.rotate}) are intentionally
+        // single-timelock-single-pubkey at the CURRENT arkd delay, and
+        // get the `metadata.source = WALLET_RECEIVE_SOURCE` tag so the
+        // next boot can find them. We deliberately do NOT re-register
+        // the matrix at a rotated pubkey: doing so would dilute the
+        // "index-0 baseline" guarantee and turn every rotation into a
+        // multi-timelock matrix expansion on every boot.
+        const baselinePubkey = await this.identity.xOnlyPublicKey();
         for (const csvTimelock of this.walletContractTimelocks) {
             const csvTimelockStr = timelockToSequence(csvTimelock).toString();
             const defaultScript = new DefaultVtxo.Script({
-                pubKey: this.offchainTapscript.options.pubKey,
+                pubKey: baselinePubkey,
                 serverPubKey: this.offchainTapscript.options.serverPubKey,
                 csvTimelock,
             });
+            const defaultScriptHex = hex.encode(defaultScript.pkScript);
             await manager.createContract({
                 type: "default",
                 params: {
@@ -656,7 +716,7 @@ export class ReadonlyWallet {
                     serverPubKey: hex.encode(defaultScript.options.serverPubKey),
                     csvTimelock: csvTimelockStr,
                 },
-                script: hex.encode(defaultScript.pkScript),
+                script: defaultScriptHex,
                 address: defaultScript
                     .address(this.network.hrp, this.arkServerPublicKey)
                     .encode(),
@@ -664,11 +724,12 @@ export class ReadonlyWallet {
             });
             if (this.offchainTapscript instanceof DelegateVtxo.Script) {
                 const delegateScript = new DelegateVtxo.Script({
-                    pubKey: this.offchainTapscript.options.pubKey,
+                    pubKey: baselinePubkey,
                     serverPubKey: this.offchainTapscript.options.serverPubKey,
                     delegatePubKey: this.offchainTapscript.options.delegatePubKey,
                     csvTimelock,
                 });
+                const delegateScriptHex = hex.encode(delegateScript.pkScript);
                 await manager.createContract({
                     type: "delegate",
                     params: {
@@ -677,7 +738,7 @@ export class ReadonlyWallet {
                         delegatePubKey: hex.encode(delegateScript.options.delegatePubKey),
                         csvTimelock: csvTimelockStr,
                     },
-                    script: hex.encode(delegateScript.pkScript),
+                    script: delegateScriptHex,
                     address: delegateScript
                         .address(this.network.hrp, this.arkServerPublicKey)
                         .encode(),
@@ -736,6 +797,15 @@ export class ReadonlyWallet {
  * ```
  */
 export class Wallet extends ReadonlyWallet {
+    /**
+     * @internal Sole write path for `offchainTapscript` after construction.
+     * Called by {@link WalletReceiveRotator.rotate} once the rotated
+     * display contract has been persisted. External code must treat
+     * `offchainTapscript` as read-only.
+     */
+    setOffchainTapscriptForRotation(tapscript) {
+        this._offchainTapscript = tapscript;
+    }
     _addPendingSpends(inputs) {
         for (const input of inputs) {
             if ("virtualStatus" in input) {
@@ -766,12 +836,13 @@ export class Wallet extends ReadonlyWallet {
     }
     constructor(identity, network, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, 
     /** @deprecated Use settlementConfig */
-    renewalConfig, delegatorProvider, watcherConfig, settlementConfig, walletContractTimelocks) {
+    renewalConfig, delegatorProvider, watcherConfig, settlementConfig, walletContractTimelocks, receiveRotator, descriptorProvider) {
         super(identity, network, onchainProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, dustAmount, walletRepository, contractRepository, delegatorProvider, watcherConfig, walletContractTimelocks);
         this.arkProvider = arkProvider;
         this.serverUnrollScript = serverUnrollScript;
         this.forfeitOutputScript = forfeitOutputScript;
         this.forfeitPubkey = forfeitPubkey;
+        this._receiveRotatorInstalled = false;
         /**
          * Async mutex that serializes all operations submitting VTXOs to the Arkade
          * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
@@ -808,6 +879,14 @@ export class Wallet extends ReadonlyWallet {
         this._delegatorManager = delegatorProvider
             ? new DelegatorManagerImpl(delegatorProvider, arkProvider, identity)
             : undefined;
+        this._receiveRotator = receiveRotator;
+        this._descriptorProvider = descriptorProvider;
+        this._signerRouter = new InputSignerRouter({
+            identity,
+            contractRepository,
+            descriptorProvider,
+            boardingPkScript: boardingTapscript.pkScript,
+        });
     }
     get assetManager() {
         this._walletAssetManager ?? (this._walletAssetManager = new AssetManager(this));
@@ -823,18 +902,48 @@ export class Wallet extends ReadonlyWallet {
         this._vtxoManagerInitializing = Promise.resolve(new VtxoManager(this, this.renewalConfig, this.settlementConfig));
         try {
             const manager = await this._vtxoManagerInitializing;
+            // First-time hookup of the HD rotator: subscribe to
+            // `vtxo_received` AFTER the contract manager (which is
+            // initialised inside the VtxoManager construction path) has
+            // registered the wallet's baseline contracts. The flag
+            // makes this idempotent across repeated `getVtxoManager`
+            // calls — install runs at most once per wallet instance.
+            // Cache the manager and flip the install flag only after
+            // `install()` resolves; otherwise a failing install would
+            // leave the manager cached and silently disable HD
+            // rotation for the lifetime of this wallet.
+            if (this._receiveRotator && !this._receiveRotatorInstalled) {
+                try {
+                    await this._receiveRotator.install(this);
+                }
+                catch (installErr) {
+                    await manager.dispose();
+                    throw installErr;
+                }
+                this._receiveRotatorInstalled = true;
+            }
             this._vtxoManager = manager;
             return manager;
         }
-        catch (error) {
-            this._vtxoManagerInitializing = undefined;
-            throw error;
-        }
         finally {
             this._vtxoManagerInitializing = undefined;
         }
     }
     async dispose() {
+        // Tear down the rotation subscription + drain in-flight rotations
+        // first so no late `vtxo_received` event can queue work on a
+        // disposing wallet, and so any in-flight `createContract` call
+        // finishes before we dispose the contract manager underneath it.
+        // A rotator-disposal failure must not abort the rest of
+        // teardown — the contract manager / super still need to run on
+        // best-effort, so we capture and rethrow at the end.
+        let rotatorError;
+        try {
+            await this._receiveRotator?.dispose();
+        }
+        catch (error) {
+            rotatorError = error;
+        }
         const manager = this._vtxoManager ??
             (this._vtxoManagerInitializing
                 ? await this._vtxoManagerInitializing.catch(() => undefined)
@@ -852,6 +961,9 @@ export class Wallet extends ReadonlyWallet {
             this._vtxoManagerInitializing = undefined;
             await super.dispose();
         }
+        if (rotatorError) {
+            throw rotatorError;
+        }
     }
     /**
      * Create a full wallet and initialize its background managers.
@@ -887,7 +999,14 @@ export class Wallet extends ReadonlyWallet {
         const forfeitPubkey = hex.decode(setup.info.forfeitPubkey).slice(1);
         const forfeitAddress = Address(setup.network).decode(setup.info.forfeitAddress);
         const forfeitOutputScript = OutScript.encode(forfeitAddress);
-        const wallet = new Wallet(config.identity, setup.network, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig, config.settlementConfig, setup.walletContractTimelocks);
+        // HD wiring (boot path) — resolved via the descriptor provider.
+        // The rotator (when present) is handed to the constructor as
+        // the last positional arg and `getVtxoManager()` lazily
+        // installs its `vtxo_received` subscription on first call,
+        // after the contract manager has registered the wallet's
+        // baseline contracts.
+        const boot = await WalletReceiveRotator.resolveBoot(config, setup);
+        const wallet = new Wallet(config.identity, setup.network, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, boot?.offchainTapscript ?? setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig, config.settlementConfig, setup.walletContractTimelocks, boot?.rotator, boot?.provider);
         await wallet.getVtxoManager();
         return wallet;
     }
@@ -934,6 +1053,14 @@ export class Wallet extends ReadonlyWallet {
         }
         if (params.selectedVtxos && params.selectedVtxos.length > 0) {
             return this._withTxLock(async () => {
+                // Snapshot the active receive tapscript synchronously
+                // before any `await` so the change output's pkScript and
+                // the change-VTXO metadata written later by
+                // `updateDbAfterOffchainTx` are bound to the same
+                // tapscript even if `WalletReceiveRotator.rotate` fires
+                // during the offchain round-trip.
+                const offchainTapscript = this.offchainTapscript;
+                const arkAddress = offchainTapscript.address(this.network.hrp, this.arkServerPublicKey);
                 const selectedVtxoSum = params
                     .selectedVtxos.map((v) => v.value)
                     .reduce((a, b) => a + b, 0);
@@ -958,8 +1085,8 @@ export class Wallet extends ReadonlyWallet {
                 // add change output if needed
                 if (selected.changeAmount > 0n) {
                     const changeOutputScript = selected.changeAmount < this.dustAmount
-                        ? this.arkAddress.subdustPkScript
-                        : this.arkAddress.pkScript;
+                        ? arkAddress.subdustPkScript
+                        : arkAddress.pkScript;
                     outputs.push({
                         script: changeOutputScript,
                         amount: BigInt(selected.changeAmount),
@@ -968,7 +1095,7 @@ export class Wallet extends ReadonlyWallet {
                 this._addPendingSpends(selected.inputs);
                 try {
                     const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selected.inputs, outputs);
-                    await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0);
+                    await this.updateDbAfterOffchainTx(selected.inputs, arkTxid, signedCheckpointTxs, params.amount, selected.changeAmount, selected.changeAmount > 0n ? outputs.length - 1 : 0, offchainTapscript);
                     return arkTxid;
                 }
                 finally {
@@ -1238,9 +1365,11 @@ export class Wallet extends ReadonlyWallet {
                     settlementPsbt.updateInput(i, {
                         tapLeafScript: [input.forfeitTapLeafScript],
                     });
-                    settlementPsbt = await this.identity.sign(settlementPsbt, [
-                        i,
-                    ]);
+                    const script = settlementPsbt.getInput(i).witnessUtxo?.script;
+                    if (!script) {
+                        throw new Error("The server returned incomplete data. Settlement input is missing witnessUtxo.script");
+                    }
+                    settlementPsbt = await this._signerRouter.sign(settlementPsbt, [{ index: i, lookupScript: script }]);
                     hasBoardingUtxos = true;
                     break;
                 }
@@ -1289,7 +1418,12 @@ export class Wallet extends ReadonlyWallet {
                 },
             ], forfeitOutputScript);
             // do not sign the connector input
-            forfeitTx = await this.identity.sign(forfeitTx, [0]);
+            forfeitTx = await this._signerRouter.sign(forfeitTx, [
+                {
+                    index: 0,
+                    lookupScript: VtxoScript.decode(input.tapTree).pkScript,
+                },
+            ]);
             signedForfeits.push(base64.encode(forfeitTx.toPSBT()));
         }
         if (signedForfeits.length > 0 || hasBoardingUtxos) {
@@ -1392,6 +1526,22 @@ export class Wallet extends ReadonlyWallet {
             },
         };
     }
+    /**
+     * Build {@link InputSigningJob}s for a tx whose signable inputs can be
+     * resolved from their own `witnessUtxo.script`. Inputs without a
+     * `witnessUtxo` are silently omitted, mirroring the wallet's
+     * historical silent-skip behaviour for cosigner/connector inputs.
+     */
+    inputSigningJobsFromWitnessUtxos(tx, indexes) {
+        const candidateIndexes = indexes ?? Array.from({ length: tx.inputsLength }, (_, i) => i);
+        const jobs = [];
+        for (const index of candidateIndexes) {
+            const script = tx.getInput(index).witnessUtxo?.script;
+            if (script)
+                jobs.push({ index, lookupScript: script });
+        }
+        return jobs;
+    }
     async safeRegisterIntent(intent, inputs) {
         try {
             return await this.arkProvider.registerIntent(intent);
@@ -1424,7 +1574,7 @@ export class Wallet extends ReadonlyWallet {
             cosigners_public_keys: cosignerPubKeys,
         };
         const proof = Intent.create(message, coins, outputs);
-        const signedProof = await this.identity.sign(proof);
+        const signedProof = await this._signerRouter.sign(proof, intentProofJobs(coins));
         return {
             proof: base64.encode(signedProof.toPSBT()),
             message,
@@ -1436,7 +1586,7 @@ export class Wallet extends ReadonlyWallet {
             expire_at: 0,
         };
         const proof = Intent.create(message, coins, []);
-        const signedProof = await this.identity.sign(proof);
+        const signedProof = await this._signerRouter.sign(proof, intentProofJobs(coins));
         return {
             proof: base64.encode(signedProof.toPSBT()),
             message,
@@ -1448,7 +1598,7 @@ export class Wallet extends ReadonlyWallet {
             expire_at: 0,
         };
         const proof = Intent.create(message, coins, []);
-        const signedProof = await this.identity.sign(proof);
+        const signedProof = await this._signerRouter.sign(proof, intentProofJobs(coins));
         return {
             proof: base64.encode(signedProof.toPSBT()),
             message,
@@ -1513,7 +1663,7 @@ export class Wallet extends ReadonlyWallet {
                 try {
                     const finalCheckpoints = await Promise.all(pendingTx.signedCheckpointTxs.map(async (c) => {
                         const tx = Transaction.fromPSBT(base64.decode(c));
-                        const signedCheckpoint = await this.identity.sign(tx);
+                        const signedCheckpoint = await this._signerRouter.sign(tx, this.inputSigningJobsFromWitnessUtxos(tx));
                         return base64.encode(signedCheckpoint.toPSBT());
                     }));
                     await this.arkProvider.finalizeTx(pendingTx.arkTxid, finalCheckpoints);
@@ -1573,10 +1723,19 @@ export class Wallet extends ReadonlyWallet {
         if (args.length === 0) {
             throw new Error("At least one receiver is required");
         }
+        // Snapshot the active receive tapscript synchronously before any
+        // `await`. `WalletReceiveRotator.rotate` mutates
+        // `this.offchainTapscript` without acquiring `_txLock`, so any
+        // yield between here and `updateDbAfterOffchainTx` opens a window
+        // where the change-output pkScript (built from `outputAddress`
+        // below) and the change-VTXO metadata (built from the snapshot
+        // inside `updateDbAfterOffchainTx`) could come from different
+        // tapscripts. Threading the snapshot pins both reads.
+        const offchainTapscript = this.offchainTapscript;
+        const outputAddress = offchainTapscript.address(this.network.hrp, this.arkServerPublicKey);
+        const address = outputAddress.encode();
         // validate recipients and populate undefined amount with dust amount
         const recipients = validateRecipients(args, Number(this.dustAmount));
-        const address = await this.getAddress();
-        const outputAddress = ArkAddress.decode(address);
         const virtualCoins = await this.getVtxos({
             withRecoverable: false,
         });
@@ -1707,7 +1866,7 @@ export class Wallet extends ReadonlyWallet {
         this._addPendingSpends(selectedCoins);
         try {
             const { arkTxid, signedCheckpointTxs } = await this.buildAndSubmitOffchainTx(selectedCoins, outputs);
-            await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, changeReceiver?.assets);
+            await this.updateDbAfterOffchainTx(selectedCoins, arkTxid, signedCheckpointTxs, sentAmount, BigInt(changeAmount), changeReceiver ? changeIndex : 0, offchainTapscript, changeReceiver?.assets);
             return arkTxid;
         }
         finally {
@@ -1726,47 +1885,25 @@ export class Wallet extends ReadonlyWallet {
                 tapLeafScript: input.forfeitTapLeafScript,
             };
         }), outputs, this.serverUnrollScript);
-        let signedVirtualTx;
-        let userSignedCheckpoints;
-        if (isBatchSignable(this.identity)) {
-            // Batch-sign arkTx + all checkpoints in one wallet popup.
-            // Clone so the provider can't mutate originals before submitTx.
-            const requests = [
-                { tx: offchainTx.arkTx.clone() },
-                ...offchainTx.checkpoints.map((c) => ({ tx: c.clone() })),
-            ];
-            const signed = await this.identity.signMultiple(requests);
-            if (signed.length !== requests.length) {
-                throw new Error(`signMultiple returned ${signed.length} transactions, expected ${requests.length}`);
-            }
-            const [firstSignedTx, ...signedCheckpoints] = signed;
-            signedVirtualTx = firstSignedTx;
-            userSignedCheckpoints = signedCheckpoints;
-        }
-        else {
-            signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
-        }
+        // arkTx inputs spend checkpoint outputs, so each input's
+        // `witnessUtxo.script` is the checkpoint pkScript — not the
+        // source VTXO contract's pkScript. Build the routing jobs from
+        // the source VTXO scripts (positionally aligned to `inputs[i]`)
+        // so the router can resolve each input's owning contract.
+        const arkTxJobs = inputs.map((input, index) => ({
+            index,
+            lookupScript: VtxoScript.decode(input.tapTree).pkScript,
+        }));
+        const signedVirtualTx = await this._signerRouter.sign(offchainTx.arkTx, arkTxJobs);
         // Mark pending before submitting — if we crash between submit and
         // finalize, the next init will recover via finalizePendingTxs.
         await this.setPendingTxFlag(true);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base64.encode(c.toPSBT())));
-        let finalCheckpoints;
-        if (userSignedCheckpoints) {
-            // Merge pre-signed user signatures onto server-signed checkpoints
-            finalCheckpoints = signedCheckpointTxs.map((c, i) => {
-                const serverSigned = Transaction.fromPSBT(base64.decode(c));
-                combineTapscriptSigs(userSignedCheckpoints[i], serverSigned);
-                return base64.encode(serverSigned.toPSBT());
-            });
-        }
-        else {
-            // Legacy: sign each checkpoint individually (N popups)
-            finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
-                const tx = Transaction.fromPSBT(base64.decode(c));
-                const signedCheckpoint = await this.identity.sign(tx);
-                return base64.encode(signedCheckpoint.toPSBT());
-            }));
-        }
+        const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
+            const tx = Transaction.fromPSBT(base64.decode(c));
+            const signedCheckpoint = await this._signerRouter.sign(tx, this.inputSigningJobsFromWitnessUtxos(tx));
+            return base64.encode(signedCheckpoint.toPSBT());
+        }));
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
         try {
             await this.setPendingTxFlag(false);
@@ -1776,8 +1913,17 @@ export class Wallet extends ReadonlyWallet {
         }
         return { arkTxid, signedCheckpointTxs };
     }
-    // mark virtual outputs as spent, save change outputs if any
-    async updateDbAfterOffchainTx(inputs, arkTxid, signedCheckpointTxs, sentAmount, changeAmount, changeVout, changeAssets) {
+    // mark virtual outputs as spent, save change outputs if any.
+    // `offchainTapscript` is the snapshot the caller captured under
+    // `_txLock` before any `await`; deriving both the change-VTXO
+    // metadata and `primaryAddress` from it here guarantees the local
+    // record matches the pkScript the server saw on the inbound
+    // transaction, even if `WalletReceiveRotator.rotate` swaps
+    // `this.offchainTapscript` mid-flight.
+    async updateDbAfterOffchainTx(inputs, arkTxid, signedCheckpointTxs, sentAmount, changeAmount, changeVout, offchainTapscript, changeAssets) {
+        const primaryAddress = offchainTapscript
+            .address(this.network.hrp, this.arkServerPublicKey)
+            .encode();
         try {
             const spentVtxos = [];
             const commitmentTxIds = new Set();
@@ -1824,7 +1970,6 @@ export class Wallet extends ReadonlyWallet {
                 }
             }
             const createdAt = Date.now();
-            const primaryAddr = this.arkAddress.encode();
             // Only save a change virtual output for preconfirmed coins (those with a batchExpiry).
             // Inputs without a batchExpiry are already settled/unrolled and don't need tracking.
             let changeVtxo;
@@ -1833,11 +1978,11 @@ export class Wallet extends ReadonlyWallet {
                     txid: arkTxid,
                     vout: changeVout,
                     createdAt: new Date(createdAt),
-                    forfeitTapLeafScript: this.offchainTapscript.forfeit(),
-                    intentTapLeafScript: this.offchainTapscript.forfeit(),
+                    forfeitTapLeafScript: offchainTapscript.forfeit(),
+                    intentTapLeafScript: offchainTapscript.forfeit(),
                     isUnrolled: false,
                     isSpent: false,
-                    tapTree: this.offchainTapscript.encode(),
+                    tapTree: offchainTapscript.encode(),
                     value: Number(changeAmount),
                     virtualStatus: {
                         state: "preconfirmed",
@@ -1848,7 +1993,7 @@ export class Wallet extends ReadonlyWallet {
                         confirmed: false,
                     },
                     assets: changeAssets,
-                    script: hex.encode(this.offchainTapscript.pkScript),
+                    script: hex.encode(offchainTapscript.pkScript),
                 };
             }
             // Route spent rows to their owning contract bucket. The wallet's
@@ -1879,9 +2024,9 @@ export class Wallet extends ReadonlyWallet {
             }
             // Change is always primary-script by construction.
             if (changeVtxo) {
-                await saveVtxosForContract(this.walletRepository, { script: changeVtxo.script, address: primaryAddr }, [changeVtxo]);
+                await saveVtxosForContract(this.walletRepository, { script: changeVtxo.script, address: primaryAddress }, [changeVtxo]);
             }
-            await this.walletRepository.saveTransactions(primaryAddr, [
+            await this.walletRepository.saveTransactions(primaryAddress, [
                 {
                     key: {
                         boardingTxid: "",