@cookill/wallet-adapter 3.1.0 → 3.1.2

package/README.md

@@ -1,40 +1,32 @@
-# @cookill/wallet-adapter v3.1.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.1
-
-- **REX (Rialo Extended Execution)**: Submit confidential transactions using TEE/MPC/FHE
-- **SfS (Stake-for-Service)**: Gasless transactions — pay fees from staking yield
-- **Scan-to-Connect**: Bidirectional QR code pairing across devices
-- **Anti-freeze architecture**: All provider calls wrapped with timeouts
-- **Silent auto-connect**: Uses `checkSession()` for session restoration
+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
 ```
 
 ## 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
@@ -44,143 +36,64 @@ import { useWallet } from '@cookill/wallet-adapter/react';
 
 function MyComponent() {
   const {
-    connected, connecting, activeAccount, state, chainId, isInstalled,
-    connect, disconnect, switchNetwork, refreshBalance,
-    signMessage, signTransaction, sendTransaction, signAndSendTransaction,
-    // REX
-    getREXCapabilities, submitREXTransaction,
-    // SfS (Gasless)
-    sendGaslessTransaction, getSfSPositions, createSfSPosition, getSfSCredits,
-    // Modal
-    openModal, closeModal,
+    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();
 }
 ```
 
-### Specialized Hooks
+### Focused Hooks
 
 ```tsx
-// Connection
 const { connect, connecting, isInstalled, error } = useConnectWallet();
 const { disconnect, connected } = useDisconnectWallet();
 const connected = useIsConnected();
-
-// Account & Balance
 const account = useActiveAccount();
 const accounts = useAccounts();
 const { balance, refresh } = useBalance();
-
-// Network
 const { network, chainId } = useNetwork();
-const { switchNetwork, network } = useSwitchNetwork();
-
-// Transactions (now includes gasless)
-const { sendTransaction, signAndSendTransaction, sendGaslessTransaction } = useSendTransaction();
+const { switchNetwork } = useSwitchNetwork();
+const { sendTransaction, signAndSendTransaction } = useSendTransaction();
 const { signMessage } = useSignMessage();
 ```
 
-### useREX — Confidential Transactions
-
-```tsx
-import { useREX } from '@cookill/wallet-adapter/react';
-
-function ConfidentialTransfer() {
-  const { capabilities, supported, submitREXTransaction } = useREX();
-
-  const handleConfidentialSend = async () => {
-    const result = await submitREXTransaction({
-      to: 'RecipientAddress...',
-      value: '1000000000',
-      rex: {
-        confidential: true,
-        privacyMode: 'auto',     // 'tee' | 'mpc' | 'fhe' | 'auto'
-        keepEncrypted: false,     // true = output stays encrypted
-      },
-    });
-    
-    console.log('TX hash:', result.hash);
-    console.log('Attestation:', result.attestation);
-  };
+## Connect Modal
 
-  return (
-    <div>
-      <p>REX supported: {supported ? 'Yes' : 'No'}</p>
-      {supported && (
-        <div>
-          <p>Privacy modes: {capabilities?.privacyModes.join(', ')}</p>
-          <button onClick={handleConfidentialSend}>
-            Send Confidential Transaction
-          </button>
-        </div>
-      )}
-    </div>
-  );
-}
-```
+The modal is rendered automatically by `WalletProvider`. It has two tabs:
 
-### useSfS — Gasless Transactions (Stake-for-Service)
+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).
 
-```tsx
-import { useSfS } from '@cookill/wallet-adapter/react';
-
-function GaslessDemo() {
-  const { positions, credits, hasCredits, createPosition, sendGasless, refresh } = useSfS();
-
-  // Create an SfS position to generate service credits
-  const handleStake = async () => {
-    await createPosition({
-      amount: '10000000000',       // 10 RLO in kelvins
-      validator: 'ValidatorAddr...', 
-      routingFraction: 0.5,        // Route 50% of yield to service credits
-    });
-    await refresh();
-  };
-
-  // Send a gasless transaction (paid from SfS credits)
-  const handleGaslessSend = async () => {
-    const result = await sendGasless({
-      to: 'RecipientAddress...',
-      value: '1000000000',         // 1 RLO
-    });
-    console.log('Gasless TX:', result.hash);
-  };
+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.
 
-  return (
-    <div>
-      <p>SfS Positions: {positions.length}</p>
-      <p>Available Credits: {credits?.available || '0'}</p>
-      <p>Credits/Epoch: {credits?.estimatedPerEpoch || '0'}</p>
-      
-      {!hasCredits ? (
-        <button onClick={handleStake}>Stake for Gasless TX</button>
-      ) : (
-        <button onClick={handleGaslessSend}>Send (Gasless)</button>
-      )}
-    </div>
-  );
-}
-```
+When the user clicks **Connect** and the extension is installed, the extension popup opens automatically — no manual action required.
 
-### useScanConnect — QR-based Cross-Device Pairing
+### Controlling the Modal
 
 ```tsx
-import { useScanConnect } from '@cookill/wallet-adapter/react';
-
-function ScanConnectDemo() {
-  const { scanURI, status, generateQR, approveSession, rejectSession } = useScanConnect();
+const { openModal, closeModal } = useWallet();
 
-  return (
-    <div>
-      <button onClick={generateQR}>Generate QR</button>
-      {scanURI && (
-        <div>
-          <p>Scan this URI: {scanURI.uri}</p>
-          <p>Status: {status}</p>
-        </div>
-      )}
-    </div>
-  );
-}
+// Or use the built-in button
+<ConnectButton />
 ```
 
 ## Vanilla JavaScript
@@ -190,213 +103,157 @@ import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter
 
 const wallet = new SheepWallet();
 
-// Standard connect
+if (!wallet.isInstalled) {
+  console.log('Extension not found');
+}
+
 const accounts = await wallet.connect();
+console.log('Address:', accounts[0].address);
 
-// REX — Confidential transaction
-const rexResult = await wallet.submitREXTransaction({
-  to: 'RecipientAddress...',
-  value: '1000000000',
-  rex: { confidential: true, privacyMode: 'auto' },
-});
+const balance = await wallet.getBalance();
+console.log('Balance:', formatBalance(balance));
 
-// SfS — Create staking position for gasless TX
-await wallet.createSfSPosition({
-  amount: '10000000000',
-  validator: 'ValidatorAddr...',
-  routingFraction: 0.5,
+await wallet.signAndSendTransaction({
+  to: 'RecipientAddress',
+  value: '1000000000', // 1 RLO in kelvins
 });
 
-// SfS — Send gasless transaction
-const result = await wallet.sendGaslessTransaction({
-  to: 'RecipientAddress...',
-  value: '1000000000',
-});
-
-// Scan-to-Connect — Generate session QR
-const session = await wallet.createScanSession();
-console.log('QR URI:', session.uri);
+await wallet.disconnect();
 ```
 
-## Components
-
-### ConnectButton
+## ConnectButton
 
 ```tsx
 <ConnectButton
-  connectLabel="Connect Wallet"
-  disconnectLabel="Disconnect"
-  showAddress={true}
-  showBalance={false}
-  showFeatures={true}    // Show REX/SfS badges
+  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"
-  autoConnect={true}
-  scanConnectRelay="wss://relay.rialo.io"
-  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>
 ```
 
-The connect modal includes two tabs:
-- **Extension**: Direct browser extension connection
-- **Scan to Connect**: Bidirectional QR code (show QR or scan QR)
-
 ## Networks
 
-| Network  | Chain ID        | RPC URL                         | Symbol | REX | SfS |
-|----------|-----------------|----------------------------------|--------|-----|-----|
-| 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   | ❌  | ❌  |
+| 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   |
 
-## REX (Rialo Extended Execution)
+## Provider Interface (window.rialo)
 
-REX enables privacy-preserving computation on Rialo using:
-- **TEE** (Trusted Execution Environments) — fastest, hardware-isolated
-- **MPC** (Multi-Party Computation) — distributed, no single trust point
-- **FHE** (Fully Homomorphic Encryption) — compute on encrypted data
-- **Auto** — protocol selects optimal privacy technology
-
-### REX Transaction Flow
-
-```
-1. User encrypts inputs with network public key
-2. Wallet submits encrypted TX to REX execution layer
-3. Nodes execute confidentially (inputs never exposed)
-4. Result is cryptographically attested
-5. Only authorized parties can decrypt output
-```
-
-### REX Config Options
+When the Sheep Wallet extension is installed, it injects `window.rialo` with this interface:
 
 ```typescript
-interface REXConfig {
-  confidential: boolean;           // Enable REX execution
-  privacyMode?: 'tee' | 'mpc' | 'fhe' | 'auto';
-  encryptedInputs?: string;        // Pre-encrypted data (base64)
-  programId?: string;              // REX program to execute
-  keepEncrypted?: boolean;         // Keep output encrypted
-  accessPolicy?: {
-    allowedDecryptors: string[];   // Who can decrypt
-    expiresAt?: number;            // Access expiry
-  };
+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;
 }
 ```
 
-## SfS (Stake-for-Service)
-
-Stake-for-Service converts staking yield into service credits that pay for gas automatically.
-
-### How It Works
+### Supported Events
 
-```
-1. User stakes RLO with a validator
-2. Sets routingFraction (0.0 - 1.0) of yield → service credits
-3. ServicePaymaster mints credits from routed yield
-4. Credits auto-pay gas for transactions
-5. No more manual gas top-ups
-```
+| Event             | Payload                           |
+|-------------------|-----------------------------------|
+| `connect`         | `{ accounts: WalletAccount[] }`   |
+| `disconnect`      | —                                 |
+| `accountsChanged` | `WalletAccount[]`                 |
+| `networkChanged`  | `{ network, chainId }`            |
 
-### SfS Types
+## Key Types
 
 ```typescript
-interface SfSPosition {
-  id: string;
-  principal: string;           // Staked amount (kelvins)
-  validator: string;           // Validator address
-  routingFraction: number;     // 0.0 - 1.0
-  creditBalance: string;       // Current credits
-  creditsPerEpoch: string;     // Estimated yield
-  status: 'active' | 'pending' | 'closed';
+interface WalletAccount {
+  address: string;
+  publicKey: string;
 }
 
-interface SfSCreditBalance {
-  available: string;
-  usedThisEpoch: string;
-  totalEarned: string;
-  estimatedPerEpoch: string;
+interface TransactionRequest {
+  to: string;
+  value: string;      // amount in kelvins (1 RLO = 1_000_000_000 kelvins)
+  data?: string;
+  memo?: string;
 }
-```
-
-## Scan-to-Connect
 
-Connect wallet on one device to dApp on another via QR code.
-
-### Bidirectional Flow
-
-**dApp → Wallet**: dApp shows QR, user scans with mobile Sheep Wallet
-**Wallet → dApp**: Wallet shows QR (Settings → Show Connect QR), dApp scans
+interface TransactionResult {
+  hash: string;
+  signature?: string;
+  status: 'pending' | 'confirmed' | 'failed';
+}
 
-### URI Format
+interface SignedMessage {
+  signature: string;
+  message: string;
+  address: string;
+}
 
-```
-rialo-wc://{sessionId}?relay={relayUrl}&topic={topic}&networks=devnet
+type RialoNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
 ```
 
 ## Utilities
 
 ```typescript
-import { 
-  formatAddress,      // (address, chars?) => "5YNm...VWr8"
-  formatBalance,      // (kelvins, decimals?) => "1.0000"
-  parseBalance,       // (rlo) => bigint (kelvins)
-  isValidAddress,     // (address) => boolean
-  isInstalled,        // () => boolean
-  NETWORKS,           // Network configurations
-} from '@cookill/wallet-adapter';
-```
-
-## TypeScript
-
-```typescript
-import type {
-  WalletAccount, TransactionRequest, TransactionResult,
-  SignedMessage, NetworkConfig, WalletInfo, RialoProvider,
-  RialoNetwork, RialoChainId,
-  // REX
-  REXConfig, REXCapabilities, REXTransactionResult, REXPrivacyMode,
-  // SfS
-  SfSPosition, SfSCreateParams, SfSUpdateParams, SfSCreditBalance,
-  // Scan-to-Connect
-  ScanConnectSession, ScanConnectURI, ScanConnectStatus,
+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';
 ```
 
-## Migration from v3.0
+## Architecture Notes
 
-```diff
-// Imports unchanged
-import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
-
-// Hook usage unchanged
-const { connect, connected } = useWallet();
-
-// New in v3.1:
-+ import { useREX, useSfS, useScanConnect } from '@cookill/wallet-adapter/react';
-+ const { submitREXTransaction } = useREX();
-+ const { sendGasless, hasCredits } = useSfS();
-+ const { generateQR, scanURI } = useScanConnect();
-
-// WalletProvider now supports scanConnectRelay prop
-+ <WalletProvider scanConnectRelay="wss://relay.rialo.io">
-
-// ConnectButton now shows feature badges
-+ <ConnectButton showFeatures={true} />
-
-// Connect modal now has "Scan to Connect" tab built-in
-```
+- 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
 

package/dist/index.d.cts

@@ -190,6 +190,7 @@ interface ScanConnectURI {
     /** Parsed session info */
     session: ScanConnectSession;
 }
+type ScanConnectStatus = 'idle' | 'generating' | 'waiting' | 'scanned' | 'approving' | 'connected' | 'expired' | 'rejected' | 'error';
 interface WalletInfo {
     id: string;
     name: string;
@@ -405,4 +406,4 @@ declare class SheepWallet {
     private _setupEvents;
 }
 
-export { type BalanceResult, NETWORKS, type NetworkConfig, type RialoChainId, type RialoNetwork, type RialoProvider, SheepWallet as RialoWallet, SheepWallet, type SignedMessage, type TransactionRequest, type TransactionResult, type WalletAccount, type WalletEventType, type WalletInfo, SheepWallet as default, formatAddress, formatBalance, fromChainId, getProvider, getProvider as getRialoProvider, isInstalled, isInstalled as isRialoInstalled, isValidAddress, normalizeAccounts, parseBalance, toChainId, waitForProvider, waitForProvider as waitForRialoProvider, withTimeout };
+export { type BalanceResult, NETWORKS, type NetworkConfig, type REXAccessPolicy, type REXCapabilities, type REXConfig, type REXPrivacyMode, type REXTransactionResult, type RialoChainId, type RialoNetwork, type RialoProvider, SheepWallet as RialoWallet, type ScanConnectDAppMetadata, type ScanConnectSession, type ScanConnectStatus, type ScanConnectURI, type ScanConnectWalletMetadata, type SfSCreateParams, type SfSCreditBalance, type SfSPosition, type SfSUpdateParams, SheepWallet, type SignedMessage, type TransactionRequest, type TransactionResult, type WalletAccount, type WalletEventType, type WalletInfo, SheepWallet as default, formatAddress, formatBalance, fromChainId, getProvider, getProvider as getRialoProvider, isInstalled, isInstalled as isRialoInstalled, isValidAddress, normalizeAccounts, parseBalance, toChainId, waitForProvider, waitForProvider as waitForRialoProvider, withTimeout };

package/dist/index.d.ts

@@ -190,6 +190,7 @@ interface ScanConnectURI {
     /** Parsed session info */
     session: ScanConnectSession;
 }
+type ScanConnectStatus = 'idle' | 'generating' | 'waiting' | 'scanned' | 'approving' | 'connected' | 'expired' | 'rejected' | 'error';
 interface WalletInfo {
     id: string;
     name: string;
@@ -405,4 +406,4 @@ declare class SheepWallet {
     private _setupEvents;
 }
 
-export { type BalanceResult, NETWORKS, type NetworkConfig, type RialoChainId, type RialoNetwork, type RialoProvider, SheepWallet as RialoWallet, SheepWallet, type SignedMessage, type TransactionRequest, type TransactionResult, type WalletAccount, type WalletEventType, type WalletInfo, SheepWallet as default, formatAddress, formatBalance, fromChainId, getProvider, getProvider as getRialoProvider, isInstalled, isInstalled as isRialoInstalled, isValidAddress, normalizeAccounts, parseBalance, toChainId, waitForProvider, waitForProvider as waitForRialoProvider, withTimeout };
+export { type BalanceResult, NETWORKS, type NetworkConfig, type REXAccessPolicy, type REXCapabilities, type REXConfig, type REXPrivacyMode, type REXTransactionResult, type RialoChainId, type RialoNetwork, type RialoProvider, SheepWallet as RialoWallet, type ScanConnectDAppMetadata, type ScanConnectSession, type ScanConnectStatus, type ScanConnectURI, type ScanConnectWalletMetadata, type SfSCreateParams, type SfSCreditBalance, type SfSPosition, type SfSUpdateParams, SheepWallet, type SignedMessage, type TransactionRequest, type TransactionResult, type WalletAccount, type WalletEventType, type WalletInfo, SheepWallet as default, formatAddress, formatBalance, fromChainId, getProvider, getProvider as getRialoProvider, isInstalled, isInstalled as isRialoInstalled, isValidAddress, normalizeAccounts, parseBalance, toChainId, waitForProvider, waitForProvider as waitForRialoProvider, withTimeout };