@hyperlane-xyz/sdk 41.3.1 → 42.0.0

package/dist/token/EvmWarpModule.js

@@ -13,16 +13,20 @@ import { EvmTokenFeeModule } from '../fee/EvmTokenFeeModule.js';
 import { mergeCrossCollateralRouters } from '../fee/crossCollateralUtils.js';
 import { TokenFeeType } from '../fee/types.js';
 import { getEvmHookUpdateTransactions } from '../hook/updates.js';
-import { stripPredicateSubHook } from '../hook/utils.js';
-import { OnchainHookType } from '../hook/types.js';
+import { collectHybridHookNodes, resolveHybridHookNodesToAddress, stripPredicateSubHook, } from '../hook/utils.js';
+import { HookType, OnchainHookType, } from '../hook/types.js';
 import { EvmIsmModule } from '../ism/EvmIsmModule.js';
+import { EvmIsmReader } from '../ism/EvmIsmReader.js';
+import { HyperlaneIsmFactory } from '../ism/HyperlaneIsmFactory.js';
+import { moduleMatchesConfig } from '../ism/utils.js';
 import { PredicateWrapperDeployer } from '../predicate/PredicateDeployer.js';
 import { resolveRouterMapConfig } from '../router/types.js';
 import { CANCELLER_ROLE, EXECUTOR_ROLE, PROPOSER_ROLE, TIMELOCK_ADMIN_ROLE, } from '../timelock/evm/constants.js';
 import { isDeterministicTimelockReadError } from '../timelock/evm/errors.js';
+import { planChainHybrid, } from '../deploy/warpHybridPlan.js';
 import { scalesEqual } from '../utils/decimals.js';
 import { IsmType } from '../ism/types.js';
-import { extractIsmAndHookFactoryAddresses, ismTreeContainsRateLimited, setRateLimitedIsmRecipient, } from '../utils/ism.js';
+import { DelayedFlowRemoteIsmsSourceType, collectHybridIsmNodes, completeHybridIsmNodes, extractIsmAndHookFactoryAddresses, ismTreeContainsHybridHookIsm, ismTreeContainsRateLimited, normalizeConfig, resolveHybridIsmNodesToAddress, setRateLimitedIsmRecipient, } from '../utils/ism.js';
 import { CCTP_PPM_STORAGE_VERSION, EvmWarpRouteReader, } from './EvmWarpRouteReader.js';
 import { EvmXERC20Module } from './EvmXERC20Module.js';
 import { TokenType } from './config.js';
@@ -198,7 +202,7 @@ export class EvmWarpModule extends HyperlaneModule {
         return deployedTimelockByConfig;
     }
     /**
-     * Updates the Warp Route contract with the provided configuration.
+     * Plans a Warp Route update as per-chain transaction groups.
      *
      * IMPORTANT — irreversible side effects when expectedConfig includes `predicateWrapper`:
      * The PredicateRouterWrapper contract is deployed on-chain during planning (before this
@@ -213,11 +217,21 @@ export class EvmWarpModule extends HyperlaneModule {
      * transaction plan can still leave an untracked timelock deployment.
      *
      * @param expectedConfig - The configuration for the token router to be updated.
-     * @returns `{txs, feeTxs, ownershipTxs}` — main txs (includes router-owner `setFeeRecipient`), fee-contract-owner txs (safe to route to a dedicated feeSubmitter), and ownership/proxyAdmin txs that must execute last.
+     * Used by warp apply to assemble one ordered batch for this chain.
      */
-    async updateSplit(expectedConfig, tokenReaderParams) {
+    async updatePhases(expectedConfig, tokenReaderParams) {
         HypTokenRouterConfigSchema.parse(expectedConfig);
         const actualConfig = await this.read();
+        const hybridPlan = this.planHybridUpdate(actualConfig, expectedConfig);
+        const actualHasDelayedFlowRouter = (typeof actualConfig.hook === 'object' &&
+            collectHybridHookNodes(actualConfig.hook).some(({ type }) => type === HookType.DELAYED_FLOW_ROUTER)) ||
+            (typeof actualConfig.interchainSecurityModule === 'object' &&
+                collectHybridIsmNodes(actualConfig.interchainSecurityModule).some(({ type }) => type === IsmType.DELAYED_FLOW_ROUTER));
+        const targetHasDelayedFlowRouter = (typeof expectedConfig.hook === 'object' &&
+            collectHybridHookNodes(expectedConfig.hook).some(({ type }) => type === HookType.DELAYED_FLOW_ROUTER)) ||
+            (typeof expectedConfig.interchainSecurityModule === 'object' &&
+                collectHybridIsmNodes(expectedConfig.interchainSecurityModule).some(({ type }) => type === IsmType.DELAYED_FLOW_ROUTER));
+        const removesDelayedFlowRouter = actualHasDelayedFlowRouter && !targetHasDelayedFlowRouter;
         expectedConfig = await this.configWithTimelockProxyAdminOwner(actualConfig, expectedConfig);
         const transactions = [];
         let xerc20Txs = [];
@@ -243,9 +257,35 @@ export class EvmWarpModule extends HyperlaneModule {
          *    because GasRouter requires routers to be enrolled before setting destination gas
          * 3. createHookAndPredicateUpdateTxs() handles hook + predicate wrapper together so the
          *    pending new hook address is threaded through without leaking into other method signatures
+         * 4. The hook transactions are pushed BEFORE the ISM transactions, whatever the order they
+         *    are built in — see the comment at the push
          */
         const upgradeTxs = await this.upgradeWarpRouteImplementationTx(actualConfig, expectedConfig);
-        transactions.push(...upgradeTxs, ...(await this.createIsmUpdateTxs(actualConfig, expectedConfig)), ...(await this.createHookAndPredicateUpdateTxs(actualConfig, expectedConfig)), ...this.createFeeHookUpdateTxs(actualConfig, expectedConfig), ...this.createUnenrollRemoteRoutersUpdateTxs(actualConfig, expectedConfig), ...this.createEnrollRemoteRoutersUpdateTxs(actualConfig, expectedConfig), 
+        // Pure hybrid validation already ran immediately after the read. Resolve
+        // (and, when needed, deploy) the shared instance for both config trees.
+        const hybrid = await this.resolveHybridInstance(actualConfig, expectedConfig, hybridPlan);
+        // With the shared address known, both trees reference it as an ordinary
+        // address child and the existing ISM/hook modules deploy whatever parents
+        // remain. Nothing downstream needs to know a hybrid is involved.
+        const resolvedConfig = hybrid
+            ? {
+                ...expectedConfig,
+                interchainSecurityModule: resolveHybridIsmNodesToAddress(hybrid.ismTree, hybrid.address),
+                hook: resolveHybridHookNodesToAddress(hybrid.hookTree, hybrid.address),
+            }
+            : expectedConfig;
+        const ismTxs = await this.createIsmUpdateTxs(actualConfig, resolvedConfig, hybrid?.address);
+        // Built after the ISM step, which may deploy the tree, but ORDERED BEFORE
+        // it: a batch executes sequentially with no rollback, so a failure between
+        // the two installs is a state the route can be left in. Hook first leaves
+        // the previous ISM verifying inbound messages. ISM first can leave a hybrid
+        // hook/ISM gating delivery while nothing drives its postDispatch — no
+        // preverification is ever sent for the messages dispatched in that window,
+        // and none can be sent afterwards, so they are permanently undeliverable.
+        // Returned in their own buckets so callers can choose the safe order within
+        // this chain's batch, including reversing it when removing delayed flow.
+        const hookTxs = await this.createHookAndPredicateUpdateTxs(actualConfig, resolvedConfig, hybrid?.address);
+        transactions.push(...this.createFeeHookUpdateTxs(actualConfig, expectedConfig), ...this.createUnenrollRemoteRoutersUpdateTxs(actualConfig, expectedConfig), ...this.createEnrollRemoteRoutersUpdateTxs(actualConfig, expectedConfig), 
         // MC unenroll before enroll for consistency with remote routers.
         // MC enrollment must come before gas setting so that MC-only domains
         ...this.createUnenrollCrossCollateralRoutersTxs(actualConfig, expectedConfig), ...this.createEnrollCrossCollateralRoutersTxs(actualConfig, expectedConfig), ...this.createSetDestinationGasUpdateTxs(actualConfig, expectedConfig), ...this.createAddRebalancersUpdateTxs(actualConfig, expectedConfig), ...this.createRemoveRebalancersUpdateTxs(actualConfig, expectedConfig), ...(await this.createAddAllowedBridgesUpdateTxs(actualConfig, expectedConfig)), ...this.createRemoveBridgesTxs(actualConfig, expectedConfig), ...this.createAddRebalanceTargetsUpdateTxs(actualConfig, expectedConfig), ...this.createRemoveRebalanceTargetsTxs(actualConfig, expectedConfig), ...this.createSetRecipientsUpdateTxs(actualConfig, expectedConfig), ...this.createRemoveRecipientsTxs(actualConfig, expectedConfig), ...(await this.createRevokeStaleBridgeAllowancesTxs(actualConfig, expectedConfig, upgradeTxs.length > 0)), ...this.createAddRemoteOutputAssetsTxs(actualConfig, expectedConfig), ...this.createRemoveRemoteOutputAssetsTxs(actualConfig, expectedConfig), ...this.createUpdateEverclearFeeParamsTxs(actualConfig, expectedConfig), ...this.createRemoveEverclearFeeParamsTxs(actualConfig, expectedConfig), ...this.createSetMaxFeePpmTxs(actualConfig, expectedConfig), ...xerc20Txs, 
@@ -256,21 +296,173 @@ export class EvmWarpModule extends HyperlaneModule {
         // Ownership/proxyAdmin must always execute last; returned separately so callers
         // can place feeTxs between main txs and ownership (see update() below).
         const ownershipTxs = [
+            ...(hybrid?.ownershipTxs ?? []),
             ...this.createOwnershipUpdateTxs(actualConfig, expectedConfig),
             ...proxyAdminUpdateTxs(this.chainId, this.args.addresses.deployedTokenRoute, actualConfig, expectedConfig),
         ];
-        return { txs: transactions, feeTxs, ownershipTxs };
+        return {
+            upgradeTxs,
+            instanceTxs: hybrid?.instanceTxs ?? [],
+            hookTxs,
+            ismTxs,
+            txs: transactions,
+            feeTxs,
+            ownershipTxs,
+            hybridIsm: hybrid?.address,
+            removesDelayedFlowRouter,
+        };
     }
     /**
-     * Backwards-compatible wrapper around `updateSplit`. Returns a flat, ordered
-     * transaction array suitable for a single submitter.
+     * Main-compatible split: router-owner work, fee-owner work, then ownership.
      */
+    async updateSplit(expectedConfig, tokenReaderParams) {
+        const { upgradeTxs, instanceTxs, hookTxs, ismTxs, txs, feeTxs, ownershipTxs, removesDelayedFlowRouter, } = await this.updatePhases(expectedConfig, tokenReaderParams);
+        return {
+            txs: removesDelayedFlowRouter
+                ? [...upgradeTxs, ...instanceTxs, ...ismTxs, ...hookTxs, ...txs]
+                : [...upgradeTxs, ...instanceTxs, ...hookTxs, ...ismTxs, ...txs],
+            feeTxs,
+            ownershipTxs,
+        };
+    }
+    /** Returns a flat, ordered transaction array suitable for one submitter. */
     async update(expectedConfig, tokenReaderParams) {
         const { txs, feeTxs, ownershipTxs } = await this.updateSplit(expectedConfig, tokenReaderParams);
         // feeTxs (fee-contract-owner calls) must come before ownershipTxs so they
         // execute before the router owner changes.
         return [...txs, ...feeTxs, ...ownershipTxs];
     }
+    /**
+     * Validates hybrid composition and fee-hook transitions before update
+     * planning reaches any operation that may deploy a contract.
+     */
+    planHybridUpdate(actualConfig, expectedConfig) {
+        // An omitted feeHook is intentionally left unchanged by warp apply. Plan
+        // against the effective value so an already-installed ERC20 fee hook
+        // cannot bypass hybrid hook composition validation.
+        const effectiveFeeHook = expectedConfig.feeHook ?? actualConfig.feeHook;
+        const plan = planChainHybrid({
+            multiProvider: this.multiProvider,
+            chain: this.chainName,
+            config: { ...expectedConfig, feeHook: effectiveFeeHook },
+        });
+        if (!plan)
+            return undefined;
+        if (plan.node.type === IsmType.DELAYED_FLOW_ROUTER &&
+            actualConfig.feeHook &&
+            !isZeroishAddress(actualConfig.feeHook) &&
+            expectedConfig.feeHook &&
+            isZeroishAddress(expectedConfig.feeHook)) {
+            const actualHook = actualConfig.hook;
+            const expectedHook = expectedConfig.hook;
+            const installedHybrid = typeof actualHook === 'object'
+                ? collectHybridHookNodes(actualHook)[0]
+                : undefined;
+            const delayedFlowHookStaysInstalled = installedHybrid?.type === HookType.DELAYED_FLOW_ROUTER &&
+                installedHybrid.duration === plan.node.duration &&
+                installedHybrid.thresholdBps === plan.node.thresholdBps &&
+                installedHybrid.maxDelay === plan.node.maxDelay &&
+                (plan.node.warpRouter === undefined ||
+                    (!!installedHybrid.warpRouter &&
+                        eqAddress(installedHybrid.warpRouter, plan.node.warpRouter))) &&
+                typeof expectedHook === 'object' &&
+                deepEquals(normalizeConfig(resolveHybridHookNodesToAddress(actualHook, constants.AddressZero)), normalizeConfig(resolveHybridHookNodesToAddress(expectedHook, constants.AddressZero)));
+            assert(delayedFlowHookStaysInstalled, `Cannot introduce, replace, or recompose ${IsmType.DELAYED_FLOW_ROUTER} on ${this.chainName} while clearing existing feeHook ${actualConfig.feeHook} in the same warp apply. Hook installation runs before router updates, leaving the delayed-flow hook active while ERC20 fee metadata still prevents its native control dispatch. Apply feeHook address(0) without changing the hook first, execute that update, then apply the ${IsmType.DELAYED_FLOW_ROUTER} config.`);
+        }
+        return plan;
+    }
+    /**
+     * Reuses or deploys the one hybrid leaf declared on both config surfaces.
+     * Parent trees only ever receive the returned address, preventing duplicate
+     * bucket state. Instance mutations are returned separately so counterpart
+     * enrollment can precede either router-surface change in this chain's batch.
+     */
+    async resolveHybridInstance(actualConfig, expectedConfig, plan) {
+        if (!plan)
+            return undefined;
+        const completed = completeHybridIsmNodes(plan.node, this.args.addresses.deployedTokenRoute, { type: DelayedFlowRemoteIsmsSourceType.Deferred }, actualConfig.owner, this.multiProvider);
+        assert(typeof completed === 'object' &&
+            (completed.type === IsmType.NET_FLOW_RATE_LIMITED ||
+                completed.type === IsmType.DELAYED_FLOW_ROUTER), `Failed to complete hybrid hook/ISM config on ${this.chainName}`);
+        // Every owner-gated mutation is signed by the router's current owner.
+        // Ownership moves to the target owner only in the final ownership phase.
+        const desired = {
+            ...completed,
+            owner: actualConfig.owner,
+        };
+        const actualHook = actualConfig.hook;
+        const hookNodes = typeof actualHook === 'object' ? collectHybridHookNodes(actualHook) : [];
+        const actualIsm = actualConfig.interchainSecurityModule;
+        const ismNodes = typeof actualIsm === 'object' ? collectHybridIsmNodes(actualIsm) : [];
+        assert(hookNodes.length <= 1 && ismNodes.length <= 1, `Expected at most one installed hybrid hook/ISM on each surface of ${this.chainName}, found ${hookNodes.length} under hook and ${ismNodes.length} under interchainSecurityModule`);
+        // Prefer the hook: submission can be interrupted after its update but before
+        // the ISM update, leaving the new leaf installed while the ISM still has the
+        // old tree. A later apply must reuse that new leaf.
+        const candidate = hookNodes[0] ?? ismNodes[0];
+        const currentAddress = candidate &&
+            'address' in candidate &&
+            typeof candidate.address === 'string'
+            ? candidate.address
+            : undefined;
+        if (currentAddress) {
+            const current = await new EvmIsmReader(this.multiProvider, this.chainName).deriveIsmConfig(currentAddress);
+            assert(typeof current === 'object' &&
+                (current.type === IsmType.NET_FLOW_RATE_LIMITED ||
+                    current.type === IsmType.DELAYED_FLOW_ROUTER), `Expected ${currentAddress} on ${this.chainName} to be a hybrid hook/ISM`);
+            const ownedByRouter = current.owner && eqAddress(current.owner, actualConfig.owner);
+            const alreadyTransferred = !ownedByRouter &&
+                current.owner &&
+                expectedConfig.owner &&
+                eqAddress(current.owner, expectedConfig.owner);
+            assert(ownedByRouter || alreadyTransferred, `Hybrid hook/ISM ${currentAddress} on ${this.chainName} is owned by ${current.owner}, but its warp router is owned by ${actualConfig.owner}. Warp apply uses the router's submitter for every non-fee mutation, so align the owners before applying this config.`);
+            if (alreadyTransferred) {
+                const factory = HyperlaneIsmFactory.fromAddressesMap({ [this.chainName]: this.args.addresses }, this.multiProvider, this.ccipContractCache, this.contractVerifier);
+                const matchesFinalConfig = await moduleMatchesConfig(this.chainName, currentAddress, { ...completed, owner: expectedConfig.owner }, this.multiProvider, factory.getContracts(this.chainName), actualConfig.mailbox);
+                assert(matchesFinalConfig, `Hybrid hook/ISM ${currentAddress} on ${this.chainName} was already transferred to the target owner ${expectedConfig.owner}, but its config does not match the target. Complete or revert the interrupted ownership transfer before changing its config.`);
+                return {
+                    address: currentAddress,
+                    ismTree: plan.ismTree,
+                    hookTree: plan.hookTree,
+                    instanceTxs: [],
+                    ownershipTxs: [],
+                };
+            }
+            const module = new EvmIsmModule(this.multiProvider, {
+                chain: this.chainName,
+                config: current,
+                addresses: {
+                    ...this.args.addresses,
+                    mailbox: actualConfig.mailbox,
+                    deployedIsm: currentAddress,
+                },
+            }, this.ccipContractCache, this.contractVerifier);
+            const txs = await module.updateDeployedInstance(desired);
+            const { deployedIsm } = module.serialize();
+            assert(deployedIsm, `Failed to resolve hybrid hook/ISM on ${this.chainName}`);
+            const ownershipTxs = transferOwnershipTransactions(this.chainId, deployedIsm, { owner: actualConfig.owner }, { owner: expectedConfig.owner }, `hybrid hook/ISM on ${this.chainName}`);
+            return {
+                address: deployedIsm,
+                ismTree: plan.ismTree,
+                hookTree: plan.hookTree,
+                instanceTxs: txs,
+                ownershipTxs,
+            };
+        }
+        const factory = HyperlaneIsmFactory.fromAddressesMap({ [this.chainName]: this.args.addresses }, this.multiProvider, this.ccipContractCache, this.contractVerifier);
+        const deployed = await factory.deployInternal({
+            destination: this.chainName,
+            config: desired,
+            mailbox: actualConfig.mailbox,
+        });
+        const ownershipTxs = transferOwnershipTransactions(this.chainId, deployed.address, { owner: actualConfig.owner }, { owner: expectedConfig.owner }, `hybrid hook/ISM on ${this.chainName}`);
+        return {
+            address: deployed.address,
+            ismTree: plan.ismTree,
+            hookTree: plan.hookTree,
+            instanceTxs: [],
+            ownershipTxs,
+        };
+    }
     /**
      * Create a transaction to update the remote routers for the Warp Route contract.
      *
@@ -907,14 +1099,14 @@ export class EvmWarpModule extends HyperlaneModule {
      * @param expectedConfig - The expected token router configuration, including the ISM configuration.
      * @returns Ethereum transaction that need to be executed to update the ISM configuration.
      */
-    async createIsmUpdateTxs(actualConfig, expectedConfig) {
+    async createIsmUpdateTxs(actualConfig, expectedConfig, opaqueHybridAddress) {
         const updateTransactions = [];
         if (!expectedConfig.interchainSecurityModule) {
             return [];
         }
         const actualDeployedIsm = derivedIsmAddress(actualConfig);
         // Try to update (may also deploy) Ism with the expected config
-        const { deployedIsm: expectedDeployedIsm, updateTransactions: ismUpdateTransactions, } = await this.deployOrUpdateIsm(actualConfig, expectedConfig);
+        const { deployedIsm: expectedDeployedIsm, updateTransactions: ismUpdateTransactions, } = await this.deployOrUpdateIsm(actualConfig, expectedConfig, opaqueHybridAddress);
         // If an ISM is updated in-place, push the update txs
         updateTransactions.push(...ismUpdateTransactions);
         // If a new ISM is deployed, push the setInterchainSecurityModule tx
@@ -936,7 +1128,7 @@ export class EvmWarpModule extends HyperlaneModule {
      * Deploys hook updates and predicate wrapper together so the post-update hook address
      * is available to deployAndConfigure without a stale on-chain read.
      */
-    async createHookAndPredicateUpdateTxs(actualConfig, expectedConfig) {
+    async createHookAndPredicateUpdateTxs(actualConfig, expectedConfig, opaqueHybridAddress) {
         let hookTransactions = [];
         let newHookAddress;
         // Explicit type annotation narrows away the undefined that TypeScript infers
@@ -957,6 +1149,10 @@ export class EvmWarpModule extends HyperlaneModule {
             ? expectedConfig.predicateWrapper
             : undefined;
         const needsPredicateRemoval = actualPredicateWrapper != null && !expectedPredicateWrapper;
+        const needsDelayedFlowRemoval = typeof expectedConfig.hook === 'string' &&
+            isZeroishAddress(expectedConfig.hook) &&
+            typeof actualHook === 'object' &&
+            collectHybridHookNodes(actualHook).some(({ type }) => type === HookType.DELAYED_FLOW_ROUTER);
         // Treat a zero-address hook the same as "no explicit hook": expandWarpDeployConfig
         // sets hook: zeroAddress as a default when the user config omits the hook field.
         // EvmHookModule.update(zeroAddress) returns [] early without updating deployedHook,
@@ -995,20 +1191,24 @@ export class EvmWarpModule extends HyperlaneModule {
                 multiProvider: this.multiProvider,
                 proxyAdminAddress,
                 rateLimitedSender: this.args.addresses.deployedTokenRoute,
+                opaqueHybridAddresses: opaqueHybridAddress
+                    ? [opaqueHybridAddress]
+                    : undefined,
             });
             hookTransactions = result.transactions;
             newHookAddress = result.newHookAddress;
         }
-        // Predicate removal when no new hook was deployed: clear the custom hook entirely.
-        // This fires whether or not expectedConfig.hook was provided — it handles both the
-        // "no hook field" case and the round-trip hazard where the operator removed
-        // predicateWrapper but left an unchanged hook field (still containing the aggregation).
-        if (needsPredicateRemoval && !newHookAddress) {
+        // Predicate and delayed-flow removals clear the custom hook when no
+        // replacement was deployed. Delayed flow requires an explicit zero target;
+        // omission retains the existing hook like every ordinary update.
+        if ((needsPredicateRemoval || needsDelayedFlowRemoval) && !newHookAddress) {
             const currentAddress = typeof actualHook === 'string' ? actualHook : actualHook.address;
             if (!isZeroishAddress(currentAddress)) {
-                this.logger.debug({ chain: this.chainName }, 'Removing predicate wrapper: generating setHook(zero) to clear custom hook');
+                this.logger.debug({ chain: this.chainName }, 'Removing custom hook: generating setHook(zero)');
                 hookTransactions.push({
-                    annotation: 'Remove predicate wrapper: clear custom hook (router will use mailbox default)',
+                    annotation: needsDelayedFlowRemoval
+                        ? 'Remove delayed-flow hook (router will use mailbox default)'
+                        : 'Remove predicate wrapper: clear custom hook (router will use mailbox default)',
                     chainId: this.chainId,
                     to: this.args.addresses.deployedTokenRoute,
                     data: MailboxClient__factory.createInterface().encodeFunctionData('setHook', [constants.AddressZero]),
@@ -1329,7 +1529,7 @@ export class EvmWarpModule extends HyperlaneModule {
      *
      * @returns Object with deployedIsm address, and update Transactions
      */
-    async deployOrUpdateIsm(actualConfig, expectedConfig) {
+    async deployOrUpdateIsm(actualConfig, expectedConfig, opaqueHybridAddress) {
         assert(expectedConfig.interchainSecurityModule, 'Ism derived incorrectly');
         if (typeof expectedConfig.interchainSecurityModule === 'string' &&
             isZeroishAddress(expectedConfig.interchainSecurityModule)) {
@@ -1348,15 +1548,27 @@ export class EvmWarpModule extends HyperlaneModule {
         // Primary default: the warp-route owner (matches deploy path in token/deploy.ts).
         // Fallback: the current on-chain ISM owner (same-type, same-owner in-place update).
         let expectedIsm = expectedConfig.interchainSecurityModule;
-        if (typeof expectedIsm === 'object' &&
-            ismTreeContainsRateLimited(expectedIsm)) {
+        if (typeof expectedIsm === 'object') {
             const actualIsm = actualConfig.interchainSecurityModule;
             const onChainOwner = typeof actualIsm === 'object' && 'owner' in actualIsm
                 ? actualIsm.owner
                 : undefined;
             const defaultOwner = expectedConfig.owner ??
                 (typeof onChainOwner === 'string' ? onChainOwner : undefined);
-            expectedIsm = setRateLimitedIsmRecipient(expectedIsm, this.args.addresses.deployedTokenRoute, defaultOwner);
+            if (ismTreeContainsRateLimited(expectedIsm)) {
+                expectedIsm = setRateLimitedIsmRecipient(expectedIsm, this.args.addresses.deployedTokenRoute, defaultOwner);
+            }
+            // Hybrid hook/ISMs need the paired warp router, which in warp-route
+            // context is always this token — configs routinely omit it (it is only
+            // required for standalone ISM deploys). Injected independently of the
+            // owner: an unresolvable owner would otherwise leave `warpRouter`
+            // missing and the update would plan against an incomplete config.
+            // `remoteIsms` is deferred: cross-chain enrollment needs every chain's
+            // instance address, so it is reconciled by a separate pass that must
+            // stay its only writer.
+            if (ismTreeContainsHybridHookIsm(expectedIsm)) {
+                expectedIsm = completeHybridIsmNodes(expectedIsm, this.args.addresses.deployedTokenRoute, { type: DelayedFlowRemoteIsmsSourceType.Deferred }, defaultOwner, this.multiProvider);
+            }
         }
         const ismModule = new EvmIsmModule(this.multiProvider, {
             chain: this.args.chain,
@@ -1368,7 +1580,7 @@ export class EvmWarpModule extends HyperlaneModule {
             },
         }, this.ccipContractCache, this.contractVerifier);
         this.logger.info(`Comparing target ISM config with ${this.args.chain} chain`);
-        const updateTransactions = await ismModule.update(expectedIsm);
+        const updateTransactions = await ismModule.update(expectedIsm, opaqueHybridAddress ? [opaqueHybridAddress] : []);
         const { deployedIsm } = ismModule.serialize();
         return { deployedIsm, updateTransactions };
     }