@rialo/frost

Rialo Frost

The wallet integration toolkit for Rialo dApps — Connect wallets, sign transactions, and build Web3 apps in minutes.

pnpm add @rialo/frost

30-Second Setup

// 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?
• Installation
• Step-by-Step Guide
• Hooks Reference
• Async/Await with mutateAsync
• Components
• Error Handling
• Advanced Usage
• Troubleshooting
• CSS Custom Properties

New to Web3?

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Your App   │ ───► │    Frost     │ ───► │   Wallet     │
│              │      │              │      │  Extension   │
│  - UI        │      │  - Discovers │      │              │
│  - Logic     │      │    wallets   │      │  - Stores    │
│  - Hooks     │      │  - Manages   │      │    keys      │
│              │      │    state     │      │  - Signs     │
└──────────────┘      └──────────────┘      └──────────────┘

Installation

Requirements

• Node.js 18+
• React 18 or 19
• A Rialo wallet extension (for testing)

Install

# 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:

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:

// 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:

// 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

import { ConnectButton } from "@rialo/frost";

function Header() {
  return (
    <nav>
      <h1>My dApp</h1>
      <ConnectButton />
    </nav>
  );
}

Option B: Build your own

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

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

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

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

Account & Wallet

Chain & Client

Balance

Signing & Transactions

Async/Await with mutateAsync

All mutation hooks (useConnectWallet, useSignMessage, useSignTransaction, useSendTransaction, useSignAndSendTransaction, useDisconnectWallet) return both mutate and mutateAsync. Note: useSwitchChain is not a mutation hook — it returns a plain function directly.

Callback Pattern (mutate)

The mutate function is fire-and-forget with callbacks:

const { mutate: send } = useSendTransaction({
  onSuccess: (result) => console.log("Sent:", result.signature),
  onError: (error) => console.error("Failed:", error),
});

// Fire and forget - no await, no return value
send({ transaction });

Async/Await Pattern (mutateAsync)

The mutateAsync function returns a Promise you can await:

const { mutateAsync: sendAsync } = useSendTransaction();

async function handleSend() {
  try {
    const result = await sendAsync({ transaction });
    console.log("Transaction signature:", result.signature);
    // Continue with next steps...
  } catch (error) {
    console.error("Transaction failed:", error);
  }
}

When to Use Each

Real-World Example: Sign Then Send

function TransactionFlow() {
  const { mutateAsync: signAsync } = useSignTransaction();
  const { mutateAsync: sendAsync } = useSendTransaction();
  const [status, setStatus] = useState<string>("");

  async function handleTransaction(transaction: Uint8Array) {
    try {
      setStatus("Signing...");
      const { signedTransaction } = await signAsync({ transaction });

      setStatus("Sending...");
      const { signature } = await sendAsync({ transaction: signedTransaction });

      setStatus(`Success! Signature: ${signature}`);
    } catch (error) {
      setStatus(`Error: ${error.message}`);
    }
  }

  return (
    <div>
      <button onClick={() => handleTransaction(myTx)}>Execute</button>
      <p>{status}</p>
    </div>
  );
}

All Mutation Hooks Support Both Patterns

// Connection
const { mutateAsync: connectAsync } = useConnectWallet();
const result = await connectAsync({ walletName: "Rialo" });

// Signing
const { mutateAsync: signMessageAsync } = useSignMessage();
const { signature } = await signMessageAsync({ message: "Hello" });

// Transactions
const { mutateAsync: signTxAsync } = useSignTransaction();
const { signedTransaction } = await signTxAsync({ transaction });

const { mutateAsync: sendTxAsync } = useSendTransaction();
const { signature } = await sendTxAsync({ transaction });

const { mutateAsync: signAndSendAsync } = useSignAndSendTransaction();
const { signature } = await signAndSendAsync({ transaction });

// Disconnect
const { mutateAsync: disconnectAsync } = useDisconnectWallet();
await disconnectAsync();

// Switch chain
const switchChain = useSwitchChain();
switchChain(getDefaultRialoClientConfig("mainnet"));

Hooks in Detail

useConnectWallet

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

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]) });

useNativeBalance

const {
  balance,      // bigint | undefined - Raw balance in kelvins
  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

import { getDefaultRialoClientConfig } from "@rialo/frost";

const switchChain = useSwitchChain();

// Switch to mainnet
switchChain(getDefaultRialoClientConfig("mainnet"));

// Switch to testnet
switchChain(getDefaultRialoClientConfig("testnet"));

Components

ConnectButton

A complete, styled connect button with dropdown:

<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
  dropdownClassName="my-dropdown"     // CSS class for dropdown container
  onConnect={(wallet, address) => {}} // Connection callback
  onDisconnect={() => {}}             // Disconnect callback
  onError={(error) => {}}             // Error callback
/>

WalletModal

A modal for wallet selection:

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:

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

Advanced Usage

Custom RPC URL

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

const config = createConfig({
  clientConfig: getDefaultRialoClientConfig("devnet"),
  storage: null, // Won't remember connected wallet
});

Share TanStack Query Client

If your app already uses TanStack Query:

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

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

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

function App() {
  const config = createConfig({ ... }); // ❌ Recreated every render
  return <FrostProvider config={config}>...</FrostProvider>;
}

Right: Creating config outside component

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

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

CSS Custom Properties

Frost components support theming via CSS custom properties. Set these variables to customize the appearance:

Colors

Backgrounds

Layout

Example: Dark Theme

: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

: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 */
}