Upgrade to 📦 sdk-dapp v.5

MIGRATION_GUIDE.md

@@ -0,0 +1,173 @@
+# @multiversx/template-dapp
+
+Migrating your application to `sdk-dapp@5.x` will probably require more code removal than insertion. Of course, each application is different, so this guide will have a generic character, pointing out the main areas where you might need to change your code.
+The main areas that might need code restructuring are:
+
+- package.json library dependencies
+- index.tsx file where the app bootstraps
+- App.tsx, the main file of your application
+- logging in and out
+- sending and signing transactions
+- component imports related to displaying data
+- types
+
+A typical migration can be seen in this [pull request](https://github.com/multiversx/mx-template-dapp/pull/343).
+
+Next, we will make a brief overview of the main changes required.
+
+## 1. Changes in [`package.json`](https://github.com/multiversx/mx-template-dapp/pull/343/files#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519)
+
+#### Dependencies
+
+
+- Updated:
+  - `@multiversx/sdk-dapp` (version `^5.x`)
+  - `@multiversx/sdk-dapp-utils` (version `2.0.0`)
+- Added:
+  - `@multiversx/sdk-dapp-ui` (version `^0.x`)
+
+## 2. Changes in [`index.tsx`](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/index.tsx)
+
+You will need to wrap your application in a call to `initApp`:
+
+```tsx
+initApp(config).then(() => {
+  ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+});
+```
+
+## 2. Summary of Changes in [`App.tsx`](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/App.tsx)
+
+- AxiosInterceptorContext is now created as a local component
+- DappProvider was removed ❌ and initialization is now made in initApp
+- NotificationModal, SignTransactionsModals and TransactionsToastList are removed ❌ and functionality is handled under the hood
+- Unlock page is a child route since it only diplays a side panel over an existing route (in our case Home `/`)
+
+## 3. Logging in and out
+
+### 3.1 [Logging in](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/pages/Unlock/Unlock.tsx)
+
+Login buttons have been removed ❌ and there is a universal Unlock side panel, which can be inserted in the DOM at a desired location.
+
+> NOTE: Web-wallet URL login is no longer supported
+
+Example of how to use the `UnlockPanelManager` in the `unlock` route is shown below. Of course the `openUnlockPanel()` method can also be linked to a button.
+
+```tsx
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { UnlockPanelManager, useGetLoginInfo } from 'lib';
+import { RouteNamesEnum } from 'localConstants';
+
+export const Unlock = () => {
+  const navigate = useNavigate();
+  const { isLoggedIn } = useGetLoginInfo();
+
+  const unlockPanelManager = UnlockPanelManager.init({
+    loginHandler: () => {
+      navigate(RouteNamesEnum.dashboard);
+    },
+    onClose: () => {
+      navigate(RouteNamesEnum.home);
+    }
+  });
+
+  const handleOpenUnlockPanel = () => {
+    unlockPanelManager.openUnlockPanel();
+  };
+
+  useEffect(() => {
+    if (isLoggedIn) {
+      navigate(RouteNamesEnum.dashboard);
+      return;
+    }
+
+    handleOpenUnlockPanel();
+  }, [isLoggedIn]);
+
+  return null;
+};
+```
+
+- isAccountLoading has been deprecated
+- `import { getIsProviderEqualTo } from “@multiversx/sdk-dapp/utils/account/getIsProviderEqualTo”` --> removed ❌
+
+### 3.2 [Logging out](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/components/Layout/Header/Header.tsx#L14)
+
+In order to perform a logut action you simply need to get the current signing provider and call the `logout()` method:
+
+```typescript
+import { getAccountProvider } from '@multiversx/sdk-dapp/out/providers/helpers/accountProvider';
+const provider = getAccountProvider();
+await provider.logout();
+```
+
+## 4. [Sending transactions](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/helpers/signAndSendTransactions.ts)
+
+- `sendTransactions` and `useSendBatchTransactions` have been replaced by `provider.signTransactions`, `txManager.send` and `txManager.track`
+- `newTransaction` function has been removed ❌ and you need to create `Transaction` objects directly
+
+## 5. [Tracking transactions](https://github.com/multiversx/mx-template-dapp/blob/423e782fec5e04b6a35b6297eaf253eb8d7ca1ba/src/helpers/signAndSendTransactions.ts#L22)
+
+Tracking transactions is now handled using the `txManager.track` method. You should use this method to monitor the status and outcome of your transactions after sending them. Refer to the linked file for implementation details and examples.
+
+```typescript
+  const txManager = TransactionManager.getInstance();
+
+  const sentTransactions = await txManager.send(signedTransactions);
+  const sessionId = await txManager.track(sentTransactions, {
+    transactionsDisplayInfo
+  });
+```
+
+ - [onFail](https://github.com/multiversx/mx-sdk-dapp/blob/0d7d9627ceccda56982a73c8ac00ed0558f0e2ec/src/hooks/transactions/useTrackTransactionStatus.ts#L34) and [onSuccess](https://github.com/multiversx/mx-sdk-dapp/blob/0d7d9627ceccda56982a73c8ac00ed0558f0e2ec/src/hooks/transactions/batch/tracker/useVerifyBatchStatus.ts#L11) callbacks can now be configured in [initApp config](https://github.com/multiversx/mx-sdk-dapp/blob/1518a070f10ef0dc133e756c07b6fc0f2165bddb/src/methods/initApp/initApp.types.ts#L42) or with [TransactionManager.setCallbacks](https://github.com/multiversx/mx-sdk-dapp/blob/1518a070f10ef0dc133e756c07b6fc0f2165bddb/src/managers/TransactionManager/TransactionManager.ts#L45)
+
+## 6. [UI components are now imported from sdk-dapp-core-ui](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDappUI/sdkDappUI.components.ts)
+
+  - [CopyButton.tsx](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDapp/components/CopyButton/CopyButton.tsx)
+  - [ExplorerLink.tsx](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDapp/components/ExplorerLink/ExplorerLink.tsx)
+  - [FormatAmount.tsx](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDapp/components/FormatAmount/FormatAmount.tsx)
+
+Some UI components were removed:
+
+  - [AxiosInteceptor](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/wrappers/AxiosInterceptorContext/AxiosInterceptorContext.tsx) ❌ no longer needed because signed token can be accessed via store directly 
+  - [IdleTimer](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/web/hooks/useIdleTimer.tsx) ❌ must be implemented locally if needed
+  - [TransactionsToastList](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/UI/TransactionsToastList/TransactionsToastList.tsx) - removed ❌
+  - [SignTransactionsModals](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/UI/SignTransactionsModals/SignTransactionsModals.tsx) - removed ❌
+  - [NotificationModal](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/UI/NotificationModal/NotificationModal.tsx) - removed ❌
+
+Some new UI elements have been added:
+
+  - [UnlockPanel](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/pages/Unlock/Unlock.tsx#L10) replaces [login buttons](https://github.com/multiversx/mx-sdk-dapp/blob/old-main/src/UI/walletConnect/WalletConnectLoginButton/WalletConnectLoginButton.tsx)
+  - [NotificationsFeed](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/components/Layout/Header/components/NotificationsButton.tsx)
+
+## 7. Methods
+
+- `import { deleteCustomToast } from “@multiversx/sdk-dapp/utils/toasts/customToastsActions”` --> `import { removeCustomToast } from “@multiversx/sdk-dapp/out/store/actions/toasts/toastsActions”`
+- `export { setNonce } from “@multiversx/sdk-dapp/out/utils/account”;` --> `export { setAccountNonce as setNonce } from “@multiversx/sdk-dapp/out/store/actions”`
+- `export { getAccount } from “@multiversx/sdk-dapp/out/utils/account”;` --> `export { getAccountFromApi as getAccount } from “@multiversx/sdk-dapp/out/apiCalls/account/getAccountFromApi”;`
+- `export {
+  setTransactionsToSignedState,
+  setTransactionsDisplayInfoState,
+} from “@multiversx/sdk-dapp/services/transactions/updateSignedTransactions”;` have been removed ❌
+- `export { deleteTransactionToast } from “@multiversx/sdk-dapp/services/transactions/clearTransactions”;` --> `export { removeTransactionToast as deleteTransactionToast } from “@multiversx/sdk-dapp/out/store/actions/toasts/toastsActions”;`
+- `export {
+  addressIsValid,
+} from “@multiversx/sdk-dapp/out/utils/account”;` --> `export { addressIsValid } from “@multiversx/sdk-dapp/out/utils/validation/addressIsValid”;`
+- `export { getShardOfAddress } from “@multiversx/sdk-dapp/out/utils/account”;` -->
+`import { AddressComputer } from “@multiversx/sdk-core/out”;
+const addressComputer = new AddressComputer();
+const getShardOfAddress = addressComputer.getShardOfAddress;
+export { getShardOfAddress };`
+- `walletConnectDeepLink` isn now set in [initApp](https://github.com/multiversx/mx-sdk-dapp/blob/1518a070f10ef0dc133e756c07b6fc0f2165bddb/src/methods/initApp/initApp.types.ts#L23C21-L23C40)
+
+
+## 7. [Types](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDapp/sdkDapp.types.ts)
+
+  - `LoginMethodsEnum` is replaced by `ProviderTypeEnum`
+  - `RawTransactionType` was removed ❌
+  - some new types were added, related to UI elements, like [MvxCopyButtonPropsType](https://github.com/multiversx/mx-template-dapp/blob/a98cadfc291321e9874acd7e53632a6b43ca8c59/src/lib/sdkDapp/components/CopyButton/CopyButton.tsx#L2)

package.json

@@ -9,9 +9,11 @@
     "@fortawesome/fontawesome-svg-core": "6.5.1",
     "@fortawesome/free-solid-svg-icons": "6.5.1",
     "@fortawesome/react-fontawesome": "0.2.0",
-    "@multiversx/sdk-core": "^14.x",
-    "@multiversx/sdk-dapp": "^4.x",
-    "axios": "1.7.4",
+    "@multiversx/sdk-core": "14.2.6",
+    "@multiversx/sdk-dapp": "^5.x",
+    "@multiversx/sdk-dapp-ui": "^0.x",
+    "@multiversx/sdk-dapp-utils": "2.0.2",
+    "axios": "1.10.0",
     "classnames": "2.3.2",
     "moment": "2.29.4",
     "react": "18.2.0",
@@ -21,12 +23,12 @@
   "scripts": {
     "lint": "eslint --ext js,ts,tsx src --fix",
     "run-cypress": "npx cypress run",
-    "start:devnet": "yarn run copy:devnet-config & vite dev",
-    "start:testnet": "yarn run copy:testnet-config & vite dev",
-    "start:mainnet": "yarn run copy:mainnet-config & vite dev",
-    "build:devnet": "yarn run copy:devnet-config & vite build",
-    "build:testnet": "yarn run copy:testnet-config & vite build",
-    "build:mainnet": "yarn run copy:mainnet-config & vite build",
+    "start:devnet": "yarn run copy:devnet-config && vite dev",
+    "start:testnet": "yarn run copy:testnet-config && vite dev",
+    "start:mainnet": "yarn run copy:mainnet-config && vite dev",
+    "build:devnet": "tsc & yarn run copy:devnet-config && vite build",
+    "build:testnet": "tsc & yarn run copy:testnet-config && vite build",
+    "build:mainnet": "tsc & yarn run copy:mainnet-config && vite build",
     "copy:devnet-config": "cp ./src/config/config.devnet.ts ./src/config/index.ts",
     "copy:testnet-config": "cp ./src/config/config.testnet.ts ./src/config/index.ts",
     "copy:mainnet-config": "cp ./src/config/config.mainnet.ts ./src/config/index.ts",
@@ -49,13 +51,12 @@
     "@types/jest": "29.5.5",
     "@types/node": "20.7.1",
     "@types/react": "18.2.23",
-    "@types/react-dom": "18.2.8",
     "@types/react-router-dom": "5.3.3",
     "@typescript-eslint/eslint-plugin": "6.7.0",
     "@typescript-eslint/parser": "6.7.0",
-    "@vitejs/plugin-basic-ssl": "^1.0.1",
+    "@vitejs/plugin-basic-ssl": "1.0.1",
     "@vitejs/plugin-react": "4.1.0",
-    "@wdio/cli": "^8.33.1",
+    "@wdio/cli": "8.33.1",
     "@wdio/concise-reporter": "8.32.4",
     "@wdio/local-runner": "8.32.4",
     "@wdio/mocha-framework": "8.32.4",
@@ -68,7 +69,7 @@
     "eslint-plugin-prettier": "5.0.0",
     "eslint-plugin-react": "7.33.2",
     "eslint-plugin-react-hooks": "4.6.0",
-    "eslint-plugin-sort-exports": "^0.9.1",
+    "eslint-plugin-sort-exports": "0.9.1",
     "jest": "29.7.0",
     "jest-environment-jsdom": "29.7.0",
     "jest-watch-typeahead": "2.2.2",

src/App.tsx

@@ -1,86 +1,36 @@
 import { Route, BrowserRouter as Router, Routes } from 'react-router-dom';
-import { Layout } from 'components';
-import {
-  apiTimeout,
-  environment,
-  sampleAuthenticatedDomains,
-  walletConnectV2ProjectId
-} from 'config';
-import {
-  AxiosInterceptorContext, // using this is optional
-  DappProvider,
-  NotificationModal,
-  SignTransactionsModals,
-  TransactionsToastList
-  // uncomment this to use the custom transaction tracker
-  // TransactionsTracker
-} from 'lib';
-import { RouteNamesEnum } from 'localConstants';
-import { PageNotFound } from 'pages';
+import { PageNotFound } from 'pages/PageNotFound/PageNotFound';
 import { routes } from 'routes';
-import { BatchTransactionsContextProvider } from 'wrappers';
-
-const AppContent = () => {
-  return (
-    <DappProvider
-      environment={environment}
-      customNetworkConfig={{
-        name: 'customConfig',
-        apiTimeout,
-        walletConnectV2ProjectId
-      }}
-      dappConfig={{
-        shouldUseWebViewProvider: true,
-        logoutRoute: RouteNamesEnum.unlock
-      }}
-      customComponents={{
-        transactionTracker: {
-          // uncomment this to use the custom transaction tracker
-          // component: TransactionsTracker,
-          props: {
-            onSuccess: (sessionId: string) => {
-              console.log(`Session ${sessionId} successfully completed`);
-            },
-            onFail: (sessionId: string, errorMessage: string) => {
-              console.log(`Session ${sessionId} failed. ${errorMessage ?? ''}`);
-            }
-          }
-        }
-      }}
-    >
-      <AxiosInterceptorContext.Listener>
-        <Layout>
-          <TransactionsToastList />
-          <NotificationModal />
-          <SignTransactionsModals />
-          <Routes>
-            {routes.map((route) => (
-              <Route
-                path={route.path}
-                key={`route-key-'${route.path}`}
-                element={<route.component />}
-              />
-            ))}
-            <Route path='*' element={<PageNotFound />} />
-          </Routes>
-        </Layout>
-      </AxiosInterceptorContext.Listener>
-    </DappProvider>
-  );
-};
+import { AxiosInterceptors, BatchTransactionsContextProvider } from 'wrappers';
+import { Layout } from './components';
 
 export const App = () => {
   return (
-    <AxiosInterceptorContext.Provider>
-      <AxiosInterceptorContext.Interceptor
-        authenticatedDomains={sampleAuthenticatedDomains}
-      >
-        <Router>
-          <BatchTransactionsContextProvider>
-            <AppContent />
-          </BatchTransactionsContextProvider>
-        </Router>
-      </AxiosInterceptorContext.Interceptor>
-    </AxiosInterceptorContext.Provider>
+    <Router>
+      <AxiosInterceptors>
+        <BatchTransactionsContextProvider>
+          <Layout>
+            <Routes>
+              {routes.map((route) => (
+                <Route
+                  key={`route-key-${route.path}`}
+                  path={route.path}
+                  element={<route.component />}
+                >
+                  {route.children?.map((child) => (
+                    <Route
+                      key={`route-key-${route.path}-${child.path}`}
+                      path={child.path}
+                      element={<child.component />}
+                    />
+                  ))}
+                </Route>
+              ))}
+              <Route path='*' element={<PageNotFound />} />
+            </Routes>
+          </Layout>
+        </BatchTransactionsContextProvider>
+      </AxiosInterceptors>
+    </Router>
   );
 };

src/components/ContractAddress/ContractAddress.tsx

@@ -1,17 +1,28 @@
 import { Label } from 'components';
 import { contractAddress } from 'config';
-import { ACCOUNTS_ENDPOINT, ExplorerLink } from 'lib';
+import {
+  ACCOUNTS_ENDPOINT,
+  getExplorerLink,
+  MvxExplorerLink,
+  useGetNetworkConfig
+} from 'lib';
 
 export const ContractAddress = () => {
+  const { network } = useGetNetworkConfig();
+  const explorerAddress = network.explorerAddress;
+  const explorerLink = getExplorerLink({
+    to: `/${ACCOUNTS_ENDPOINT}/${contractAddress}`,
+    explorerAddress
+  });
   return (
     <p>
       <Label>Contract: </Label>
-      <ExplorerLink
-        page={`/${ACCOUNTS_ENDPOINT}/${contractAddress}`}
+      <MvxExplorerLink
+        link={explorerLink}
         className='border-b border-dotted border-gray-500 hover:border-solid hover:border-gray-800'
       >
         {contractAddress}
-      </ExplorerLink>
+      </MvxExplorerLink>
     </p>
   );
 };