feat: add sequential batch support (#5762)

## Explanation

The `TransactionController` currently lacks support for sequential batch
transactions, which are required for the stablecoin lending feature.
Specifically, there is no mechanism to execute multiple transactions
(e.g., approval + token deposit) sequentially while ensuring
confirmation for each transaction. This limitation prevents efficient
batch processing to support new features.

**What solution do these changes offer?**
The `SequentialPublishBatchHook` introduces a default mechanism for
handling batch transactions when no custom `publishBatchHook` is
provided. It ensures transactions are published sequentially, waiting
for confirmation before proceeding to the next. If any transaction fails
to publish or confirm, the batch process halts and throws an error.

**Key Features:**

- Sequential Execution: Publishes transactions one at a time and waits
for confirmation.
- Error Handling: Halts the batch if any transaction fails to publish or
confirm.
- Polling for Confirmation: Retries confirmation checks up to a maximum
number of attempts.

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

 Fixes MetaMask/MetaMask-planning#4695

## Changelog

<!--
THIS SECTION IS NO LONGER NEEDED.

The process for updating changelogs has changed. Please consult the
"Updating changelogs" section of the Contributing doc for more.
-->

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [ ] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

Author: vinistevam

packages/transaction-controller/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add sequential batch support when `publishBatchHook` is not defined ([#5762](https://github.com/MetaMask/core/pull/5762))
+
 ### Fixed
 
 - Fix `userFeeLevel` as `dappSuggested` initially when dApp suggested gas values for legacy transactions ([#5821](https://github.com/MetaMask/core/pull/5821))

packages/transaction-controller/src/TransactionController.ts

@@ -1024,6 +1024,11 @@ export class TransactionController extends BaseController<
   async addTransactionBatch(
     request: TransactionBatchRequest,
   ): Promise<TransactionBatchResult> {
+    const { blockTracker } = this.messagingSystem.call(
+      `NetworkController:getNetworkClientById`,
+      request.networkClientId,
+    );
+
     return await addTransactionBatch({
       addTransaction: this.addTransaction.bind(this),
       getChainId: this.#getChainId.bind(this),
@@ -1036,6 +1041,17 @@ export class TransactionController extends BaseController<
       publicKeyEIP7702: this.#publicKeyEIP7702,
       request,
       updateTransaction: this.#updateTransactionInternal.bind(this),
+      publishTransaction: (
+        ethQuery: EthQuery,
+        transactionMeta: TransactionMeta,
+      ) => this.#publishTransaction(ethQuery, transactionMeta) as Promise<Hex>,
+      getPendingTransactionTracker: (networkClientId: NetworkClientId) =>
+        this.#createPendingTransactionTracker({
+          provider: this.#getProvider({ networkClientId }),
+          blockTracker,
+          chainId: this.#getChainId(networkClientId),
+          networkClientId,
+        }),
     });
   }
 

packages/transaction-controller/src/helpers/PendingTransactionTracker.test.ts

@@ -1151,4 +1151,53 @@ describe('PendingTransactionTracker', () => {
       expect(transactionMeta.txReceipt).toBeUndefined();
     });
   });
+
+  describe('addTransactionToPoll', () => {
+    it('adds a transaction to poll and sets #transactionToForcePoll', () => {
+      pendingTransactionTracker = new PendingTransactionTracker(options);
+
+      pendingTransactionTracker.addTransactionToPoll(
+        TRANSACTION_SUBMITTED_MOCK,
+      );
+
+      expect(transactionPoller.setPendingTransactions).toHaveBeenCalledWith([
+        TRANSACTION_SUBMITTED_MOCK,
+      ]);
+      expect(transactionPoller.start).toHaveBeenCalledTimes(1);
+    });
+
+    describe('emits confirm event and clean transactionToForcePoll', () => {
+      it('if receipt has success status', async () => {
+        const transaction = { ...TRANSACTION_SUBMITTED_MOCK };
+        const getTransactions = jest
+          .fn()
+          .mockReturnValue(freeze([transaction], true));
+
+        pendingTransactionTracker = new PendingTransactionTracker({
+          ...options,
+          getTransactions,
+        });
+
+        pendingTransactionTracker.addTransactionToPoll(
+          TRANSACTION_SUBMITTED_MOCK,
+        );
+
+        const listener = jest.fn();
+        pendingTransactionTracker.hub.addListener(
+          'transaction-confirmed',
+          listener,
+        );
+
+        queryMock.mockResolvedValueOnce(RECEIPT_MOCK);
+        queryMock.mockResolvedValueOnce(BLOCK_MOCK);
+
+        await onPoll();
+
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(listener).toHaveBeenCalledWith(
+          expect.objectContaining(TRANSACTION_SUBMITTED_MOCK),
+        );
+      });
+    });
+  });
 });

packages/transaction-controller/src/helpers/PendingTransactionTracker.ts

@@ -93,6 +93,8 @@ export class PendingTransactionTracker {
 
   readonly #transactionPoller: TransactionPoller;
 
+  #transactionToForcePoll: TransactionMeta | undefined;
+
   readonly #beforeCheckPendingTransaction: (
     transactionMeta: TransactionMeta,
   ) => Promise<boolean>;
@@ -139,6 +141,7 @@ export class PendingTransactionTracker {
     this.#getGlobalLock = getGlobalLock;
     this.#publishTransaction = publishTransaction;
     this.#running = false;
+    this.#transactionToForcePoll = undefined;
 
     this.#transactionPoller = new TransactionPoller({
       blockTracker,
@@ -167,6 +170,22 @@ export class PendingTransactionTracker {
     }
   };
 
+  /**
+   * Adds a transaction to the polling mechanism for monitoring its status.
+   *
+   * This method forcefully adds a single transaction to the list of transactions
+   * being polled, ensuring that its status is checked, event emitted but no update is performed.
+   * It overrides the default behavior by prioritizing the given transaction for polling.
+   *
+   * @param transactionMeta - The transaction metadata to be added for polling.
+   *
+   * The transaction will now be monitored for updates, such as confirmation or failure.
+   */
+  addTransactionToPoll(transactionMeta: TransactionMeta): void {
+    this.#start([transactionMeta]);
+    this.#transactionToForcePoll = transactionMeta;
+  }
+
   /**
    * Force checks the network if the given transaction is confirmed and updates it's status.
    *
@@ -232,7 +251,10 @@ export class PendingTransactionTracker {
   async #checkTransactions() {
     this.#log('Checking transactions');
 
-    const pendingTransactions = this.#getPendingTransactions();
+    const pendingTransactions: TransactionMeta[] = [
+      ...this.#getPendingTransactions(),
+      ...(this.#transactionToForcePoll ? [this.#transactionToForcePoll] : []),
+    ];
 
     if (!pendingTransactions.length) {
       this.#log('No pending transactions to check');
@@ -353,6 +375,12 @@ export class PendingTransactionTracker {
     return blocksSinceFirstRetry >= requiredBlocksSinceFirstRetry;
   }
 
+  #cleanTransactionToForcePoll(transactionId: string) {
+    if (this.#transactionToForcePoll?.id === transactionId) {
+      this.#transactionToForcePoll = undefined;
+    }
+  }
+
   async #checkTransaction(txMeta: TransactionMeta) {
     const { hash, id } = txMeta;
 
@@ -429,6 +457,12 @@ export class PendingTransactionTracker {
 
     this.#log('Transaction confirmed', id);
 
+    if (this.#transactionToForcePoll) {
+      this.#cleanTransactionToForcePoll(txMeta.id);
+      this.hub.emit('transaction-confirmed', txMeta);
+      return;
+    }
+
     const { baseFeePerGas, timestamp: blockTimestamp } =
       await this.#getBlockByHash(blockHash, false);
 
@@ -525,11 +559,13 @@ export class PendingTransactionTracker {
 
   #failTransaction(txMeta: TransactionMeta, error: Error) {
     this.#log('Transaction failed', txMeta.id, error);
+    this.#cleanTransactionToForcePoll(txMeta.id);
     this.hub.emit('transaction-failed', txMeta, error);
   }
 
   #dropTransaction(txMeta: TransactionMeta) {
     this.#log('Transaction dropped', txMeta.id);
+    this.#cleanTransactionToForcePoll(txMeta.id);
     this.hub.emit('transaction-dropped', txMeta);
   }