This repository's contents have been migrated to the v3
branch on the https://github.com/TxnLab/use-wallet repository. All further development will continue there.
use-wallet-js
is a TypeScript library aimed at integrating Algorand wallets into decentralized applications (dApps). This vanilla JS version is a framework agnostic rewrite of the @txnlab/use-wallet
React library: https://github.com/TxnLab/use-wallet
This version of UseWallet generally follows the same design principles as the React version, with a few key differences:
-
Framework Agnostic: Unlike v2, which uses React Hooks,
use-wallet-js
employs TypeScript classes, making it usable in non-React dApps. -
Efficient: The core library has been optimized for speed and simplicity:
- Framework-independent
- Implements on-demand loading for wallet SDKs
-
Dynamic SDK Initialization: Instead of initializing all wallet SDKs upfront,
use-wallet-js
dynamically imports the relevant SDK only when a "Connect" action has been triggered. -
Switching Networks: The library lets you configure and set the network(s) your application uses, exposing an algod client instance for the current active network. This pattern was inspired by solid-algo-wallets and allows for easy switching between public/local networks.
-
State Updates: Each of the exported classes exposes a
subscribe
method for subscribing to state updates. In the absense of React, this provides a way for UI elements to re-render when the state changes.
At a high level, use-wallet-js
retains a familiar structure and API for users of v2.x, principally through the WalletManager
class. This class echoes the useWallet
hook API from the previous version, aiming to make transitions between versions as seamless as possible.
While the library in its current form exports only classes, future updates will include framework-specific wrappers for React, Vue, Svelte, and Solid. These wrappers will be built on top of the core library, and will be published as separate packages [TBD].
This repository will serve as the alpha stage for the @txnlab/use-wallet
v3.0.0 release.
Once it reaches beta stage, the commit history will be patched to a branch on the TxnLab/use-wallet repository, with pre-releases published as @txnlab/use-wallet@3.0.0-beta.*
on NPM.
Updates will be posted in the #use-wallet channel on the NFDomains Discord and from the @TxnLab Twitter.
Feedback from the Algorand community during this stage will impact the quality and utility of the final release! Engage with the development, report bugs, and start discussions using the GitHub Issues.
Install the package using NPM:
npm install @txnlab/use-wallet-js
Install peer dependencies:
npm install @blockshake/defly-connect @perawallet/connect @walletconnect/modal @walletconnect/sign-client @walletconnect/types algosdk
The WalletManager
class is the main entry point for the library. It is responsible for initializing the wallet SDKs, managing the network, and handling wallet connections.
import { NetworkId, WalletId, WalletManager } from '@txnlab/use-wallet-js'
const walletManager = new WalletManager({
wallets: [
WalletId.DEFLY,
WalletId.EXODUS,
WalletId.PERA,
{
id: WalletId.WALLETCONNECT,
options: { projectId: '<YOUR_PROJECT_ID>' }
}
],
network: NetworkId.TESTNET
})
Each wallet you wish to support must be included in the wallets
array.
To initialize wallets with default options, pass the wallet ID using the WalletId
enum. To use custom options, pass an object with the id
and options
properties.
Note: WalletConnect's
projectId
option is required. You can get a project ID by registering your application at https://cloud.walletconnect.com/
The network
property is used to set the default network for the application. It can be set to either BETANET
, TESTNET
, MAINNET
, or LOCALNET
. The default (if unset) is TESTNET
.
The active network is persisted to local storage. If your application supports switching networks, when a user revisits your app or refreshes the page, the active network from the previous session will be restored.
The WalletManager
class exposes an algodClient
property, which is an instance of the algosdk.Algodv2
class. This client is initialized with the default network, and can be used to make requests to an Algorand node.
const algodClient = walletManager.algodClient
If the active network changes, the algodClient
instance will be updated to reflect the new network.
By default, the algodClient
instance connects to AlgoNode's free (as in 🍺) API for public networks, and http://localhost
for LOCALNET
. You can override this behavior by passing an algod
configuration object to the WalletManager
constructor.
To configure the algodClient
for the active network only, pass an object with token
, baseServer
and port
properties:
const walletManager = new WalletManager({
wallets: [...],
network: NetworkId.TESTNET,
algod: {
token: '<YOUR_TOKEN>',
baseServer: '<YOUR_SERVER_URL>',
port: '<YOUR_PORT>', // string | number
}
})
To configure the algodClient
for specific networks, pass a mapped object of the network(s) you wish to configure, where each key is a NetworkId
and each value is an algod
configuration object:
const walletManager = new WalletManager({
wallets: [...],
network: NetworkId.TESTNET,
algod: {
[NetworkId.TESTNET]: {
token: '<YOUR_TOKEN>',
baseServer: '<YOUR_SERVER_URL>',
port: '<YOUR_PORT>'
},
[NetworkId.MAINNET]: {
token: '<YOUR_TOKEN>',
baseServer: '<YOUR_SERVER_URL>',
port: '<YOUR_PORT>'
}
}
})
The WalletManager
class manages wallets, networks, and states.
class WalletManager {
constructor({
wallets: Array<T | WalletIdConfig<T>>,
network?: NetworkId,
algod?: NetworkConfig
}: WalletManagerConstructor)
}
-
Subscribes to state changes.
callback
: The function to be executed when the state changes.
-
Sets the active network.
network
: The network to be set as active.
- Refreshes/resumes the sessions of all wallets.
- Returns all wallet instances.
- Returns the currently active network.
- Returns the Algod client for the active network.
- Returns the currently active wallet instance.
- Returns accounts of the currently active wallet.
- Returns addresses of the currently active wallet's accounts.
- Returns the currently active account.
- Returns the address of the currently active account.
- Throws an error if no active wallet, or returns the
signTransactions
method from the active wallet:
public signTransactions(
txnGroup: algosdk.Transaction[] | algosdk.Transaction[][] | Uint8Array[] | Uint8Array[][],
indexesToSign?: number[],
returnGroup?: boolean // default: true
): Promise<Uint8Array[]>
- Throws an error if no active wallet, or returns a
TransactionSigner
function that signs with the active wallet.
public transactionSigner(
txnGroup: algosdk.Transaction[],
indexesToSign: number[]
): Promise<Uint8Array[]>
- Throws an error if no active account, or returns a
TransactionSignerAccount
object withaddr
set to the active address andsigner
set tothis.transactionSigner
(see above).
/** A wrapper around `TransactionSigner` that also has the sender address. */
interface TransactionSignerAccount {
addr: Readonly<string>
signer: TransactionSigner
}
See the examples/vanilla-ts directory for a simple Vite app that demonstrates the library's functionality.
Coming soon
Coming soon
MIT ©2024 TxnLab, Inc.