added ExtensionTools: zero-dependency module to work with Polkadot and Ethereum browser extensions

Author: fend25

README.md

@@ -66,3 +66,200 @@ Utf16.lengthInBytes('👨🏼‍👩🏼‍👧🏼‍👧🏼') // 19
 ```
 
 **[Full documentation for the UTF and hex string helpers](https://github.com/fend25/utf-helpers#readme)**
+
+## Extension tools
+
+### Ethereum
+
+A tiny (0.5 Kb) and zero-dependency module to detect whether metamask extension presents,
+detect whether the access is granted and get account(s) or request access.
+
+Node.js-safe, it will not throw unexpected errors like "cannot find window".  
+Also, these methods are safe in a common way, they don't throw errors, 
+but return wrapped result or error with additional info.
+
+The `ExtensionsTools`, `Ethereum` and `Polkadot` modules should be imported directly from  
+`@unique-nft/utils/extension` because they are not available at `@unique-nft/utils`.
+
+For Ethereum browser extensions, like metamask:
+
+```ts
+import {ExtensionTools} from '@unique-nft/utils/extension'
+
+const Ethereum = ExtensionTools.Ethereum
+//or
+import {Ethereum} from '@unique-nft/utils/extension'
+
+const getAccountsResult = await Ethereum.getAccounts()
+/*
+{
+  accounts: ['0xf8cC75F76d46c3b1c5F270Fe06c8FFdeAB8E5eaB'],
+  info: {extensionFound: true, chainId: '0x22b2', chainIdNumber: 8882},
+  selectedAddress: 0xf8cC75F76d46c3b1c5F270Fe06c8FFdeAB8E5eaB
+}
+// or, when there is no granted account:
+{accounts: [], selectedAddress: null, info: {extensionFound: true, chainId: '0x22b2', chainIdNumber: 8882}}
+// or, when there is no extension:
+{accounts: [], selectedAddress: null, info: {extensionFound: false}}
+// in Node.js `info.extensionFound is` always false.
+*/
+```
+
+Simple example which just checks extension and tries to get an address without prompting user:
+
+```ts
+import {Ethereum} from '@unique-nft/utils/extension'
+
+let result = await Ethereum.getAccounts()
+
+if (result.info.extensionFound && result.selectedAddress) {
+  //woohoo, let's create a Web3 Provider like that:
+  const provider = new ethers.providers.Web3Provider(window.ethereum)
+  console.log(ethers.utils.formatEther(await provider.getBalance(result.selectedAddress)))
+}
+```
+
+More complex example, when we want to request user to grant access.  
+_Note: If user has already granted access, it will work silently, just like_ `getAccounts`.
+
+```ts
+import {Ethereum} from '@unique-nft/utils/extension'
+
+const result = await Ethereum.requestAccounts()
+
+if (result.selectedAddress) {
+  //woohoo, let's create a Web3 Provider like that:
+  const provider = new ethers.providers.Web3Provider(window.ethereum)
+  console.log(ethers.utils.formatEther(await provider.getBalance(result.selectedAddress)))
+} else {
+  if (result.info.userRejected) {
+    console.log(`Oops, user doesn't want us. Let's show them some kawaii popup`)
+  } else {
+    console.error(result.info.error)
+  }
+}
+```
+
+### Polkadot
+
+A tiny (1.5 Kb) and zero-dependency (no WASM, no anything) module to work with Polkadot extensions family - 
+Polkadot.js, Subwallet, Talisman and other Polkadot.js-compatible wallets.  
+Actually it's a neat and really useful replacement for the extension-dapp module.
+
+This module works in browsers with multiple wallets, it can detect whether there is an extension installed
+and contains the boilerplate logic around detecting wallets, it's access and so on.
+
+Node.js-safe, it will not throw unexpected errors like "cannot find window".  
+Also, these methods are safe in a common way, they don't throw errors,
+but return wrapped result or error with additional info.
+
+The `ExtensionsTools`, `Ethereum` and `Polkadot` modules should be imported directly  
+from `@unique-nft/utils/extension` because they are not available at `@unique-nft/utils`.
+
+```ts
+import {ExtensionTools} from '@unique-nft/utils/extension'
+//or
+import {Polkadot} from '@unique-nft/utils/extension'
+
+const result = await Polkadot.enableAndLoadAllWallets()
+
+result.info.extensionFound // boolean, in Node.js it's always false.
+
+result.accounts[0].address // string
+```
+
+Also, it contains ready signer object for the [Unique SDK](https://www.npmjs.com/package/@unique-nft/sdk):
+
+```ts
+import {Polkadot} from '@unique-nft/utils/extension'
+import {Sdk} from '@unique-nft/sdk'
+
+const {accounts} = await Polkadot.enableAndLoadAllWallets() // Some checks are omitted
+const account = accounts[0] // For the simplicity
+
+const sdk = new Sdk({
+  baseUrl: 'https://rest.opal.uniquenetwork.dev/v1',
+  signer: account.uniqueSdkSigner
+})
+
+// or provide it (or override default one) on demand with specific request:
+
+const sdkWithoutSigner = new Sdk({baseUrl: 'https://rest.opal.uniquenetwork.dev/v1'})
+
+const result = await sdkWithoutSigner.balance.transfer.submitWaitResult({
+  amount: 1,
+  address: account.address,
+  destination: "5..." // some another address
+}, {
+  signer: account.uniqueSdkSigner
+})
+```
+
+##### Return types
+
+`enableAndLoadAllWallets` and `loadEnabledWallets` return such result:
+
+```ts
+export interface IPolkadotExtensionLoadWalletsResult {
+  info: {
+    extensionFound: boolean
+    accountsFound: boolean
+    userHasWalletsButHasNoAccounts: boolean
+    userHasBlockedAllWallets: boolean
+  }
+
+  accounts: IPolkadotExtensionAccount[]
+  
+  wallets: IPolkadotExtensionWallet[]
+
+  rejectedWallets: Array<{
+    name: string
+    version: string
+    isEnabled: boolean | undefined
+    prettyName: string
+    logo: {
+      ipfsCid: string,
+      url: string,
+    }
+    error: Error
+    isBlockedByUser: boolean
+  }>
+}
+```
+
+where `IPolkadotExtensionAccount` is:
+
+```ts
+export interface IPolkadotExtensionAccount extends Omit<Signer, 'signRaw'> {
+  name: string
+  id: string
+  address: string
+  addressShort: string
+  
+  wallet: {
+    name: string
+    version: string
+    isEnabled: boolean | undefined
+    prettyName: string
+    logo: {
+      ipfsCid: string,
+      url: string,
+    }
+  }
+  
+  signRaw: (raw: SignerPayloadRawWithAddressAndTypeOptional | string) => Promise<SignerResult>
+  signPayload: (payload: SignerPayloadJSON) => Promise<SignerResult>
+  update?: (id: number, status: any) => void
+
+  uniqueSdkSigner: {
+    sign: (unsignedTxPayload: SDK_UnsignedTxPayloadBody) => Promise<SDK_SignTxResultResponse>
+  }
+
+  meta: {
+    genesisHash: string | null
+    name: string
+    source: string
+  }
+  type: KeypairType // 'ed25519' | 'sr25519' | 'ecdsa' | 'ethereum'
+}
+```

configs/tsup.config.ts

@@ -6,6 +6,7 @@ export default defineConfig([
       index: "src/index.ts",
       string: "src/StringUtils/index.ts",
       address: "src/Address/index.ts",
+      extension: "src/ExtensionTools/index.ts",
     },
     format: [
       "esm",

src/ExtensionTools/ethereum.ts

@@ -0,0 +1,101 @@
+export interface IEthereumRequestAccountsResult {
+  accounts: string[]
+  selectedAddress: string | null
+  info: {
+    extensionFound: boolean
+    chainId?: string
+    chainIdNumber?: number
+    userRejected?: boolean
+    error?: Error
+  }
+}
+
+export interface AddEthereumChainParameter {
+  chainId: string // A 0x-prefixed hexadecimal string
+  chainName: string
+  nativeCurrency: {
+    name: string
+    symbol: string // 2-6 characters long
+    decimals: 18
+  }
+  rpcUrls: string[]
+  blockExplorerUrls?: string[]
+  iconUrls?: string[] // Currently ignored
+}
+
+
+export const requestAccounts = async (): Promise<Promise<IEthereumRequestAccountsResult>> => {
+  if (typeof window === 'undefined' || !(window as any).ethereum) {
+    return {accounts: [], selectedAddress: null, info: {extensionFound: false}}
+  }
+  const ethereum = (window as any).ethereum
+  let accounts: string[] = []
+  try {
+    accounts = await ethereum.request({method: 'eth_requestAccounts'})
+    return {
+      accounts,
+      selectedAddress: ethereum.selectedAddress,
+      info: {
+        extensionFound: true,
+        chainId: ethereum.chainId,
+        chainIdNumber: parseInt(ethereum.chainId, 16),
+      },
+    }
+  } catch (error: any) {
+    // EIP-1193 userRejectedRequest error code is 4001
+    // If this happens, the user rejected the connection request.
+
+    return {
+      accounts: [],
+      selectedAddress: null,
+      info: {extensionFound: true, userRejected: error.code === 4001, error},
+    }
+  }
+}
+
+export const getAccounts = async (): Promise<IEthereumRequestAccountsResult> => {
+  if (typeof window === 'undefined' || !(window as any).ethereum) {
+    return {accounts: [], selectedAddress: null, info: {extensionFound: false}}
+  }
+  const ethereum = (window as any).ethereum
+
+  const accounts: string[] = await ethereum.request({method: 'eth_accounts'})
+  return {
+    accounts,
+    selectedAddress: ethereum.selectedAddress,
+    info: {
+      extensionFound: true,
+      chainId: ethereum.chainId,
+      chainIdNumber: parseInt(ethereum.chainId, 16),
+    },
+  }
+}
+
+export const addChainToMetamask = async(chainData: AddEthereumChainParameter): Promise<void> => {
+  const safeGetAccountsResult = await getAccounts()
+  if (!safeGetAccountsResult.info.extensionFound) {
+    throw new Error(`No browser extension found`)
+  }
+  const ethereum = (window as any).ethereum
+
+  if (ethereum.chainId === chainData.chainId) {
+    console.log(`No need to add the chain to wallet - wallet already has ${chainData.chainName}'s chainId: ${ethereum.chainId} (${parseInt(ethereum.chainId)})`)
+    return
+  }
+
+  try {
+    await ethereum.request({
+      method: 'wallet_addEthereumChain',
+      params: [chainData],
+    })
+  } catch (error: any) {
+    console.error('Error during attempt to add chain to wallet', error.code, error)
+    throw error
+  }
+}
+
+export const Ethereum = {
+  requestAccounts,
+  getAccounts,
+  addChainToMetamask,
+}

src/ExtensionTools/index.ts

@@ -0,0 +1,35 @@
+import {Ethereum} from './ethereum'
+import {Polkadot} from './polkadot'
+
+const ExtensionTools = {
+  Ethereum,
+  Polkadot,
+}
+
+export {ExtensionTools, Ethereum, Polkadot}
+
+export default ExtensionTools
+
+// =========================================
+// types
+// =========================================
+
+export type {
+  AddEthereumChainParameter,
+  IEthereumRequestAccountsResult,
+} from './ethereum'
+
+export type {
+  IPolkadotExtensionWallet,
+  IPolkadotExtensionWalletInfo,
+  IPolkadotExtensionAccount,
+  IPolkadotExtensionGenericInfo,
+  IPolkadotExtensionLoadWalletsResult,
+  IPolkadotExtensionListWalletsResult,
+  IPolkadotExtensionLoadWalletByNameResult,
+  SignerPayloadJSON,
+  SignerPayloadRaw,
+  SignerPayloadRawWithAddressAndTypeOptional,
+  SignerPayloadJSONWithAddressOptional,
+  SignerResult,
+} from './polkadot'