…foundation (#29917)

## **Description**

This is PR 2 for the Predict Deposit Wallet migration and is temporarily
opened against `predict/dw-confirmation-hooks` to accelerate review
while PR 1 is reviewed. Once PR 1 merges, this PR should be
rebased/retargeted to `main`.

Polymarket migrated new API users from the legacy Safe/proxy wallet
model to deterministic Deposit Wallets. This PR adds the shared Predict
Deposit Wallet foundation and enables the deposit flow while preserving
legacy Safe behavior for users with existing Polymarket activity.

Included changes:

- Adds `walletType` to Predict account state and routes users by legacy
Safe activity:
  - legacy Safe with raw Polymarket activity stays on Safe
  - legacy Safe without activity routes to Deposit Wallet
  - deployed legacy Safe + Activity API failure fails closed
- Adds Deposit Wallet helper utilities for deterministic address
derivation, relayer proxy calls, polling, EIP-712 batch execution, and
CLOB balance-allowance sync.
- Adds Deposit Wallet deposit preflight to deploy/setup allowances in
`beforePublish`.
- Adds legacy Safe migration sweep planning for zero-activity users with
stranded pUSD/USDC.e.
- Updates deposit preparation so Deposit Wallet users receive pUSD
transfers to their Deposit Wallet.
- Updates balance/position lookup to use the active Predict wallet.
- Adds post-confirm best-effort CLOB balance-allowance sync for Deposit
Wallet deposits and deposit-and-order deposits.
- Keeps order and claim execution support out of scope for this PR;
those follow in separate PRs.

Validation performed:

- `yarn jest
app/components/UI/Predict/providers/polymarket/depositWallet.test.ts
app/components/UI/Predict/providers/polymarket/preflight/legacySafeMigration.test.ts
app/components/UI/Predict/providers/polymarket/preflight/depositWallet.test.ts
app/components/UI/Predict/providers/polymarket/preflight/v2AllowanceRequirements.test.ts
app/components/UI/Predict/providers/polymarket/PolymarketProvider.test.ts
app/components/UI/Predict/controllers/PredictController.test.ts
app/components/UI/Predict/hooks/usePredictAccountState.test.ts
--runInBand --forceExit`
- `yarn lint:tsc`

## **Changelog**

CHANGELOG entry: Added support for Polymarket Deposit Wallet deposits in
Predict

## **Related issues**

Fixes:
[PRED-858](https://consensyssoftware.atlassian.net/browse/PRED-858)

## **Manual testing steps**

```gherkin
Feature: Predict Deposit Wallet deposits

  Scenario: new Predict user deposits to a Polymarket Deposit Wallet
    Given the selected wallet has no legacy Safe Polymarket activity
    And the user opens Predict deposit

    When user confirms a Predict deposit
    Then the Deposit Wallet setup preflight runs through the relayer
    And the pUSD deposit transaction transfers funds to the derived Deposit Wallet
    And the deposit completes without changing legacy Safe users' behavior
```

```gherkin
Feature: Legacy Safe compatibility

  Scenario: existing Predict user with legacy Safe activity deposits
    Given the selected wallet has a deployed legacy Safe with Polymarket activity

    When user prepares a Predict deposit
    Then Predict keeps using the legacy Safe path
    And no Deposit Wallet relayer preflight is run
```

## **Screenshots/Recordings**

N/A — core/provider flow changes covered by tests and manual wallet-flow
validation.

### **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)

- [ ] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [ ] I've tested with a power user scenario
- Use these [power-user
SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

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.


[PRED-858]:
https://consensyssoftware.atlassian.net/browse/PRED-858?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> High risk because it changes how Predict chooses deposit addresses and
adds new pre-publish relayer/batch execution plus post-confirm sync,
which directly affects deposit and deposit+order transaction flows and
fund routing.
> 
> **Overview**
> Adds first-class support for Polymarket **Deposit Wallet** accounts in
Predict by extending `AccountState` with `walletType` and routing users
to either legacy Safe or a deterministic deposit wallet based on legacy
Safe deployment and Polymarket Activity API results (failing closed on
API errors).
> 
> Implements deposit-wallet infrastructure in the Polymarket provider:
deterministic address derivation, relayer proxy calls/polling, EIP-712
batch execution, allowance-preflight planning (excluding Permit2), and a
legacy Safe “sweep” preflight to migrate stranded USDC.e/pUSD to the
deposit wallet.
> 
> Updates the deposit pipeline to (1) build deposits targeting the
deposit wallet (with optional sweep), (2) run a new `beforePublish`
deposit-wallet preflight to ensure wallet deployment and required
allowances, and (3) on confirmed deposits/deposit+order, invalidate
cached account state and best-effort sync CLOB balance/allowance—waiting
for that sync before placing the follow-on order.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c5f61e2. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->