feat(checkout): GFI-107: Transfer Widget (#2572)

keithbro-imx · Jeet · web-flow · commit b69ff42298bf · 2025-03-18T23:41:10.000Z
Co-authored-by: Jeet &lt;jeet.parikh@immutable.com&gt;
diff --git a/packages/checkout/sdk/src/widgets/definitions/configurations/index.ts b/packages/checkout/sdk/src/widgets/definitions/configurations/index.ts
@@ -9,3 +9,4 @@ export * from './widget';
 export * from './addTokens';
 export * from './commerce';
 export * from './purchase';
+export * from './transfer';
diff --git a/packages/checkout/sdk/src/widgets/definitions/configurations/transfer.ts b/packages/checkout/sdk/src/widgets/definitions/configurations/transfer.ts
@@ -0,0 +1,7 @@
+import { WidgetConfiguration } from './widget';
+
+/**
+ * Transfer Widget Configuration represents the configuration options for the Transfer Widget.
+ */
+export type TransferWidgetConfiguration = {
+} & WidgetConfiguration;
diff --git a/packages/checkout/sdk/src/widgets/definitions/events/index.ts b/packages/checkout/sdk/src/widgets/definitions/events/index.ts
@@ -9,3 +9,4 @@ export * from './onramp';
 export * from './commerce';
 export * from './addTokens';
 export * from './purchase';
+export * from './transfer';
diff --git a/packages/checkout/sdk/src/widgets/definitions/events/transfer.ts b/packages/checkout/sdk/src/widgets/definitions/events/transfer.ts
@@ -0,0 +1,29 @@
+export enum TransferEventType {
+  CLOSE_WIDGET = 'close-widget',
+  REJECTED = 'rejected',
+  SUCCESS = 'success',
+  FAILURE = 'failure',
+}
+
+/**
+ * Represents a successful transfer.
+ */
+export type TransferSuccess = {
+  transactionHash: string;
+};
+
+/**
+ * Type representing a transfer failure
+ * @property {string} reason
+ */
+export type TransferFailed = {
+  reason: string;
+  timestamp: number;
+};
+
+/**
+ * Type representing a transfer rejected
+ * @property {string} reason
+ */
+export type TransferRejected = {
+};
diff --git a/packages/checkout/sdk/src/widgets/definitions/events/widgets.ts b/packages/checkout/sdk/src/widgets/definitions/events/widgets.ts
@@ -15,6 +15,7 @@ export enum IMTBLWidgetEvents {
   IMTBL_COMMERCE_WIDGET_EVENT = 'imtbl-commerce-widget',
   IMTBL_ADD_TOKENS_WIDGET_EVENT = 'imtbl-add-tokens-widget',
   IMTBL_PURCHASE_WIDGET_EVENT = 'imtbl-purchase-widget',
+  IMTBL_TRANSFER_WIDGET_EVENT = 'imtbl-transfer-widget',
 }
 
 /**
diff --git a/packages/checkout/sdk/src/widgets/definitions/parameters/commerce.ts b/packages/checkout/sdk/src/widgets/definitions/parameters/commerce.ts
@@ -8,6 +8,7 @@ import { OnRampWidgetParams } from './onramp';
 import { SaleWidgetParams } from './sale';
 import { AddTokensWidgetParams } from './addTokens';
 import { PurchaseWidgetParams } from './purchase';
+import { TransferWidgetParams } from './transfer';
 
 export enum CommerceFlowType {
   CONNECT = 'CONNECT',
@@ -18,6 +19,7 @@ export enum CommerceFlowType {
   ONRAMP = 'ONRAMP',
   ADD_TOKENS = 'ADD_TOKENS',
   PURCHASE = 'PURCHASE',
+  TRANSFER = 'TRANSFER',
 }
 
 export type CommerceWidgetConnectFlowParams = {
@@ -52,6 +54,10 @@ export type CommerceWidgetPurchaseFlowParams = {
   flow: CommerceFlowType.PURCHASE;
 } & PurchaseWidgetParams;
 
+export type CommerceWidgetTransferFlowParams = {
+  flow: CommerceFlowType.TRANSFER;
+} & TransferWidgetParams;
+
 export type CommerceWidgetFlowParams =
   | CommerceWidgetConnectFlowParams
   | CommerceWidgetWalletFlowParams
@@ -60,7 +66,8 @@ export type CommerceWidgetFlowParams =
   | CommerceWidgetOnRampFlowParams
   | CommerceWidgetSaleFlowParams
   | CommerceWidgetAddTokensFlowParams
-  | CommerceWidgetPurchaseFlowParams;
+  | CommerceWidgetPurchaseFlowParams
+  | CommerceWidgetTransferFlowParams;
 
 export type CommerceWidgetParams = {
   /** The language to use for the Commerce Widget */
diff --git a/packages/checkout/sdk/src/widgets/definitions/parameters/index.ts b/packages/checkout/sdk/src/widgets/definitions/parameters/index.ts
@@ -1,4 +1,5 @@
 export type { AddTokensWidgetParams } from './addTokens';
+export type { TransferWidgetParams } from './transfer';
 
 export * from './connect';
 export * from './bridge';
diff --git a/packages/checkout/sdk/src/widgets/definitions/parameters/transfer.ts b/packages/checkout/sdk/src/widgets/definitions/parameters/transfer.ts
@@ -0,0 +1,18 @@
+import { WidgetLanguage } from '../configurations/widget';
+
+export type TransferWidgetParams = {
+  /** The language to use for the Purchase widget */
+  language?: WidgetLanguage;
+
+  /** The amount to transfer */
+  amount?: string;
+
+  /** The token address to transfer */
+  tokenAddress?: `0x${string}` | 'native';
+
+  /** The to address to transfer to */
+  toAddress?: `0x${string}`;
+
+  /** Whether to show the back button */
+  showBackButton?: boolean;
+};
diff --git a/packages/checkout/sdk/src/widgets/definitions/types.ts b/packages/checkout/sdk/src/widgets/definitions/types.ts
@@ -59,6 +59,7 @@ import {
   AddTokensWidgetParams,
   SaleWidgetParams,
   PurchaseWidgetParams,
+  TransferWidgetParams,
 } from './parameters';
 import {
   BridgeWidgetConfiguration,
@@ -71,8 +72,12 @@ import {
   AddTokensWidgetConfiguration,
   WidgetTheme,
   PurchaseWidgetConfiguration,
+  TransferWidgetConfiguration,
 } from './configurations';
 import { WrappedBrowserProvider } from '../../types';
+import {
+  TransferEventType, TransferFailed, TransferRejected, TransferSuccess,
+} from './events/transfer';
 
 /**
  * Enum representing the list of widget types.
@@ -87,6 +92,7 @@ export enum WidgetType {
   IMMUTABLE_COMMERCE = 'immutableCommerce',
   ADD_TOKENS = 'addTokens',
   PURCHASE = 'purchase',
+  TRANSFER = 'transfer',
 }
 
 /**
@@ -107,6 +113,7 @@ export type WidgetConfigurations = {
   [WidgetType.ADD_TOKENS]: AddTokensWidgetConfiguration;
   [WidgetType.PURCHASE]: PurchaseWidgetConfiguration;
   [WidgetType.IMMUTABLE_COMMERCE]: CommerceWidgetConfiguration;
+  [WidgetType.TRANSFER]: TransferWidgetConfiguration;
 };
 
 // Mapping each widget type to their parameters
@@ -120,6 +127,7 @@ export type WidgetParameters = {
   [WidgetType.ADD_TOKENS]: AddTokensWidgetParams;
   [WidgetType.PURCHASE]: PurchaseWidgetParams;
   [WidgetType.IMMUTABLE_COMMERCE]: CommerceWidgetParams;
+  [WidgetType.TRANSFER]: TransferWidgetParams;
 };
 
 /**
@@ -236,6 +244,14 @@ export type WidgetEventData = {
     [PurchaseEventType.FAILURE]: PurchaseFailed;
   } & OrchestrationMapping &
   ProviderEventMapping;
+
+  [WidgetType.TRANSFER]: {
+    [TransferEventType.CLOSE_WIDGET]: {};
+    [TransferEventType.SUCCESS]: TransferSuccess;
+    [TransferEventType.FAILURE]: TransferFailed;
+    [TransferEventType.REJECTED]: TransferRejected;
+  } & OrchestrationMapping &
+  ProviderEventMapping;
 };
 
 /**
diff --git a/packages/checkout/widgets-lib/.eslintrc.cjs b/packages/checkout/widgets-lib/.eslintrc.cjs
@@ -69,5 +69,6 @@ module.exports = {
     "jsx-a11y/anchor-has-content": "off",
     "jsx-a11y/control-has-associated-label": "off",
     "react/jsx-props-no-spreading": "off",
+    "implicit-arrow-linebreak": "off",
   }
 }
diff --git a/packages/checkout/widgets-lib/src/components/ConnectLoader/ConnectLoader.tsx b/packages/checkout/widgets-lib/src/components/ConnectLoader/ConnectLoader.tsx
@@ -160,7 +160,7 @@ export function ConnectLoader({
   };
 
   useEffect(() => {
-    if (window === undefined) {
+    if (typeof window === 'undefined') {
       // eslint-disable-next-line no-console
       console.error('missing window object: please run Checkout client side');
       return;
diff --git a/packages/checkout/widgets-lib/src/context/analytics-provider/SegmentAnalyticsProvider.ts b/packages/checkout/widgets-lib/src/context/analytics-provider/SegmentAnalyticsProvider.ts
@@ -13,6 +13,7 @@ export enum UserJourney {
   SALE = 'PrimarySale',
   ADD_TOKENS = 'AddTokens',
   PURCHASE = 'Purchase',
+  TRANSFER = 'Transfer',
 }
 
 export type AnalyticsControlTypes =
diff --git a/packages/checkout/widgets-lib/src/context/view-context/CheckoutWidgetViewContextTypes.ts b/packages/checkout/widgets-lib/src/context/view-context/CheckoutWidgetViewContextTypes.ts
@@ -16,6 +16,8 @@ import {
   WalletWidgetConfiguration,
   PurchaseWidgetConfiguration,
   PurchaseWidgetParams,
+  TransferWidgetParams,
+  TransferWidgetConfiguration,
 } from '@imtbl/checkout-sdk';
 import { ViewType } from './ViewType';
 
@@ -27,7 +29,8 @@ export type CheckoutWidgetView =
   | SwapView
   | OnRampView
   | BridgeView
-  | PurchaseView;
+  | PurchaseView
+  | TransferView;
 
 interface ConnectView extends ViewType {
   type: CommerceFlowType.CONNECT;
@@ -94,3 +97,11 @@ interface BridgeView extends ViewType {
     config: BridgeWidgetConfiguration;
   };
 }
+
+interface TransferView extends ViewType {
+  type: CommerceFlowType.TRANSFER;
+  data: {
+    params: TransferWidgetParams;
+    config: TransferWidgetConfiguration;
+  };
+}
diff --git a/packages/checkout/widgets-lib/src/context/view-context/TransferViewContextTypes.ts b/packages/checkout/widgets-lib/src/context/view-context/TransferViewContextTypes.ts
@@ -0,0 +1,11 @@
+import { ViewType } from './ViewType';
+
+export enum TransferWidgetViews {
+  TRANSFER = 'TRANSFER',
+}
+
+export type TransferWidgetView = TransferView;
+
+interface TransferView extends ViewType {
+  type: TransferWidgetViews.TRANSFER;
+}
diff --git a/packages/checkout/widgets-lib/src/context/view-context/ViewContext.tsx b/packages/checkout/widgets-lib/src/context/view-context/ViewContext.tsx
@@ -11,6 +11,7 @@ import { OnRampWidgetView } from './OnRampViewContextTypes';
 import { AddTokensWidgetView } from './AddTokensViewContextTypes';
 import { CheckoutWidgetView } from './CheckoutWidgetViewContextTypes';
 import { PurchaseWidgetView } from './PurchaseViewContextTypes';
+import { TransferWidgetView } from './TransferViewContextTypes';
 
 export enum SharedViews {
   LOADING_VIEW = 'LOADING_VIEW',
@@ -56,7 +57,8 @@ export type View =
   | BridgeWidgetView
   | AddTokensWidgetView
   | CheckoutWidgetView
-  | PurchaseWidgetView;
+  | PurchaseWidgetView
+  | TransferWidgetView;
 
 export interface ViewState {
   view: View;
diff --git a/packages/checkout/widgets-lib/src/locales/en.json b/packages/checkout/widgets-lib/src/locales/en.json
@@ -134,6 +134,29 @@
         "linkText": "Visit our FAQs"
       }
     },
+    "TRANSFER": {
+      "header": {
+        "title": "Send tokens"
+      },
+      "content": {
+        "fiatPricePrefix": "≈ USD",
+        "availableBalancePrefix": "Available",
+        "notAllExchangesSupportImmutableZkEVM": "Not all Exchanges Support Immutable zkEVM!",
+        "notAllExchangesSupportImmutableZkEVMDescription": "You can only send tokens within the Immutable zkEVM network. Some exchanges do not support Immutable zkEVM, so ensure your destination is compatible before sending, as retrieving funds can be difficult to impossible.",
+        "tokensSentSuccessfully": "Tokens Sent Successfully",
+        "seeTransactionOnImmutableZkEVM": "See transaction on Immutable zkEVM",
+        "sendingTokens": "Sending Tokens",
+        "waitingForYouToApproveTxn": "Waiting for you to Approve Transaction",
+        "waitingForYouToApproveTxnDescription": "Approve the transaction request to complete this transaction"
+      },
+      "form": {
+        "buttonText": "Send",
+        "coinSelectorHeading": "Select a token",
+        "coinAmountHeading": "Send",
+        "toAddressHeading": "To address",
+        "continueButtonText": "Continue"
+      }
+    },
     "SWAP": {
       "header": {
         "title": "Swap tokens"
diff --git a/packages/checkout/widgets-lib/src/widgets/immutable-commerce/CommerceWidget.tsx b/packages/checkout/widgets-lib/src/widgets/immutable-commerce/CommerceWidget.tsx
@@ -48,6 +48,7 @@ import {
   initialCommerceState,
 } from './context/CommerceContext';
 import PurchaseWidget from '../purchase/PurchaseWidget';
+import TransferWidget from '../transfer/TransferWidget';
 
 export type CommerceWidgetInputs = {
   checkout: Checkout;
@@ -327,6 +328,14 @@ export default function CommerceWidget(props: CommerceWidgetInputs) {
                   showBackButton={showBackButton}
                 />
               )}
+              {view.type === CommerceFlowType.TRANSFER && (
+                <TransferWidget
+                  config={widgetsConfig}
+                  {...(view.data.params || {})}
+                  {...(view.data.config || {})}
+                  showBackButton={showBackButton}
+                />
+              )}
             </Suspense>
           </ConnectLoader>
         )}
diff --git a/packages/checkout/widgets-lib/src/widgets/immutable-commerce/CommerceWidgetRoot.tsx b/packages/checkout/widgets-lib/src/widgets/immutable-commerce/CommerceWidgetRoot.tsx
@@ -14,8 +14,10 @@ import {
   CommerceWidgetSaleFlowParams,
   CommerceFlowType,
   CommerceWidgetPurchaseFlowParams,
+  CommerceWidgetTransferFlowParams,
 } from '@imtbl/checkout-sdk';
 import React, { Suspense } from 'react';
+import { isAddress } from 'ethers';
 import { ThemeProvider } from '../../components/ThemeProvider/ThemeProvider';
 import { CustomAnalyticsProvider } from '../../context/analytics-provider/CustomAnalyticsProvider';
 import { HandoverProvider } from '../../context/handover-context/HandoverProvider';
@@ -170,6 +172,30 @@ export class CommerceWidgetRoot extends Base<WidgetType.IMMUTABLE_COMMERCE> {
     };
   }
 
+  protected getValidTransferFlowParams(params: CommerceWidgetTransferFlowParams) {
+    const validatedParams = { ...params };
+
+    if (params.amount && !isValidAmount(params.amount)) {
+      // eslint-disable-next-line no-console
+      console.warn('[IMTBL]: invalid "amount" widget input');
+      validatedParams.amount = undefined;
+    }
+
+    if (params.tokenAddress && !isValidAddress(params.tokenAddress)) {
+      // eslint-disable-next-line no-console
+      console.warn('[IMTBL]: invalid "fromTokenAddress" widget input');
+      validatedParams.tokenAddress = undefined;
+    }
+
+    if (params.toAddress && !isAddress(params.toAddress)) {
+      // eslint-disable-next-line no-console
+      console.warn('[IMTBL]: invalid "toAddress" widget input');
+      validatedParams.toAddress = undefined;
+    }
+
+    return validatedParams;
+  }
+
   protected getValidSwapFlowParams(params: CommerceWidgetSwapFlowParams) {
     const validatedParams = { ...params };
 
@@ -262,6 +288,8 @@ export class CommerceWidgetRoot extends Base<WidgetType.IMMUTABLE_COMMERCE> {
         return this.getValidAddTokensFlowParams(params);
       case CommerceFlowType.PURCHASE:
         return this.getValidPurchaseFlowParams(params);
+      case CommerceFlowType.TRANSFER:
+        return this.getValidTransferFlowParams(params);
       default:
         // eslint-disable-next-line no-console
         console.warn(
diff --git a/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/getConnectLoaderParams.ts b/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/getConnectLoaderParams.ts
@@ -46,6 +46,7 @@ export function getConnectLoaderParams(
       };
     case CommerceFlowType.SALE:
     case CommerceFlowType.SWAP:
+    case CommerceFlowType.TRANSFER:
       return {
         checkout,
         browserProvider,
diff --git a/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/getFlowRequiresContext.ts b/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/getFlowRequiresContext.ts
@@ -8,6 +8,7 @@ const connectLoaderFlows = [
   CommerceFlowType.SWAP,
   CommerceFlowType.WALLET,
   CommerceFlowType.ONRAMP,
+  CommerceFlowType.TRANSFER,
 ] as unknown[];
 
 /**
diff --git a/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/isValidCommerceFlow.ts b/packages/checkout/widgets-lib/src/widgets/immutable-commerce/functions/isValidCommerceFlow.ts
@@ -10,6 +10,7 @@ export const commerceFlows = [
   CommerceFlowType.ONRAMP,
   CommerceFlowType.ADD_TOKENS,
   CommerceFlowType.PURCHASE,
+  CommerceFlowType.TRANSFER,
 ];
 
 /**
diff --git a/packages/checkout/widgets-lib/src/widgets/swap/context/SwapContext.test.ts b/packages/checkout/widgets-lib/src/widgets/swap/context/SwapContext.test.ts
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/AwaitingApproval.tsx b/packages/checkout/widgets-lib/src/widgets/transfer/AwaitingApproval.tsx
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/SendingTokens.tsx b/packages/checkout/widgets-lib/src/widgets/transfer/SendingTokens.tsx
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/TransferComplete.tsx b/packages/checkout/widgets-lib/src/widgets/transfer/TransferComplete.tsx
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/TransferForm.tsx b/packages/checkout/widgets-lib/src/widgets/transfer/TransferForm.tsx
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/TransferWidget.tsx b/packages/checkout/widgets-lib/src/widgets/transfer/TransferWidget.tsx
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/context.ts b/packages/checkout/widgets-lib/src/widgets/transfer/context.ts
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/events.ts b/packages/checkout/widgets-lib/src/widgets/transfer/events.ts
diff --git a/packages/checkout/widgets-lib/src/widgets/transfer/functions.ts b/packages/checkout/widgets-lib/src/widgets/transfer/functions.ts
diff --git a/packages/checkout/widgets-sample-app/src/components/ui/checkout/checkout.tsx b/packages/checkout/widgets-sample-app/src/components/ui/checkout/checkout.tsx

Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ export enum IMTBLWidgetEvents {`
`15`	`15`	`IMTBL_COMMERCE_WIDGET_EVENT = 'imtbl-commerce-widget',`
`16`	`16`	`IMTBL_ADD_TOKENS_WIDGET_EVENT = 'imtbl-add-tokens-widget',`
`17`	`17`	`IMTBL_PURCHASE_WIDGET_EVENT = 'imtbl-purchase-widget',`
	`18`	`+ IMTBL_TRANSFER_WIDGET_EVENT = 'imtbl-transfer-widget',`
`18`	`19`	`}`
`19`	`20`
`20`	`21`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`export type { AddTokensWidgetParams } from './addTokens';`
	`2`	`+export type { TransferWidgetParams } from './transfer';`
`2`	`3`
`3`	`4`	`export * from './connect';`
`4`	`5`	`export * from './bridge';`
Original file line number	Diff line number	Diff line change
`@@ -69,5 +69,6 @@ module.exports = {`
`69`	`69`	`"jsx-a11y/anchor-has-content": "off",`
`70`	`70`	`"jsx-a11y/control-has-associated-label": "off",`
`71`	`71`	`"react/jsx-props-no-spreading": "off",`
	`72`	`+ "implicit-arrow-linebreak": "off",`
`72`	`73`	`}`
`73`	`74`	`}`