@avalabs/avacloud-waas-react v1.0.10

@avalabs/avacloud-waas-react

Official React SDK for AvaCloud Wallet-as-a-Service (WaaS) integration. This library provides a seamless way to integrate AvaCloud wallet functionality into your React applications.

Installation

# npm
npm install @avalabs/avacloud-waas-react

# yarn
yarn add @avalabs/avacloud-waas-react

# pnpm
pnpm add @avalabs/avacloud-waas-react

Quick Start

Wrap your application with the AvaCloudWalletProvider:

import { AvaCloudWalletProvider } from '@avalabs/avacloud-waas-react';

function App() {
  return (
    <AvaCloudWalletProvider 
      orgId="your-avacloud-org-id" // Required
      chainId={43113} // Avalanche Fuji Testnet
    >
      <YourApp />
    </AvaCloudWalletProvider>
  );
}

Use the wallet hooks and components in your application:

import { useAvaCloudWallet, LoginButton, WalletDisplay } from '@avalabs/avacloud-waas-react';

function YourComponent() {
  const { isAuthenticated, isLoading, user, wallet } = useAvaCloudWallet();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      {isAuthenticated ? (
        <>
          <p>Welcome, {user?.email || 'User'}!</p>
          <WalletDisplay />
        </>
      ) : (
        <LoginButton />
      )}
    </div>
  );
}

Core Components

AvaCloudWalletProvider

The main provider component that wraps your application and provides wallet context.

<AvaCloudWalletProvider
  orgId="your-avacloud-org-id" // Required
  chainId={43113}
  darkMode={false}
  onAuthSuccess={(user) => console.log('Auth success', user)}
  onAuthError={(error) => console.error('Auth error', error)}
  onWalletUpdate={(wallet) => console.log('Wallet updated', wallet)}
>
  {children}
</AvaCloudWalletProvider>

Props

UI Components

• LoginButton: Button component for initiating the login flow
• WalletButton: Button component for displaying wallet information and actions
• WalletDisplay: Component for displaying wallet address and balance
• UserProfile: Component for displaying user profile information
• WalletCard: Card component for displaying wallet information
• TokensView: Component for displaying token balances
• SendView: Component for sending tokens
• ReceiveView: Component for receiving tokens (displays QR code)
• ExportView: Component for exporting wallet information

Hooks

useAvaCloudWallet

The main hook for accessing wallet state and methods.

const {
  isAuthenticated,
  isLoading,
  user,
  wallet,
  login,
  logout,
  addAccount,
} = useAvaCloudWallet();

useAuth

Simplified hook for basic authentication state.

const { isAuthenticated, login, logout } = useAuth();

useSignMessage

Hook for signing messages with the connected wallet.

const { signMessage, isLoading, error } = useSignMessage();

const handleSign = async () => {
  try {
    const signature = await signMessage('Hello, AvaCloud!');
    console.log('Signature:', signature);
  } catch (error) {
    console.error('Error signing message:', error);
  }
};

useSignTransaction

Hook for signing transactions with the connected wallet.

const { signTransaction, isLoading, error } = useSignTransaction();

const handleSignTx = async () => {
  try {
    const signedTx = await signTransaction({
      to: '0x...',
      value: '0.1',
      data: '0x...',
    });
    console.log('Signed transaction:', signedTx);
  } catch (error) {
    console.error('Error signing transaction:', error);
  }
};

useTransferTokens

Hook for transferring tokens.

const { transfer, isLoading, error } = useTransferTokens();

const handleTransfer = async () => {
  try {
    const txHash = await transfer({
      to: '0x...',
      amount: '0.1',
      tokenAddress: '0x...', // Optional, use null for native token
    });
    console.log('Transaction hash:', txHash);
  } catch (error) {
    console.error('Error transferring tokens:', error);
  }
};

useUserWallets

Hook for accessing and managing user wallets.

const { wallets, isLoading, error } = useUserWallets();

useChainId

Hook for accessing and setting the current chain ID.

const { chainId, setChainId } = useChainId();

Advanced Usage

Theme Customization

Use the ThemeProvider to customize the appearance of UI components:

import { ThemeProvider } from '@avalabs/avacloud-waas-react';

function App() {
  return (
    <ThemeProvider darkMode={true}>
      <YourApp />
    </ThemeProvider>
  );
}

Custom Authentication Flow

You can implement a custom authentication flow using the lower-level hooks:

import { usePostMessage } from '@avalabs/avacloud-waas-react';

function CustomAuth() {
  const { sendMessage, lastMessage } = usePostMessage();

  const handleCustomLogin = () => {
    sendMessage({
      type: 'login',
      payload: {
        // Custom payload
      }
    });
  };

  // Handle response in useEffect
  useEffect(() => {
    if (lastMessage?.type === 'login_success') {
      // Handle successful login
    }
  }, [lastMessage]);

  return (
    <button onClick={handleCustomLogin}>
      Custom Login
    </button>
  );
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

MIT © Ava Labs, Inc.

Using the AvaCloud Organization ID

The AvaCloudWalletProvider requires an AvaCloud organization ID (orgId). This is used to fetch the organization configuration from the AvaCloud API, which includes the mapping to the appropriate wallet service organization ID used for wallet operations.

import { AvaCloudWalletProvider } from '@avalabs/avacloud-waas-react';

function App() {
  return (
    <AvaCloudWalletProvider
      orgId="your-avacloud-org-id" // Required AvaCloud organization ID
    >
      <YourApp />
    </AvaCloudWalletProvider>
  );
}

When provided, the orgId will be used to:

1. Fetch the organization configuration from the AvaCloud API
2. Map to the appropriate wallet service organization ID
3. Use the mapped ID for wallet operations

This enables organizations to have their AvaCloud identity seamlessly map to their WaaS wallets.