feat(deposit): deeplink initial support (MetaMask#19404)

wachunei · web-flow · commit fb7b81de4a48 · 2025-09-11T17:12:05.000Z
## **Description** This PR adds initial support for the Deposit flow to be exposed to the Deeplinks by using `/deposit` URL ## **Changelog**  CHANGELOG entry: Added `/deposit` action for deeplinking into Deposit. ## **Related issues** Fixes: https://consensyssoftware.atlassian.net/browse/TRAM-2653 ## **Manual testing steps** ```gherkin Feature: Deposit Scenario: user deeplinks into deposit feature Given app is in the background When user visits /deposit deeplink Then app handles it correctly and navigates to Deposit ``` ## **Screenshots/Recordings** ### **Before** ### **After** https://github.com/user-attachments/assets/b01da70a-186a-4322-963a-932311453612 ## **Pre-merge author checklist** - [ ] 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). - [ ] I've completed the PR template to the best of my ability - [ ] I’ve included tests if applicable - [ ] 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. ## **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.
diff --git a/app/components/UI/Card/components/AddFundsBottomSheet/AddFundsBottomSheet.test.tsx b/app/components/UI/Card/components/AddFundsBottomSheet/AddFundsBottomSheet.test.tsx
@@ -8,11 +8,11 @@ import { isSwapsAllowed } from '../../../Swaps/utils';
 import { MetaMetricsEvents, useMetrics } from '../../../../hooks/useMetrics';
 import { getDecimalChainId } from '../../../../../util/networks';
 import { trace, TraceName } from '../../../../../util/trace';
-import Routes from '../../../../../constants/navigation/Routes';
 import { CardTokenAllowance, AllowanceState } from '../../types';
 import { BottomSheetRef } from '../../../../../component-library/components/BottomSheets/BottomSheet';
 import { renderScreen } from '../../../../../util/test/renderWithProvider';
 import { backgroundState } from '../../../../../util/test/initial-root-state';
+import { createDepositNavigationDetails } from '../../../Ramp/Deposit/routes/utils';
 
 // Mock dependencies
 jest.mock('../../hooks/useOpenSwaps', () => ({
@@ -297,7 +297,9 @@ describe('AddFundsBottomSheet', () => {
 
     fireEvent.press(getByText('Fund with cash'));
 
-    expect(mockNavigate).toHaveBeenCalledWith(Routes.DEPOSIT.ID);
+    expect(mockNavigate).toHaveBeenCalledWith(
+      ...createDepositNavigationDetails(),
+    );
   });
 
   it('handles ref prop correctly', () => {
diff --git a/app/components/UI/Card/components/AddFundsBottomSheet/AddFundsBottomSheet.tsx b/app/components/UI/Card/components/AddFundsBottomSheet/AddFundsBottomSheet.tsx
@@ -1,4 +1,5 @@
 import React, { useCallback } from 'react';
+import { NavigationProp, ParamListBase } from '@react-navigation/native';
 import BottomSheet, {
   BottomSheetRef,
 } from '../../../../../component-library/components/BottomSheets/BottomSheet';
@@ -23,20 +24,20 @@ import { CardTokenAllowance } from '../../types';
 import AppConstants from '../../../../../core/AppConstants';
 import { isSwapsAllowed } from '../../../Swaps/utils';
 import useDepositEnabled from '../../../Ramp/Deposit/hooks/useDepositEnabled';
-import Routes from '../../../../../constants/navigation/Routes';
 import { getDecimalChainId } from '../../../../../util/networks';
 import { trace, TraceName } from '../../../../../util/trace';
 import { useOpenSwaps } from '../../hooks/useOpenSwaps';
 import { MetaMetricsEvents, useMetrics } from '../../../../hooks/useMetrics';
 import { strings } from '../../../../../../locales/i18n';
 import { CardHomeSelectors } from '../../../../../../e2e/selectors/Card/CardHome.selectors';
+import { createDepositNavigationDetails } from '../../../Ramp/Deposit/routes/utils';
 
 export interface AddFundsBottomSheetProps {
   setOpenAddFundsBottomSheet: (open: boolean) => void;
   sheetRef: React.RefObject<BottomSheetRef>;
   priorityToken?: CardTokenAllowance;
   chainId: string;
-  navigate: (route: string) => void;
+  navigate: NavigationProp<ParamListBase>['navigate'];
 }
 
 const AddFundsBottomSheet: React.FC<AddFundsBottomSheetProps> = ({
@@ -71,7 +72,7 @@ const AddFundsBottomSheet: React.FC<AddFundsBottomSheetProps> = ({
 
   const openDeposit = useCallback(() => {
     closeBottomSheetAndNavigate(() => {
-      navigate(Routes.DEPOSIT.ID);
+      navigate(...createDepositNavigationDetails());
     });
     trackEvent(
       createEventBuilder(
diff --git a/app/components/UI/FundActionMenu/FundActionMenu.test.tsx b/app/components/UI/FundActionMenu/FundActionMenu.test.tsx
@@ -8,7 +8,7 @@ import { useSelector } from 'react-redux';
 import { MetaMetricsEvents } from '../../../core/Analytics';
 import { WalletActionsBottomSheetSelectorsIDs } from '../../../../e2e/selectors/wallet/WalletActionsBottomSheet.selectors';
 import { RampType } from '../../../reducers/fiatOrders/types';
-import Routes from '../../../constants/navigation/Routes';
+import { createDepositNavigationDetails } from '../Ramp/Deposit/routes/utils';
 
 // Internal dependencies.
 import { useMetrics } from '../../hooks/useMetrics';
@@ -244,7 +244,9 @@ describe('FundActionMenu', () => {
       );
 
       await waitFor(() => {
-        expect(mockNavigate).toHaveBeenCalledWith(Routes.DEPOSIT.ID);
+        expect(mockNavigate).toHaveBeenCalledWith(
+          ...createDepositNavigationDetails(),
+        );
       });
     });
 
diff --git a/app/components/UI/FundActionMenu/FundActionMenu.tsx b/app/components/UI/FundActionMenu/FundActionMenu.tsx
@@ -26,7 +26,7 @@ import { trace, TraceName } from '../../../util/trace';
 import { selectCanSignTransactions } from '../../../selectors/accountsController';
 import { RampType } from '../../../reducers/fiatOrders/types';
 import useDepositEnabled from '../Ramp/Deposit/hooks/useDepositEnabled';
-import Routes from '../../../constants/navigation/Routes';
+import { createDepositNavigationDetails } from '../Ramp/Deposit/routes/utils';
 
 // Types
 import type {
@@ -115,7 +115,7 @@ const FundActionMenu = () => {
             ramp_type: 'DEPOSIT',
           },
           traceName: TraceName.LoadDepositExperience,
-          navigationAction: () => navigate(Routes.DEPOSIT.ID),
+          navigationAction: () => navigate(...createDepositNavigationDetails()),
         },
         {
           type: 'buy',
diff --git a/app/components/UI/Ramp/Aggregator/Views/OrdersList/OrdersList.test.tsx b/app/components/UI/Ramp/Aggregator/Views/OrdersList/OrdersList.test.tsx
@@ -291,9 +291,6 @@ describe('OrdersList', () => {
         ],
         [
           "Deposit",
-          {
-            "screen": "DepositRoot",
-          },
         ],
       ]
     `);
diff --git a/app/components/UI/Ramp/Aggregator/Views/OrdersList/OrdersList.tsx b/app/components/UI/Ramp/Aggregator/Views/OrdersList/OrdersList.tsx
@@ -6,6 +6,7 @@ import { useSelector } from 'react-redux';
 import { OrderOrderTypeEnum } from '@consensys/on-ramp-sdk/dist/API';
 
 import { createOrderDetailsNavDetails } from '../OrderDetails/OrderDetails';
+import { createDepositNavigationDetails } from '../../../Deposit/routes/utils';
 import OrderListItem from '../../components/OrderListItem';
 import Row from '../../components/Row';
 import createStyles from './OrdersList.styles';
@@ -28,7 +29,6 @@ import { FiatOrder, getOrders } from '../../../../../../reducers/fiatOrders';
 import { strings } from '../../../../../../../locales/i18n';
 import { useTheme } from '../../../../../../util/theme';
 import { createDepositOrderDetailsNavDetails } from '../../../Deposit/Views/DepositOrderDetails/DepositOrderDetails';
-import Routes from '../../../../../../constants/navigation/Routes';
 
 type filterType = 'ALL' | 'PURCHASE' | 'SELL';
 
@@ -83,9 +83,7 @@ function OrdersList() {
       const order = orders.find((o) => o.id === orderId);
 
       if (order?.state === FIAT_ORDER_STATES.CREATED) {
-        navigation.navigate(Routes.DEPOSIT.ID, {
-          screen: Routes.DEPOSIT.ROOT,
-        });
+        navigation.navigate(...createDepositNavigationDetails());
       } else {
         navigation.navigate(
           ...createDepositOrderDetailsNavDetails({
diff --git a/app/components/UI/Ramp/Aggregator/deeplink/handleRampUrl.ts b/app/components/UI/Ramp/Aggregator/deeplink/handleRampUrl.ts
@@ -1,6 +1,6 @@
 import { NavigationProp, ParamListBase } from '@react-navigation/native';
 import handleRedirection from './handleRedirection';
-import getRedirectPathsAndParams from './utils/getRedirectPathAndParams';
+import getRedirectPathsAndParams from '../../utils/getRedirectPathAndParams';
 import { RampType } from '../types';
 import parseRampIntent from '../utils/parseRampIntent';
 import {
diff --git a/app/components/UI/Ramp/Deposit/deeplink/handleDepositUrl.test.ts b/app/components/UI/Ramp/Deposit/deeplink/handleDepositUrl.test.ts
@@ -0,0 +1,51 @@
+import { NavigationProp, ParamListBase } from '@react-navigation/native';
+import Routes from '../../../../../constants/navigation/Routes';
+import handleDepositUrl from './handleDepositUrl';
+
+jest.mock('@react-navigation/native');
+
+describe('handleDepositUrl', () => {
+  let navigation: NavigationProp<ParamListBase>;
+
+  beforeEach(() => {
+    navigation = {
+      navigate: jest.fn(),
+    } as unknown as NavigationProp<ParamListBase>;
+  });
+
+  it('navigates to Deposit route when query params do not have allowed fields', () => {
+    handleDepositUrl({
+      depositPath: '?as=example',
+      navigation,
+    });
+    expect(navigation.navigate).toHaveBeenCalledWith(Routes.DEPOSIT.ID);
+  });
+
+  it('navigates to Deposit route when query params are allowed', () => {
+    handleDepositUrl({
+      depositPath:
+        '?assetId=eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      navigation,
+    });
+    expect(navigation.navigate).toHaveBeenCalledWith(Routes.DEPOSIT.ID, {
+      screen: Routes.DEPOSIT.ID,
+      params: {
+        assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      },
+    });
+  });
+
+  it('navigates to Deposit route when query params are encoded and allowed', () => {
+    handleDepositUrl({
+      depositPath:
+        '?assetId=eip155%3A1%2Ferc20%3A0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      navigation,
+    });
+    expect(navigation.navigate).toHaveBeenCalledWith(Routes.DEPOSIT.ID, {
+      screen: Routes.DEPOSIT.ID,
+      params: {
+        assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      },
+    });
+  });
+});
diff --git a/app/components/UI/Ramp/Deposit/deeplink/handleDepositUrl.ts b/app/components/UI/Ramp/Deposit/deeplink/handleDepositUrl.ts
@@ -0,0 +1,30 @@
+import { NavigationProp, ParamListBase } from '@react-navigation/native';
+import Logger from '../../../../../util/Logger';
+import getRedirectPathsAndParams from '../../utils/getRedirectPathAndParams';
+import { createDepositNavigationDetails } from '../routes/utils';
+import parseDepositParams from './utils/parseDepositParams';
+
+interface DepositUrlOptions {
+  depositPath: string;
+  navigation: NavigationProp<ParamListBase>;
+}
+
+export default function handleDepositUrl({
+  depositPath,
+  navigation,
+}: DepositUrlOptions) {
+  try {
+    const [, pathParams] = getRedirectPathsAndParams(depositPath);
+
+    let depositParams;
+    if (pathParams) {
+      depositParams = parseDepositParams(pathParams);
+    }
+    navigation.navigate(...createDepositNavigationDetails(depositParams));
+  } catch (error) {
+    Logger.error(
+      error as Error,
+      `Error in handleDepositUrl. depositPath: ${depositPath}`,
+    );
+  }
+}
diff --git a/app/components/UI/Ramp/Deposit/deeplink/utils/parseDepositParams.test.ts b/app/components/UI/Ramp/Deposit/deeplink/utils/parseDepositParams.test.ts
@@ -0,0 +1,45 @@
+import parseDepositParams from './parseDepositParams';
+
+describe('parseDepositParams', () => {
+  it('returns undefined if depositParams do not contain necessary fields', () => {
+    const depositParams = {};
+    const result = parseDepositParams(depositParams);
+    expect(result).toBeUndefined();
+  });
+
+  it('returns a DepositNavigationParams object if depositParams contain necessary fields', () => {
+    const depositParams = {
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      amount: '10',
+    };
+    const result = parseDepositParams(depositParams);
+    expect(result).toEqual({
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      amount: '10',
+    });
+  });
+
+  it('returns a DepositNavigationParams object with only defined fields', () => {
+    const depositParams = {
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      amount: '10',
+      extraneaous: 'field',
+    };
+    const result = parseDepositParams(depositParams);
+    expect(result).toEqual({
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      amount: '10',
+    });
+  });
+
+  it('returns a DepositNavigationParams object with only defined values', () => {
+    const depositParams = {
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+      amount: undefined,
+    };
+    const result = parseDepositParams(depositParams);
+    expect(result).toEqual({
+      assetId: 'eip155:1/erc20:0xacA92E438df0B2401fF60dA7E4337B687a2435DA',
+    });
+  });
+});
diff --git a/app/components/UI/Ramp/Deposit/deeplink/utils/parseDepositParams.ts b/app/components/UI/Ramp/Deposit/deeplink/utils/parseDepositParams.ts
@@ -0,0 +1,23 @@
+import { DepositNavigationParams } from '../../types';
+
+export default function parseDepositParams(
+  depositParams: Record<string, string | undefined>,
+): DepositNavigationParams | undefined {
+  // create a params object if the pathParams contain the necessary fields
+  const params: DepositNavigationParams = {
+    assetId: depositParams.assetId,
+    amount: depositParams.amount,
+  };
+
+  if (!params.assetId && !params.amount) {
+    return undefined;
+  }
+
+  Object.keys(params).forEach(
+    (key) =>
+      params[key as keyof DepositNavigationParams] === undefined &&
+      delete params[key as keyof DepositNavigationParams],
+  );
+
+  return params;
+}
diff --git a/app/components/UI/Ramp/Deposit/routes/utils.ts b/app/components/UI/Ramp/Deposit/routes/utils.ts
@@ -0,0 +1,12 @@
+import { DepositNavigationParams } from '../types';
+import Routes from '../../../../../constants/navigation/Routes';
+
+export function createDepositNavigationDetails(
+  params?: DepositNavigationParams,
+) {
+  const route = Routes.DEPOSIT.ID;
+  if (!params) {
+    return [route] as const;
+  }
+  return [route, { screen: route, params }] as const;
+}
diff --git a/app/components/UI/Ramp/Deposit/types/index.ts b/app/components/UI/Ramp/Deposit/types/index.ts
@@ -1 +1,2 @@
 export * from './analytics';
+export * from './navigationParams';
diff --git a/app/components/UI/Ramp/Deposit/types/navigationParams.ts b/app/components/UI/Ramp/Deposit/types/navigationParams.ts
@@ -0,0 +1,4 @@
+export interface DepositNavigationParams {
+  assetId?: string;
+  amount?: string;
+}
diff --git a/app/components/UI/Ramp/utils/getRedirectPathAndParams.test.ts b/app/components/UI/Ramp/utils/getRedirectPathAndParams.test.ts
diff --git a/app/components/UI/Ramp/utils/getRedirectPathAndParams.ts b/app/components/UI/Ramp/utils/getRedirectPathAndParams.ts
@@ -1,10 +1,10 @@
 const dummyProtocol = 'dummy:';
 
-export default function getRedirectPathsAndParams(rampPath: string) {
+export default function getRedirectPathsAndParams(path: string) {
   let pathnames: string[] = [];
   let params;
   try {
-    const urlObject = new URL(`${dummyProtocol}${rampPath}`);
+    const urlObject = new URL(`${dummyProtocol}${path}`);
     pathnames = `${urlObject.hostname}${urlObject.pathname}`
       .split('/')
       .filter(Boolean);
diff --git a/app/components/UI/Tokens/TokenList/TokenListFooter/index.tsx b/app/components/UI/Tokens/TokenList/TokenListFooter/index.tsx
@@ -19,9 +19,9 @@ import {
 } from '../../../../../components/hooks/useMetrics';
 import { getDecimalChainId } from '../../../../../util/networks';
 import { selectChainId } from '../../../../../selectors/networkController';
-import Routes from '../../../../../constants/navigation/Routes';
 import { trace, TraceName } from '../../../../../util/trace';
 import { useSelectedAccountMultichainBalances } from '../../../../hooks/useMultichainBalances';
+import { createDepositNavigationDetails } from '../../../Ramp/Deposit/routes/utils';
 
 export const TokenListFooter = () => {
   const chainId = useSelector(selectChainId);
@@ -36,7 +36,7 @@ export const TokenListFooter = () => {
     selectedAccountMultichainBalance?.totalFiatBalance === 0;
 
   const goToDeposit = () => {
-    navigation.navigate(Routes.DEPOSIT.ID);
+    navigation.navigate(...createDepositNavigationDetails());
 
     trackEvent(
       createEventBuilder(
diff --git a/app/constants/deeplinks.ts b/app/constants/deeplinks.ts
@@ -26,6 +26,7 @@ export enum ACTIONS {
   BUY_CRYPTO = 'buy-crypto',
   SELL = 'sell',
   SELL_CRYPTO = 'sell-crypto',
+  DEPOSIT = 'deposit',
   HOME = 'home',
   SWAP = 'swap',
   EMPTY = '',
diff --git a/app/core/DeeplinkManager/DeeplinkManager.ts b/app/core/DeeplinkManager/DeeplinkManager.ts
@@ -5,6 +5,7 @@ import { Dispatch } from 'redux';
 import handleBrowserUrl from './Handlers/handleBrowserUrl';
 import handleEthereumUrl from './Handlers/handleEthereumUrl';
 import handleRampUrl from './Handlers/handleRampUrl';
+import handleDepositCashUrl from './Handlers/handleDepositCashUrl';
 import switchNetwork from './Handlers/switchNetwork';
 import parseDeeplink from './ParseManager/parseDeeplink';
 import approveTransaction from './TransactionManager/approveTransaction';
@@ -95,6 +96,13 @@ class DeeplinkManager {
     });
   }
 
+  _handleDepositCash(depositCashPath: string) {
+    handleDepositCashUrl({
+      depositPath: depositCashPath,
+      navigation: this.navigation,
+    });
+  }
+
   // NOTE: open the home screen for new subdomain
   _handleOpenHome() {
     this.navigation.navigate(Routes.WALLET.HOME);
diff --git a/app/core/DeeplinkManager/Handlers/handleDepositCashUrl.ts b/app/core/DeeplinkManager/Handlers/handleDepositCashUrl.ts
@@ -0,0 +1 @@
+export { default } from '../../../components/UI/Ramp/Deposit/deeplink/handleDepositUrl';
diff --git a/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.test.ts b/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.test.ts
diff --git a/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.ts b/app/core/DeeplinkManager/ParseManager/handleMetaMaskDeeplink.ts
diff --git a/app/core/DeeplinkManager/ParseManager/handleUniversalLink.test.ts b/app/core/DeeplinkManager/ParseManager/handleUniversalLink.test.ts
diff --git a/app/core/DeeplinkManager/ParseManager/handleUniversalLink.ts b/app/core/DeeplinkManager/ParseManager/handleUniversalLink.ts

Original file line number	Diff line number	Diff line change
`@@ -291,9 +291,6 @@ describe('OrdersList', () => {`
`291`	`291`	`],`
`292`	`292`	`[`
`293`	`293`	`"Deposit",`
`294`		`- {`
`295`		`- "screen": "DepositRoot",`
`296`		`- },`
`297`	`294`	`],`
`298`	`295`	`]`
`299`	`296`	`);