Skip to content

TXN-1540: Custom Provider documentation #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 82 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -45,6 +45,11 @@ Version 2.x introduces [WalletConnect 2.0 support](#walletconnect-20-support).
- [WalletConnect 2.0 Support](#walletconnect-20-support)
- [Defly Wallet (iOS) beta](#defly-wallet-ios-beta)
- [Pera Wallet (Android) beta](#pera-wallet-android-beta)
- ["Module not found" errors in Next.js 13](#module-not-found-errors-in-nextjs-13)
- [Custom Provider](#custom-provider)
- [Custom Provider example](#custom-provider-example)
- [Initializing Custom Provider](#initializing-custom-provider)
- [Manual Provider (example implementation)](#manual-provider-example-implementation)
- [Migration Guide](#migration-guide)
- [Local Development](#local-development)
- [Support](#support)
@@ -476,6 +481,10 @@ useEffect(() => {

- Documentation - https://developer.algorand.org/docs/rest-apis/kmd

### Custom Provider

- Documentation - [Custom Provider](#custom-provider)

## Legacy Wallet Support

Support for these wallets will be removed in a future release.
@@ -714,6 +723,79 @@ module.exports = nextConfig

See https://github.com/WalletConnect/walletconnect-monorepo/issues/1908#issuecomment-1487801131

## Custom Provider

As of v2.2.0, you can now add support for a **custom provider** that delegates wallet actions to your application. This is useful if you want to support a wallet that is not yet integrated with UseWallet, or if your application requires any additional, custom interactions.

### Custom Provider example

```jsx
import { PROVIDER_ID, Metadata, CustomProvider } from '@txnlab/use-wallet'
import type _algosdk from 'algosdk'

export class MyCustomProvider implements CustomProvider {
algosdk: typeof _algosdk

constructor(algosdk: typeof _algosdk, ...) {
this.algosdk = algosdk
// ...
}

async connect(metadata: Metadata): Promise<Wallet> {
// connect to wallet
}

async disconnect(): Promise<void> {
// disconnect from wallet
}

async reconnect(metadata: Metadata): Promise<Wallet | null> {
// reconnect to wallet
}

async signTransactions(
connectedAccounts: string[],
txnGroups: Uint8Array[] | Uint8Array[][],
indexesToSign?: number[] | undefined,
returnGroup?: boolean | undefined
): Promise<Uint8Array[]> {
// sign transactions
}
}
```

### Initializing Custom Provider

```jsx
const providers = useInitializeProviders({
providers: [
{
id: PROVIDER_ID.CUSTOM,
clientOptions: {
name: 'My Custom Provider',
icon: 'data:image/png;base64...',
getProvider: (params: {
network?: Network
algod?: algosdk.Algodv2
algosdkStatic?: typeof algosdk
}) => {
return new MyCustomProvider(params.algosdkStatic ?? algosdk)
}
}
}
// other providers...
]
})
```

### Manual Provider (example implementation)

See [TestManualProvider.ts](https://github.com/TxnLab/use-wallet/blob/main/src/components/Example/TestManualProvider.tsx) for a full example implementation of a custom provider. You can try it by running

```bash
yarn storybook
```

## Migration Guide

Version 2.x is a major version bump, and includes some breaking changes from 1.x.
7 changes: 4 additions & 3 deletions src/clients/custom/client.ts
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@ import { DEFAULT_NETWORK, PROVIDER_ID } from '../../constants'
import { debugLog } from '../../utils/debugLog'
import { ICON } from './constants'
import type _algosdk from 'algosdk'
import type { Network } from '../../types/node'
import type { AlgodClientOptions, Network } from '../../types/node'
import type { InitParams } from '../../types/providers'
import type { Metadata, Wallet } from '../../types/wallet'
import type { CustomProvider, CustomWalletClientConstructor } from './types'
@@ -46,8 +46,9 @@ class CustomWalletClient extends BaseClient {
throw new Error(`Attempt to create custom wallet with no provider specified.`)
}

const algosdk = algosdkStatic || (await Algod.init(algodOptions)).algosdk
const algodClient = getAlgodClient(algosdk, algodOptions)
const algosdk: typeof _algosdk =
algosdkStatic || (await Algod.init(algodOptions as AlgodClientOptions)).algosdk
const algodClient = getAlgodClient(algosdk, algodOptions as AlgodClientOptions)

try {
return new CustomWalletClient({