fix(sdk): resolve xERC20Lockbox fee token from on-chain router.token()

The xERC20Lockbox deploy config stores the lockbox address, but the
router's token()/feeToken() returns the underlying wrapped ERC20. Fee
token resolution now reads token() on-chain for the lockbox variant so
the deployed fee contract matches the router's `fee must match token`
check. Added an xERC20Lockbox CLI e2e test alongside the existing xERC20
coverage.

Author: haggis-hyperlane

.changeset/sdk-xerc20-token-fee.md

@@ -2,4 +2,4 @@
 '@hyperlane-xyz/sdk': patch
 ---
 
-The SDK fee-token resolution now supports xERC20 and xERC20Lockbox warp routes. Previously `getFeeTokenAddress` threw `Unsupported token type for fee resolution` for these types, which blocked applying a `tokenFee` (including OQLF) to xERC20 routes via `warp deploy`/`warp apply`. It now returns the wrapped/collateral token address, matching the contract's `feeToken()` which returns `token()` when a fee hook is set. Added SDK hardhat tests for the xERC20 fee-setting path and CLI e2e tests asserting xERC20 routes can be deployed with fees and updated.
+The SDK fee-token resolution now supports xERC20 and xERC20Lockbox warp routes. Previously `getFeeTokenAddress` threw `Unsupported token type for fee resolution` for these types, which blocked applying a `tokenFee` (including OQLF) to xERC20 routes via `warp deploy`/`warp apply`. For plain xERC20 the fee token resolves to the configured xERC20 token. For xERC20Lockbox the deploy config stores the lockbox address, but the router's `token()`/`feeToken()` returns the underlying wrapped ERC20; fee-token resolution now reads this on-chain for the lockbox variant so the deployed fee contract's token matches `token()` and passes the router's `fee must match token` check. Added SDK unit and hardhat tests (including an xERC20Lockbox deploy regression) plus CLI e2e tests asserting xERC20 and xERC20Lockbox routes can be deployed with fees and updated.

typescript/cli/src/tests/ethereum/warp/warp-xerc20-fee.e2e-test.ts

@@ -4,7 +4,7 @@ import { expect } from 'chai';
 import { Wallet } from 'ethers';
 import { $ } from 'zx';
 
-import { type XERC20VSTest } from '@hyperlane-xyz/core';
+import { type XERC20LockboxTest, type XERC20VSTest } from '@hyperlane-xyz/core';
 import { type ChainAddresses } from '@hyperlane-xyz/registry';
 import {
   type ChainMetadata,
@@ -14,11 +14,20 @@ import {
   type WarpRouteDeployConfig,
   WarpRouteDeployConfigSchema,
 } from '@hyperlane-xyz/sdk';
-import { type Address, assert, isNullish } from '@hyperlane-xyz/utils';
+import {
+  type Address,
+  assert,
+  eqAddress,
+  isNullish,
+} from '@hyperlane-xyz/utils';
 
 import { readYamlOrJson, writeYamlOrJson } from '../../../utils/files.js';
 import { deployOrUseExistingCore } from '../commands/core.js';
-import { deployXERC20VSToken } from '../commands/helpers.js';
+import {
+  deployToken,
+  deployXERC20LockboxToken,
+  deployXERC20VSToken,
+} from '../commands/helpers.js';
 import {
   hyperlaneWarpApply,
   hyperlaneWarpDeploy,
@@ -143,4 +152,73 @@ describe('hyperlane warp xERC20 token fee e2e tests', function () {
       expect(fee.token).to.equal(xerc20.address);
     });
   });
+
+  // Regression for the xERC20Lockbox fee-token resolution bug: the deploy
+  // config stores token = lockbox address, but the router's token()/feeToken()
+  // returns the underlying wrapped ERC20. The fee contract must be deployed
+  // with token() so the router's fee==token() check passes; the SDK reads this
+  // on-chain for the lockbox variant.
+  describe('xERC20Lockbox token fee', () => {
+    const LB_SYMBOL = 'XLBFEE';
+    const LB_WARP_ROUTE_ID = getWarpRouteId(LB_SYMBOL, [CHAIN_NAME_2]);
+    const LB_CORE_PATH = getCombinedWarpRoutePath(LB_SYMBOL, [CHAIN_NAME_2]);
+    const LB_REGISTRY_DEPLOY_PATH = getCombinedWarpDeployPath(LB_SYMBOL, [
+      CHAIN_NAME_2,
+    ]);
+    const LB_DEPLOY_PATH = `${TEMP_PATH}/warp-xerc20lockbox-fee-deploy.yaml`;
+
+    let lockbox: XERC20LockboxTest;
+    let wrappedToken: Address;
+
+    before(async function () {
+      const underlying = await deployToken(
+        ANVIL_KEY,
+        CHAIN_NAME_2,
+        18,
+        LB_SYMBOL,
+      );
+      lockbox = await deployXERC20LockboxToken(
+        ANVIL_KEY,
+        CHAIN_NAME_2,
+        underlying,
+      );
+      // The lockbox exposes its underlying wrapped ERC20 via ERC20().
+      wrappedToken = await lockbox.ERC20();
+    });
+
+    function buildLockboxConfig(bps?: number): WarpRouteDeployConfig {
+      return WarpRouteDeployConfigSchema.parse({
+        [CHAIN_NAME_2]: {
+          type: TokenType.XERC20Lockbox,
+          token: lockbox.address,
+          mailbox: chain2Addresses.mailbox,
+          owner: ownerAddress,
+          ...(isNullish(bps)
+            ? {}
+            : { tokenFee: { type: TokenFeeType.LinearFee, bps } }),
+        },
+      });
+    }
+
+    it('deploys an xERC20Lockbox warp route with a LinearFee resolved to the wrapped token', async function () {
+      writeYamlOrJson(LB_DEPLOY_PATH, buildLockboxConfig(FEE_BPS));
+      await hyperlaneWarpDeploy(LB_DEPLOY_PATH, LB_WARP_ROUTE_ID);
+
+      const config = (
+        await readWarpConfig(
+          CHAIN_NAME_2,
+          LB_CORE_PATH,
+          LB_REGISTRY_DEPLOY_PATH,
+        )
+      )[CHAIN_NAME_2];
+
+      const fee = TokenFeeConfigSchema.parse(config.tokenFee);
+      assert(fee.type === TokenFeeType.LinearFee, 'expected a LinearFee');
+      expect(fee.bps).to.equal(FEE_BPS);
+      // The fee token must be the underlying wrapped ERC20 (router.token()),
+      // NOT the lockbox address stored in the deploy config.
+      expect(eqAddress(fee.token, wrappedToken)).to.be.true;
+      expect(eqAddress(fee.token, lockbox.address)).to.be.false;
+    });
+  });
 });

typescript/sdk/src/token/EvmWarpModule.ts

@@ -1898,10 +1898,11 @@ export class EvmWarpModule extends HyperlaneModule<
     }
 
     const routerAddress = this.args.addresses.deployedTokenRoute;
-    const resolvedTokenFee = resolveTokenFeeAddress(
+    const resolvedTokenFee = await resolveTokenFeeAddress(
       expectedConfig.tokenFee,
       routerAddress,
       expectedConfig,
+      this.multiProvider.getProvider(this.chainId),
     );
 
     const currentTokenFee = actualConfig.tokenFee;

typescript/sdk/src/token/configUtils.test.ts

@@ -1,12 +1,12 @@
 import { expect } from 'chai';
-import { constants } from 'ethers';
+import { constants, providers } from 'ethers';
+import sinon from 'sinon';
 
+import { HypXERC20Lockbox__factory } from '@hyperlane-xyz/core';
 import { assert } from '@hyperlane-xyz/utils';
 
 import {
   DEFAULT_ROUTER_KEY,
-  ResolvedCrossCollateralRoutingFeeConfigInput,
-  ResolvedLinearFeeConfigInput,
   ResolvedRoutingFeeConfigInput,
   TokenFeeType,
 } from '../fee/types.js';
@@ -623,6 +623,22 @@ describe('configUtils', () => {
     const ROUTER_ADDRESS = '0x1234567890123456789012345678901234567890';
     const OWNER_ADDRESS = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd';
     const COLLATERAL_TOKEN = '0x9999999999999999999999999999999999999999';
+    // The lockbox's on-chain token() returns the underlying wrapped ERC20,
+    // which is distinct from the lockbox address stored in tokenConfig.token.
+    const LOCKBOX_ADDRESS = '0x8888888888888888888888888888888888888888';
+    const LOCKBOX_WRAPPED_TOKEN = '0x7777777777777777777777777777777777777777';
+
+    let sandbox: sinon.SinonSandbox;
+    let provider: providers.Provider;
+
+    beforeEach(() => {
+      sandbox = sinon.createSandbox();
+      provider = buildMultiProvider().getProvider(test1.name);
+    });
+
+    afterEach(() => {
+      sandbox.restore();
+    });
 
     const syntheticConfig: HypTokenConfig = {
       type: TokenType.synthetic,
@@ -644,95 +660,109 @@ describe('configUtils', () => {
 
     const xerc20LockboxConfig: HypTokenConfig = {
       type: TokenType.XERC20Lockbox,
-      token: COLLATERAL_TOKEN,
+      token: LOCKBOX_ADDRESS,
     };
 
-    it('should resolve token to router address for synthetic tokens', () => {
+    it('should resolve token to router address for synthetic tokens', async () => {
       const input = {
         type: TokenFeeType.LinearFee,
         owner: OWNER_ADDRESS,
         bps: 100,
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         syntheticConfig,
-      ) as ResolvedLinearFeeConfigInput;
+        provider,
+      );
 
+      assert(result.type === TokenFeeType.LinearFee, 'expected a LinearFee');
       expect(result.token).to.equal(ROUTER_ADDRESS);
       expect(result.owner).to.equal(OWNER_ADDRESS);
     });
 
-    it('should resolve token to collateral address for collateral tokens', () => {
+    it('should resolve token to collateral address for collateral tokens', async () => {
       const input = {
         type: TokenFeeType.LinearFee,
         owner: OWNER_ADDRESS,
         bps: 100,
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         collateralConfig,
-      ) as ResolvedLinearFeeConfigInput;
+        provider,
+      );
 
+      assert(result.type === TokenFeeType.LinearFee, 'expected a LinearFee');
       expect(result.token).to.equal(COLLATERAL_TOKEN);
     });
 
-    it('should resolve token to AddressZero for native tokens', () => {
+    it('should resolve token to AddressZero for native tokens', async () => {
       const input = {
         type: TokenFeeType.LinearFee,
         owner: OWNER_ADDRESS,
         bps: 100,
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         nativeConfig,
-      ) as ResolvedLinearFeeConfigInput;
+        provider,
+      );
 
+      assert(result.type === TokenFeeType.LinearFee, 'expected a LinearFee');
       expect(result.token).to.equal(constants.AddressZero);
     });
 
-    it('should resolve token to wrapped token address for xERC20 tokens', () => {
+    it('should resolve token to the xERC20 token address for xERC20 tokens', async () => {
       const input = {
         type: TokenFeeType.LinearFee,
         owner: OWNER_ADDRESS,
         bps: 100,
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         xerc20Config,
+        provider,
       );
 
-      expect('token' in result ? result.token : undefined).to.equal(
-        COLLATERAL_TOKEN,
-      );
+      assert(result.type === TokenFeeType.LinearFee, 'expected a LinearFee');
+      expect(result.token).to.equal(COLLATERAL_TOKEN);
     });
 
-    it('should resolve token to wrapped token address for xERC20Lockbox tokens', () => {
+    it('should resolve token to the on-chain wrapped token for xERC20Lockbox tokens', async () => {
+      // For a lockbox, the fee token must match the router's token() (the
+      // underlying wrapped ERC20), NOT the lockbox address in the config.
+      const tokenStub = sandbox.stub().resolves(LOCKBOX_WRAPPED_TOKEN);
+      sandbox.stub(HypXERC20Lockbox__factory, 'connect').returns({
+        token: tokenStub,
+      } as any);
+
       const input = {
         type: TokenFeeType.LinearFee,
         owner: OWNER_ADDRESS,
         bps: 100,
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         xerc20LockboxConfig,
+        provider,
       );
 
-      expect('token' in result ? result.token : undefined).to.equal(
-        COLLATERAL_TOKEN,
-      );
+      assert(result.type === TokenFeeType.LinearFee, 'expected a LinearFee');
+      expect(result.token).to.equal(LOCKBOX_WRAPPED_TOKEN);
+      expect(result.token).to.not.equal(LOCKBOX_ADDRESS);
     });
 
-    it('should resolve nested feeContracts tokens for RoutingFee', () => {
+    it('should resolve nested feeContracts tokens for RoutingFee', async () => {
       const input = {
         type: TokenFeeType.RoutingFee,
         owner: OWNER_ADDRESS,
@@ -750,37 +780,38 @@ describe('configUtils', () => {
         },
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         syntheticConfig,
-      ) as ResolvedRoutingFeeConfigInput;
+        provider,
+      );
 
+      assert(result.type === TokenFeeType.RoutingFee, 'expected a RoutingFee');
       expect(result.token).to.equal(ROUTER_ADDRESS);
-      expect(result.type).to.equal(TokenFeeType.RoutingFee);
-
       expect(result.feeContracts.ethereum.token).to.equal(ROUTER_ADDRESS);
       expect(result.feeContracts.arbitrum.token).to.equal(ROUTER_ADDRESS);
     });
 
-    it('should handle RoutingFee with empty feeContracts', () => {
+    it('should handle RoutingFee with empty feeContracts', async () => {
       const input = {
         type: TokenFeeType.RoutingFee,
         owner: OWNER_ADDRESS,
         feeContracts: {},
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         syntheticConfig,
-      ) as ResolvedRoutingFeeConfigInput;
+        provider,
+      );
 
+      assert(result.type === TokenFeeType.RoutingFee, 'expected a RoutingFee');
       expect(result.token).to.equal(ROUTER_ADDRESS);
-      expect(result.type).to.equal(TokenFeeType.RoutingFee);
     });
 
-    it('should resolve token for nested cross collateral feeContracts', () => {
+    it('should resolve token for nested cross collateral feeContracts', async () => {
       const ROUTER_KEY =
         '0x1111111111111111111111111111111111111111111111111111111111111111';
       const input = {
@@ -802,12 +833,17 @@ describe('configUtils', () => {
         },
       };
 
-      const result = resolveTokenFeeAddress(
+      const result = await resolveTokenFeeAddress(
         input,
         ROUTER_ADDRESS,
         syntheticConfig,
-      ) as ResolvedCrossCollateralRoutingFeeConfigInput;
+        provider,
+      );
 
+      assert(
+        result.type === TokenFeeType.CrossCollateralRoutingFee,
+        'expected a CrossCollateralRoutingFee',
+      );
       expect(result.feeContracts.ethereum[DEFAULT_ROUTER_KEY]?.token).to.equal(
         ROUTER_ADDRESS,
       );