@rialo/frost 0.1.0

package/README.md

@@ -0,0 +1,778 @@
+# Rialo Frost 🧊
+
+**The wallet integration toolkit for Rialo dApps** — Connect wallets, sign transactions, and build Web3 apps in minutes.
+
+```bash
+pnpm add @rialo/frost
+```
+
+## 30-Second Setup
+
+```tsx
+// 1. Create config (do this once, outside components)
+import { createConfig, getDefaultRialoClientConfig } from "@rialo/frost";
+
+export const config = createConfig({
+  clientConfig: getDefaultRialoClientConfig("devnet"),
+});
+
+// 2. Wrap your app
+import { FrostProvider, ConnectButton } from "@rialo/frost";
+
+function App() {
+  return (
+    <FrostProvider config={config}>
+      <ConnectButton />
+    </FrostProvider>
+  );
+}
+```
+
+That's it. You now have a working wallet connection button.
+
+---
+
+## Table of Contents
+
+- [New to Web3?](#new-to-web3)
+- [Installation](#installation)
+- [Step-by-Step Guide](#step-by-step-guide)
+- [Hooks Reference](#hooks-reference)
+- [Components](#components)
+- [Error Handling](#error-handling)
+- [Advanced Usage](#advanced-usage)
+- [Troubleshooting](#troubleshooting)
+- [CSS Custom Properties](#css-custom-properties)
+
+---
+
+## New to Web3?
+
+<details>
+<summary><strong>Click here if you're new to blockchain development</strong></summary>
+
+### What You Need to Know
+
+**Wallet** = A browser extension (like MetaMask, but for Rialo) that stores the user's private keys and lets them approve transactions.
+
+**Account/Address** = A public identifier (like `7xKXtg2CW87d97...`) that represents a user on the blockchain. One wallet can have multiple accounts.
+
+**Signing** = When a user cryptographically approves something using their wallet. This proves they own the account without exposing their private key.
+
+**Transaction** = An operation that changes state on the blockchain (sending tokens, interacting with smart contracts, etc.).
+
+### How Frost Fits In
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│   Your App   │ ───► │    Frost     │ ───► │   Wallet     │
+│              │      │              │      │  Extension   │
+│  - UI        │      │  - Discovers │      │              │
+│  - Logic     │      │    wallets   │      │  - Stores    │
+│  - Hooks     │      │  - Manages   │      │    keys      │
+│              │      │    state     │      │  - Signs     │
+└──────────────┘      └──────────────┘      └──────────────┘
+```
+
+Frost handles all the complex wallet communication so you can focus on building your app.
+
+</details>
+
+---
+
+## Installation
+
+### Requirements
+
+- Node.js 18+
+- React 18 or 19
+- A Rialo wallet extension (for testing)
+
+### Install
+
+```bash
+# pnpm (recommended)
+pnpm add @rialo/frost
+
+# npm
+npm install @rialo/frost
+
+# yarn
+yarn add @rialo/frost
+```
+
+### For Non-React Apps
+
+Use the framework-agnostic core package:
+
+```bash
+pnpm add @rialo/frost-core
+```
+
+---
+
+## Step-by-Step Guide
+
+### Step 1: Create Your Config
+
+Create a file called `frost.config.ts` in your `src` folder:
+
+```typescript
+// src/frost.config.ts
+import { createConfig, getDefaultRialoClientConfig } from "@rialo/frost";
+
+export const frostConfig = createConfig({
+  clientConfig: getDefaultRialoClientConfig("devnet"), // Use "mainnet" for production
+  autoConnect: true, // Reconnect automatically on page refresh
+});
+```
+
+> ⚠️ **Important**: Create the config outside of React components. This prevents it from being recreated on every render.
+
+### Step 2: Add the Provider
+
+Wrap your app with `FrostProvider`:
+
+```tsx
+// src/App.tsx
+import { FrostProvider } from "@rialo/frost";
+import { frostConfig } from "./frost.config";
+
+function App() {
+  return (
+    <FrostProvider config={frostConfig}>
+      <YourApp />
+    </FrostProvider>
+  );
+}
+```
+
+### Step 3: Add a Connect Button
+
+**Option A: Use the built-in component**
+
+```tsx
+import { ConnectButton } from "@rialo/frost";
+
+function Header() {
+  return (
+    <nav>
+      <h1>My dApp</h1>
+      <ConnectButton />
+    </nav>
+  );
+}
+```
+
+**Option B: Build your own**
+
+```tsx
+import {
+  useWallets,
+  useConnectWallet,
+  useDisconnectWallet,
+  useIsConnected,
+  useActiveAccount,
+} from "@rialo/frost";
+
+function CustomConnectButton() {
+  const wallets = useWallets();
+  const { mutate: connect, isPending } = useConnectWallet();
+  const { mutate: disconnect } = useDisconnectWallet();
+  const isConnected = useIsConnected();
+  const account = useActiveAccount();
+
+  if (isConnected && account) {
+    return (
+      <div>
+        <span>{account.address.slice(0, 6)}...{account.address.slice(-4)}</span>
+        <button onClick={() => disconnect()}>Disconnect</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      {wallets.map((wallet) => (
+        <button
+          key={wallet.name}
+          onClick={() => connect({ walletName: wallet.name })}
+          disabled={isPending}
+        >
+          {wallet.icon && <img src={wallet.icon} alt="" width={20} />}
+          Connect {wallet.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### Step 4: Display Balance
+
+```tsx
+import { useNativeBalance, useIsConnected } from "@rialo/frost";
+
+function Balance() {
+  const isConnected = useIsConnected();
+  const { formatted, isLoading, refetch } = useNativeBalance();
+
+  if (!isConnected) return null;
+
+  return (
+    <div>
+      {isLoading ? "Loading..." : `${formatted} RIA`}
+      <button onClick={() => refetch()}>↻</button>
+    </div>
+  );
+}
+```
+
+### Step 5: Sign Messages
+
+```tsx
+import { useSignMessage, useIsConnected } from "@rialo/frost";
+
+function SignDemo() {
+  const isConnected = useIsConnected();
+  const { mutate: signMessage, isPending } = useSignMessage({
+    onSuccess: (result) => {
+      console.log("Signature:", result.signature);
+    },
+  });
+
+  if (!isConnected) return <p>Connect wallet first</p>;
+
+  return (
+    <button
+      onClick={() => signMessage({ message: "Hello from my dApp!" })}
+      disabled={isPending}
+    >
+      {isPending ? "Signing..." : "Sign Message"}
+    </button>
+  );
+}
+```
+
+### Step 6: Send Transactions
+
+```tsx
+import { useSendTransaction } from "@rialo/frost";
+
+function SendTx({ transaction }: { transaction: Uint8Array }) {
+  const { mutate: send, isPending, isSuccess, data } = useSendTransaction({
+    onSuccess: (result) => {
+      console.log("Transaction sent:", result.signature);
+    },
+    onError: (error) => {
+      console.error("Failed:", error.message);
+    },
+  });
+
+  return (
+    <div>
+      <button onClick={() => send({ transaction })} disabled={isPending}>
+        {isPending ? "Sending..." : "Send Transaction"}
+      </button>
+      {isSuccess && <p>✓ Signature: {data.signature}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## Hooks Reference
+
+### Connection
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useWallets()` | `WalletEntity[]` | All discovered wallets |
+| `useWalletsReady()` | `boolean` | True when wallet discovery is complete |
+| `useConnectWallet()` | Mutation | Connect to a wallet |
+| `useDisconnectWallet()` | Mutation | Disconnect current wallet |
+| `useConnectionStatus()` | `ConnectionStatus` | `"disconnected"` \| `"connecting"` \| `"connected"` \| `"reconnecting"` |
+| `useIsConnected()` | `boolean` | True if connected |
+
+### Account & Wallet
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useActiveWallet()` | `WalletEntity \| null` | Currently connected wallet |
+| `useActiveAccount()` | `AccountEntity \| null` | Currently active account |
+| `useAccounts()` | `AccountEntity[]` | All accounts from connected wallet |
+
+### Chain & Client
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useChainId()` | `string` | Current chain ID (e.g., `"rialo:devnet"`) |
+| `useSwitchChain()` | Mutation | Switch to a different network |
+| `useClient()` | `RialoClient` | Direct RPC client access |
+
+### Balance
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useNativeBalance()` | `{ formatted, balance, isLoading, refetch }` | Native token balance |
+
+### Signing & Transactions
+
+| Hook | Description |
+|------|-------------|
+| `useSignMessage()` | Sign arbitrary messages |
+| `useSignIn()` | Sign-In with Wallet (SIWS authentication) |
+| `useSignTransaction()` | Sign transaction without sending |
+| `useSendTransaction()` | Sign and send via wallet |
+| `useSignAndSendTransaction()` | Sign via wallet, send via Frost's RPC |
+
+---
+
+## Hooks in Detail
+
+### useConnectWallet
+
+```tsx
+const {
+  mutate: connect,  // Call to trigger connection
+  isPending,        // True while connecting
+  isSuccess,        // True after successful connection
+  isError,          // True if connection failed
+  error,            // Error object if failed
+  data,             // ConnectResult if successful
+} = useConnectWallet({
+  onSuccess: (result) => {
+    console.log("Connected:", result.walletName, result.accountAddress);
+  },
+  onError: (error) => {
+    console.error("Failed:", error.message);
+  },
+});
+
+// Usage
+connect({ walletName: "Rialo" });
+```
+
+### useSignMessage
+
+```tsx
+const { mutate: signMessage, isPending } = useSignMessage({
+  onSuccess: (result) => {
+    // result.signature: Uint8Array
+    // result.signedMessage: Uint8Array
+  },
+});
+
+// Sign a string
+signMessage({ message: "Hello World" });
+
+// Sign raw bytes
+signMessage({ message: new Uint8Array([1, 2, 3]) });
+```
+
+### useSignIn
+
+SIWS (Sign-In with Wallet) for authentication:
+
+```tsx
+const { mutate: signIn } = useSignIn({
+  onSuccess: async (result) => {
+    // Send to your backend for verification
+    await fetch("/api/auth", {
+      method: "POST",
+      body: JSON.stringify({
+        signature: Array.from(result.signature),
+        message: Array.from(result.signedMessage),
+        address: result.account.address,
+      }),
+    });
+  },
+});
+
+signIn({
+  domain: window.location.host,
+  statement: "Sign in to MyApp",
+  nonce: crypto.randomUUID(),
+  expirationTime: new Date(Date.now() + 3600000).toISOString(),
+});
+```
+
+### useNativeBalance
+
+```tsx
+const {
+  balance,      // bigint | undefined - Raw balance in lamports
+  formatted,    // string | undefined - Human readable (e.g., "1.5")
+  isLoading,    // boolean
+  isFetching,   // boolean - True during refetch
+  isError,      // boolean
+  error,        // Error | null
+  refetch,      // () => void
+} = useNativeBalance({
+  address: "optional-address", // Defaults to active account
+  decimals: 9,                 // Defaults to 9
+});
+```
+
+### useSwitchChain
+
+```tsx
+import { getDefaultRialoClientConfig } from "@rialo/frost";
+
+const { mutate: switchChain } = useSwitchChain();
+
+// Switch to mainnet
+switchChain(getDefaultRialoClientConfig("mainnet"));
+
+// Switch to testnet
+switchChain(getDefaultRialoClientConfig("testnet"));
+```
+
+---
+
+## Components
+
+### ConnectButton
+
+A complete, styled connect button with dropdown:
+
+```tsx
+<ConnectButton
+  label="Connect Wallet"              // Button text when disconnected
+  connectingLabel="Connecting..."     // Text while connecting
+  connectedLabel={(addr, wallet) =>   // Text when connected
+    `${addr.slice(0, 6)}...`
+  }
+  showDropdown={true}                 // Show dropdown when connected
+  onConnect={(wallet, address) => {}} // Connection callback
+  onDisconnect={() => {}}             // Disconnect callback
+  onError={(error) => {}}             // Error callback
+/>
+```
+
+### WalletModal
+
+A modal for wallet selection:
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<WalletModal
+  open={open}
+  onClose={() => setOpen(false)}
+  onConnect={(walletName, address) => {
+    console.log(`Connected to ${walletName}`);
+    setOpen(false);
+  }}
+  onError={(error, walletName) => {
+    console.error(`${walletName} failed:`, error);
+  }}
+  title="Select a Wallet"
+/>
+```
+
+---
+
+## Error Handling
+
+Frost provides typed errors for precise handling:
+
+```tsx
+import { isFrostError, type FrostError } from "@rialo/frost";
+
+function handleError(error: Error) {
+  if (!isFrostError(error)) {
+    console.error("Unknown error:", error);
+    return;
+  }
+
+  switch (error.code) {
+    case "WALLET_NOT_FOUND":
+      alert(`Install ${error.walletName} to continue`);
+      break;
+    case "WALLET_DISCONNECTED":
+      alert("Please connect your wallet");
+      break;
+    case "UNSUPPORTED_CHAIN":
+      alert("Switch to a supported network");
+      break;
+    case "UNSUPPORTED_FEATURE":
+      alert("Your wallet doesn't support this feature");
+      break;
+    case "CONNECTION_FAILED":
+      alert("Connection rejected or failed");
+      break;
+    case "SESSION_EXPIRED":
+      alert("Session expired, please reconnect");
+      break;
+    case "TRANSACTION_FAILED":
+      alert(`Transaction failed: ${error.reason}`);
+      break;
+    case "WALLET_ERROR":
+      alert(error.message);
+      break;
+  }
+}
+```
+
+### Error Types
+
+| Code | Class | When |
+|------|-------|------|
+| `WALLET_NOT_FOUND` | `WalletNotFoundError` | Wallet extension not installed |
+| `WALLET_DISCONNECTED` | `WalletDisconnectedError` | No wallet connected |
+| `UNSUPPORTED_CHAIN` | `UnsupportedChainError` | Wallet doesn't support current chain |
+| `UNSUPPORTED_FEATURE` | `UnsupportedFeatureError` | Missing wallet capability |
+| `CONNECTION_FAILED` | `ConnectionFailedError` | User rejected or wallet error |
+| `SESSION_EXPIRED` | `SessionExpiredError` | Saved session too old |
+| `TRANSACTION_FAILED` | `TransactionFailedError` | Transaction confirmed but execution failed on-chain |
+| `WALLET_ERROR` | `WalletError` | Generic wallet error |
+
+---
+
+## Advanced Usage
+
+### Custom RPC URL
+
+```typescript
+import { createConfig } from "@rialo/frost";
+
+const config = createConfig({
+  clientConfig: {
+    chain: {
+      id: "rialo:mainnet",
+      name: "Mainnet",
+      rpcUrl: "https://my-custom-rpc.example.com",
+    },
+    transport: { timeout: 30000 },
+  },
+});
+```
+
+### Disable Session Persistence
+
+```typescript
+const config = createConfig({
+  clientConfig: getDefaultRialoClientConfig("devnet"),
+  storage: null, // Won't remember connected wallet
+});
+```
+
+### Share TanStack Query Client
+
+If your app already uses TanStack Query:
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FrostProvider config={frostConfig} queryClient={queryClient}>
+        <YourApp />
+      </FrostProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+### Direct Config Access
+
+```tsx
+import { useFrostConfig } from "@rialo/frost";
+
+function Advanced() {
+  const config = useFrostConfig();
+
+  // Access RPC client
+  const client = config.client;
+
+  // Get chain ID
+  const chainId = config.getChainId();
+
+  // Switch chain imperatively
+  config.switchChain(getDefaultRialoClientConfig("mainnet"));
+}
+```
+
+### Non-React Usage
+
+```typescript
+import {
+  createConfig,
+  getDefaultRialoClientConfig,
+  connect,
+  disconnect,
+  signTransaction,
+  WalletRegistry,
+  WalletEventBridge,
+  initializeConfig,
+} from "@rialo/frost-core";
+
+// Setup
+const config = createConfig({
+  clientConfig: getDefaultRialoClientConfig("devnet"),
+});
+
+const registry = new WalletRegistry(config);
+const bridge = new WalletEventBridge(config);
+initializeConfig(config, registry, bridge);
+
+// Connect
+const { accountAddress } = await connect(config, { walletName: "Rialo" });
+
+// Sign
+const { signedTransaction } = await signTransaction(config, { transaction });
+
+// Disconnect
+await disconnect(config);
+
+// Cleanup
+config.destroy();
+```
+
+---
+
+## Troubleshooting
+
+### "No wallets found"
+
+1. Install a Rialo wallet extension
+2. Make sure it's enabled for your site
+3. Refresh the page
+
+### Connection keeps failing
+
+1. Unlock your wallet
+2. Check if the wallet supports your network (devnet/mainnet)
+3. Try disabling and re-enabling the extension
+4. Clear localStorage and refresh
+
+### Hooks not updating
+
+**Wrong:** Creating config inside component
+
+```tsx
+function App() {
+  const config = createConfig({ ... }); // ❌ Recreated every render
+  return <FrostProvider config={config}>...</FrostProvider>;
+}
+```
+
+**Right:** Creating config outside component
+
+```tsx
+const config = createConfig({ ... }); // ✅ Created once
+
+function App() {
+  return <FrostProvider config={config}>...</FrostProvider>;
+}
+```
+
+### "Session expired" on page load
+
+This is expected behavior. The default session TTL is 7 days. Users just need to reconnect.
+
+---
+
+## Configuration Options
+
+```typescript
+interface CreateConfigOptions {
+  /** RPC client configuration (required) */
+  clientConfig: RialoClientConfig;
+
+  /** Auto-reconnect on page load (default: true) */
+  autoConnect?: boolean;
+
+  /** Session TTL in ms (default: 7 days) */
+  sessionTTL?: number;
+
+  /** Storage key prefix (default: "rialo-frost") */
+  storageKey?: string;
+
+  /** Custom storage (default: localStorage, null to disable) */
+  storage?: Storage | null;
+}
+```
+
+---
+
+## Networks
+
+| Network | Chain ID | Use Case |
+|---------|----------|----------|
+| Devnet | `rialo:devnet` | Development (free test tokens) |
+| Testnet | `rialo:testnet` | Pre-production testing |
+| Mainnet | `rialo:mainnet` | Production |
+
+---
+
+## CSS Custom Properties
+
+Frost components support theming via CSS custom properties. Set these variables to customize the appearance:
+
+### Colors
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--frost-primary` | `#3b82f6` | Primary brand color (buttons, accents) |
+| `--frost-text-color` | `#111827` | Main text color |
+| `--frost-text-secondary` | `#6b7280` | Secondary/muted text |
+| `--frost-border-color` | `#e5e7eb` | Border and divider color |
+| `--frost-danger` | `#ef4444` | Destructive action color (disconnect) |
+
+### Backgrounds
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--frost-button-text` | `#ffffff` | Button text color |
+| `--frost-button-connected-bg` | `#f3f4f6` | Connected button background |
+| `--frost-button-connected-text` | `#111827` | Connected button text |
+| `--frost-dropdown-bg` | `#ffffff` | Dropdown menu background |
+| `--frost-hover-bg` | `#f3f4f6` | Hover state background |
+| `--frost-modal-bg` | `#ffffff` | Modal dialog background |
+| `--frost-overlay-bg` | `rgba(0, 0, 0, 0.5)` | Modal overlay background |
+| `--frost-icon-bg` | `#f3f4f6` | Wallet icon background |
+
+### Layout
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--frost-border-radius` | `8px` | Default border radius |
+| `--frost-border-radius-sm` | `6px` | Small border radius |
+| `--frost-modal-max-width` | `400px` | Maximum modal width |
+| `--frost-shadow` | `0 4px 16px rgba(0, 0, 0, 0.12)` | Box shadow |
+| `--frost-z-index` | `9999` | Z-index for overlays |
+
+### Example: Dark Theme
+
+```css
+:root {
+  --frost-primary: #60a5fa;
+  --frost-text-color: #f9fafb;
+  --frost-text-secondary: #9ca3af;
+  --frost-border-color: #374151;
+  --frost-button-text: #ffffff;
+  --frost-button-connected-bg: #1f2937;
+  --frost-button-connected-text: #f9fafb;
+  --frost-dropdown-bg: #1f2937;
+  --frost-hover-bg: #374151;
+  --frost-modal-bg: #111827;
+  --frost-overlay-bg: rgba(0, 0, 0, 0.7);
+  --frost-icon-bg: #374151;
+}
+```
+
+### Example: Custom Brand Colors
+
+```css
+:root {
+  --frost-primary: #8b5cf6;           /* Purple primary */
+  --frost-border-radius: 12px;        /* More rounded */
+  --frost-shadow: 0 8px 32px rgba(139, 92, 246, 0.2);  /* Purple tinted shadow */
+}
+```