feat: Modular Tx Submission – Create Transformer + Submitter + Builder Abstraction

.changeset/blue-kings-compare.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/sdk': minor
+---
+
+Adds modular transaction submission support for SDK clients, e.g. CLI.

typescript/sdk/package.json

@@ -7,6 +7,8 @@
     "@cosmjs/stargate": "^0.31.3",
     "@hyperlane-xyz/core": "3.10.0",
     "@hyperlane-xyz/utils": "3.10.0",
+    "@safe-global/api-kit": "1.3.0",
+    "@safe-global/protocol-kit": "1.3.0",
     "@solana/spl-token": "^0.3.8",
     "@solana/web3.js": "^1.78.0",
     "@types/coingecko-api": "^1.0.10",
@@ -17,6 +19,7 @@
     "cross-fetch": "^3.1.5",
     "ethers": "^5.7.2",
     "pino": "^8.19.0",
+    "stack-typescript": "^1.0.4",
     "viem": "^1.20.0",
     "zod": "^3.21.2"
   },

typescript/sdk/src/providers/MultiProvider.ts

@@ -349,7 +349,7 @@ export class MultiProvider<MetaExt = {}> extends ChainMetadataManager<MetaExt> {
     tx: PopulatedTransaction,
     from?: string,
   ): Promise<providers.TransactionRequest> {
-    const txFrom = from ? from : await this.getSignerAddress(chainNameOrId);
+    const txFrom = from ?? (await this.getSignerAddress(chainNameOrId));
     const overrides = this.getTransactionOverrides(chainNameOrId);
     return {
       ...tx,

typescript/sdk/src/providers/transactions/submitter/TxSubmitter.ts

@@ -0,0 +1,30 @@
+import { ChainName } from '../../../types.js';
+import { MultiProvider } from '../../MultiProvider.js';
+import {
+  TypedTransaction,
+  TypedTransactionReceipt,
+} from '../../ProviderType.js';
+
+import { TxSubmitterType } from './TxSubmitterTypes.js';
+
+export interface TxSubmitterInterface<
+  TX extends TypedTransaction,
+  TR extends TypedTransactionReceipt,
+> {
+  /**
+   * Defines the type of tx submitter.
+   */
+  txSubmitterType: TxSubmitterType;
+  multiProvider: MultiProvider;
+  chain: ChainName;
+  /**
+   * Should execute all transactions and return their receipts.
+   * @param txs The array of transactions to execute
+   */
+  submitTxs(txs: TX[]): Promise<TR[] | void>;
+  /**
+   * Should execute a transaction and return its receipt.
+   * @param tx The transaction to execute
+   */
+  submitTx?(tx: TX): Promise<TR | void>;
+}

typescript/sdk/src/providers/transactions/submitter/TxSubmitterTypes.ts

@@ -0,0 +1,5 @@
+export enum TxSubmitterType {
+  JSON_RPC = 'Json RPC',
+  IMPERSONATED_ACCOUNT = 'Impersonated Account',
+  GNOSIS_SAFE = 'Gnosis Safe',
+}

typescript/sdk/src/providers/transactions/submitter/builder/TxSubmitterBuilder.ts

@@ -0,0 +1,109 @@
+import assert from 'assert';
+import { Logger } from 'pino';
+import { Stack } from 'stack-typescript';
+
+import { rootLogger } from '@hyperlane-xyz/utils';
+
+import {
+  TypedTransaction,
+  TypedTransactionReceipt,
+} from '../../../ProviderType.js';
+import { TxTransformerInterface } from '../../transformer/TxTransformer.js';
+import { TxSubmitterInterface } from '../TxSubmitter.js';
+
+/**
+ * Builds a TxSubmitterBuilder for batch transaction submission.
+ *
+ * Example use-cases:
+ *  const eV5builder = new TxSubmitterBuilder<EV5Transaction, EV5TransactionReceipt>();
+ *  let txReceipts = eV5builder.for(
+ *    new GnosisSafeTxSubmitter(chainA)
+ *  ).transform(
+ *    InterchainAccountTxTransformer(chainB)
+ *  ).submit(
+ *    txs
+ *  );
+ *  txReceipts = eV5builder.for(
+ *    new ImpersonatedAccountTxSubmitter(chainA)
+ *  ).submit(txs);
+ *  txReceipts = eV5builder.for(
+ *    new JsonRpcTxSubmitter(chainC)
+ *  ).submit(txs);
+ */
+export class TxSubmitterBuilder<
+  TX extends TypedTransaction,
+  TR extends TypedTransactionReceipt,
+> {
+  protected readonly logger: Logger = rootLogger.child({
+    module: 'submitter-builder',
+  });
+
+  private currentSubmitter?: TxSubmitterInterface<TX, TR>;
+
+  constructor(
+    private readonly currentTransformers: Stack<
+      TxTransformerInterface<TX>
+    > = new Stack<TxTransformerInterface<TX>>(),
+  ) {}
+
+  /**
+   * Sets the current submitter for the builder.
+   * @param txSubmitterOrType The submitter to add to the builder
+   */
+  public for(
+    txSubmitter: TxSubmitterInterface<TX, TR>,
+  ): TxSubmitterBuilder<TX, TR> {
+    this.currentSubmitter = txSubmitter;
+    return this;
+  }
+
+  /**
+   * Adds a transformer for the builder.
+   * @param txTransformerOrType The transformer to add to the builder
+   */
+  public transform(
+    txTransformer: TxTransformerInterface<TX>,
+  ): TxSubmitterBuilder<TX, TR> {
+    assert(
+      this.currentSubmitter,
+      'No submitter specified for which to execute the transform.',
+    );
+
+    this.currentTransformers.push(txTransformer);
+    return this;
+  }
+
+  /**
+   * Submits a set of transactions to the builder.
+   * @param txs The transactions to submit
+   */
+  public async submit(txs: TX[]): Promise<TR[]> {
+    assert(
+      this.currentSubmitter,
+      'Must specify submitter to submit transactions.',
+    );
+
+    this.logger.info(
+      `Submitting ${txs.length} transactions to the ${this.currentSubmitter.txSubmitterType} submitter...`,
+    );
+
+    let transformedTxs = txs;
+    while (this.currentTransformers.size > 0) {
+      const currentTransformer: TxTransformerInterface<TX> =
+        this.currentTransformers.pop();
+      transformedTxs = await currentTransformer.transformTxs(transformedTxs);
+      this.logger.info(
+        `🔄 Transformed ${transformedTxs.length} transactions with the ${currentTransformer.txTransformerType} transformer...`,
+      );
+    }
+
+    const txReceipts = await this.currentSubmitter.submitTxs(transformedTxs);
+    this.logger.info(
+      `✅ Successfully submitted ${transformedTxs.length} transactions to the ${this.currentSubmitter.txSubmitterType} submitter.`,
+    );
+
+    this.currentSubmitter = undefined;
+
+    return txReceipts ?? [];
+  }
+}

typescript/sdk/src/providers/transactions/submitter/ethersV5/GnosisSafeTxSubmitter.ts

@@ -0,0 +1,112 @@
+import SafeApiKit from '@safe-global/api-kit';
+import Safe, { EthSafeSignature } from '@safe-global/protocol-kit';
+import assert from 'assert';
+import { Logger } from 'pino';
+
+import { Address, rootLogger } from '@hyperlane-xyz/utils';
+
+import { ChainName } from '../../../../types.js';
+import { getSafe, getSafeService } from '../../../../utils/gnosisSafe.js';
+import { MultiProvider } from '../../../MultiProvider.js';
+import {
+  EthersV5Transaction,
+  EthersV5TransactionReceipt,
+} from '../../../ProviderType.js';
+import { TxSubmitterInterface } from '../TxSubmitter.js';
+import { TxSubmitterType } from '../TxSubmitterTypes.js';
+
+enum OperationType {
+  Call = 0,
+  DelegateCall = 1,
+}
+
+interface MetaTransactionData {
+  to: string;
+  value: string;
+  data: string;
+  operation?: OperationType;
+}
+
+interface SafeTransactionData extends MetaTransactionData {
+  operation: OperationType;
+  safeTxGas: string;
+  baseGas: string;
+  gasPrice: string;
+  gasToken: string;
+  refundReceiver: string;
+  nonce: number;
+}
+
+interface GnosisSafeTxSubmitterProps {
+  safeAddress: Address;
+  signerAddress?: Address;
+}
+
+export class GnosisSafeTxSubmitter
+  implements
+    TxSubmitterInterface<EthersV5Transaction, EthersV5TransactionReceipt>
+{
+  public readonly txSubmitterType: TxSubmitterType =
+    TxSubmitterType.GNOSIS_SAFE;
+
+  protected readonly logger: Logger = rootLogger.child({
+    module: 'gnosis-safe-submitter',
+  });
+
+  constructor(
+    public readonly multiProvider: MultiProvider,
+    public readonly chain: ChainName,
+    public readonly props: GnosisSafeTxSubmitterProps,
+  ) {}
+
+  public async submitTxs(txs: EthersV5Transaction[]): Promise<void> {
+    const safe: Safe.default = await getSafe(
+      this.chain,
+      this.multiProvider,
+      this.props.safeAddress,
+    );
+    const safeService: SafeApiKit.default = getSafeService(
+      this.chain,
+      this.multiProvider,
+    );
+    const nextNonce: number = await safeService.getNextNonce(
+      this.props.safeAddress,
+    );
+    const safeTransactionBatch: MetaTransactionData[] = txs.map(
+      ({ transaction }: EthersV5Transaction) => {
+        const { to, data, value } = transaction;
+        assert(
+          to && data,
+          'Invalid EthersV5Transaction: Missing required metadata.',
+        );
+        return { to, data, value: value?.toString() ?? '0' };
+      },
+    );
+    const safeTransaction = await safe.createTransaction({
+      safeTransactionData: safeTransactionBatch,
+      options: { nonce: nextNonce },
+    });
+    const safeTransactionData: SafeTransactionData = safeTransaction.data;
+    const safeTxHash: string = await safe.getTransactionHash(safeTransaction);
+    let senderAddress: Address | undefined = this.props.signerAddress;
+    if (!senderAddress) {
+      senderAddress = await this.multiProvider.getSignerAddress(this.chain);
+    }
+    const safeSignature: EthSafeSignature = await safe.signTransactionHash(
+      safeTxHash,
+    );
+    const senderSignature: string = safeSignature.data;
+
+    this.logger.debug(
+      `Submitting transaction proposal to ${this.props.safeAddress} on ${this.chain}: ${safeTxHash}`,
+    );
+
+    return safeService.proposeTransaction({
+      safeAddress: this.props.safeAddress,
+      safeTransactionData,
+      safeTxHash,
+      senderAddress,
+      senderSignature,
+    });
+  }
+}

typescript/sdk/src/providers/transactions/submitter/ethersV5/ImpersonatedAccountTxSubmitter.ts

@@ -0,0 +1,66 @@
+import { ContractReceipt } from 'ethers';
+import { Logger } from 'pino';
+
+import { rootLogger } from '@hyperlane-xyz/utils';
+import { Address } from '@hyperlane-xyz/utils';
+
+import { ChainName } from '../../../../types.js';
+import { impersonateAccount } from '../../../../utils/fork.js';
+import { MultiProvider } from '../../../MultiProvider.js';
+import {
+  EthersV5Transaction,
+  EthersV5TransactionReceipt,
+  ProviderType,
+} from '../../../ProviderType.js';
+import { TxSubmitterInterface } from '../TxSubmitter.js';
+import { TxSubmitterType } from '../TxSubmitterTypes.js';
+
+interface ImpersonatedAccountTxSubmitterProps {
+  address: Address;
+}
+
+export class ImpersonatedAccountTxSubmitter
+  implements
+    TxSubmitterInterface<EthersV5Transaction, EthersV5TransactionReceipt>
+{
+  public readonly txSubmitterType: TxSubmitterType =
+    TxSubmitterType.IMPERSONATED_ACCOUNT;
+
+  protected readonly logger: Logger = rootLogger.child({
+    module: 'impersonated-account-submitter',
+  });
+
+  constructor(
+    public readonly multiProvider: MultiProvider,
+    public readonly chain: ChainName,
+    public readonly props: ImpersonatedAccountTxSubmitterProps,
+  ) {}
+
+  public async submitTxs(
+    txs: EthersV5Transaction[],
+  ): Promise<EthersV5TransactionReceipt[]> {
+    const receipts: EthersV5TransactionReceipt[] = [];
+    for (const tx of txs) {
+      const receipt = await this.submitTx(tx);
+      receipts.push(receipt);
+    }
+    return receipts;
+  }
+
+  public async submitTx(
+    tx: EthersV5Transaction,
+  ): Promise<EthersV5TransactionReceipt> {
+    const signer = await impersonateAccount(this.props.address);
+    this.multiProvider.setSigner(this.chain, signer);
+    const receipt: ContractReceipt = await this.multiProvider.sendTransaction(
+      this.chain,
+      tx.transaction,
+    );
+
+    this.logger.debug(
+      `Submitted EthersV5Transaction on ${this.chain}: ${receipt.transactionHash}`,
+    );
+
+    return { type: ProviderType.EthersV5, receipt };
+  }
+}