feat(sdk): support fractional basis points via number type (#8378)

Author: Mo-Hussain

.changeset/brave-bears-smile.md

@@ -0,0 +1,12 @@
+---
+"@hyperlane-xyz/sdk": major
+---
+
+The bps type was changed from bigint to number throughout the LinearFee fee system to support fractional basis points (e.g., 1.5 bps).
+
+Breaking changes:
+- `convertToBps()` return type changed from `bigint` to `number`
+- `convertFromBps()` parameter type changed from `bigint` to `number`
+- `LinearFeeConfig.bps` and `LinearFeeInputConfig.bps` types changed from `bigint` to `number`
+- `ZBps` schema no longer accepts `bigint` input — callers using `bps: 5n` must change to `bps: 5`
+- `TokenFeeConfigSchema` and `LinearFeeConfigSchema` bps field type changed from `bigint` to `number`

typescript/cli/src/tests/ethereum/warp/apply/warp-apply-ownership-updates.e2e-test.ts

@@ -187,7 +187,7 @@ describe('hyperlane warp apply E2E (ownership updates)', async function () {
     const tokenFeeConfig = {
       type: TokenFeeType.LinearFee as const,
       owner: feeOwner,
-      bps: BigInt('100'),
+      bps: 100,
     };
 
     const warpDeployConfig = fixture.getDeployConfig();

typescript/cli/src/tests/ethereum/warp/warp-deploy-2.e2e-test.ts

@@ -278,7 +278,7 @@ describe('hyperlane warp deploy e2e tests', async function () {
       const tokenFee = {
         type: TokenFeeType.LinearFee,
         token: tokenChain2.address,
-        bps: 1n,
+        bps: 1,
       };
 
       const warpConfig = WarpRouteDeployConfigSchema.parse({
@@ -316,7 +316,7 @@ describe('hyperlane warp deploy e2e tests', async function () {
       const tokenFee = {
         type: TokenFeeType.LinearFee,
         owner: ownerAddress,
-        bps: 1n,
+        bps: 1,
       };
 
       const warpConfig = WarpRouteDeployConfigSchema.parse({
@@ -419,7 +419,7 @@ describe('hyperlane warp deploy e2e tests', async function () {
           owner: ownerAddress,
           tokenFee: {
             type: TokenFeeType.LinearFee,
-            bps: 100n,
+            bps: 100,
           },
         },
       });
@@ -622,7 +622,7 @@ describe('hyperlane warp deploy e2e tests', async function () {
     });
 
     it('should deploy a synthetic token with LinearFee using only bps (computed path)', async () => {
-      const providedBps = 100n;
+      const providedBps = 100;
 
       const warpConfig = WarpRouteDeployConfigSchema.parse({
         [CHAIN_NAME_2]: {
@@ -661,7 +661,7 @@ describe('hyperlane warp deploy e2e tests', async function () {
       expect(syntheticConfig.tokenFee?.type).to.equal(TokenFeeType.LinearFee);
 
       const tokenFee = syntheticConfig.tokenFee as LinearFeeConfig;
-      expect(BigInt(tokenFee.bps)).to.equal(providedBps);
+      expect(tokenFee.bps).to.equal(providedBps);
       expect(tokenFee.maxFee).to.exist;
       expect(tokenFee.halfAmount).to.exist;
       expect(BigInt(tokenFee.maxFee) > 0n).to.be.true;

typescript/infra/config/environments/mainnet3/warp/configGetters/getEclipseUSDCWarpConfig.ts

@@ -240,7 +240,7 @@ export const buildEclipseUSDCWarpConfig = async (
         tokenFee: getFixedRoutingFeeConfig(
           getWarpFeeOwner(chain),
           destinations,
-          5n,
+          5,
           feeParams,
         ),
       };

typescript/infra/config/environments/mainnet3/warp/configGetters/getEniWarpConfigs.ts

@@ -25,7 +25,7 @@ const owners = {
   polygon: '0x3211A1Fea94cd4000Bd82D7C9E9334E51938De1b',
 } as const;
 
-const WARP_FEE_BPS = 8n;
+const WARP_FEE_BPS = 8;
 
 const usdcTokenAddresses = {
   arbitrum: tokens.arbitrum.USDC,

typescript/infra/config/environments/mainnet3/warp/configGetters/getVictionETHWarpConfig.ts

@@ -78,7 +78,7 @@ export const getVictionETHWarpConfig = async (
         tokenFee: getFixedRoutingFeeConfig(
           getWarpFeeOwner(currentChain),
           feeDestinations,
-          10n,
+          10,
         ),
         proxyAdmin: {
           owner:

typescript/infra/config/environments/mainnet3/warp/configGetters/utils.ts

@@ -195,7 +195,7 @@ export const getNativeTokenConfigForChain = <
 export function getFixedRoutingFeeConfig(
   owner: Address,
   feeDestinations: readonly ChainName[],
-  bps: bigint,
+  bps: number,
   feeParams?: Record<string, { maxFee: string; halfAmount: string }>,
 ): TokenFeeConfigInput {
   const feeContracts: Record<ChainName, TokenFeeConfigInput> = {};

typescript/sdk/src/fee/EvmTokenFeeDeployer.hardhat-test.ts

@@ -10,6 +10,7 @@ import { MultiProvider } from '../providers/MultiProvider.js';
 
 import { EvmTokenFeeDeployer } from './EvmTokenFeeDeployer.js';
 import { BPS, HALF_AMOUNT, MAX_FEE } from './EvmTokenFeeReader.hardhat-test.js';
+import { BPS_PRECISION } from './utils.js';
 import {
   LinearFeeConfig,
   ProgressiveFeeConfig,
@@ -145,7 +146,9 @@ describe('EvmTokenFeeDeployer', () => {
     ](1, addressToBytes32(signer.address), amount);
 
     expect(quote.length).to.equal(1);
-    expect(quote[0].amount).to.be.equal((BigInt(amount) * BPS) / 10_000n);
+    expect(quote[0].amount).to.be.equal(
+      (BigInt(amount) * BigInt(BPS)) / BPS_PRECISION,
+    );
     expect(quote[0].token).to.equal(token.address);
 
     // If no fee contract is set, the quote should be zero

typescript/sdk/src/fee/EvmTokenFeeModule.hardhat-test.ts

@@ -13,7 +13,10 @@ import { normalizeConfig } from '../utils/ism.js';
 
 import { EvmTokenFeeModule } from './EvmTokenFeeModule.js';
 import { BPS, HALF_AMOUNT, MAX_FEE } from './EvmTokenFeeReader.hardhat-test.js';
-import { TokenFeeReaderParams } from './EvmTokenFeeReader.js';
+import {
+  EvmTokenFeeReader,
+  TokenFeeReaderParams,
+} from './EvmTokenFeeReader.js';
 import {
   LinearFeeConfig,
   ResolvedTokenFeeConfigInput,
@@ -70,7 +73,11 @@ describe('EvmTokenFeeModule', () => {
     });
     const onchainConfig = await module.read();
     expect(normalizeConfig(onchainConfig)).to.deep.equal(
-      normalizeConfig({ ...config, maxFee: MAX_FEE, halfAmount: HALF_AMOUNT }),
+      normalizeConfig({
+        ...config,
+        maxFee: MAX_FEE,
+        halfAmount: HALF_AMOUNT,
+      }),
     );
   });
 
@@ -172,7 +179,7 @@ describe('EvmTokenFeeModule', () => {
         chain: test4Chain,
         config,
       });
-      const updatedConfig = { ...config, bps: BPS + 1n };
+      const updatedConfig = { ...config, bps: BPS + 1 };
       await expectTxsAndUpdate(module, updatedConfig, 0);
       const onchainConfig = await module.read();
       assert(
@@ -202,7 +209,7 @@ describe('EvmTokenFeeModule', () => {
         feeContracts: {
           [test4Chain]: {
             ...feeContracts[test4Chain],
-            bps: BPS + 1n,
+            bps: BPS + 1,
           },
         },
       };
@@ -254,7 +261,10 @@ describe('EvmTokenFeeModule', () => {
           ...routingFeeConfig,
           owner: newOwner,
           feeContracts: {
-            [test4Chain]: { ...feeContracts[test4Chain], owner: newOwner },
+            [test4Chain]: {
+              ...feeContracts[test4Chain],
+              owner: newOwner,
+            },
           },
         },
         2,
@@ -297,7 +307,7 @@ describe('EvmTokenFeeModule', () => {
         feeContracts: {
           [test4Chain]: {
             ...feeContracts[test4Chain],
-            bps: BPS + 1n,
+            bps: BPS + 1,
           },
         },
       };
@@ -373,7 +383,7 @@ describe('EvmTokenFeeModule', () => {
         type: TokenFeeType.LinearFee,
         owner: signer.address,
         token: zeroSupplyToken.address,
-        bps: 8n,
+        bps: 8,
       };
 
       const expandedConfig = await EvmTokenFeeModule.expandConfig({
@@ -386,16 +396,16 @@ describe('EvmTokenFeeModule', () => {
         expandedConfig.type === TokenFeeType.LinearFee,
         `Must be ${TokenFeeType.LinearFee}`,
       );
-      const linearConfig = expandedConfig as LinearFeeConfig;
-      expect(linearConfig.maxFee > 0n).to.be.true;
-      expect(linearConfig.halfAmount > 0n).to.be.true;
-      expect(linearConfig.bps).to.equal(8n);
+
+      expect(expandedConfig.maxFee > 0n).to.be.true;
+      expect(expandedConfig.halfAmount > 0n).to.be.true;
+      expect(expandedConfig.bps).to.equal(8);
 
       const roundTripBps = convertToBps(
-        linearConfig.maxFee,
-        linearConfig.halfAmount,
+        expandedConfig.maxFee,
+        expandedConfig.halfAmount,
       );
-      expect(roundTripBps).to.equal(8n);
+      expect(roundTripBps).to.equal(8);
     });
 
     it('should expand nested RoutingFee config for zero-supply token', async () => {
@@ -412,7 +422,7 @@ describe('EvmTokenFeeModule', () => {
             type: TokenFeeType.LinearFee,
             owner: signer.address,
             token: zeroSupplyToken.address,
-            bps: 8n,
+            bps: 8,
           },
         },
       };
@@ -438,7 +448,7 @@ describe('EvmTokenFeeModule', () => {
       const linearFee = nestedFee as LinearFeeConfig;
       expect(linearFee.maxFee > 0n).to.be.true;
       expect(linearFee.halfAmount > 0n).to.be.true;
-      expect(linearFee.bps).to.equal(8n);
+      expect(linearFee.bps).to.equal(8);
     });
 
     it('should expand config with explicit maxFee/halfAmount (no bps) and preserve values', async () => {
@@ -466,11 +476,10 @@ describe('EvmTokenFeeModule', () => {
         expandedConfig.type === TokenFeeType.LinearFee,
         `Must be ${TokenFeeType.LinearFee}`,
       );
-      const linearConfig = expandedConfig as LinearFeeConfig;
 
-      expect(linearConfig.maxFee).to.equal(explicitMaxFee);
-      expect(linearConfig.halfAmount).to.equal(explicitHalfAmount);
-      expect(linearConfig.bps).to.equal(expectedBps);
+      expect(expandedConfig.maxFee).to.equal(explicitMaxFee);
+      expect(expandedConfig.halfAmount).to.equal(explicitHalfAmount);
+      expect(expandedConfig.bps).to.equal(expectedBps);
     });
 
     it('should expand nested RoutingFee with explicit maxFee/halfAmount in child LinearFee', async () => {
@@ -525,7 +534,7 @@ describe('EvmTokenFeeModule', () => {
           [test4Chain]: {
             type: TokenFeeType.LinearFee,
             owner: signer.address,
-            bps: 8n,
+            bps: 8,
           },
         },
       } as ResolvedTokenFeeConfigInput;
@@ -545,5 +554,32 @@ describe('EvmTokenFeeModule', () => {
       assert(nestedFee, 'Nested fee must exist');
       expect(nestedFee.token).to.equal(token.address);
     });
+
+    it('should expand config with fractional bps (1.5)', async () => {
+      const reader = new EvmTokenFeeReader(multiProvider, test4Chain);
+      const expected = reader.convertFromBps(1.5);
+
+      const inputConfig: ResolvedTokenFeeConfigInput = {
+        type: TokenFeeType.LinearFee,
+        owner: signer.address,
+        token: token.address,
+        bps: 1.5,
+      };
+
+      const expandedConfig = await EvmTokenFeeModule.expandConfig({
+        config: inputConfig,
+        multiProvider,
+        chainName: test4Chain,
+      });
+
+      assert(
+        expandedConfig.type === TokenFeeType.LinearFee,
+        `Must be ${TokenFeeType.LinearFee}`,
+      );
+
+      expect(expandedConfig.maxFee).to.equal(expected.maxFee);
+      expect(expandedConfig.halfAmount).to.equal(expected.halfAmount);
+      expect(expandedConfig.bps).to.equal(1.5);
+    });
   });
 });

typescript/sdk/src/fee/EvmTokenFeeModule.ts

@@ -149,7 +149,7 @@ export class EvmTokenFeeModule extends HyperlaneModule<
 
       let maxFee: bigint;
       let halfAmount: bigint;
-      let bps: bigint;
+      let bps: number;
 
       const reader = new EvmTokenFeeReader(
         params.multiProvider,