chore(runway): cherry-pick feat(predict): add confirmation hook plumbing (#30079)

- feat(predict): add confirmation hook plumbing (#29914)

## **Description**

This PR adds minimal Predict confirmation hook plumbing needed by the
upcoming Polymarket Deposit Wallet migration.

It wires TransactionController confirmation lifecycle hooks to
PredictController while keeping Predict behavior as passthrough by
default:

- `beforePublish` delegates to `PredictController.beforePublish`, which
currently returns `true`.
- `publish` delegates to `PredictController.publish` before Transaction
Pay / 7702 / Smart Transactions, and continues normal publishing when
Predict returns no transaction hash.
- If a future Predict publish implementation returns `{ transactionHash,
isIntentComplete: true }`, TransactionController marks the latest
transaction meta as `isIntentComplete` before returning the hash.

This PR intentionally contains no Polymarket Deposit Wallet business
logic. It is a small foundation PR for confirmation-team review.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: N/A — preparatory plumbing for the Predict Deposit Wallet
migration.

## **Manual testing steps**

```gherkin
Feature: Predict confirmation hook plumbing

  Scenario: non-Predict transactions continue through the normal publish flow
    Given a transaction is published through TransactionController
    And PredictController.publish returns no transaction hash

    When the publish hook runs
    Then Transaction Pay / 7702 / Smart Transaction publishing continues as before

  Scenario: Predict publish can complete a transaction intent
    Given PredictController.publish returns a transaction hash and isIntentComplete

    When the publish hook runs
    Then normal publishing is short-circuited
    And the latest TransactionController transaction meta is marked intent complete
```

Local validation run:

```bash
yarn jest app/core/Engine/controllers/transaction-controller/transaction-controller-init.test.ts app/components/UI/Predict/controllers/PredictController.test.ts --runInBand
yarn lint:tsc
```

## **Screenshots/Recordings**

N/A — no UI changes.

### **Before**

N/A

### **After**

N/A

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding

Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [ ] I've applied the right labels on the PR (see [labeling

guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [x] I've tested on Android
- N/A — hook plumbing only, no UI/runtime performance path manually
exercised.
- [x] I've tested with a power user scenario
  - N/A — hook plumbing only, no account/token rendering path changed.
- [x] I've instrumented key operations with Sentry traces for production
performance metrics
  - N/A — this PR only adds passthrough hook plumbing.

For performance guidelines and tooling, see the [Performance

Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches transaction publishing lifecycle by adding new hooks and a
short-circuit path, which could affect submission ordering and
integration with Pay/7702/Smart Transactions if miswired. Default
behavior remains passthrough, reducing blast radius.
> 
> **Overview**
> Adds Predict-specific confirmation hook plumbing into the transaction
submission lifecycle. TransactionController init now calls
`PredictController:beforePublish` as a new `hooks.beforePublish`, and
calls `PredictController:publish` at the start of `hooks.publish`,
**short-circuiting** the rest of the publish pipeline when Predict
returns a `transactionHash`.
> 
> Updates PredictController to expose new messenger methods
(`beforePublish`, `publish`) with default passthrough implementations,
extends messenger action typings/permissions accordingly, and adds unit
tests verifying delegation, call ordering, and the short-circuit
behavior.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
3f9d618. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
[e5a8b17](e5a8b17)

Co-authored-by: Luis Taniça <matallui@gmail.com>

Author: runway-github[bot]

app/components/UI/Predict/controllers/PredictController-method-action-types.ts

@@ -248,11 +248,21 @@ export type PredictControllerPrepareWithdrawAction = {
   handler: PredictController['prepareWithdraw'];
 };
 
+export type PredictControllerBeforePublishAction = {
+  type: `PredictController:beforePublish`;
+  handler: PredictController['beforePublish'];
+};
+
 export type PredictControllerBeforeSignAction = {
   type: `PredictController:beforeSign`;
   handler: PredictController['beforeSign'];
 };
 
+export type PredictControllerPublishAction = {
+  type: `PredictController:publish`;
+  handler: PredictController['publish'];
+};
+
 export type PredictControllerClearWithdrawTransactionAction = {
   type: `PredictController:clearWithdrawTransaction`;
   handler: PredictController['clearWithdrawTransaction'];
@@ -300,5 +310,7 @@ export type PredictControllerMethodActions =
   | PredictControllerGetAccountStateAction
   | PredictControllerGetBalanceAction
   | PredictControllerPrepareWithdrawAction
+  | PredictControllerBeforePublishAction
   | PredictControllerBeforeSignAction
+  | PredictControllerPublishAction
   | PredictControllerClearWithdrawTransactionAction;

app/components/UI/Predict/controllers/PredictController.test.ts

@@ -6139,6 +6139,40 @@ describe('PredictController', () => {
     });
   });
 
+  describe('beforePublish', () => {
+    it('passes through by default', async () => {
+      await withController(async ({ controller }) => {
+        const result = await controller.beforePublish({
+          transactionMeta: {
+            id: 'tx-1',
+            txParams: {
+              from: MOCK_ADDRESS,
+            },
+          } as TransactionMeta,
+        });
+
+        expect(result).toBe(true);
+      });
+    });
+  });
+
+  describe('publish', () => {
+    it('passes through by default', async () => {
+      await withController(async ({ controller }) => {
+        const result = await controller.publish({
+          transactionMeta: {
+            id: 'tx-1',
+            txParams: {
+              from: MOCK_ADDRESS,
+            },
+          } as TransactionMeta,
+        });
+
+        expect(result).toEqual({ transactionHash: undefined });
+      });
+    });
+  });
+
   describe('beforeSign', () => {
     const mockTransactionMeta = {
       id: 'tx-1',

app/components/UI/Predict/controllers/PredictController.ts

@@ -345,6 +345,7 @@ export interface PredictControllerOptions {
 }
 
 const MESSENGER_EXPOSED_METHODS = [
+  'beforePublish',
   'beforeSign',
   'claimWithConfirmation',
   'clearActiveOrder',
@@ -370,6 +371,7 @@ const MESSENGER_EXPOSED_METHODS = [
   'onPlaceOrderSuccess',
   'placeOrder',
   'prepareWithdraw',
+  'publish',
   'previewOrder',
   'refreshEligibility',
   'selectPaymentToken',
@@ -2619,6 +2621,12 @@ export class PredictController extends BaseController<
     }
   }
 
+  public async beforePublish(_request: {
+    transactionMeta: TransactionMeta;
+  }): Promise<boolean> {
+    return true;
+  }
+
   public async beforeSign(request: {
     transactionMeta: TransactionMeta;
   }): Promise<
@@ -2722,6 +2730,12 @@ export class PredictController extends BaseController<
     };
   }
 
+  public async publish(_request: {
+    transactionMeta: TransactionMeta;
+  }): Promise<{ transactionHash?: string }> {
+    return { transactionHash: undefined };
+  }
+
   public clearWithdrawTransaction(): void {
     this.update((state) => {
       state.withdrawTransaction = null;
@@ -2730,6 +2744,7 @@ export class PredictController extends BaseController<
 }
 
 export type {
+  PredictControllerBeforePublishAction,
   PredictControllerBeforeSignAction,
   PredictControllerClaimWithConfirmationAction,
   PredictControllerClearActiveOrderAction,
@@ -2754,6 +2769,7 @@ export type {
   PredictControllerPlaceOrderAction,
   PredictControllerPrepareWithdrawAction,
   PredictControllerPreviewOrderAction,
+  PredictControllerPublishAction,
   PredictControllerRefreshEligibilityAction,
   PredictControllerSelectPaymentTokenAction,
   PredictControllerSetSelectedPaymentTokenAction,

app/core/Engine/controllers/transaction-controller/transaction-controller-init.test.ts

@@ -92,10 +92,20 @@ const MOCK_TRANSACTION_META = {
  * with the default mock.
  * @returns A mock NetworkController.
  */
+type ControllerMock = NetworkController & {
+  beforePublish: jest.Mock;
+  beforeSign: jest.Mock;
+  publish: jest.Mock;
+};
+
 function buildControllerMock(
-  partialMock?: Partial<NetworkController>,
-): NetworkController {
-  const defaultControllerMocks = {};
+  partialMock?: Partial<ControllerMock>,
+): ControllerMock {
+  const defaultControllerMocks = {
+    beforePublish: jest.fn().mockResolvedValue(true),
+    beforeSign: jest.fn(),
+    publish: jest.fn().mockResolvedValue({ transactionHash: undefined }),
+  };
 
   // @ts-expect-error Incomplete mock, just includes properties used by code-under-test.
   return {
@@ -112,22 +122,43 @@ function buildInitRequestMock(
     TransactionControllerInitMessenger
   >
 > {
+  const {
+    predictControllerMock: providedPredictControllerMock,
+    ...requestOverrides
+  } = initRequestProperties;
+  const predictControllerMock =
+    (providedPredictControllerMock as ControllerMock | undefined) ??
+    buildControllerMock();
   const initMessenger = new ExtendedMessenger<MockAnyNamespace>({
     namespace: MOCK_ANY_NAMESPACE,
   });
   const baseControllerMessenger = new ExtendedMessenger<MockAnyNamespace>({
     namespace: MOCK_ANY_NAMESPACE,
   });
+  (initMessenger as unknown as { call: jest.Mock }).call = jest.fn(
+    (actionType: string, params: unknown) => {
+      if (actionType === 'PredictController:beforePublish') {
+        return predictControllerMock.beforePublish(params);
+      }
+
+      if (actionType === 'PredictController:publish') {
+        return predictControllerMock.publish(params);
+      }
+
+      throw new Error(`Unexpected init messenger action: ${actionType}`);
+    },
+  );
+
   const requestMock = {
     ...buildMessengerClientInitRequestMock(baseControllerMessenger),
     initMessenger:
       initMessenger as unknown as TransactionControllerInitMessenger,
     controllerMessenger:
       baseControllerMessenger as unknown as TransactionControllerMessenger,
-    ...initRequestProperties,
+    ...requestOverrides,
   };
 
-  if (!initRequestProperties.getMessengerClient) {
+  if (!requestOverrides.getMessengerClient) {
     requestMock.getMessengerClient.mockReturnValue(buildControllerMock());
   }
 
@@ -180,9 +211,11 @@ describe('Transaction Controller Init', () => {
   ): TransactionControllerOptions[T] {
     const requestMock = buildInitRequestMock(initRequestProperties);
 
-    requestMock.getMessengerClient.mockReturnValue(
-      buildControllerMock(dependencyProperties),
-    );
+    if (!initRequestProperties.getMessengerClient) {
+      requestMock.getMessengerClient.mockReturnValue(
+        buildControllerMock(dependencyProperties),
+      );
+    }
 
     TransactionControllerInit(requestMock);
 
@@ -320,6 +353,25 @@ describe('Transaction Controller Init', () => {
     expect(optionFn?.()).toBe(false);
   });
 
+  describe('beforePublish hook', () => {
+    it('delegates to PredictController beforePublish', async () => {
+      const predictControllerMock = buildControllerMock();
+      const hooks = testConstructorOption(
+        'hooks',
+        {},
+        {
+          predictControllerMock,
+        },
+      );
+
+      await hooks?.beforePublish?.(MOCK_TRANSACTION_META);
+
+      expect(predictControllerMock.beforePublish).toHaveBeenCalledWith({
+        transactionMeta: MOCK_TRANSACTION_META,
+      });
+    });
+  });
+
   describe('publish hook', () => {
     it('calls submitSmartTransactionHook', async () => {
       const hooks = testConstructorOption('hooks');
@@ -347,6 +399,53 @@ describe('Transaction Controller Init', () => {
       expect(payHookMock).toHaveBeenCalledTimes(1);
     });
 
+    it('calls Predict publish before pay and smart transaction hooks', async () => {
+      const predictControllerMock = buildControllerMock();
+      const hooks = testConstructorOption(
+        'hooks',
+        {},
+        {
+          predictControllerMock,
+        },
+      );
+
+      await hooks?.publish?.(MOCK_TRANSACTION_META);
+
+      expect(predictControllerMock.publish).toHaveBeenCalledWith({
+        transactionMeta: MOCK_TRANSACTION_META,
+      });
+      expect(payHookMock).toHaveBeenCalledTimes(1);
+      expect(
+        (predictControllerMock.publish as jest.Mock).mock
+          .invocationCallOrder[0],
+      ).toBeLessThan(payHookMock.mock.invocationCallOrder[0]);
+      expect(
+        (predictControllerMock.publish as jest.Mock).mock
+          .invocationCallOrder[0],
+      ).toBeLessThan(
+        submitSmartTransactionHookMock.mock.invocationCallOrder[0],
+      );
+    });
+
+    it('short-circuits publish when Predict returns a transaction hash', async () => {
+      const predictControllerMock = buildControllerMock({
+        publish: jest.fn().mockResolvedValue({ transactionHash: '0xpredict' }),
+      } as unknown as Partial<NetworkController>);
+      const hooks = testConstructorOption(
+        'hooks',
+        {},
+        {
+          predictControllerMock,
+        },
+      );
+
+      const result = await hooks?.publish?.(MOCK_TRANSACTION_META);
+
+      expect(result).toEqual({ transactionHash: '0xpredict' });
+      expect(payHookMock).not.toHaveBeenCalled();
+      expect(submitSmartTransactionHookMock).not.toHaveBeenCalled();
+    });
+
     it('passes isSmartTransaction returning false to pay hook when stxDisabled is true', async () => {
       selectMetaMaskPayFlagsMock.mockReturnValue({
         attemptsMax: 2,

app/core/Engine/controllers/transaction-controller/transaction-controller-init.ts

@@ -136,6 +136,8 @@ export const TransactionControllerInit: MessengerClientInitFunction<
               transactions:
                 _request.transactions as PublishBatchHookTransaction[],
             }),
+          beforePublish: (transactionMeta: TransactionMeta) =>
+            beforePublish(transactionMeta, initMessenger),
           beforeSign: (_request: { transactionMeta: TransactionMeta }) =>
             beforeSign(_request, request),
         },
@@ -226,6 +228,15 @@ async function publishHook({
   initMessenger: TransactionControllerInitMessenger;
   signedTransactionInHex: Hex;
 }): Promise<{ transactionHash?: string }> {
+  const { transactionHash: predictTransactionHash } = await initMessenger.call(
+    'PredictController:publish',
+    { transactionMeta },
+  );
+
+  if (predictTransactionHash) {
+    return { transactionHash: predictTransactionHash };
+  }
+
   const state = getState();
 
   const { shouldUseSmartTransaction, featureFlags } =
@@ -441,6 +452,15 @@ function getControllers(
   };
 }
 
+function beforePublish(
+  transactionMeta: TransactionMeta,
+  initMessenger: TransactionControllerInitMessenger,
+) {
+  return initMessenger.call('PredictController:beforePublish', {
+    transactionMeta,
+  });
+}
+
 function beforeSign(
   hookRequest: { transactionMeta: TransactionMeta },
   request: MessengerClientInitRequest<

app/core/Engine/messengers/transaction-controller-messenger/transaction-controller-messenger.ts

@@ -55,6 +55,10 @@ import {
   MessengerActions,
   MessengerEvents,
 } from '@metamask/messenger';
+import type {
+  PredictControllerBeforePublishAction,
+  PredictControllerPublishAction,
+} from '../../../../components/UI/Predict/controllers/PredictController-method-action-types';
 
 export function getTransactionControllerMessenger(
   rootMessenger: RootMessenger,
@@ -114,7 +118,9 @@ type InitMessengerActions =
   | TransactionPayControllerGetDelegationTransactionAction
   | TransactionPayControllerGetStateAction
   | TransactionPayControllerGetStrategyAction
-  | AnalyticsControllerActions;
+  | AnalyticsControllerActions
+  | PredictControllerBeforePublishAction
+  | PredictControllerPublishAction;
 
 type InitMessengerEvents =
   | BridgeStatusControllerEvents
@@ -173,6 +179,8 @@ export function getTransactionControllerInitMessenger(
       'TransactionPayController:getState',
       'TransactionPayController:getStrategy',
       'AnalyticsController:trackEvent',
+      'PredictController:beforePublish',
+      'PredictController:publish',
     ],
     events: [
       'BridgeStatusController:stateChange',