refactor: Refactor Wallet Implementations

docs/guides/custom-wallets.md

@@ -8,11 +8,9 @@ The basic structure of a (browser) wallet should look like:
 
 ```ts
 import {
-  WalletModule,
+  WalletModuleFactory,
   WalletBehaviourFactory,
   BrowserWallet,
-  Action,
-  Transaction,
 } from "@near-wallet-selector/core";
 
 export interface MyWalletParams {
@@ -21,30 +19,19 @@ export interface MyWalletParams {
 
 const MyWallet: WalletBehaviourFactory<BrowserWallet> = ({
   options,
-  emitter,
   provider,
 }) => {
+  // Initialise wallet-sepecific client(s) here.
+
   return {
-    async isAvailable() {
-      // Determine whether My Wallet is available.
-      // For example, some wallets aren't supported on mobile.
-
-      return true;
-    },
-
     async connect() {
       // Connect to My Wallet for access to account(s).
 
-      const accounts = [];
-      emitter.emit("connected", { accounts });
-
-      return accounts;
+      return [];
     },
 
     async disconnect() {
       // Disconnect from accounts and cleanup (e.g. listeners).
-
-      emitter.emit("disconnected", null);
     },
 
     async getAccounts() {
@@ -79,23 +66,31 @@ const MyWallet: WalletBehaviourFactory<BrowserWallet> = ({
 
 export function setupMyWallet({
   iconUrl = "./assets/my-wallet-icon.png",
-}: MyWalletParams = {}): WalletModule<BrowserWallet> {
-  return {
-    id: "my-wallet",
-    type: "browser",
-    name: "My Wallet",
-    description: null,
-    iconUrl,
-    wallet: MyWallet,
+}: MyWalletParams = {}): WalletModuleFactory<BrowserWallet> {
+  return async () => {
+    // Return null here when wallet is unavailable.
+
+    return {
+      id: "my-wallet",
+      type: "browser",
+      metadata: {
+        name: "My Wallet",
+        description: null,
+        iconUrl,
+      },
+      init: MyWallet,
+    };
   };
 }
 ```
 
-`WalletModule` is made up of two main parts:
-- Behaviour: `wallet`.
-- Metadata: `id`, `type`, `name`, `description` and `iconUrl`.
+`WalletModule` (return type of `WalletModuleFactory`) is made up of four properties:
+- `id`: Unique identifier for the wallet.
+- `type`: Type of wallet to infer the behaviour and metadata.
+- `metadata`: Metadata for displaying information to the user.
+- `init`: The implementation (behaviour) of the wallet.
 
-The metadata of a wallet is accessible as part of the selector's `wallets` state. It's important that `id` is unique to avoid conflicts with other wallets installed by a dApp. The `type` property is coupled to the parameter we pass to `WalletModule` and `WalletBehaviourFactory`.
+A variation of `WalletModule` is added to state during setup under `modules` (`ModuleState`) and accessed by the UI to display the available wallets. It's important that `id` is unique to avoid conflicts with other wallets installed by a dApp. The `type` property is coupled to the parameter we pass to `WalletModuleFactory` and `WalletBehaviourFactory`.
 
 Although we've tried to implement a polymorphic approach to wallets, there are some differences between wallet types that means your implementation won't always mirror other wallets such as Sender vs. Ledger. There are currently four types of wallet:
 
@@ -106,25 +101,15 @@ Although we've tried to implement a polymorphic approach to wallets, there are s
 
 ## Methods
 
-### `isAvailable`
-
-This method is used to determine whether a wallet is available for connecting. For example, injected wallets such as Sender are unavailable on mobile where browser extensions are not supported. The UI will hide the wallet when `false` is returned.
-
-> Note: Injected wallets should be considered available if they aren't installed. The modal handles this case by displaying a download link (using `getDownloadUrl`) when attempting to connect.
-
 ### `connect`
 
-This method handles wallet setup (e.g. initialising wallet-specific libraries) and requesting access to accounts via `FunctionCall` access keys. It's important that `connected` is emitted only when we successfully gain access to at least one account.
+This method handles access to accounts via `FunctionCall` access keys. It's important that at least one account is returned to be in a connected state.
 
 > Note: Hardware wallets are passed a `derivationPath` where other wallets types are called without any parameters.
 
-> Note: The combination of setup and connecting is still under review.
-
 ### `disconnect`
 
-This method handles disconnecting from accounts and cleanup such as event listeners. It's called when either the user specifically disconnects or when switching to a different wallet. It's important that `disconnected` is emitted regardless of exceptions.
-
-> Note: The requirement to emit "disconnected" is still under review and may be removed in favour of accepting the Promise settling as a signal that this method has completed. 
+This method handles disconnecting from accounts and cleanup such as event listeners. It's called when either the user specifically disconnects or when switching to a different wallet.
 
 ### `getAccounts`
 
@@ -143,9 +128,3 @@ Where you might have to construct NEAR Transactions and send them yourself, you
 This method is similar to `signAndSendTransaction` but instead sends a batch of Transactions.
 
 > Note: Exactly how this method should behave when transactions fail is still under review with no clear "right" way to do it. NEAR Wallet (website) seems to ignore any transactions that fail and continue executing the rest. Our approach attempts to execute the transactions in a series and bail if any fail (we will look to improve this in the future by implementing a retry feature).
-
-### `getDownloadUrl`
-
-This method returns the download link for users who haven't installed the wallet. This is usually the Chrome Web Store but ideally this should be browser aware to give the best experience for the user.
-
-> Note: This method is only applicable to injected wallets.

examples/react/src/components/Content.tsx

@@ -77,14 +77,13 @@ const Content: React.FC = () => {
     selector.show();
   };
 
-  const handleSignOut = () => {
-    selector
-      .wallet()
-      .disconnect()
-      .catch((err) => {
-        console.log("Failed to sign out");
-        console.error(err);
-      });
+  const handleSignOut = async () => {
+    const wallet = await selector.wallet();
+
+    wallet.disconnect().catch((err) => {
+      console.log("Failed to sign out");
+      console.error(err);
+    });
   };
 
   const handleSwitchProvider = () => {
@@ -101,10 +100,11 @@ const Content: React.FC = () => {
     alert("Switched account to " + nextAccountId);
   };
 
-  const handleSendMultipleTransactions = () => {
+  const handleSendMultipleTransactions = async () => {
     const { contractId } = selector.options;
+    const wallet = await selector.wallet();
 
-    selector.wallet().signAndSendTransactions({
+    await wallet.signAndSendTransactions({
       transactions: [
         {
           // Deploy your own version of https://github.com/near-examples/rust-counter using Gitpod to get a valid receiverId.
@@ -140,7 +140,7 @@ const Content: React.FC = () => {
   };
 
   const handleSubmit = useCallback(
-    (e: SubmitEvent) => {
+    async (e: SubmitEvent) => {
       e.preventDefault();
 
       // TODO: Fix the typing so that target.elements exists..
@@ -153,8 +153,10 @@ const Content: React.FC = () => {
       // TODO: optimistically update page with new message,
       // update blockchain data in background
       // add uuid to each message, so we know which one is already known
-      selector
-        .wallet()
+
+      const wallet = await selector.wallet();
+
+      wallet
         .signAndSendTransaction({
           signerId: accountId!,
           actions: [

examples/react/src/contexts/WalletSelectorContext.tsx

@@ -60,14 +60,15 @@ export const WalletSelectorContextProvider: React.FC = ({ children }) => {
     setupWalletSelector({
       network: "testnet",
       contractId: "guest-book.testnet",
-      wallets: [
+      debug: true,
+      modules: [
         setupNearWallet(),
         setupSender(),
         setupMathWallet(),
         setupLedger(),
         setupWalletConnect({
           projectId: "c4f79cc...",
-          appMetadata: {
+          metadata: {
             name: "NEAR Wallet Selector",
             description: "Example dApp used by NEAR Wallet Selector",
             url: "https://github.com/near/wallet-selector",

packages/core/src/index.ts

@@ -10,21 +10,29 @@ export { Optional } from "./lib/utils.types";
 
 export {
   WalletSelectorState,
-  WalletState,
+  ModuleState,
   AccountState,
 } from "./lib/store.types";
 
 export {
-  Wallet,
-  WalletType,
-  WalletMetadata,
-  WalletBehaviour,
+  WalletModuleFactory,
   WalletModule,
   WalletBehaviourFactory,
+  WalletBehaviourOptions,
+  Wallet,
+  WalletType,
+  BrowserWalletMetadata,
+  BrowserWalletBehaviour,
   BrowserWallet,
+  InjectedWalletMetadata,
+  InjectedWalletBehaviour,
   InjectedWallet,
-  HardwareWallet,
+  HardwareWalletMetadata,
   HardwareWalletConnectParams,
+  HardwareWalletBehaviour,
+  HardwareWallet,
+  BridgeWalletMetadata,
+  BridgeWalletBehaviour,
   BridgeWallet,
   Transaction,
   Action,
@@ -39,7 +47,5 @@ export {
   DeleteAccountAction,
 } from "./lib/wallet";
 
-export { errors } from "./lib/errors";
-
 export { transformActions } from "./lib/wallet";
 export { waitFor } from "./lib/helpers";

packages/core/src/lib/constants.ts

@@ -1,4 +1,5 @@
 export const PACKAGE_NAME = "near-wallet-selector";
-export const LOCAL_STORAGE_SELECTED_WALLET_ID = `selectedWalletId`;
+export const SELECTED_WALLET_ID = `selectedWalletId`;
+export const PENDING_SELECTED_WALLET_ID = `selectedWalletId:pending`;
 
 export const DEFAULT_DERIVATION_PATH = "44'/397'/0'/0'/1'";

packages/core/src/lib/modal/components/LedgerDerivationPath.tsx

@@ -25,27 +25,29 @@ export const LedgerDerivationPath: React.FC<LedgerDerivationPathProps> = ({
     setLedgerDerivationPath(e.target.value);
   };
 
-  const handleConnectClick = () => {
+  const handleConnectClick = async () => {
     setIsLoading(true);
     // TODO: Can't assume "ledger" once we implement more hardware wallets.
-    const wallet = selector.wallet("ledger");
+    const wallet = await selector.wallet("ledger");
 
     if (wallet.type !== "hardware") {
       return;
     }
 
     setIsLoading(true);
 
-    wallet
+    return wallet
       .connect({ derivationPath: ledgerDerivationPath })
       .then(() => onConnected())
       .catch((err) => setLedgerError(`Error: ${err.message}`))
       .finally(() => setIsLoading(false));
   };
 
-  const handleEnterClick: KeyboardEventHandler<HTMLInputElement> = (e) => {
+  const handleEnterClick: KeyboardEventHandler<HTMLInputElement> = async (
+    e
+  ) => {
     if (e.key === "Enter") {
-      handleConnectClick();
+      await handleConnectClick();
     }
   };
 

packages/core/src/lib/modal/components/Modal.tsx

@@ -1,11 +1,9 @@
 import React, { MouseEvent, useCallback, useEffect, useState } from "react";
 
-import { Wallet } from "../../wallet";
 import { WalletSelectorModal, ModalOptions, Theme } from "../modal.types";
 import { WalletSelector } from "../../wallet-selector.types";
 import { ModalRouteName } from "./Modal.types";
 import { LedgerDerivationPath } from "./LedgerDerivationPath";
-import { WalletNotInstalled } from "./WalletNotInstalled";
 import { WalletNetworkChanged } from "./WalletNetworkChanged";
 import { WalletOptions } from "./WalletOptions";
 import { AlertMessage } from "./AlertMessage";
@@ -38,9 +36,6 @@ export const Modal: React.FC<ModalProps> = ({
   hide,
 }) => {
   const [routeName, setRouteName] = useState<ModalRouteName>("WalletOptions");
-  const [notInstalledWallet, setNotInstalledWallet] = useState<Wallet | null>(
-    null
-  );
   const [alertMessage, setAlertMessage] = useState<string | null>(null);
 
   useEffect(() => {
@@ -63,7 +58,6 @@ export const Modal: React.FC<ModalProps> = ({
 
   const handleDismissClick = useCallback(() => {
     setAlertMessage(null);
-    setNotInstalledWallet(null);
     setRouteName("WalletOptions");
     hide();
   }, [hide]);
@@ -113,16 +107,12 @@ export const Modal: React.FC<ModalProps> = ({
             <WalletOptions
               selector={selector}
               options={options}
-              onWalletNotInstalled={(wallet) => {
-                setNotInstalledWallet(wallet);
-                return setRouteName("WalletNotInstalled");
-              }}
               onConnectHardwareWallet={() => {
                 setRouteName("LedgerDerivationPath");
               }}
               onConnected={handleDismissClick}
-              onError={(message) => {
-                setAlertMessage(message);
+              onError={(err) => {
+                setAlertMessage(err.message);
                 setRouteName("AlertMessage");
               }}
             />
@@ -134,15 +124,6 @@ export const Modal: React.FC<ModalProps> = ({
               onBack={() => setRouteName("WalletOptions")}
             />
           )}
-          {routeName === "WalletNotInstalled" && notInstalledWallet && (
-            <WalletNotInstalled
-              notInstalledWallet={notInstalledWallet}
-              onBack={() => {
-                setNotInstalledWallet(null);
-                setRouteName("WalletOptions");
-              }}
-            />
-          )}
           {routeName === "WalletNetworkChanged" && (
             <WalletNetworkChanged
               selector={selector}