@avail-project/wallet-sdk

v1.0.8

Published

2 months ago

![Avail Wallet SDK](https://files.availproject.org/avail-wallet-sdk/meta.svg)

0High
0Medium
0Low

avail wallet connect react

Avail Wallet SDK

A React library for integrating Avail blockchain wallets into your application. Supports multiple wallet providers including SubWallet, Talisman, and MetaMask Snap with built-in UI components and persistent connections.

Installation

npm install avail-wallet-sdk
# or
pnpm install avail-wallet-sdk
# or
yarn add avail-wallet-sdk

Quick Start

Basic Setup

import { AvailWalletProvider, AvailWalletConnect } from 'avail-wallet-sdk';
import 'avail-wallet-sdk/index.css'; // Import styles

function App() {
  return (
    <AvailWalletProvider>
      <AvailWalletConnect />
    </AvailWalletProvider>
  );
}

Next.js Setup

App Router

// app/providers.tsx
"use client";
import { AvailWalletProvider } from 'avail-wallet-sdk';
import 'avail-wallet-sdk/index.css';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AvailWalletProvider>
      {children}
    </AvailWalletProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>
          {children}
        </Providers>
      </body>
    </html>
  );
}

Pages Router

// _app.tsx
import { AvailWalletProvider } from 'avail-wallet-sdk';
import 'avail-wallet-sdk/index.css';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <AvailWalletProvider>
      <Component {...pageProps} />
    </AvailWalletProvider>
  );
}

Components

Wallet Components

`AvailWalletProvider`

The root provider that manages wallet state and API connections.

import { AvailWalletProvider } from 'avail-wallet-sdk';

<AvailWalletProvider
  rpcUrl="wss://turing-rpc.avail.so/ws" // Optional: custom RPC URL
  api={externalApi} // Optional: provide your own API instance
>
  {children}
</AvailWalletProvider>

`AvailWalletConnect`

Main wallet connection component with built-in UI.

import { AvailWalletConnect, Button } from 'avail-wallet-sdk';

// Default UI
<AvailWalletConnect />

// With custom trigger button
<AvailWalletConnect>
  <Button variant="primary" size="lg">
    Connect Your Wallet
  </Button>
</AvailWalletConnect>

// With custom connected state
<AvailWalletConnect
  connectedChildren={
    <div className="flex items-center gap-2">
      <span>✓ Connected</span>
      <DisconnectWallet />
    </div>
  }
/>

Hooks

Core Hooks

`useAvailWallet`

Access wallet connection state and API.

import { useAvailWallet } from 'avail-wallet-sdk';

function MyComponent() {
  const { api, isConnected, rpcUrl, setRpcUrl, open, setOpen } = useAvailWallet();

  return (
    <div>
      {isConnected ? 'Connected to Avail' : 'Not connected'}
      <button onClick={() => setOpen(true)}>Open Wallet</button>
    </div>
  );
}

`useAvailAccount`

Manage selected account and wallet.

import { useAvailAccount } from 'avail-wallet-sdk';

function AccountInfo() {
  const {
    selected,
    selectedWallet,
    setSelected,
    setSelectedWallet,
    metadataUpdated,
    clearWalletState
  } = useAvailAccount();

  return (
    <div>
      {selected && (
        <p>Connected: {selected.name} ({selected.address})</p>
      )}
      <button onClick={clearWalletState}>Disconnect</button>
    </div>
  );
}

`useApi`

Direct access to the Avail API instance.

import { useApi } from 'avail-wallet-sdk';

function ApiComponent() {
  const { api, isReady, setApi, ensureConnection } = useApi();

  useEffect(() => {
    if (isReady) {
      // Use the API
      console.log('Chain:', api?.runtimeChain.toString());
    }
  }, [isReady, api]);
}

MetaMask Snap Hooks

`useMetaMask`

Access MetaMask state and Snap information.

import { useMetaMask } from 'avail-wallet-sdk';

function MetaMaskInfo() {
  const { installedSnap, metamaskInstalled } = useMetaMask();

  return (
    <div>
      MetaMask: {metamaskInstalled ? 'Installed' : 'Not found'}
      Snap: {installedSnap ? 'Connected' : 'Not connected'}
    </div>
  );
}

`useRequestSnap`

Request installation of Avail Snap.

import { useRequestSnap } from 'avail-wallet-sdk';

function SnapInstaller() {
  const requestSnap = useRequestSnap();

  const handleInstall = async () => {
    try {
      await requestSnap();
      console.log('Snap installed successfully');
    } catch (error) {
      console.error('Failed to install snap:', error);
    }
  };

  return <button onClick={handleInstall}>Install Avail Snap</button>;
}

`useInvokeSnap`

Call methods on the installed Snap.

import { useInvokeSnap } from 'avail-wallet-sdk';

function SnapMethods() {
  const invokeSnap = useInvokeSnap();

  const getAddress = async () => {
    try {
      const address = await invokeSnap({ method: 'getAddress' });
      console.log('Address:', address);
    } catch (error) {
      console.error('Failed to get address:', error);
    }
  };

  return <button onClick={getAddress}>Get Address</button>;
}

Advanced Usage

Custom RPC Endpoint

import { AvailWalletProvider } from 'avail-wallet-sdk';

<AvailWalletProvider rpcUrl="wss://your-custom-rpc.com/ws">
  <App />
</AvailWalletProvider>

External API Instance

import { AvailWalletProvider } from 'avail-wallet-sdk';
import { initApi } from 'avail-wallet-sdk/utils';

function App() {
  const [api, setApi] = useState();

  useEffect(() => {
    initApi('wss://turing-rpc.avail.so/ws').then(setApi);
  }, []);

  return (
    <AvailWalletProvider api={api}>
      <MyApp />
    </AvailWalletProvider>
  );
}

Custom Wallet Connection Button

import { AvailWalletConnect, useAvailAccount } from 'avail-wallet-sdk';

function CustomWalletButton() {
  const { selected } = useAvailAccount();

  return (
    <AvailWalletConnect>
      <button className="my-custom-button">
        {selected ? `Connected: ${selected.name}` : 'Connect Wallet'}
      </button>
    </AvailWalletConnect>
  );
}

Metadata Management

import { updateMetadata, getInjectorMetadata } from 'avail-wallet-sdk/utils';

// Update wallet metadata
await updateMetadata({
  api,
  account: selectedAccount,
  metadataCookie: metadataState,
  selectedWallet: wallet,
  setCookie: (name, value) => {
    // Handle metadata cookie storage
  }
});

// Get injector metadata
const metadata = getInjectorMetadata(api);

Styling & Customization

CSS Import

The SDK includes all necessary styles and fonts. Simply import the CSS:

import 'avail-wallet-sdk/index.css';

Font Classes

Use built-in font utilities in your custom components:

.font-ppmori          /* PP Mori Regular */
.font-ppmorisemibold  /* PP Mori SemiBold */
.font-thicccboiregular    /* THICCCBOI Regular */
.font-thicccboisemibold   /* THICCCBOI SemiBold */
.font-thicccboibold       /* THICCCBOI Bold */

Custom Button Styling

Override button styles with CSS:

/* Custom primary button */
.my-wallet-button {
  @apply bg-gradient-to-r from-purple-500 to-blue-500 text-white font-bold py-2 px-4 rounded-full;
}

Tailwind Configuration

If using Tailwind CSS, include the SDK in your config:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/avail-wallet-sdk/**/*.{js,ts,jsx,tsx}'
  ],
  // ... rest of config
}

TypeScript Support

The SDK is fully typed. Import types as needed:

import type {
  AvailWalletProviderProps,
  AvailWalletConnectProps,
  ExtendedWalletAccount,
  UpdateMetadataParams,
  WalletSelectionProps,
  AccountSelectionProps,
  DisconnectWalletProps
} from 'avail-wallet-sdk';

State Persistence

Wallet connections are automatically persisted in localStorage. Users will remain connected between browser sessions without needing to reconnect.

Supported Wallets

SubWallet - Recommended Avail wallet
Talisman - Multi-chain wallet
PolkadotJS - Official Polkadot wallet
MetaMask Snap - Avail integration for MetaMask
Other Polkadot ecosystem wallets

Exports Reference

Main Entry Point

// Components
export { AvailWalletProvider, AvailWalletConnect, WalletSelector, AccountSelector, DisconnectWallet }
export { Button, Badge, Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter }

// Hooks
export { useAvailWallet, useAvailAccount, useApi }
export { useMetaMask, useMetaMaskContext, useRequestSnap, useInvokeSnap, MetaMaskProvider }

// Types
export type { AvailWalletProviderProps, AvailWalletConnectProps, ExtendedWalletAccount, ... }

Utils Entry Point

import { updateMetadata, getInjectorMetadata, initApi, cn } from 'avail-wallet-sdk/utils';

License

This project is licensed under the MIT License.