@cookill/wallet-adapter 3.0.0 → 3.1.1

package/README.md

@@ -1,41 +1,32 @@
-# @cookill/wallet-adapter v3.0.0
+# @cookill/wallet-adapter
 
-Official wallet adapter for **Sheep Wallet** on Rialo blockchain.
+Wallet adapter for **Sheep Wallet** — the browser extension wallet for the Rialo blockchain.
 
-## 🚀 What's New in v3.0
-
-- **Anti-freeze architecture**: All provider calls wrapped with timeouts
-- **Clean separation**: Core (vanilla JS) vs React layer
-- **Silent auto-connect**: Uses `checkSession()` instead of `connect()` for session restoration
-- **No more hangs**: 20-second timeout on connection, 30-second on operations
+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
 
 ```bash
 npm install @cookill/wallet-adapter
-# or
-pnpm add @cookill/wallet-adapter
-# or
-yarn add @cookill/wallet-adapter
 ```
 
 ## Quick Start (React)
 
 ```tsx
-import { WalletProvider, ConnectButton, WalletErrorBoundary } from '@cookill/wallet-adapter/react';
+import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
 
 function App() {
   return (
-    <WalletErrorBoundary>
-      <WalletProvider network="devnet" autoConnect>
-        <ConnectButton />
-        <YourDApp />
-      </WalletProvider>
-    </WalletErrorBoundary>
+    <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
@@ -45,65 +36,64 @@ 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
-    
+    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>
-    
-    // Transactions
-    signMessage,         // (message: string) => Promise<SignedMessage>
-    signTransaction,     // (tx) => Promise<string>
-    sendTransaction,     // (tx) => Promise<TransactionResult>
-    signAndSendTransaction, // (tx) => Promise<TransactionResult>
-    
-    // Modal
-    openModal,
-    closeModal,
+    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();
-
-  return (
-    <div>
-      {connected ? (
-        <p>Connected: {activeAccount?.address}</p>
-      ) : (
-        <button onClick={connect}>Connect</button>
-      )}
-    </div>
-  );
 }
 ```
 
-### Specialized Hooks
+### Focused Hooks
 
 ```tsx
-// 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();
+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.
 
-// Transactions
-const { signMessage, connected } = useSignMessage();
-const { sendTransaction, signAndSendTransaction, connected } = useSendTransaction();
+When the user clicks **Connect** and the extension is installed, the extension popup opens automatically — no manual action required.
+
+### Controlling the Modal
+
+```tsx
+const { openModal, closeModal } = useWallet();
+
+// Or use the built-in button
+<ConnectButton />
 ```
 
 ## Vanilla JavaScript
@@ -111,203 +101,159 @@ const { sendTransaction, signAndSendTransaction, connected } = useSendTransactio
 ```typescript
 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);
+if (!wallet.isInstalled) {
+  console.log('Extension not found');
 }
 
-// Get balance
-const balance = await wallet.getBalance();
-console.log('Balance:', formatBalance(balance), 'RLO');
+const accounts = await wallet.connect();
+console.log('Address:', accounts[0].address);
 
-// Sign message
-const signed = await wallet.signMessage('Hello!');
+const balance = await wallet.getBalance();
+console.log('Balance:', formatBalance(balance));
 
-// Send transaction
-const tx = await wallet.signAndSendTransaction({
-  to: 'RecipientAddress...',
+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
-
-```typescript
-// 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',
-  });
-}
+await wallet.disconnect();
 ```
 
-## Components
-
-### ConnectButton
+## ConnectButton
 
 ```tsx
 <ConnectButton
-  connectLabel="Connect Wallet"
-  disconnectLabel="Disconnect"
-  showAddress={true}
-  showBalance={false}
-  className="my-button"
-  style={{ backgroundColor: '#6EB9A8' }}
+  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
+## WalletProvider Props
 
 ```tsx
 <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)}
+  network="devnet"            // default network
+  autoConnect={true}          // silently restore previous session on load
+  onConnect={(accounts) => {}}
+  onDisconnect={() => {}}
+  onNetworkChange={(net) => {}}
+  onError={(error) => {}}
 >
   {children}
 </WalletProvider>
 ```
 
-### Error Boundary & Loading States
-
-```tsx
-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   |
+| 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
+## Provider Interface (window.rialo)
 
-```typescript
-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
+When the Sheep Wallet extension is installed, it injects `window.rialo` with this interface:
 
 ```typescript
-import type {
-  WalletAccount,
-  TransactionRequest,
-  TransactionResult,
-  SignedMessage,
-  BalanceResult,
-  NetworkConfig,
-  WalletInfo,
-  RialoProvider,
-  RialoNetwork,
-  RialoChainId,
-} from '@cookill/wallet-adapter';
+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;
+}
 ```
 
-## Troubleshooting
-
-### Connection hangs / freezes
+### Supported Events
 
-v3.0 has built-in 20-second timeout. If connection still hangs:
+| Event             | Payload                           |
+|-------------------|-----------------------------------|
+| `connect`         | `{ accounts: WalletAccount[] }`   |
+| `disconnect`      | —                                 |
+| `accountsChanged` | `WalletAccount[]`                 |
+| `networkChanged`  | `{ network, chainId }`            |
 
-1. Make sure extension is installed and unlocked
-2. Check if popup was blocked by browser
-3. Try refreshing the page
+## Key Types
 
-### Auto-connect not working
+```typescript
+interface WalletAccount {
+  address: string;
+  publicKey: string;
+}
 
-Auto-connect uses `checkSession()` which only restores **existing** sessions silently.
-It won't trigger the approval popup. User must explicitly call `connect()` first time.
+interface TransactionRequest {
+  to: string;
+  value: string;      // amount in kelvins (1 RLO = 1_000_000_000 kelvins)
+  data?: string;
+  memo?: string;
+}
 
-### Modal not opening
+interface TransactionResult {
+  hash: string;
+  signature?: string;
+  status: 'pending' | 'confirmed' | 'failed';
+}
 
-The `WalletProvider` renders the modal automatically. If you see issues:
+interface SignedMessage {
+  signature: string;
+  message: string;
+  address: string;
+}
 
-```tsx
-// Make sure you're inside WalletProvider
-const { openModal } = useWallet();
-openModal(); // This should work
+type RialoNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
 ```
 
-## Migration from v2.x
+## Utilities
 
-```diff
-// Imports are the same
-import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
+```typescript
+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';
+```
 
-// Hook usage is the same
-const { connect, connected } = useWallet();
+## Architecture Notes
 
-// Main changes:
-// - connect() now has 20s timeout built-in
-// - autoConnect uses checkSession() (silent, never triggers popup)
-// - New SheepWallet class for vanilla JS (replaces RialoWallet)
-```
+- 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