@cookill/wallet-adapter

Wallet adapter for Sheep Wallet — the browser extension wallet for the Rialo blockchain.

Provides a drop-in React provider, responsive connect modal, and vanilla JS class so dApp developers can integrate Sheep Wallet without writing custom UI.

Installation

npm install @cookill/wallet-adapter

Quick Start (React)

import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';

function App() {
  return (
    <WalletProvider network="devnet" autoConnect>
      <ConnectButton />
      <YourDApp />
    </WalletProvider>
  );
}

WalletProvider renders a built-in connect modal automatically. On desktop the modal opens centered; on mobile it slides up from the bottom as a sheet. No custom modal code needed.

React Hooks

useWallet

import { useWallet } from '@cookill/wallet-adapter/react';

function MyComponent() {
  const {
    connected,       // boolean — is wallet connected
    connecting,      // boolean — connection in progress
    activeAccount,   // WalletAccount | null — first connected account
    chainId,         // string — e.g. "rialo:devnet"
    isInstalled,     // boolean — extension detected in browser

    // Actions
    connect,         // () => Promise<WalletAccount[]>
    disconnect,      // () => Promise<void>
    switchNetwork,   // (network) => Promise<void>
    refreshBalance,  // () => Promise<void>

    // Signing & Transactions
    signMessage,             // (msg: string) => Promise<SignedMessage>
    signTransaction,         // (tx) => Promise<string>
    sendTransaction,         // (tx) => Promise<TransactionResult>
    signAndSendTransaction,  // (tx) => Promise<TransactionResult>

    // Modal control
    openModal,   // () => void — open the connect modal
    closeModal,  // () => void — close it
  } = useWallet();
}

Focused Hooks

const { connect, connecting, isInstalled, error } = useConnectWallet();
const { disconnect, connected } = useDisconnectWallet();
const connected = useIsConnected();
const account = useActiveAccount();
const accounts = useAccounts();
const { balance, refresh } = useBalance();
const { network, chainId } = useNetwork();
const { switchNetwork } = useSwitchNetwork();
const { sendTransaction, signAndSendTransaction } = useSendTransaction();
const { signMessage } = useSignMessage();

Connect Modal

The modal is rendered automatically by WalletProvider. It has two tabs:

1. Extension — Detects the installed Sheep Wallet extension and connects directly. If the extension is not installed, a download link is shown.
2. Scan to Connect — Generates a QR code that a mobile Sheep Wallet can scan to pair cross-device. Also supports the reverse flow (wallet shows QR, dApp scans).

On mobile viewports the modal slides up from the bottom as a sheet and can be dismissed by swiping down. On desktop it opens as a centered dialog.

When the user clicks Connect and the extension is installed, the extension popup opens automatically — no manual action required.

Controlling the Modal

const { openModal, closeModal } = useWallet();

// Or use the built-in button
<ConnectButton />

Vanilla JavaScript

import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';

const wallet = new SheepWallet();

if (!wallet.isInstalled) {
  console.log('Extension not found');
}

const accounts = await wallet.connect();
console.log('Address:', accounts[0].address);

const balance = await wallet.getBalance();
console.log('Balance:', formatBalance(balance));

await wallet.signAndSendTransaction({
  to: 'RecipientAddress',
  value: '1000000000', // 1 RLO in kelvins
});

await wallet.disconnect();

ConnectButton

<ConnectButton
  connectLabel="Connect Wallet"   // label when disconnected
  disconnectLabel="Disconnect"     // dropdown label when connected
  showAddress={true}               // show truncated address when connected
  showBalance={false}              // show RLO balance next to address
/>

WalletProvider Props

<WalletProvider
  network="devnet"            // default network
  autoConnect={true}          // silently restore previous session on load
  onConnect={(accounts) => {}}
  onDisconnect={() => {}}
  onNetworkChange={(net) => {}}
  onError={(error) => {}}
>
  {children}
</WalletProvider>

Networks

| Network | Chain ID | RPC URL | Symbol | |----------|-----------------|--------------------------------|--------| | Mainnet | rialo:mainnet | https://mainnet.rialo.io:4101 | RLO | | Testnet | rialo:testnet | https://testnet.rialo.io:4101 | tRLO | | Devnet | rialo:devnet | https://devnet.rialo.io:4101 | dRLO | | Localnet | rialo:localnet | http://localhost:4101 | lRLO |

Provider Interface (window.rialo)

When the Sheep Wallet extension is installed, it injects window.rialo with this interface:

interface RialoProvider {
  isRialo: boolean;
  isSheepWallet: boolean;
  version: string;

  // Connection
  connect(): Promise<WalletAccount[]>;
  disconnect(): Promise<void>;
  isConnected(): Promise<boolean>;
  getAccounts(): Promise<WalletAccount[]>;

  // Transactions
  signTransaction(tx: TransactionRequest): Promise<{ signature: string }>;
  sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
  signAndSendTransaction(tx: TransactionRequest): Promise<TransactionResult>;

  // Message Signing
  signMessage(message: string | Uint8Array): Promise<SignedMessage>;

  // Network
  getNetwork(): Promise<RialoNetwork>;
  switchNetwork(network: RialoNetwork): Promise<void>;
  getBalance(address?: string): Promise<BalanceResult>;

  // Events
  on(event: WalletEvent, callback: Function): () => void;

  // State (synchronous getters)
  readonly connected: boolean;
  readonly accounts: WalletAccount[];
  readonly address: string | null;
  readonly network: RialoNetwork;
  readonly chainId: string;
}

Supported Events

| Event | Payload | |-------------------|-----------------------------------| | connect | { accounts: WalletAccount[] } | | disconnect | — | | accountsChanged | WalletAccount[] | | networkChanged | { network, chainId } |

Key Types

interface WalletAccount {
  address: string;
  publicKey: string;
}

interface TransactionRequest {
  to: string;
  value: string;      // amount in kelvins (1 RLO = 1_000_000_000 kelvins)
  data?: string;
  memo?: string;
}

interface TransactionResult {
  hash: string;
  signature?: string;
  status: 'pending' | 'confirmed' | 'failed';
}

interface SignedMessage {
  signature: string;
  message: string;
  address: string;
}

type RialoNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';

Utilities

import {
  formatAddress,   // (address, chars?) => "5YNm...VWr8"
  formatBalance,   // (kelvins, decimals?) => "1.0000"
  parseBalance,    // (rlo) => bigint (kelvins)
  isValidAddress,  // (address) => boolean
  isInstalled,     // () => boolean
  NETWORKS,        // Record<RialoNetwork, NetworkConfig>
} from '@cookill/wallet-adapter';

Architecture Notes

• All provider calls are wrapped with a 20-second timeout to prevent dApp freezes if the extension stops responding.
• autoConnect uses a silent checkSession() that never triggers a user-facing approval popup — it only restores an existing session.
• The connect modal is rendered inside WalletProvider so you never need to manage modal state yourself.

License

MIT