@avalabs/avacloud-waas-react 1.0.0-canary.1

package/README.md

@@ -0,0 +1,447 @@
+# @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.
+
+[![npm version](https://img.shields.io/npm/v/@avalabs/avacloud-waas-react.svg)](https://www.npmjs.com/package/@avalabs/avacloud-waas-react)
+[![License](https://img.shields.io/npm/l/@avalabs/avacloud-waas-react.svg)](https://github.com/ava-labs/avacloud-waas-react/blob/main/LICENSE)
+
+
+## Installation
+
+```bash
+# 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`:
+
+```tsx
+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:
+
+```tsx
+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.
+
+```tsx
+<AvaCloudWalletProvider
+  orgId="your-avacloud-org-id" // Required - your AvaCloud organization ID
+  chainId={43113}               // Optional - defaults to Avalanche Fuji Testnet
+  darkMode={false}              // Optional - theme mode for UI components
+  onAuthSuccess={(user) => console.log('Auth success', user)}
+  onAuthError={(error) => console.error('Auth error', error)}
+  onWalletUpdate={(wallet) => console.log('Wallet updated', wallet)}
+>
+  {children}
+</AvaCloudWalletProvider>
+```
+
+#### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `orgId` | `string` | **Required** - Your AvaCloud organization ID used to fetch wallet configuration |
+| `env` | `'local' \| 'development' \| 'prod'` | Environment to use (default: `'prod'`) |
+| `chainId` | `number` | EVM chain ID (default: `43113` - Avalanche Fuji Testnet) |
+| `darkMode` | `boolean` | Enable dark mode for UI components (default: `false`) |
+| `onAuthSuccess` | `(user: Auth0User) => void` | Callback on successful authentication |
+| `onAuthError` | `(error: Error) => void` | Callback on authentication error |
+| `onWalletUpdate` | `(wallet: WalletInfo) => void` | Callback when wallet information updates |
+
+### 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.
+
+```tsx
+const {
+  isAuthenticated,
+  isLoading,
+  user,
+  wallet,
+  login,
+  logout,
+  addAccount,
+} = useAvaCloudWallet();
+```
+
+### useAuth
+
+Simplified hook for basic authentication state.
+
+```tsx
+const { isAuthenticated, login, logout } = useAuth();
+```
+
+### useSignMessage
+
+Hook for signing messages with the connected wallet.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+const { wallets, isLoading, error } = useUserWallets();
+```
+
+### useChainId
+
+Hook for accessing and setting the current chain ID.
+
+```tsx
+const { chainId, setChainId } = useChainId();
+```
+
+### useGaslessTransaction
+
+Hook for sending gasless (meta-)transactions through AvaCloud's gas relayer.
+
+```tsx
+import { useGaslessTransaction, useGlacier } from '@avalabs/avacloud-waas-react';
+
+function CounterExample() {
+  // Retrieve the current subnet RPC URL from Glacier
+  const { blockchain } = useGlacier();
+
+  const gaslessConfig = {
+    relayerUrl: 'https://gas-relayer.avax-test.network/printedapr/testnet/rpc', // AvaCloud relayer RPC
+    subnetRpcUrl: blockchain?.rpcUrl || '',                                    // Target subnet RPC
+    forwarderAddress: '0x52ec85e43d09889b2bf9e431935356e06f023680',            // AvaCloud forwarder
+    domainName: 'Counter',
+    domainVersion: '1',
+    requestType: 'Message',
+    suffixType: 'bytes32',  // Optional – request suffix type
+    suffixName: 'XMKUCJONOFSUSFCYHTYHCLX', // Optional – request suffix name
+  } as const;
+
+  // Counter contract information
+  const COUNTER_CONTRACT_ADDRESS = '0xe4bB5F15dc278197FcE9B21e5aC0442a95e25b5f';
+  const COUNTER_INCREMENT_ABI = [
+    {
+      inputs: [],
+      name: 'increment',
+      outputs: [],
+      stateMutability: 'nonpayable',
+      type: 'function',
+    },
+  ] as const;
+
+  const {
+    sendGaslessTransaction,
+    isLoading,
+    error,
+    txHash,
+    reset,
+  } = useGaslessTransaction({
+    gaslessConfig,
+    contractAddress: COUNTER_CONTRACT_ADDRESS,
+    abi: COUNTER_INCREMENT_ABI,
+  });
+
+  const handleIncrement = () =>
+    sendGaslessTransaction({ functionName: 'increment' });
+
+  return (
+    <div>
+      <button onClick={handleIncrement} disabled={isLoading}>
+        Increment counter (no gas)
+      </button>
+
+      {isLoading && <p>Sending transaction…</p>}
+      {txHash && <p>Transaction hash: {txHash}</p>}
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+
+      <button onClick={reset}>Reset</button>
+    </div>
+  );
+}
+```
+
+**Parameters returned by the hook**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `sendGaslessTransaction` | `(params: { functionName: string; args?: unknown[]; abi?: unknown; contractAddress?: string }) => Promise<void>` | Sends the meta-transaction |
+| `isLoading` | `boolean` | `true` while the transaction is being prepared or broadcast |
+| `error` | `string \| null` | Error message, if any |
+| `txHash` | `string \| null` | Transaction hash once broadcast |
+| `reset` | `() => void` | Resets the hook state |
+
+
+## WAGMI Integration
+
+This SDK includes a WAGMI connector that allows you to use AvaCloud wallets with WAGMI (React Ethereum Library).
+
+### Prerequisites
+
+Install the required WAGMI dependencies:
+
+```bash
+npm install wagmi viem@2.x @tanstack/react-query
+```
+
+### Setting up WAGMI with AvaCloud
+
+```tsx
+import { WagmiProvider, createConfig } from 'wagmi';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { avaCloudWallet } from '@avalabs/avacloud-waas-react';
+import { avalancheFuji } from 'wagmi/chains';
+import { http } from 'wagmi';
+
+const queryClient = new QueryClient();
+
+const config = createConfig({
+  chains: [avalancheFuji],
+  connectors: [
+    avaCloudWallet(),
+  ],
+  transports: {
+    [avalancheFuji.id]: http(),
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <WagmiProvider config={config}>
+        <AvaCloudWalletProvider orgId="your-avacloud-org-id">
+          <YourApp />
+        </AvaCloudWalletProvider>
+      </WagmiProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Using WAGMI Hooks
+
+Once configured, use standard WAGMI hooks with your AvaCloud wallet:
+
+```tsx
+import { useAccount, useConnect, useDisconnect, useSignMessage } from 'wagmi';
+
+function WagmiExample() {
+  const { address, isConnected } = useAccount();
+  const { connect, connectors } = useConnect();
+  const { disconnect } = useDisconnect();
+  const { signMessage } = useSignMessage();
+
+  const handleConnect = () => {
+    const avaCloudConnector = connectors.find(c => c.id === 'avaCloudWallet');
+    if (avaCloudConnector) {
+      connect({ connector: avaCloudConnector });
+    }
+  };
+
+  const handleSign = async () => {
+    const signature = await signMessage({ message: 'Hello from WAGMI!' });
+    console.log('Signature:', signature);
+  };
+
+  return (
+    <div>
+      {isConnected ? (
+        <>
+          <p>Connected: {address}</p>
+          <button onClick={() => disconnect()}>Disconnect</button>
+          <button onClick={handleSign}>Sign Message</button>
+        </>
+      ) : (
+        <button onClick={handleConnect}>Connect AvaCloud Wallet</button>
+      )}
+    </div>
+  );
+}
+```
+
+### Important Notes
+
+- The AvaCloud WAGMI connector requires the `AvaCloudWalletProvider` to be present in your component tree
+- Authentication is still managed through the AvaCloud SDK's authentication flow
+- The connector automatically syncs with the wallet state from `AvaCloudWalletProvider`
+- All standard WAGMI hooks and functionality are supported
+
+## Advanced Usage
+
+### Theme Customization
+
+Use the `ThemeProvider` to customize the appearance of UI components:
+
+```tsx
+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:
+
+```tsx
+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](https://github.com/ava-labs/avacloud-waas-react/blob/main/CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Ava Labs, Inc.](https://github.com/ava-labs)