@volr/react

Volr React SDK - React hooks for Volr Web3 Payment Builder.

Installation

yarn add @volr/react

Quick Start

Basic Setup

import { VolrProvider, useVolr } from '@volr/react';

function App() {
  return (
    <VolrProvider
      config={{
        projectApiKey: 'your-project-api-key',
      }}
    >
      <YourApp />
    </VolrProvider>
  );
}

function YourApp() {
  const { evm, isLoggedIn, logout } = useVolr();

  if (!isLoggedIn) {
    return <div>Please login</div>;
  }

  // Get wallet address
  const address = evm.address;

  // Sign a message (chain-agnostic)
  const signature = await evm.signMessage('Hello, World!');

  // Read contract (chain-specific)
  const balance = await evm.client(8453).readContract({
    address: '0x...',
    abi: erc20Abi,
    functionName: 'balanceOf',
    args: [address],
  });

  // Send transaction (chain-specific)
  const result = await evm.client(8453).sendTransaction({
    to: '0x...',
    data: '0x...',
  });

  // Send batch (chain-specific)
  const result = await evm.client(8453).sendBatch([
    {
      target: '0x...',
      abi: erc20Abi,
      functionName: 'transfer',
      args: ['0x...', BigInt(1000000)],
    },
  ]);
}

API

useVolr

Main hook for wallet operations.

const {
  evm,        // EvmNamespace (see below)
  evmAddress, // `0x${string}` | undefined (deprecated, use evm.address)
  email,      // string | undefined
  isLoggedIn, // boolean
  signerType, // 'passkey' | 'external_wallet' | 'mpc' | undefined
  logout,     // () => Promise<void>
  isLoading,  // boolean
  error,      // Error | null
} = useVolr();

EvmNamespace

The evm object provides chain-agnostic operations and a client() method for chain-specific operations.

// Chain-agnostic operations
evm.address                    // `0x${string}` | undefined
await evm.signMessage('Hello') // Sign message (EIP-191)
await evm.signTypedData({...}) // Sign typed data (EIP-712)

// Chain-specific operations
const client = evm.client(8453);

EvmChainClient

Returned by evm.client(chainId) for chain-specific operations.

const client = evm.client(8453);

// Read contract
const balance = await client.readContract({
  address: tokenAddress,
  abi: erc20Abi,
  functionName: 'balanceOf',
  args: [userAddress],
});

// Get balance
const ethBalance = await client.getBalance('0x...');

// Send single transaction
const result = await client.sendTransaction({
  to: '0x...',
  data: '0x...',
  value: 0n,
});

// Send batch (with ABI)
const result = await client.sendBatch([
  {
    target: tokenAddress,
    abi: erc20Abi,
    functionName: 'transfer',
    args: [recipient, amount],
    gasLimit: 100000n,
  },
]);

// Send batch (raw calls)
const result = await client.sendBatch([
  {
    target: '0x...',
    data: '0x...',
    value: 0n,
    gasLimit: 100000n,
  },
]);

Message Signing

Sign messages and typed data without specifying a chain (uses the same private key).

// Sign a simple message
const signature = await evm.signMessage('Hello, World!');

// Sign raw bytes
const signature = await evm.signMessage(new Uint8Array([1, 2, 3]));

// Sign EIP-712 typed data
const signature = await evm.signTypedData({
  domain: {
    name: 'MyApp',
    version: '1',
    chainId: 1,
    verifyingContract: '0x...',
  },
  types: {
    Message: [{ name: 'content', type: 'string' }],
  },
  message: { content: 'Hello' },
});

Features

• Simple API: useVolr() provides everything you need
• Session Management: Automatic token refresh and tab synchronization
• EIP-7702 Support: Gasless transactions with session keys
• Passkey Integration: Secure signing with device passkeys
• Type-Safe: Full TypeScript support
• SSR Safe: Works with Next.js and other SSR frameworks
• Call Builders: buildCall() and buildCalls() utilities for easy transaction building

OAuth Handling

The SDK provides useVolrAuthCallback to handle OAuth redirects:

import { useVolrAuthCallback } from '@volr/react';

function AuthCallback() {
  const { isLoading, error, isNewUser, user } = useVolrAuthCallback({
    onSuccess: (user) => {
      console.log('Logged in:', user);
    },
    onError: (err) => {
      console.error('Login failed:', err);
    },
  });

  if (isLoading) return <div>Processing authentication...</div>;
  if (error) return <div>Error: {error}</div>;
  
  return <div>Redirecting...</div>;
}

Failure Semantics

• revertOnFail defaults to true - any failed call reverts the entire batch
• Calls to non-contract addresses are rejected
• For ERC20 methods, if a token returns false, the batch is treated as failed

Diagnostics

When gas estimation or simulation fails, the backend includes developerDiagnostics in the error response:

• topLevel.reason: Decoded revert reason
• calls[]: Per-call diagnostics with target, selector, isContract, callResult, decodedRevert

Use these to pinpoint which call failed and why.

License

MIT