@cookill/wallet-adapter 3.0.0 → 3.1.0

package/README.md

@@ -1,13 +1,14 @@
-# @cookill/wallet-adapter v3.0.0
+# @cookill/wallet-adapter v3.1.0
 
 Official wallet adapter for **Sheep Wallet** on Rialo blockchain.
 
-## 🚀 What's New in v3.0
+## 🚀 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
-- **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
+- **Silent auto-connect**: Uses `checkSession()` for session restoration
 
 ## Installation
 
@@ -15,8 +16,6 @@ Official wallet adapter for **Sheep Wallet** on Rialo blockchain.
 npm install @cookill/wallet-adapter
 # or
 pnpm add @cookill/wallet-adapter
-# or
-yarn add @cookill/wallet-adapter
 ```
 
 ## Quick Start (React)
@@ -45,40 +44,16 @@ 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>
-    
+    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,
+    openModal, closeModal,
   } = useWallet();
-
-  return (
-    <div>
-      {connected ? (
-        <p>Connected: {activeAccount?.address}</p>
-      ) : (
-        <button onClick={connect}>Connect</button>
-      )}
-    </div>
-  );
 }
 ```
 
@@ -90,76 +65,157 @@ const { connect, connecting, isInstalled, error } = useConnectWallet();
 const { disconnect, connected } = useDisconnectWallet();
 const connected = useIsConnected();
 
-// Account
+// Account & Balance
 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();
+// Transactions (now includes gasless)
+const { sendTransaction, signAndSendTransaction, sendGaslessTransaction } = useSendTransaction();
+const { signMessage } = useSignMessage();
 ```
 
-## Vanilla JavaScript
+### useREX — Confidential Transactions
 
-```typescript
-import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';
+```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);
+  };
 
-// Check if installed
-if (!isInstalled()) {
-  console.log('Please install Sheep Wallet');
+  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>
+  );
 }
+```
 
-// Create wallet instance
-const wallet = new SheepWallet();
+### 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);
+  };
 
-// 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);
+  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>
+  );
 }
+```
 
-// Get balance
-const balance = await wallet.getBalance();
-console.log('Balance:', formatBalance(balance), 'RLO');
+### useScanConnect — QR-based Cross-Device Pairing
 
-// Sign message
-const signed = await wallet.signMessage('Hello!');
+```tsx
+import { useScanConnect } from '@cookill/wallet-adapter/react';
 
-// Send transaction
-const tx = await wallet.signAndSendTransaction({
-  to: 'RecipientAddress...',
-  value: '1000000000', // 1 RLO in kelvins
-});
-console.log('TX Hash:', tx.hash);
+function ScanConnectDemo() {
+  const { scanURI, status, generateQR, approveSession, rejectSession } = useScanConnect();
 
-// Silent session check (for auto-connect, never triggers approval)
-const existingSession = await wallet.checkSession();
-if (existingSession) {
-  console.log('Session restored:', existingSession[0].address);
+  return (
+    <div>
+      <button onClick={generateQR}>Generate QR</button>
+      {scanURI && (
+        <div>
+          <p>Scan this URI: {scanURI.uri}</p>
+          <p>Status: {status}</p>
+        </div>
+      )}
+    </div>
+  );
 }
 ```
 
-## Direct Provider Access
+## Vanilla JavaScript
 
 ```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',
-  });
-}
+import { SheepWallet, isInstalled, formatBalance } from '@cookill/wallet-adapter';
+
+const wallet = new SheepWallet();
+
+// Standard connect
+const accounts = await wallet.connect();
+
+// 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,
+});
+
+// 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);
 ```
 
 ## Components
@@ -172,8 +228,7 @@ if (window.rialo) {
   disconnectLabel="Disconnect"
   showAddress={true}
   showBalance={false}
-  className="my-button"
-  style={{ backgroundColor: '#6EB9A8' }}
+  showFeatures={true}    // Show REX/SfS badges
 />
 ```
 
@@ -181,9 +236,9 @@ if (window.rialo) {
 
 ```tsx
 <WalletProvider
-  network="devnet"        // 'mainnet' | 'testnet' | 'devnet' | 'localnet'
-  autoConnect={true}      // Restore session silently on mount
-  wallets={[customWallet]} // Additional wallets to show
+  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)}
@@ -193,47 +248,102 @@ if (window.rialo) {
 </WalletProvider>
 ```
 
-### Error Boundary & Loading States
+The connect modal includes two tabs:
+- **Extension**: Direct browser extension connection
+- **Scan to Connect**: Bidirectional QR code (show QR or scan QR)
 
-```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()}
-/>
+## 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   | ❌  | ❌  |
+
+## REX (Rialo Extended Execution)
+
+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
 
-<LoadingSpinner size="md" color="#6EB9A8" />
+```
+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
+```
 
-<ConnectionStatus status="connecting" />
-<ConnectionStatus status="approving" message="Check your wallet" />
-<ConnectionStatus status="error" onRetry={() => connect()} />
+### REX Config Options
+
+```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
+  };
+}
 ```
 
-## Networks
+## SfS (Stake-for-Service)
+
+Stake-for-Service converts staking yield into service credits that pay for gas automatically.
+
+### How It Works
+
+```
+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
+```
+
+### SfS 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 SfSCreditBalance {
+  available: string;
+  usedThisEpoch: string;
+  totalEarned: string;
+  estimatedPerEpoch: string;
+}
+```
+
+## Scan-to-Connect
+
+Connect wallet on one device to dApp on another via QR code.
 
-| 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   |
+### Bidirectional Flow
+
+**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
 
@@ -243,11 +353,7 @@ import {
   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';
 ```
@@ -256,57 +362,40 @@ import {
 
 ```typescript
 import type {
-  WalletAccount,
-  TransactionRequest,
-  TransactionResult,
-  SignedMessage,
-  BalanceResult,
-  NetworkConfig,
-  WalletInfo,
-  RialoProvider,
-  RialoNetwork,
-  RialoChainId,
+  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
-
-### Connection hangs / freezes
-
-v3.0 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 not opening
-
-The `WalletProvider` renders the modal automatically. If you see issues:
-
-```tsx
-// Make sure you're inside WalletProvider
-const { openModal } = useWallet();
-openModal(); // This should work
-```
-
-## Migration from v2.x
+## Migration from v3.0
 
 ```diff
-// Imports are the same
+// Imports unchanged
 import { WalletProvider, ConnectButton } from '@cookill/wallet-adapter/react';
 
-// Hook usage is the same
+// Hook usage unchanged
 const { connect, connected } = useWallet();
 
-// Main changes:
-// - connect() now has 20s timeout built-in
-// - autoConnect uses checkSession() (silent, never triggers popup)
-// - New SheepWallet class for vanilla JS (replaces RialoWallet)
+// 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
 ```
 
 ## License