feat(provider-sdk, deploy-sdk): initial fee support on multi-vm (#8627)

Author: xeno097

.changeset/fee-type-support.md

@@ -0,0 +1,12 @@
+---
+"@hyperlane-xyz/provider-sdk": minor
+"@hyperlane-xyz/deploy-sdk": minor
+"@hyperlane-xyz/sealevel-sdk": patch
+"@hyperlane-xyz/cosmos-sdk": patch
+"@hyperlane-xyz/radix-sdk": patch
+"@hyperlane-xyz/starknet-sdk": patch
+"@hyperlane-xyz/aleo-sdk": patch
+"@hyperlane-xyz/tron-sdk": patch
+---
+
+Multi-VM fee type support was added to provider-sdk and deploy-sdk. Fee types (linear, regressive, progressive, offchainQuotedLinear, routing, crossCollateralRouting) were defined with Config API and Artifact API variants. FeeReader and FeeWriter with required FeeReadContext were added to deploy-sdk. Fee was integrated into warp types and the warp writer update flow. All protocol providers received createFeeArtifactManager stubs.

typescript/aleo-sdk/src/clients/protocol.ts

@@ -19,6 +19,7 @@ import {
   type TxReceipt,
 } from '@hyperlane-xyz/provider-sdk/module';
 import { type IRawWarpArtifactManager } from '@hyperlane-xyz/provider-sdk/warp';
+import { type IRawFeeArtifactManager } from '@hyperlane-xyz/provider-sdk/fee';
 import { type IRawValidatorAnnounceArtifactManager } from '@hyperlane-xyz/provider-sdk/validator-announce';
 import { assert } from '@hyperlane-xyz/utils';
 
@@ -190,6 +191,12 @@ export class AleoProtocolProvider implements ProtocolProvider {
     );
   }
 
+  createFeeArtifactManager(
+    _chainMetadata: ChainMetadataForAltVM,
+  ): IRawFeeArtifactManager | null {
+    return null;
+  }
+
   getMinGas(): MinimumRequiredGasByAction {
     return {
       CORE_DEPLOY_GAS: 0n,

typescript/cosmos-sdk/src/clients/protocol.ts

@@ -16,6 +16,7 @@ import {
   type TxReceipt,
 } from '@hyperlane-xyz/provider-sdk/module';
 import { type IRawWarpArtifactManager } from '@hyperlane-xyz/provider-sdk/warp';
+import { type IRawFeeArtifactManager } from '@hyperlane-xyz/provider-sdk/fee';
 import { type IRawValidatorAnnounceArtifactManager } from '@hyperlane-xyz/provider-sdk/validator-announce';
 import { assert } from '@hyperlane-xyz/utils';
 
@@ -118,6 +119,12 @@ export class CosmosNativeProtocolProvider implements ProtocolProvider {
     return null;
   }
 
+  createFeeArtifactManager(
+    _chainMetadata: ChainMetadataForAltVM,
+  ): IRawFeeArtifactManager | null {
+    return null;
+  }
+
   getMinGas(): MinimumRequiredGasByAction {
     return {
       CORE_DEPLOY_GAS: BigInt(1e6),

typescript/deploy-sdk/src/core/core-artifact-reader.test.ts

@@ -33,6 +33,7 @@ const mockProtocolProvider: ProtocolProvider = {
   createHookArtifactManager: sinon.stub(),
   createMailboxArtifactManager: sinon.stub(),
   createValidatorAnnounceArtifactManager: sinon.stub(),
+  createFeeArtifactManager: sinon.stub(),
   getMinGas: sinon.stub(),
   createWarpArtifactManager: sinon.stub(),
 };

typescript/deploy-sdk/src/core/core-writer.test.ts

@@ -152,6 +152,7 @@ describe('CoreWriter', () => {
       createHookArtifactManager: sinon.stub().returns(mockHookArtifactManager),
       createMailboxArtifactManager: sinon.stub(),
       createValidatorAnnounceArtifactManager: sinon.stub(),
+      createFeeArtifactManager: sinon.stub(),
       getMinGas: sinon.stub(),
       createWarpArtifactManager: sinon.stub(),
     } satisfies ProtocolProvider;

typescript/deploy-sdk/src/fee/fee-reader.ts

@@ -0,0 +1,55 @@
+import {
+  ChainMetadataForAltVM,
+  getProtocolProvider,
+} from '@hyperlane-xyz/provider-sdk';
+import { ArtifactReader } from '@hyperlane-xyz/provider-sdk/artifact';
+import {
+  DeployedFeeAddress,
+  DeployedFeeArtifact,
+  FeeArtifactConfig,
+  FeeReadContext,
+  IRawFeeArtifactManager,
+} from '@hyperlane-xyz/provider-sdk/fee';
+
+/**
+ * Factory function to create a FeeReader instance.
+ * Returns null if the protocol does not support fee programs.
+ *
+ * @param chainMetadata Chain metadata for the target chain
+ * @param context Required fee read context with domains and routers to check
+ * @returns A FeeReader instance, or null if the protocol does not support fees
+ */
+export function createFeeReader(
+  chainMetadata: ChainMetadataForAltVM,
+  context: FeeReadContext,
+): FeeReader | null {
+  const protocolProvider = getProtocolProvider(chainMetadata.protocol);
+  const artifactManager: IRawFeeArtifactManager | null =
+    protocolProvider.createFeeArtifactManager(chainMetadata);
+
+  if (!artifactManager) {
+    return null;
+  }
+
+  return new FeeReader(artifactManager, context);
+}
+
+/**
+ * Generic Fee Reader that reads fee configurations from on-chain state.
+ *
+ * The FeeReadContext is required at construction time to ensure the reader always
+ * knows which domains and routers to check (some fee contracts are not enumerable).
+ */
+export class FeeReader implements ArtifactReader<
+  FeeArtifactConfig,
+  DeployedFeeAddress
+> {
+  constructor(
+    protected readonly artifactManager: IRawFeeArtifactManager,
+    protected readonly context: FeeReadContext,
+  ) {}
+
+  async read(address: string): Promise<DeployedFeeArtifact> {
+    return this.artifactManager.readFee(address, this.context);
+  }
+}

typescript/deploy-sdk/src/fee/fee-writer.ts

@@ -0,0 +1,79 @@
+import {
+  ChainMetadataForAltVM,
+  getProtocolProvider,
+} from '@hyperlane-xyz/provider-sdk';
+import { ISigner } from '@hyperlane-xyz/provider-sdk/altvm';
+import {
+  ArtifactNew,
+  ArtifactWriter,
+} from '@hyperlane-xyz/provider-sdk/artifact';
+import {
+  DeployedFeeAddress,
+  DeployedFeeArtifact,
+  FeeArtifactConfig,
+  FeeReadContext,
+  IRawFeeArtifactManager,
+} from '@hyperlane-xyz/provider-sdk/fee';
+import { AnnotatedTx, TxReceipt } from '@hyperlane-xyz/provider-sdk/module';
+
+import { FeeReader } from './fee-reader.js';
+
+/**
+ * Factory function to create a FeeWriter instance.
+ * Returns null if the protocol does not support fee programs.
+ *
+ * @param chainMetadata Chain metadata for the target chain
+ * @param signer Signer interface for signing transactions
+ * @param context Required fee read context with domains and routers to check
+ * @returns A FeeWriter instance, or null if the protocol does not support fees
+ */
+export function createFeeWriter(
+  chainMetadata: ChainMetadataForAltVM,
+  signer: ISigner<AnnotatedTx, TxReceipt>,
+  context: FeeReadContext,
+): FeeWriter | null {
+  const protocolProvider = getProtocolProvider(chainMetadata.protocol);
+  const artifactManager: IRawFeeArtifactManager | null =
+    protocolProvider.createFeeArtifactManager(chainMetadata);
+
+  if (!artifactManager) {
+    return null;
+  }
+
+  return new FeeWriter(artifactManager, context, signer);
+}
+
+/**
+ * FeeWriter handles creation and updates of fee configurations using the Artifact API.
+ * It delegates to protocol-specific artifact writers for individual fee types.
+ *
+ * Extends FeeReader to inherit read() functionality.
+ * The FeeReadContext is required at construction time to ensure the reader always
+ * knows which domains and routers to check (some fee contracts are not enumerable).
+ */
+export class FeeWriter
+  extends FeeReader
+  implements ArtifactWriter<FeeArtifactConfig, DeployedFeeAddress>
+{
+  constructor(
+    artifactManager: IRawFeeArtifactManager,
+    context: FeeReadContext,
+    private readonly signer: ISigner<AnnotatedTx, TxReceipt>,
+  ) {
+    super(artifactManager, context);
+  }
+
+  async create(
+    artifact: ArtifactNew<FeeArtifactConfig>,
+  ): Promise<[DeployedFeeArtifact, TxReceipt[]]> {
+    const { config } = artifact;
+    const writer = this.artifactManager.createWriter(config.type, this.signer);
+    return writer.create(artifact);
+  }
+
+  async update(artifact: DeployedFeeArtifact): Promise<AnnotatedTx[]> {
+    const { config } = artifact;
+    const writer = this.artifactManager.createWriter(config.type, this.signer);
+    return writer.update(artifact);
+  }
+}

typescript/deploy-sdk/src/index.ts

@@ -3,6 +3,8 @@
 // import { AltVMFileSubmitter } from '@hyperlane-xyz/deploy-sdk/AltVMFileSubmitter';
 
 export { AltVMJsonRpcSubmitter } from './AltVMJsonRpcSubmitter.js';
+export { createFeeReader, FeeReader } from './fee/fee-reader.js';
+export { createFeeWriter, FeeWriter } from './fee/fee-writer.js';
 export {
   CoreArtifactReader,
   createCoreReader,

typescript/deploy-sdk/src/warp/warp-reader.ts

@@ -2,13 +2,19 @@ import {
   ChainMetadataForAltVM,
   getProtocolProvider,
 } from '@hyperlane-xyz/provider-sdk';
+import { assert } from '@hyperlane-xyz/utils';
 import {
   Artifact,
   ArtifactReader,
   isArtifactDeployed,
   isArtifactUnderived,
 } from '@hyperlane-xyz/provider-sdk/artifact';
 import { ChainLookup } from '@hyperlane-xyz/provider-sdk/chain';
+import {
+  DeployedFeeAddress,
+  DeployedFeeArtifact,
+  FeeArtifactConfig,
+} from '@hyperlane-xyz/provider-sdk/fee';
 import {
   DeployedHookAddress,
   DeployedHookArtifact,
@@ -25,9 +31,11 @@ import {
   DerivedWarpConfig,
   IRawWarpArtifactManager,
   WarpArtifactConfig,
+  buildFeeReadContextFromWarpArtifactConfig,
   warpArtifactToDerivedConfig,
 } from '@hyperlane-xyz/provider-sdk/warp';
 
+import { createFeeReader } from '../fee/fee-reader.js';
 import { HookReader, createHookReader } from '../hook/hook-reader.js';
 import { IsmReader, createIsmReader } from '../ism/generic-ism.js';
 
@@ -69,12 +77,19 @@ export class WarpTokenReader implements ArtifactReader<
       rawArtifact.config.hook,
     );
 
+    // Expand nested Fee artifact if present
+    const expandedFeeArtifact = await this.expandFeeArtifact(
+      rawArtifact.config,
+      rawArtifact.config.fee,
+    );
+
     return {
       ...rawArtifact,
       config: {
         ...rawArtifact.config,
         interchainSecurityModule: expandedIsmArtifact,
         hook: expandedHookArtifact,
+        fee: expandedFeeArtifact,
       },
     };
   }
@@ -134,6 +149,40 @@ export class WarpTokenReader implements ArtifactReader<
     );
   }
 
+  /**
+   * Expands a Fee artifact by reading it if underived.
+   * Builds FeeReadContext from the warp config's remote routers and CC routers.
+   * Returns undefined only when no feeArtifact is provided. Deployed artifacts
+   * are returned as-is. Underived artifacts are read via the fee reader.
+   * Throws if a fee artifact exists but the protocol has no fee artifact manager.
+   */
+  private async expandFeeArtifact(
+    warpConfig: WarpArtifactConfig,
+    feeArtifact?: Artifact<FeeArtifactConfig, DeployedFeeAddress>,
+  ): Promise<DeployedFeeArtifact | undefined> {
+    if (!feeArtifact) {
+      return undefined;
+    }
+
+    if (isArtifactDeployed(feeArtifact)) {
+      return feeArtifact;
+    }
+
+    if (isArtifactUnderived(feeArtifact)) {
+      const context = buildFeeReadContextFromWarpArtifactConfig(warpConfig);
+      const feeReader = createFeeReader(this.chainMetadata, context);
+      assert(
+        feeReader,
+        `Fee artifact present on warp config but protocol ${this.chainMetadata.protocol} has no fee artifact manager`,
+      );
+      return feeReader.read(feeArtifact.deployed.address);
+    }
+
+    throw new Error(
+      `Unexpected Fee artifact state 'new' when reading warp token Fee configuration`,
+    );
+  }
+
   /**
    * Backward compatibility method that converts DeployedWarpArtifact to DerivedWarpConfig.
    * This allows WarpTokenReader to be used as a drop-in replacement for the old AltVMWarpRouteReader.