@volr/react 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# @volr/react
+
+Volr React SDK - React hooks and UI components for Volr Web3 Payment Builder.
+
+## Installation
+
+```bash
+yarn add @volr/react
+```
+
+## Quick Start
+
+### Basic Setup
+
+```tsx
+import { VolrProvider, useVolrWallet } from '@volr/react';
+
+function App() {
+  return (
+    <VolrProvider
+      config={{
+        apiBaseUrl: 'https://api.volr.io',
+        defaultChainId: 8453,
+        invokerAddressMap: {
+          8453: '0x...',
+        },
+      }}
+    >
+      <YourApp />
+    </VolrProvider>
+  );
+}
+
+function YourApp() {
+  const { evm } = useVolrWallet();
+
+  // Read contract
+  const balance = await evm(8453).readContract({
+    address: '0x...',
+    abi: erc20Abi,
+    functionName: 'balanceOf',
+    args: ['0x...'],
+  });
+
+  // Send transaction
+  const result = await evm(8453).sendTransaction(
+    {
+      to: '0x...',
+      data: '0x...',
+    },
+    {
+      policyId: '0x' + '0'.repeat(64),
+      signer: mySigner,
+    }
+  );
+}
+```
+
+### Advanced Usage
+
+For advanced users who need more control, you can use the low-level hooks:
+
+```tsx
+import { usePrecheck, useRelay, buildCall } from '@volr/react';
+
+function AdvancedComponent() {
+  const { precheck } = usePrecheck();
+  const { relay } = useRelay();
+
+  // Build call manually
+  const call = buildCall({
+    target: '0x...',
+    abi: erc20Abi,
+    functionName: 'transfer',
+    args: ['0x...', BigInt(1000000)],
+  });
+
+  // Use precheck and relay directly
+  const quote = await precheck({ auth, calls: [call] });
+  const result = await relay(input, { signer, rpcClient });
+}
+```
+
+## Features
+
+- **Developer-Friendly API**: `useVolrWallet()` provides a simple, intuitive interface
+- **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
+
+## Failure Semantics
+
+- Relay enforces strict failure-by-default:
+  - `revertOnFail` defaults to `true` and any failed call reverts the entire batch.
+  - Calls to non-contract addresses are rejected.
+  - For ERC20 methods (`transfer`, `transferFrom`, `approve`, `increaseAllowance`, `decreaseAllowance`), if a token returns `false`, the batch is treated as failed (even if it doesn't revert).
+  - Backend precheck rejects obvious failures (non-contract targets; ERC20 `false` on simulation) before submitting.
+
+## Diagnostics
+
+When gas estimation or simulation fails, the backend includes a `developerDiagnostics` object in the error response (and FAILED transaction meta). This contains:
+
+- `topLevel.reason`: Decoded revert reason for the overall execution attempt
+- `calls[]`: Per-call diagnostics with:
+  - `index`, `target`, `selector`
+  - `isContract` (EOA detection)
+  - `callResult` (raw `eth_call` return data)
+  - `decodedRevert` (human-readable when available)
+
+The SDK surfaces these in console for convenience:
+- Precheck errors: `[volr][precheck] developerDiagnostics: ...`
+- Relay errors: `[volr][relay] developerDiagnostics: ...`
+
+Use these to pinpoint which call failed and why (e.g., EOA target, ERC20 returned false, custom revert).
+
+## Documentation
+
+- **[React Integration Guide](./REACT_INTEGRATION.md)** - Complete guide for integrating Volr React SDK
+- **[Contract Integration Guide](../CONTRACT_INTEGRATION.md)** - Guide for SDK engineers
+- [Volr Documentation](https://docs.volr.io) - Detailed API reference
+