@cookill/wallet-adapter 2.5.4 → 3.1.0

package/README.md

@@ -1,48 +1,27 @@
-# @cookill/wallet-adapter v2.5.0
+# @cookill/wallet-adapter v3.1.0
 
 Official wallet adapter for **Sheep Wallet** on 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
+
 ## Installation
 
 ```bash
 npm install @cookill/wallet-adapter
+# or
+pnpm add @cookill/wallet-adapter
 ```
 
-## ⚠️ IMPORTANT: Vite Configuration
-
-**If you're using Vite**, you MUST add React deduplication to prevent "stuck connection" issues:
-
-```typescript
-// vite.config.ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import path from "path";
-
-export default defineConfig({
-  plugins: [react()],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-    // CRITICAL: Prevent duplicate React instances
-    dedupe: ["react", "react-dom", "react/jsx-runtime"],
-  },
-  optimizeDeps: {
-    include: ["react", "react-dom"],
-  },
-});
-```
-
-**Without this configuration**, the wallet modal may not open and connections will appear "stuck".
-
-## Quick Start
+## Quick Start (React)
 
 ```tsx
-import {
-  WalletProvider,
-  ConnectButton,
-  WalletErrorBoundary,
-} from '@cookill/wallet-adapter/react';
+import { WalletProvider, ConnectButton, WalletErrorBoundary } from '@cookill/wallet-adapter/react';
 
 function App() {
   return (
@@ -60,112 +39,206 @@ function App() {
 
 ### useWallet
 
-Main hook for wallet state and actions:
-
 ```tsx
 import { useWallet } from '@cookill/wallet-adapter/react';
 
 function MyComponent() {
   const {
-    // State
-    connected,           // boolean - is wallet connected
-    connecting,          // boolean - connection in progress
-    accounts,            // WalletAccount[] - all connected accounts
-    activeAccount,       // WalletAccount | null - primary account
-    network,             // 'mainnet' | 'testnet' | 'devnet' | 'localnet'
-    chainId,             // 'rialo:devnet' etc
-    balance,             // string | null (in kelvins)
-    error,               // Error | null
-    
-    // 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>
-    
+    connected, connecting, activeAccount, state, chainId, isInstalled,
+    connect, disconnect, switchNetwork, refreshBalance,
+    signMessage, signTransaction, sendTransaction, signAndSendTransaction,
+    // REX
+    getREXCapabilities, submitREXTransaction,
+    // SfS (Gasless)
+    sendGaslessTransaction, getSfSPositions, createSfSPosition, getSfSCredits,
     // Modal
-    isModalOpen,
-    openModal,
-    closeModal,
+    openModal, closeModal,
   } = useWallet();
+}
+```
+
+### Specialized 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 { 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);
+  };
+
+  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>
+  );
+}
+```
+
+### useSfS — Gasless Transactions (Stake-for-Service)
+
+```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);
+  };
 
   return (
     <div>
-      {connected ? (
-        <p>Connected: {activeAccount?.address}</p>
+      <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={openModal}>Connect</button>
+        <button onClick={handleGaslessSend}>Send (Gasless)</button>
       )}
     </div>
   );
 }
 ```
 
-### Convenience Hooks
+### useScanConnect — QR-based Cross-Device Pairing
 
 ```tsx
-// Check connection status
-const connected = useIsConnected();
+import { useScanConnect } from '@cookill/wallet-adapter/react';
 
-// Get active account
-const account = useActiveAccount();
+function ScanConnectDemo() {
+  const { scanURI, status, generateQR, approveSession, rejectSession } = useScanConnect();
 
-// Get all accounts
-const accounts = useAccounts();
+  return (
+    <div>
+      <button onClick={generateQR}>Generate QR</button>
+      {scanURI && (
+        <div>
+          <p>Scan this URI: {scanURI.uri}</p>
+          <p>Status: {status}</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
 
-// Balance with formatting
-const { balance, formatted, refresh } = useBalance();
-// formatted: "1,234.5678 RLO"
+## Vanilla JavaScript
 
-// Network info
-const { network, chainId, config } = useNetwork();
+```typescript
+import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';
 
-// Switch network with loading state
-const { switchNetwork, switching, error } = useSwitchNetwork();
+const wallet = new SheepWallet();
 
-// Connect with modal
-const { connect, connecting, isInstalled, error } = useConnectWallet();
+// Standard connect
+const accounts = await wallet.connect();
 
-// Disconnect
-const { disconnect, connected } = useDisconnectWallet();
+// REX — Confidential transaction
+const rexResult = await wallet.submitREXTransaction({
+  to: 'RecipientAddress...',
+  value: '1000000000',
+  rex: { confidential: true, privacyMode: 'auto' },
+});
+
+// SfS — Create staking position for gasless TX
+await wallet.createSfSPosition({
+  amount: '10000000000',
+  validator: 'ValidatorAddr...',
+  routingFraction: 0.5,
+});
 
-// Sign message with loading state
-const { sign, signing, signature, error } = useSignMessage();
+// SfS — Send gasless transaction
+const result = await wallet.sendGaslessTransaction({
+  to: 'RecipientAddress...',
+  value: '1000000000',
+});
 
-// Send transaction with loading state
-const { send, sending, txHash, error, reset } = useSendTransaction();
+// Scan-to-Connect — Generate session QR
+const session = await wallet.createScanSession();
+console.log('QR URI:', session.uri);
 ```
 
 ## Components
 
 ### ConnectButton
 
-Pre-styled connect button:
-
 ```tsx
 <ConnectButton
   connectLabel="Connect Wallet"
   disconnectLabel="Disconnect"
   showAddress={true}
   showBalance={false}
-  className="my-button"
+  showFeatures={true}    // Show REX/SfS badges
 />
 ```
 
 ### WalletProvider
 
-Wrap your app to provide wallet context:
-
 ```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)}
@@ -175,150 +248,156 @@ Wrap your app to provide wallet context:
 </WalletProvider>
 ```
 
-### WalletErrorBoundary
+The connect modal includes two tabs:
+- **Extension**: Direct browser extension connection
+- **Scan to Connect**: Bidirectional QR code (show QR or scan QR)
 
-Prevents blank screens from uncaught errors:
+## Networks
 
-```tsx
-<WalletErrorBoundary
-  fallback={<div>Something went wrong</div>}
-  onError={(error, errorInfo) => logError(error)}
->
-  <YourComponent />
-</WalletErrorBoundary>
-```
+| 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   | ❌  | ❌  |
 
-## Vanilla JavaScript (Non-React)
+## REX (Rialo Extended Execution)
 
-```typescript
-import { RialoWallet, isRialoInstalled, formatBalance } from '@cookill/wallet-adapter';
+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
 
-// Check if extension is installed
-if (!isRialoInstalled()) {
-  console.log('Please install Sheep Wallet');
-  window.open('https://rialo.io/wallet', '_blank');
-}
+### 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
+```
 
-// Create wallet instance
-const wallet = new RialoWallet();
+### REX Config Options
 
-// Connect
-const accounts = await wallet.connect();
-console.log('Connected:', accounts[0].address);
+```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
+  };
+}
+```
 
-// Get balance
-const balance = await wallet.getBalance();
-console.log('Balance:', formatBalance(balance), 'RLO');
+## SfS (Stake-for-Service)
 
-// Sign message
-const signed = await wallet.signMessage('Hello!');
-console.log('Signature:', signed.signature);
+Stake-for-Service converts staking yield into service credits that pay for gas automatically.
 
-// Send transaction
-const tx = await wallet.signAndSendTransaction({
-  to: 'RecipientAddress...',
-  value: '1000000000', // 1 RLO in kelvins
-});
-console.log('TX Hash:', tx.hash);
+### How It Works
 
-// Listen to events
-wallet.on('disconnect', () => {
-  console.log('Wallet disconnected');
-});
+```
+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
 ```
 
-## Direct Provider Access
-
-Access `window.rialo` directly:
+### SfS Types
 
 ```typescript
-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',
-  });
+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 SfSCreditBalance {
+  available: string;
+  usedThisEpoch: string;
+  totalEarned: string;
+  estimatedPerEpoch: string;
 }
 ```
 
-## Networks
+## Scan-to-Connect
+
+Connect wallet on one device to dApp on another via QR code.
+
+### Bidirectional Flow
 
-| 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   |
+**dApp → Wallet**: dApp shows QR, user scans with mobile Sheep Wallet
+**Wallet → dApp**: Wallet shows QR (Settings → Show Connect QR), dApp scans
+
+### URI Format
+
+```
+rialo-wc://{sessionId}?relay={relayUrl}&topic={topic}&networks=devnet
+```
 
 ## Utilities
 
 ```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'
-  isRialoInstalled,     // () => boolean
-  getRialoProvider,     // () => RialoProvider | undefined
-  waitForRialoProvider, // (timeout?) => Promise<RialoProvider>
-  NETWORKS,             // Network configurations
+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
 
-Full TypeScript support with all types exported:
-
 ```typescript
 import type {
-  WalletAccount,
-  TransactionRequest,
-  TransactionResult,
-  SignedMessage,
-  BalanceResult,
-  NetworkConfig,
-  WalletInfo,
-  RialoProvider,
-  RialoNetwork,
-  RialoChain,
+  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,
 } from '@cookill/wallet-adapter';
 ```
 
-## Troubleshooting
-
-### Modal not opening / Connection stuck
+## Migration from v3.0
 
-1. **Add Vite dedupe config** (see top of this README)
-2. Clear `node_modules` and reinstall: `rm -rf node_modules && npm install`
-3. Check console for errors
+```diff
+// Imports unchanged
+import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
 
-### Extension not detected
+// Hook usage unchanged
+const { connect, connected } = useWallet();
 
-1. Make sure Sheep Wallet extension is installed
-2. Refresh the page after installing
-3. Check if `window.rialo` exists in browser console
+// New in v3.1:
++ import { useREX, useSfS, useScanConnect } from '@cookill/wallet-adapter/react';
++ const { submitREXTransaction } = useREX();
++ const { sendGasless, hasCredits } = useSfS();
++ const { generateQR, scanURI } = useScanConnect();
 
-### Transaction fails
+// WalletProvider now supports scanConnectRelay prop
++ <WalletProvider scanConnectRelay="wss://relay.rialo.io">
 
-1. Ensure wallet is unlocked
-2. Check you have sufficient balance
-3. Verify recipient address is valid
+// ConnectButton now shows feature badges
++ <ConnectButton showFeatures={true} />
 
-## Changelog
-
-### v2.5.0
-- Fixed bundling to properly externalize React
-- Added WalletErrorBoundary component
-- Added loading states (ApprovalPending, ConnectionStatus)
-- Improved modal with singleton pattern
-- Updated Vite configuration requirements
-
-### v2.4.x
-- Initial public release
+// Connect modal now has "Scan to Connect" tab built-in
+```
 
 ## License
 
-MIT
+MIT