@avalabs/avacloud-waas-react 1.0.10 → 1.0.14-nightly.20250704

package/README.md

@@ -73,9 +73,9 @@ The main provider component that wraps your application and provides wallet cont
 
 ```tsx
 <AvaCloudWalletProvider
-  orgId="your-avacloud-org-id" // Required
-  chainId={43113}
-  darkMode={false}
+  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)}
@@ -88,13 +88,13 @@ The main provider component that wraps your application and provides wallet cont
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `orgId` | `string` | Required AvaCloud organization ID |
-| `env` | `'local' \| 'development' \| 'prod'` | (Optional) Environment to use. Defaults to 'prod'. |
-| `chainId` | `number` | (Optional) EVM chain ID to use (defaults to Avalanche Fuji Testnet - 43113) |
-| `darkMode` | `boolean` | (Optional) Whether to use dark mode for UI components |
-| `onAuthSuccess` | `(user: Auth0User) => void` | (Optional) Callback called when authentication is successful |
-| `onAuthError` | `(error: Error) => void` | (Optional) Callback called when authentication fails |
-| `onWalletUpdate` | `(wallet: WalletInfo) => void` | (Optional) Callback called when wallet information is updated |
+| `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
 
@@ -209,6 +209,176 @@ Hook for accessing and setting the current chain ID.
 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
@@ -274,30 +444,4 @@ We welcome contributions! Please see [CONTRIBUTING.md](https://github.com/ava-la
 
 ## License
 
-MIT © [Ava Labs, Inc.](https://github.com/ava-labs)
-
-## 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.
-
-```jsx
-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. 
+MIT © [Ava Labs, Inc.](https://github.com/ava-labs) 

package/dist/index.d.mts

@@ -1,9 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _cubist_labs_cubesigner_sdk from '@cubist-labs/cubesigner-sdk';
-import { IdentityProof, CubeSignerClient } from '@cubist-labs/cubesigner-sdk';
-import { PropsWithChildren, ButtonHTMLAttributes } from 'react';
+import { CubeSignerClient, IdentityProof } from '@cubist-labs/cubesigner-sdk';
+import { PropsWithChildren, ButtonHTMLAttributes, ReactNode } from 'react';
 import { ButtonProps } from '@avalabs/core-k2-components';
-import { Hex, TransactionRequest, Signature, Hash } from 'viem';
+import { Hex, Signature, TransactionRequest, Hash } from 'viem';
+import * as _tanstack_react_query_build_legacy_types from '@tanstack/react-query/build/legacy/types';
+import { CreateConnectorFn } from '@wagmi/core';
 
 /**
  * Cubist wallet information
@@ -365,6 +367,32 @@ interface WalletCardProps {
 }
 declare function WalletCard({ onClose }: WalletCardProps): react_jsx_runtime.JSX.Element | null;
 
+interface BlockchainData {
+    chainId: string;
+    chainName: string;
+    description: string;
+    platformChainId: string;
+    subnetId: string;
+    vmId: string;
+    vmName: string;
+    explorerUrl: string;
+    rpcUrl: string;
+    wsUrl: string;
+    isTestnet: boolean;
+    utilityAddresses: {
+        multicall: string;
+    };
+    networkToken: {
+        name: string;
+        symbol: string;
+        decimals: number;
+        logoUri: string;
+        description: string;
+    };
+    chainLogoUri: string;
+    private: boolean;
+    enabledFeatures: string[];
+}
 interface TokenReputation {
     verified: boolean;
     popular: boolean;
@@ -518,4 +546,77 @@ interface UseUserWalletsResult {
 }
 declare function useUserWallets(): UseUserWalletsResult;
 
-export { type AddAccountMessage, type AdminPortalSettings, type Auth0User, type AuthMessage, type AuthMessagePayload, type AuthStateUpdateMessage, type AuthStatusMessage, type AvaCloudEnvironment, type AvaCloudWalletContextType, AvaCloudWalletProvider, type AvaCloudWalletProviderProps, type BaseAuthMessage, type CheckAuthStatusMessage, type CubistWalletInfo, type ErrorMessage, ExportView, type GetOidcMessage, type IframeReadyMessage, LoginButton, type LoginRequestMessage, type LogoutRequestMessage, type MessageType, type OrgConfig, type ReceiveOidcMessage, ReceiveView, type RegisterMessage, type RegisterPayload, type RegisterSuccessMessage, SendView, type SignupRequestMessage, ThemeProvider, TokensView, type UserInfo, UserProfile, VM, WalletButton, WalletCard, WalletDisplay, type WalletInfo, type WalletKeysErrorMessage, type WalletKeysUpdateMessage, useAuth, useAvaCloudWallet, useChainId, usePostMessage, useSignMessage, useSignTransaction, useThemeMode, useTransferTokens, useUserWallets };
+declare function useGlacier(): {
+    balance: string;
+    isLoadingBalance: boolean;
+    currencySymbol: string;
+    blockchain: BlockchainData | undefined;
+};
+declare function useBlockchain(chainId: string): _tanstack_react_query_build_legacy_types.UseQueryResult<BlockchainData, Error>;
+
+declare function avaCloudWallet(): CreateConnectorFn;
+
+interface GaslessConfig {
+    /** URL of the AvaCloud gasless relayer RPC endpoint */
+    relayerUrl: string;
+    /** Public JSON-RPC endpoint of the target subnet */
+    subnetRpcUrl: string;
+    /** Forwarder contract address provided by AvaCloud */
+    forwarderAddress: string;
+    /** EIP-712 domain name, e.g. "domain" */
+    domainName: string;
+    /** EIP-712 domain version, e.g. "1" */
+    domainVersion: string;
+    /** Primary type for the request, e.g. "Message" */
+    requestType: string;
+    /** Suffix for the request in format "type name" (e.g. "bytes32 XMKUCJONOFSUSFCYHTYHCLX") */
+    suffix?: string;
+}
+interface FetchGaslessConfigParams {
+    orgId: string;
+    subnetId: string;
+}
+interface GaslessProviderProps {
+    children: ReactNode;
+    /** Optional pre-fetched config (skip network fetch when supplied) */
+    config?: GaslessConfig;
+    /** Parameters required to fetch config from the auth service */
+    fetchParams?: FetchGaslessConfigParams;
+}
+/**
+ * GaslessProvider – supplies gasless relayer configuration to hooks
+ *
+ * NOTE:  For security reasons, this provider expects the configuration to be
+ *        provided by the integrator.  The intention is that your backend (or
+ *        another trusted environment) fetches the relayer configuration via
+ *        AvaCloud's internal endpoint and forwards the non-sensitive parts
+ *        (relayer URL, forwarder address, etc.) to the browser.
+ */
+declare function GaslessProvider({ children, config, fetchParams }: GaslessProviderProps): react_jsx_runtime.JSX.Element;
+
+interface GaslessTxState {
+    isLoading: boolean;
+    error: string | null;
+    txHash: string | null;
+}
+interface SendGaslessTransactionParams {
+    functionName: string;
+    args?: unknown[];
+    abi?: unknown;
+    contractAddress?: string;
+}
+interface UseGaslessTransactionReturn extends GaslessTxState {
+    sendGaslessTransaction: (params: SendGaslessTransactionParams) => Promise<void>;
+    reset: () => void;
+}
+interface UseGaslessTransactionOptions {
+    /** Gasless transaction configuration */
+    gaslessConfig: GaslessConfig;
+    /** Default contract address (can be overridden per call) */
+    contractAddress?: string;
+    /** Default ABI (can be overridden per call) */
+    abi?: unknown;
+}
+declare function useGaslessTransaction({ gaslessConfig, contractAddress: defaultContractAddress, abi: defaultAbi }: UseGaslessTransactionOptions): UseGaslessTransactionReturn;
+
+export { type AddAccountMessage, type AdminPortalSettings, type Auth0User, type AuthMessage, type AuthMessagePayload, type AuthStateUpdateMessage, type AuthStatusMessage, type AvaCloudEnvironment, type AvaCloudWalletContextType, AvaCloudWalletProvider, type AvaCloudWalletProviderProps, type BaseAuthMessage, type CheckAuthStatusMessage, type CubistWalletInfo, type ErrorMessage, ExportView, GaslessProvider, type GetOidcMessage, type IframeReadyMessage, LoginButton, type LoginRequestMessage, type LogoutRequestMessage, type MessageType, type OrgConfig, type ReceiveOidcMessage, ReceiveView, type RegisterMessage, type RegisterPayload, type RegisterSuccessMessage, SendView, type SignupRequestMessage, ThemeProvider, TokensView, type UserInfo, UserProfile, VM, WalletButton, WalletCard, WalletDisplay, type WalletInfo, type WalletKeysErrorMessage, type WalletKeysUpdateMessage, avaCloudWallet, useAuth, useAvaCloudWallet, useBlockchain, useChainId, useGaslessTransaction, useGlacier, usePostMessage, useSignMessage, useSignTransaction, useThemeMode, useTransferTokens, useUserWallets };

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _cubist_labs_cubesigner_sdk from '@cubist-labs/cubesigner-sdk';
-import { IdentityProof, CubeSignerClient } from '@cubist-labs/cubesigner-sdk';
-import { PropsWithChildren, ButtonHTMLAttributes } from 'react';
+import { CubeSignerClient, IdentityProof } from '@cubist-labs/cubesigner-sdk';
+import { PropsWithChildren, ButtonHTMLAttributes, ReactNode } from 'react';
 import { ButtonProps } from '@avalabs/core-k2-components';
-import { Hex, TransactionRequest, Signature, Hash } from 'viem';
+import { Hex, Signature, TransactionRequest, Hash } from 'viem';
+import * as _tanstack_react_query_build_legacy_types from '@tanstack/react-query/build/legacy/types';
+import { CreateConnectorFn } from '@wagmi/core';
 
 /**
  * Cubist wallet information
@@ -365,6 +367,32 @@ interface WalletCardProps {
 }
 declare function WalletCard({ onClose }: WalletCardProps): react_jsx_runtime.JSX.Element | null;
 
+interface BlockchainData {
+    chainId: string;
+    chainName: string;
+    description: string;
+    platformChainId: string;
+    subnetId: string;
+    vmId: string;
+    vmName: string;
+    explorerUrl: string;
+    rpcUrl: string;
+    wsUrl: string;
+    isTestnet: boolean;
+    utilityAddresses: {
+        multicall: string;
+    };
+    networkToken: {
+        name: string;
+        symbol: string;
+        decimals: number;
+        logoUri: string;
+        description: string;
+    };
+    chainLogoUri: string;
+    private: boolean;
+    enabledFeatures: string[];
+}
 interface TokenReputation {
     verified: boolean;
     popular: boolean;
@@ -518,4 +546,77 @@ interface UseUserWalletsResult {
 }
 declare function useUserWallets(): UseUserWalletsResult;
 
-export { type AddAccountMessage, type AdminPortalSettings, type Auth0User, type AuthMessage, type AuthMessagePayload, type AuthStateUpdateMessage, type AuthStatusMessage, type AvaCloudEnvironment, type AvaCloudWalletContextType, AvaCloudWalletProvider, type AvaCloudWalletProviderProps, type BaseAuthMessage, type CheckAuthStatusMessage, type CubistWalletInfo, type ErrorMessage, ExportView, type GetOidcMessage, type IframeReadyMessage, LoginButton, type LoginRequestMessage, type LogoutRequestMessage, type MessageType, type OrgConfig, type ReceiveOidcMessage, ReceiveView, type RegisterMessage, type RegisterPayload, type RegisterSuccessMessage, SendView, type SignupRequestMessage, ThemeProvider, TokensView, type UserInfo, UserProfile, VM, WalletButton, WalletCard, WalletDisplay, type WalletInfo, type WalletKeysErrorMessage, type WalletKeysUpdateMessage, useAuth, useAvaCloudWallet, useChainId, usePostMessage, useSignMessage, useSignTransaction, useThemeMode, useTransferTokens, useUserWallets };
+declare function useGlacier(): {
+    balance: string;
+    isLoadingBalance: boolean;
+    currencySymbol: string;
+    blockchain: BlockchainData | undefined;
+};
+declare function useBlockchain(chainId: string): _tanstack_react_query_build_legacy_types.UseQueryResult<BlockchainData, Error>;
+
+declare function avaCloudWallet(): CreateConnectorFn;
+
+interface GaslessConfig {
+    /** URL of the AvaCloud gasless relayer RPC endpoint */
+    relayerUrl: string;
+    /** Public JSON-RPC endpoint of the target subnet */
+    subnetRpcUrl: string;
+    /** Forwarder contract address provided by AvaCloud */
+    forwarderAddress: string;
+    /** EIP-712 domain name, e.g. "domain" */
+    domainName: string;
+    /** EIP-712 domain version, e.g. "1" */
+    domainVersion: string;
+    /** Primary type for the request, e.g. "Message" */
+    requestType: string;
+    /** Suffix for the request in format "type name" (e.g. "bytes32 XMKUCJONOFSUSFCYHTYHCLX") */
+    suffix?: string;
+}
+interface FetchGaslessConfigParams {
+    orgId: string;
+    subnetId: string;
+}
+interface GaslessProviderProps {
+    children: ReactNode;
+    /** Optional pre-fetched config (skip network fetch when supplied) */
+    config?: GaslessConfig;
+    /** Parameters required to fetch config from the auth service */
+    fetchParams?: FetchGaslessConfigParams;
+}
+/**
+ * GaslessProvider – supplies gasless relayer configuration to hooks
+ *
+ * NOTE:  For security reasons, this provider expects the configuration to be
+ *        provided by the integrator.  The intention is that your backend (or
+ *        another trusted environment) fetches the relayer configuration via
+ *        AvaCloud's internal endpoint and forwards the non-sensitive parts
+ *        (relayer URL, forwarder address, etc.) to the browser.
+ */
+declare function GaslessProvider({ children, config, fetchParams }: GaslessProviderProps): react_jsx_runtime.JSX.Element;
+
+interface GaslessTxState {
+    isLoading: boolean;
+    error: string | null;
+    txHash: string | null;
+}
+interface SendGaslessTransactionParams {
+    functionName: string;
+    args?: unknown[];
+    abi?: unknown;
+    contractAddress?: string;
+}
+interface UseGaslessTransactionReturn extends GaslessTxState {
+    sendGaslessTransaction: (params: SendGaslessTransactionParams) => Promise<void>;
+    reset: () => void;
+}
+interface UseGaslessTransactionOptions {
+    /** Gasless transaction configuration */
+    gaslessConfig: GaslessConfig;
+    /** Default contract address (can be overridden per call) */
+    contractAddress?: string;
+    /** Default ABI (can be overridden per call) */
+    abi?: unknown;
+}
+declare function useGaslessTransaction({ gaslessConfig, contractAddress: defaultContractAddress, abi: defaultAbi }: UseGaslessTransactionOptions): UseGaslessTransactionReturn;
+
+export { type AddAccountMessage, type AdminPortalSettings, type Auth0User, type AuthMessage, type AuthMessagePayload, type AuthStateUpdateMessage, type AuthStatusMessage, type AvaCloudEnvironment, type AvaCloudWalletContextType, AvaCloudWalletProvider, type AvaCloudWalletProviderProps, type BaseAuthMessage, type CheckAuthStatusMessage, type CubistWalletInfo, type ErrorMessage, ExportView, GaslessProvider, type GetOidcMessage, type IframeReadyMessage, LoginButton, type LoginRequestMessage, type LogoutRequestMessage, type MessageType, type OrgConfig, type ReceiveOidcMessage, ReceiveView, type RegisterMessage, type RegisterPayload, type RegisterSuccessMessage, SendView, type SignupRequestMessage, ThemeProvider, TokensView, type UserInfo, UserProfile, VM, WalletButton, WalletCard, WalletDisplay, type WalletInfo, type WalletKeysErrorMessage, type WalletKeysUpdateMessage, avaCloudWallet, useAuth, useAvaCloudWallet, useBlockchain, useChainId, useGaslessTransaction, useGlacier, usePostMessage, useSignMessage, useSignTransaction, useThemeMode, useTransferTokens, useUserWallets };