@cookill/wallet-adapter 3.1.4 → 3.1.6

package/README.md

@@ -2,8 +2,6 @@
 
 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
 
 ```bash
@@ -25,7 +23,9 @@ function App() {
 }
 ```
 
-`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.
+`WalletProvider` renders a built-in connect modal automatically. On desktop it opens centered; on mobile it slides up as a sheet.
+
+> **Note:** The built-in modal has known interaction issues (tab switching may close the modal, connect button may not trigger the extension). For production use, we recommend building a custom modal using the `connect()` function directly — see [Custom Modal](#custom-modal) below.
 
 ## React Hooks
 
@@ -34,31 +34,29 @@ function App() {
 ```tsx
 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();
-}
+const {
+  connected,       // boolean
+  connecting,      // boolean
+  activeAccount,   // WalletAccount | null
+  chainId,         // string — e.g. "rialo:devnet"
+  isInstalled,     // boolean — extension detected
+
+  // 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>
+
+  // Built-in modal control (has known issues — see note above)
+  openModal,   // () => void
+  closeModal,  // () => void
+} = useWallet();
 ```
 
 ### Focused Hooks
@@ -72,30 +70,76 @@ const accounts = useAccounts();
 const { balance, refresh } = useBalance();
 const { network, chainId } = useNetwork();
 const { switchNetwork } = useSwitchNetwork();
-const { sendTransaction, signAndSendTransaction } = useSendTransaction();
+const { sendTransaction, signAndSendTransaction, sendGaslessTransaction } = useSendTransaction();
 const { signMessage } = useSignMessage();
 ```
 
-## Connect Modal
+### REX (Confidential Transactions)
+
+```tsx
+const { capabilities, supported, submitREXTransaction } = useREX();
+```
+
+### SfS (Stake-for-Service / Gasless)
 
-The modal is rendered automatically by `WalletProvider`. It has two tabs:
+```tsx
+const { positions, credits, hasCredits, createPosition, sendGasless, refresh } = useSfS();
+```
 
-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).
+### Scan-to-Connect
 
-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.
+```tsx
+const { scanURI, status, generateQR, approveSession, rejectSession } = useScanConnect();
+```
 
-When the user clicks **Connect** and the extension is installed, the extension popup opens automatically — no manual action required.
+## Custom Modal
 
-### Controlling the Modal
+The built-in modal rendered by `WalletProvider` has known issues with event propagation. For a reliable connection experience, build your own modal and call `connect()` directly:
 
 ```tsx
-const { openModal, closeModal } = useWallet();
+import { useConnectWallet, useScanConnect, isInstalled } from '@cookill/wallet-adapter/react';
+
+function MyConnectModal({ open, onClose }) {
+  const { connect, connecting, error } = useConnectWallet();
+  const { scanURI, status, generateQR } = useScanConnect();
 
-// Or use the built-in button
-<ConnectButton />
+  const handleConnect = async () => {
+    try {
+      const accounts = await connect();
+      console.log('Connected:', accounts[0].address);
+      onClose();
+    } catch (err) {
+      console.error('Connection failed:', err);
+    }
+  };
+
+  if (!open) return null;
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal-content" onClick={e => e.stopPropagation()}>
+        <h2>Connect Wallet</h2>
+
+        {isInstalled() ? (
+          <button onClick={handleConnect} disabled={connecting}>
+            {connecting ? 'Approve in extension...' : 'Connect Sheep Wallet'}
+          </button>
+        ) : (
+          <a href="https://rialo.io/wallet" target="_blank">Install Sheep Wallet</a>
+        )}
+
+        {error && <p className="error">{error.message}</p>}
+      </div>
+    </div>
+  );
+}
 ```
 
+Key points:
+- Use `connect()` from `useConnectWallet()` — this calls `window.rialo.connect()` which triggers the extension's approval popup
+- The `connect()` call has a 20-second timeout to prevent dApp freezes
+- Use `isInstalled()` to check if the extension is present before connecting
+
 ## Vanilla JavaScript
 
 ```typescript
@@ -108,8 +152,6 @@ if (!wallet.isInstalled) {
 }
 
 const accounts = await wallet.connect();
-console.log('Address:', accounts[0].address);
-
 const balance = await wallet.getBalance();
 console.log('Balance:', formatBalance(balance));
 
@@ -125,27 +167,27 @@ await wallet.disconnect();
 
 ```tsx
 <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
+  connectLabel="Connect Wallet"
+  disconnectLabel="Disconnect"
+  showAddress={true}
+  showBalance={false}
+  showFeatures={false}
 />
 ```
 
+> **Note:** When the extension is installed, `ConnectButton` calls `connect()` directly (no modal). When not installed, it opens the built-in modal with a download link.
+
 ## WalletProvider Props
 
-```tsx
-<WalletProvider
-  network="devnet"            // default network
-  autoConnect={true}          // silently restore previous session on load
-  onConnect={(accounts) => {}}
-  onDisconnect={() => {}}
-  onNetworkChange={(net) => {}}
-  onError={(error) => {}}
->
-  {children}
-</WalletProvider>
-```
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `network` | `RialoNetwork` | `'devnet'` | Default network |
+| `autoConnect` | `boolean` | `true` | Silently restore previous session on load |
+| `scanConnectRelay` | `string` | `'wss://relay.rialo.io'` | Relay URL for scan-to-connect |
+| `onConnect` | `(accounts) => void` | — | Called after successful connection |
+| `onDisconnect` | `() => void` | — | Called after disconnect |
+| `onError` | `(error) => void` | — | Called on connection errors |
+| `onNetworkChange` | `(network) => void` | — | Called when network changes |
 
 ## Networks
 
@@ -156,56 +198,6 @@ await wallet.disconnect();
 | 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:
-
-```typescript
-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
 
 ```typescript
@@ -219,6 +211,7 @@ interface TransactionRequest {
   value: string;      // amount in kelvins (1 RLO = 1_000_000_000 kelvins)
   data?: string;
   memo?: string;
+  gasless?: boolean;   // set by sendGaslessTransaction
 }
 
 interface TransactionResult {
@@ -244,16 +237,22 @@ import {
   formatBalance,   // (kelvins, decimals?) => "1.0000"
   parseBalance,    // (rlo) => bigint (kelvins)
   isValidAddress,  // (address) => boolean
-  isInstalled,     // () => boolean
+  isInstalled,     // () => boolean — checks window.rialo
   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.
+- All provider calls have a 20-second timeout to prevent dApp freezes
+- `autoConnect` uses `checkSession()` — never triggers a user-facing popup
+- The built-in modal is rendered inside `WalletProvider` automatically
+- `ConnectButton` bypasses the modal when the extension is installed
+
+## Known Issues
+
+1. **Built-in modal tab switching** — Clicking "Scan to Connect" tab may close the modal due to event propagation. Workaround: use a custom modal.
+2. **Built-in modal connect button** — May not trigger the extension popup in some environments. Workaround: use `connect()` directly.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cookill/wallet-adapter",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Official Sheep Wallet adapter for Rialo blockchain - REX confidential TX, SfS gasless TX, Scan-to-Connect",
   "author": "CookilLabs",
   "license": "MIT",