feat: use-wallet v2 integration, expanded guidelines, improvements in kmd support (#13)

* refactor: changing name for kmd

Author: aorumbayev

.gitattributes

@@ -1 +1 @@
-* text=lf
+* text=auto eol=lf

.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Proposed Changes
+
+-
+-
+-

template_content/.algokit.toml

@@ -1,2 +1,2 @@
 [algokit]
-min_version = "v1.1.0"
+min_version = "v1.3.0b1"

template_content/.env.template.jinja

@@ -16,6 +16,17 @@ VITE_INDEXER_TOKEN={{ indexer_token }}
 VITE_INDEXER_SERVER={{ indexer_server }}
 VITE_INDEXER_PORT={{ indexer_port }}
 
+# KMD
+# Please note:
+# 1. This is only needed for LocalNet since
+# by default KMD provider is ignored on other networks.
+# 2. AlgoKit LocalNet starts with a single wallet called 'unencrypted-default-wallet',
+# with heaps of tokens available for testing.
+VITE_KMD_TOKEN={{ algod_token }}
+VITE_KMD_SERVER={{ algod_server }}
+VITE_KMD_PORT=4002
+VITE_KMD_WALLET="unencrypted-default-wallet"
+VITE_KMD_PASSWORD=""
 
 # # ======================
 # # TestNet configuration:

template_content/.gitattributes

@@ -1 +1 @@
-* text=lf
+* text=auto eol=lf

template_content/README.md.jinja

@@ -8,8 +8,10 @@ This starter React project has been generated using AlgoKit. See below for defau
 
 1. Clone this repository locally
 2. Install pre-requisites:
+   - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine.
    - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The minimum required version is `1.1`. Ensure you can execute `algokit --version` and get `1.1` or later.
    - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will run `npm install` to install NPM packages and dependencies for your frontend component/webapp.
+   - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you.
 3. Open the project and start debugging / developing via:
    - VS Code
      1. Open the repository root in VS Code
@@ -24,6 +26,8 @@ This starter React project has been generated using AlgoKit. See below for defau
 1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again
 2. Follow step 3 above
 
+> Please note, by default frontend is pre configured to run against Algorand LocalNet. If you want to run against TestNet or MainNet, comment out the current environment variable and uncomment the relevant one in [`.env`](.env) file that is created after running bootstrap command and based on [`.env.template`](.env.template).
+
 {% if use_github_actions -%}
 
 ### Continuous Integration
@@ -44,6 +48,19 @@ The project template provides base Github Actions workflows for continuous deplo
 
 {% endif -%}
 
+# Algorand Wallet integrations
+
+The template comes with [`use-wallet`](https://github.com/txnlab/use-wallet) integration, which provides a React hook for connecting to an Algorand wallet providers. The following wallet providers are included by default:
+- LocalNet:
+- - [KMD/Local Wallet](https://github.com/TxnLab/use-wallet#kmd-algorand-key-management-daemon) - Algorand's Key Management Daemon (KMD) is a service that manages Algorand private keys and signs transactions. Works best with AlgoKit LocalNet and allows you to easily test and interact with your dApps locally.
+- TestNet and others:
+- - [Pera Wallet](https://perawallet.app).
+- - [Defly Wallet](https://defly.app).
+- - [Exodus Wallet](https://www.exodus.com).
+- - [Daffi Wallet](https://www.daffi.me).
+
+Refer to official [`use-wallet`](https://github.com/txnlab/use-wallet) documentation for detailed guidelines on how to integrate with other wallet providers (such as WalletConnect v2). Too see implementation details on the use wallet hook and initialization of extra wallet providers refer to [`App.tsx`](./src/App.tsx).
+
 # Tools
 
 This project makes use of React and Tailwind to provider a base project configuration to develop frontends for your Algorand dApps and interactions with smart contracts. The following tools are in use:
@@ -54,9 +71,9 @@ This project makes use of React and Tailwind to provider a base project configur
 - [Tailwind CSS](https://tailwindcss.com/) - A utility-first CSS framework for rapidly building custom designs.
 {% endif -%}{% if use_daisy_ui -%}
 - [daisyUI](https://daisyui.com/) - A component library for Tailwind CSS.
-{% endif -%}{% if use_wallet -%}
-- [use-wallet](https://github.com/txnlab/use-wallet) - A React hook for connecting to an Algorand wallet providers. Includes integrations with [Exodus](https://www.exodus.com/), [Pera](https://perawallet.app/), and [Defly](https://defly.app/).
-{% endif -%}- [npm](https://www.npmjs.com/): Node.js package manager
+{% endif -%}
+- [use-wallet](https://github.com/txnlab/use-wallet) - A React hook for connecting to an Algorand wallet providers.
+- [npm](https://www.npmjs.com/): Node.js package manager
 {% if use_jest -%}
 - [jest](https://jestjs.io/): JavaScript testing framework
 {% endif -%}{% if use_playwright -%}
@@ -75,4 +92,27 @@ It has also been configured to have a productive dev experience out of the box i
 
 # Integrating with smart contracts and application clients
 
-Refer to the detailed guidance on [integrating with smart contracts and application clients](./src/contracts/README.md). In essence, for any smart contract codebase generated with AlgoKit or ther tools that produce compile contracts into ARC34 compliant app specifications, you can use the `algokit generate` command to generate TypeScript or Python typed client. Once generated simply drag and drop the generated client into `./src/contracts` and import it into your React components as you see fit.
+Refer to the detailed guidance on [integrating with smart contracts and application clients](./src/contracts/README.md). In essence, for any smart contract codebase generated with AlgoKit or other tools that produce compile contracts into ARC34 compliant app specifications, you can use the `algokit generate` command to generate TypeScript or Python typed client. Once generated simply drag and drop the generated client into `./src/contracts` and import it into your React components as you see fit.
+
+# Vite compatibility with `js-algorand-sdk` and `algokit clients`
+
+If you are receiving `address malformed` errors when sending direct calls to abi methods on AlgoKit typed clients where ABI parameters expect ABI transactions to be passed, this is a known edge case and a bug that occurs on [Vite in dev mode](https://github.com/vitejs/vite/issues/9528). A fix is in the works on [js-algorand-sdk](https://github.com/algorand/js-algorand-sdk/issues/740) side (which is used as a main low-level dependency by AlgoKit to generate typed clients), but in the meantime you can use a simple workaround described below:
+
+```ts
+Instead of:
+
+const response = await myAlgoKitTypedClient
+  .someExternalMethod({
+    some_txn_param: someTxnObject,
+  })
+
+use:
+
+const response = await appClient
+  .compose()
+  .someExternalMethod({
+    some_txn_param: someTxnObject,
+  })
+  .execute()
+```
+

template_content/package.json.jinja

@@ -15,7 +15,7 @@
     {% if use_eslint_prettier -%}
     "eslint": "8.42.0",
     "eslint-config-prettier": "8.8.0",
-    "eslint-plugin-prettier": "4.2.1",
+    "eslint-plugin-prettier": "5.0.0",
     "@typescript-eslint/eslint-plugin": "5.59.9",
     "@typescript-eslint/parser": "5.59.9",
     {% endif -%}
@@ -36,12 +36,12 @@
     "vite": "4.3.9"
   },
   "dependencies": {
-    "@walletconnect/modal-sign-html": "^2.5.5",
-    "@algorandfoundation/algokit-utils": "^2.2.0",
-    "@blockshake/defly-connect": "1.1.5",
-    "@daffiwallet/connect": "1.0.3",
-    "@perawallet/connect": "1.2.3",
-    "@txnlab/use-wallet": "2.0.0",
+    "@walletconnect/modal-sign-html": "^2.6.0",
+    "@algorandfoundation/algokit-utils": "^2.3.1",
+    "@blockshake/defly-connect": "^1.1.5",
+    "@daffiwallet/connect": "^1.0.3",
+    "@perawallet/connect": "^1.3.1",
+    "@txnlab/use-wallet": "^2.0.0",
     "algosdk": "^2.3.0",
     {% if use_daisy_ui -%}
     "daisyui": "3.1.0",

template_content/src/App.tsx

@@ -1,10 +1,39 @@
-import { WalletProvider, useWallet } from '@txnlab/use-wallet'
+import { DeflyWalletConnect } from '@blockshake/defly-connect'
+import { DaffiWalletConnect } from '@daffiwallet/connect'
+import { PeraWalletConnect } from '@perawallet/connect'
+import { PROVIDER_ID, ProvidersArray, WalletProvider, useInitializeProviders, useWallet } from '@txnlab/use-wallet'
+import algosdk from 'algosdk'
 import { SnackbarProvider } from 'notistack'
 import { useState } from 'react'
 import ConnectWallet from './components/ConnectWallet'
 import Transact from './components/Transact'
-import { useAlgoWallet } from './hooks/useAlgoWalletProvider'
-import { getAlgodConfigFromViteEnvironment } from './utils/network/getAlgoClientConfigs'
+import { getAlgodConfigFromViteEnvironment, getKmdConfigFromViteEnvironment } from './utils/network/getAlgoClientConfigs'
+
+let providersArray: ProvidersArray
+if (import.meta.env.VITE_ALGOD_NETWORK === '') {
+  const kmdConfig = getKmdConfigFromViteEnvironment()
+  providersArray = [
+    {
+      id: PROVIDER_ID.KMD,
+      clientOptions: {
+        wallet: kmdConfig.wallet,
+        password: kmdConfig.password,
+        host: kmdConfig.server,
+        token: String(kmdConfig.token),
+        port: String(kmdConfig.port),
+      },
+    },
+  ]
+} else {
+  providersArray = [
+    { id: PROVIDER_ID.DEFLY, clientStatic: DeflyWalletConnect },
+    { id: PROVIDER_ID.PERA, clientStatic: PeraWalletConnect },
+    { id: PROVIDER_ID.DAFFI, clientStatic: DaffiWalletConnect },
+    { id: PROVIDER_ID.EXODUS },
+    // If you are interested in WalletConnect v2 provider
+    // refer to https://github.com/TxnLab/use-wallet for detailed integration instructions
+  ]
+}
 
 export default function App() {
   const [openWalletModal, setOpenWalletModal] = useState<boolean>(false)
@@ -21,17 +50,20 @@ export default function App() {
 
   const algodConfig = getAlgodConfigFromViteEnvironment()
 
-  const walletProviders = useAlgoWallet({
-    nodeToken: String(algodConfig.token),
-    nodeServer: algodConfig.server,
-    nodePort: String(algodConfig.port),
-    network: algodConfig.network,
-    autoConnect: true,
+  const walletProviders = useInitializeProviders({
+    providers: providersArray,
+    nodeConfig: {
+      network: algodConfig.network,
+      nodeServer: algodConfig.server,
+      nodePort: String(algodConfig.port),
+      nodeToken: String(algodConfig.token),
+    },
+    algosdkStatic: algosdk,
   })
 
   return (
     <SnackbarProvider maxSnack={3}>
-      <WalletProvider value={walletProviders.walletProviders}>
+      <WalletProvider value={walletProviders}>
         <div className="hero min-h-screen bg-teal-400">
           <div className="hero-content text-center rounded-lg p-6 max-w-md bg-white mx-auto">
             <div className="max-w-md">

template_content/src/components/ConnectWallet.tsx.jinja

@@ -1,4 +1,4 @@
-import { useWallet } from '@txnlab/use-wallet'
+import { Provider, useWallet } from '@txnlab/use-wallet'
 import Account from './Account'
 
 interface ConnectWalletInterface {
@@ -9,6 +9,8 @@ interface ConnectWalletInterface {
 const ConnectWallet = ({ openModal, closeModal }: ConnectWalletInterface) => {
   const { providers, activeAddress } = useWallet()
 
+  const isKmd = (provider: Provider) => provider.metadata.name.toLowerCase() === 'kmd'
+
   return (
     <dialog id="connect_wallet_modal" className={`modal ${openModal ? 'modal-open' : ''}`}{% if use_daisy_ui == false -%} style={{ '{{' }} display: openModal ? 'block' : 'none' {{ '}}' }}{% endif -%}>
       <form method="dialog" className="modal-box">
@@ -32,12 +34,14 @@ const ConnectWallet = ({ openModal, closeModal }: ConnectWalletInterface) => {
                   return provider.connect()
                 }}
               >
-                <img
-                  alt={`wallet_icon_${provider.metadata.id}`}
-                  src={provider.metadata.icon}
-                  style={{ '{{' }} objectFit: 'contain', width: '30px', height: 'auto' {{ '}}' }}
-                />
-                <span>{provider.metadata.name}</span>
+                {!isKmd(provider) && (
+                  <img
+                    alt={`wallet_icon_${provider.metadata.id}`}
+                    src={provider.metadata.icon}
+                    style={{ '{{' }} objectFit: 'contain', width: '30px', height: 'auto' {{ '}}' }}
+                  />
+                )}
+                <span>{isKmd(provider) ? 'LocalNet Wallet' : provider.metadata.name}</span>
               </button>
             ))}
         </div>
@@ -57,7 +61,18 @@ const ConnectWallet = ({ openModal, closeModal }: ConnectWalletInterface) => {
               className="btn btn-warning"
               data-test-id="logout"
               onClick={() => {
-                providers?.find((p) => p.isActive)?.disconnect()
+                if (providers) {
+                  const activeProvider = providers.find((p) => p.isActive)
+                  if (activeProvider) {
+                    activeProvider.disconnect()
+                  } else {
+                    // Required for logout/cleanup of inactive providers
+                    // For instance, when you login to localnet wallet and switch network
+                    // to testnet/mainnet or vice verse.
+                    localStorage.removeItem('txnlab-use-wallet')
+                    window.location.reload()
+                  }
+                }
               }}
             >
               Logout

template_content/src/components/ErrorBoundary.tsx

@@ -1,39 +1,42 @@
-import React, { ErrorInfo, ReactNode } from 'react'
+import React, { ReactNode } from 'react'
 
 interface ErrorBoundaryProps {
   children: ReactNode
-  fallback: ReactNode
 }
 
 interface ErrorBoundaryState {
   hasError: boolean
+  error: Error | null
 }
 
 class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
   constructor(props: ErrorBoundaryProps) {
     super(props)
-    this.state = { hasError: false }
+    this.state = { hasError: false, error: null }
   }
 
-  static getDerivedStateFromError(_: Error): ErrorBoundaryState {
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
     // Update state so the next render will show the fallback UI.
-    return { hasError: true }
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  componentDidCatch(error: Error, info: ErrorInfo): void {
-    // Example "componentStack":
-    //   in ComponentThatThrows (created by App)
-    //   in ErrorBoundary (created by App)
-    //   in div (created by App)
-    //   in App
-    // logErrorToMyService(error, info.componentStack)
+    return { hasError: true, error: error }
   }
 
   render(): ReactNode {
     if (this.state.hasError) {
       // You can render any custom fallback UI
-      return this.props.fallback
+      return (
+        <div className="hero min-h-screen bg-teal-400">
+          <div className="hero-content text-center rounded-lg p-6 max-w-md bg-white mx-auto">
+            <div className="max-w-md">
+              <h1 className="text-4xl">Error occured</h1>
+              <p className="py-6">
+                {this.state.error?.message.includes('Attempt to get default algod configuration')
+                  ? 'Please make sure to set up your environment variables correctly. Create a .env file based on .env.template and fill in the required values. This controls the network and credentials for connections with Algod and Indexer.'
+                  : this.state.error?.message}
+              </p>
+            </div>
+          </div>
+        </div>
+      )
     }
 
     return this.props.children