Skip to content

SilentRhetoric/solid-algo-wallets

Repository files navigation

Solid Algo Wallets

solid-algo-wallets

npm version

The solid-algo-wallets library provides a simple, unified interface for integrating several Algorand wallets into a web application client built with SolidJS. A live demo can be found at https://solid-algo-wallets-example.netlify.app.

This work has been performed with support from the Algorand Foundation xGov Grants Program.

Quick start

Install it

npm i solid-algo-wallets
# or
yarn add solid-algo-wallets
# or
pnpm add solid-algo-wallets

Use it

import { UseSolidAlgoWallets } from 'solid-algo-wallets'

Global This

In order to use the library in the browser with Buffer, the following must be added to index.html (or at the Javascript entrypoint of your project):

<script>
  global = globalThis
</script>

Overview

The solid-algo-wallets library provides a simple, unified interface for integrating Algorand wallets into a web application client built with SolidJS.

Importing solid-algo-wallet into your app client provides convenient functions to:

  • Access multiple wallet interfaces
  • Get icons and images for the wallets
  • Connect to a wallet and get connected acounts
  • Select an account to use in the app
  • Provide the selected account as a reactive signal
  • Sign transactions with the connected wallet account
  • Reconnect to the wallet on page reload

Example SolidJS Application

A working demo can be found here: https://solid-algo-wallets-example.netlify.app

The example app code can be found here: https://github.com/SilentRhetoric/solid-algo-wallets-example

Supported Wallets

The following wallet interfaces are supported and the library provides icons & logos:

Wallet Home Page Technical Docs Notes
Defly https://defly.app https://docs.defly.app/app/overview Mobile
Pera https://perawallet.app https://docs.perawallet.app Mobile & Web
Exodus https://www.exodus.com https://docs.exodus.com Chrome extension, MainNet only
Ledger https://www.ledger.com/ledger-live https://github.com/LedgerHQ/ledger-live/tree/develop/libs/ledgerjs/packages/hw-app-algorand Direct USB in Chrome
WalletConnect https://walletconnect.com https://docs.walletconnect.com/2.0/ Any compatible app
MetaMask (experimental) https://metamask.io https://snapalgo.io https://snapalgo.io/docs Pre-release Algorand Snap running in MetaMask Flask https://metamask.io/flask/

WalletConnect-compatible Wallets

The following wallets are known to be compatible with the generic WalletConnect interface:

Wallet Home Page Technical Docs Notes
AWallet https://www.a-wallet.net/ https://github.com/scholtz/wallet/ Manual connection to web wallet via copy/paste

Potential Additional Wallets

The following wallets have been identified as supporting Algorand but have not been evaluated for integration. Pull requests encouraged!

Wallet Home Page Technical Docs Notes
D'CENT https://dcentwallet.com https://dev-docs.dcentwallet.com/dwc/Introduction Hardware and app wallets
OneKey https://onekey.so https://developer.onekey.so/connect-to-hardware/hardware-sdk/api-reference/algorand/algosigntransaction
Guarda https://guarda.com

Known Unsupported Wallets

  • Daffi Wallet is not able to establish a WalletConnect session as of Sep 9th, 2023 and so is not included. A Pull Request would be accepted when the wallet can be successfully connected.

  • AlgoSigner is no longer maintained by PureStake and so is not included.

  • MyAlgo has shut down and so is not included.

How It Works

Configuration

The library is configured using environment variables from a .env file in the project which uses the library. A .env.template file is provided in this repo. The following things are configurable:

  • Algod server/token/port for each public network as well as AlgoKit LocalNet
  • Block explorer base URL to construct explorer links for each network. Supports AlgoExplorer and Dappflow linking.
  • Project ID, Project Name, Project Description, Project URL, and Project ICON for the Dapp's project on WalletConnect

UseSolidAlgoWallets

The UseSolidAlgoWallets function returns a reactive root that provides the active wallet/metadata/address, methods to connect/reconnect/disconnect wallets, and a transactionSigher function that enables signing transactions with the connected wallet.

UseNetwork

The UseNetwork function returns a reactive root that provides an alogd client for the selected network, as well as helpful functions to create URLs for block explorer linking.

Design Decisions

The solid-algo-wallets library was designed in an opinionated way to provide a large menu of wallet connectivity options in a simple package for developers and experience for users. Following are some of the design decisions and the rationale behind them.

Signing Interface

The wallet signing function follows the type of the Algorand JavaScript SDK TransactionSigner type (https://algorand.github.io/js-algorand-sdk/types/TransactionSigner.html). This makes it easy to use the wallet signing function together with the rest of the JS SDK and its atomic transaction group functions.

This design was chosen because it makes it easy to invoke the signing function, which only requires providing an array of algosdk.Transaction class objects and an array of indexes to sign in that Transaction array. The app can simply pass in the JavaScript objects without needing to handle encoding/decoding.

Single Active Wallet & Account

When using the library, a single wallet can be connected to the application at a time. From that wallet, multiple accounts can be selected on the wallet side and provided to the app as an array. The user can then choose a single account from that array to be the active account in the app's state for signing transactions via the connected wallet.

This design strives to implement the principle that blockchain apps should have clear, simple, and intuitive user interfaces that enable great user experiences. Using decentralized apps already involves a number of UX complexities, so this library avoids having multiple wallets connected simultaneously due to the additional UX complexity that introduces.

State Management

The library is designed to manage state globally using SolidJS reactive roots on the client side of the web appplication. This allows a web app to consume/set the app's wallet state easily from anywhere in the code.

This design was chosen both for simplicity and also because truly decentralized web apps should allow users to use the client without dependency on a back-end server. These wallet interfaces should be managed on the client so that an end user can download and install a web app locally and continue using it even if the host server becomes unavailable.

Note that this approach is not suitable for Solid Start apps which utilize server-side rendering (SSR) and will cause problems. It may be possible to provide the reactive roots to a context provider, but this is untested as yet.

Additional Resources

To learn more about SolidJS, visit https://www.solidjs.com.

To learn more about developing on Algorand, visit https://developer.algorand.org.