@cookill/wallet-adapter v3.2.1

Official wallet adapter for Sheep Wallet on Rialo blockchain.

🚀 What's New in v3.2.1

• Anti-freeze connect flow: connect path remains timeout-protected
• Luxury Minimal WalletModal: rebranded Sheep Wallet modal with clearer connect state
• ConnectButton behavior fix: disconnected click now opens modal consistently
• Safer developer guidance: docs clarified to avoid misleading integration assumptions

Installation

npm install @cookill/wallet-adapter
# or
pnpm add @cookill/wallet-adapter
# or
yarn add @cookill/wallet-adapter

Quick Start (React)

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

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

React Hooks

useWallet

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

function MyComponent() {
  const {
    // State
    connected,           // boolean
    connecting,          // boolean
    activeAccount,       // WalletAccount | null
    state,               // Full state object
    chainId,             // 'rialo:devnet' etc
    isInstalled,         // boolean
    
    // Actions
    connect,             // () => Promise<WalletAccount[]>
    disconnect,          // () => Promise<void>
    switchNetwork,       // (network) => Promise<void>
    refreshBalance,      // () => Promise<void>
    
    // Transactions
    signMessage,         // (message: string) => Promise<SignedMessage>
    signTransaction,     // (tx) => Promise<string>
    sendTransaction,     // (tx) => Promise<TransactionResult>
    signAndSendTransaction, // (tx) => Promise<TransactionResult>
    
    // Modal
    openModal,
    closeModal,
  } = useWallet();

  return (
    <div>
      {connected ? (
        <p>Connected: {activeAccount?.address}</p>
      ) : (
        <button onClick={connect}>Connect</button>
      )}
    </div>
  );
}

Specialized Hooks

// Connection
const { connect, connecting, isInstalled, error } = useConnectWallet();
const { disconnect, connected } = useDisconnectWallet();
const connected = useIsConnected();

// Account
const account = useActiveAccount();
const accounts = useAccounts();

// Balance
const { balance, refresh } = useBalance();

// Network
const { network, chainId } = useNetwork();
const { switchNetwork, network } = useSwitchNetwork();

// Transactions
const { signMessage, connected } = useSignMessage();
const { sendTransaction, signAndSendTransaction, connected } = useSendTransaction();

Vanilla JavaScript

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

// Check if installed
if (!isInstalled()) {
  console.log('Please install Sheep Wallet');
}

// Create wallet instance
const wallet = new SheepWallet();

// Connect (with built-in timeout)
try {
  const accounts = await wallet.connect();
  console.log('Connected:', accounts[0].address);
} catch (error) {
  console.error('Connection failed:', error.message);
}

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

// Sign message
const signed = await wallet.signMessage('Hello!');

// Send transaction
const tx = await wallet.signAndSendTransaction({
  to: 'RecipientAddress...',
  value: '1000000000', // 1 RLO in kelvins
});
console.log('TX Hash:', tx.hash);

// Silent session check (for auto-connect, never triggers approval)
const existingSession = await wallet.checkSession();
if (existingSession) {
  console.log('Session restored:', existingSession[0].address);
}

Direct Provider Access

// Access window.rialo directly
if (window.rialo) {
  const accounts = await window.rialo.connect();
  const balance = await window.rialo.getBalance();
  const tx = await window.rialo.signAndSendTransaction({
    to: 'RecipientAddress...',
    value: '1000000000',
  });
}

Components

ConnectButton

<ConnectButton
  connectLabel="Connect Wallet"
  disconnectLabel="Disconnect"
  showAddress={true}
  showBalance={false}
  className="my-button"
  style={{ backgroundColor: '#6EB9A8' }}
/>

WalletProvider

<WalletProvider
  network="devnet"        // 'mainnet' | 'testnet' | 'devnet' | 'localnet'
  autoConnect={true}      // Restore session silently on mount
  wallets={[customWallet]} // Additional wallets to show
  onConnect={(accounts) => console.log('Connected', accounts)}
  onDisconnect={() => console.log('Disconnected')}
  onNetworkChange={(network) => console.log('Network:', network)}
  onError={(error) => console.error(error)}
>
  {children}
</WalletProvider>

Error Boundary & Loading States

import { 
  WalletErrorBoundary,
  ApprovalPending,
  LoadingSpinner,
  ConnectionStatus,
} from '@cookill/wallet-adapter/react';

// Error Boundary
<WalletErrorBoundary 
  fallback={<CustomError />} 
  onError={(error, info) => logError(error)}
>
  <WalletProvider>...</WalletProvider>
</WalletErrorBoundary>

// Loading states
<ApprovalPending
  title="Waiting for Approval"
  message="Please approve in Sheep Wallet"
  walletName="Sheep Wallet"
  onCancel={() => disconnect()}
/>

<LoadingSpinner size="md" color="#6EB9A8" />

<ConnectionStatus status="connecting" />
<ConnectionStatus status="approving" message="Check your wallet" />
<ConnectionStatus status="error" onRetry={() => connect()} />

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 |

Utilities

import { 
  formatAddress,      // (address, chars?) => "5YNm...VWr8"
  formatBalance,      // (kelvins, decimals?) => "1.0000"
  parseBalance,       // (rlo) => bigint (kelvins)
  isValidAddress,     // (address) => boolean
  toChainId,          // (network) => 'rialo:devnet'
  fromChainId,        // (chainId) => 'devnet'
  isInstalled,        // () => boolean
  getProvider,        // () => RialoProvider | undefined
  waitForProvider,    // (timeout?) => Promise<RialoProvider | undefined>
  NETWORKS,           // Network configurations
} from '@cookill/wallet-adapter';

TypeScript

import type {
  WalletAccount,
  TransactionRequest,
  TransactionResult,
  SignedMessage,
  BalanceResult,
  NetworkConfig,
  WalletInfo,
  RialoProvider,
  RialoNetwork,
  RialoChainId,
} from '@cookill/wallet-adapter';

Troubleshooting

Connection hangs / freezes

v3.2.1 has built-in 20-second timeout. If connection still hangs:

1. Make sure extension is installed and unlocked
2. Check if popup was blocked by browser
3. Try refreshing the page

Auto-connect not working

Auto-connect uses checkSession() which only restores existing sessions silently. It won't trigger the approval popup. User must explicitly call connect() first time.

Modal connect flow

ConnectButton now always opens the modal when disconnected, then connection is initiated from the modal so extension approval flow stays consistent and never feels like a silent fail.

const { openModal } = useWallet();
openModal();

Migration from v3.0.x

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

 const { connect, connected } = useWallet();
 
 // v3.2.1 updates:
 // - ConnectButton opens WalletModal when disconnected
 // - WalletModal uses refreshed Sheep Wallet Luxury Minimal branding
 // - connect() path remains timeout-guarded

Important note about QR / scan-to-connect

Core @cookill/wallet-adapter/react does not ship camera QR scanner UI. If your app needs QR scan/connect flow, implement custom modal UI at app layer and pass resulting URI to your own connect handler.

License

MIT