@cookill/wallet-adapter 2.5.4 → 3.1.0

package/dist/index.d.ts

@@ -1,12 +1,29 @@
 /**
- * @cookill/wallet-adapter v2.5.0
- * Sheep Wallet adapter for Rialo blockchain dApps
+ * @cookill/wallet-adapter v3.1.0
+ * Core type definitions
+ *
+ * Includes support for:
+ * - REX (Rialo Extended Execution) — confidential computation transactions
+ * - SfS (Stake-for-Service) — gasless transactions via staking yield
+ * - Scan-to-Connect — QR-based cross-device wallet pairing
  */
-type RialoChain = 'rialo:mainnet' | 'rialo:testnet' | 'rialo:devnet' | 'rialo:localnet';
 type RialoNetwork = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+type RialoChainId = `rialo:${RialoNetwork}`;
+interface NetworkConfig {
+    chainId: RialoChainId;
+    name: string;
+    rpcUrl: string;
+    wsUrl?: string;
+    explorerUrl?: string;
+    symbol: string;
+    decimals: number;
+    supportsREX?: boolean;
+    supportsSfS?: boolean;
+}
+declare const NETWORKS: Record<RialoNetwork, NetworkConfig>;
 interface WalletAccount {
     address: string;
-    publicKey?: Uint8Array | string;
+    publicKey?: string | Uint8Array;
     label?: string;
 }
 interface TransactionRequest {
@@ -14,12 +31,20 @@ interface TransactionRequest {
     value: string;
     data?: string;
     memo?: string;
+    /** If true, attempt to pay gas via Stake-for-Service credits */
+    gasless?: boolean;
+    /** REX confidential execution context */
+    rex?: REXConfig;
 }
 interface TransactionResult {
     hash: string;
     signature?: string;
     status: 'pending' | 'confirmed' | 'failed';
     blockNumber?: number;
+    /** Whether gas was paid via SfS credits */
+    gasless?: boolean;
+    /** REX execution proof if confidential */
+    rexProof?: string;
 }
 interface SignedMessage {
     signature: string;
@@ -29,17 +54,141 @@ interface SignedMessage {
 }
 interface BalanceResult {
     balance: string;
-    balanceKelvins: string;
     formatted: string;
 }
-interface NetworkConfig {
-    chainId: string;
+/**
+ * REX enables privacy-preserving computation on Rialo.
+ * Transactions can be executed confidentially using TEEs, MPC, or FHE
+ * without exposing inputs to the public blockchain.
+ */
+/** Privacy technology used for confidential computation */
+type REXPrivacyMode = 'tee' | 'mpc' | 'fhe' | 'auto';
+interface REXConfig {
+    /** Enable confidential execution */
+    confidential: boolean;
+    /** Privacy technology to use (default: 'auto' — protocol selects optimal) */
+    privacyMode?: REXPrivacyMode;
+    /** Encrypted inputs (base64-encoded ciphertext) */
+    encryptedInputs?: string;
+    /** REX program ID to execute */
+    programId?: string;
+    /** Whether output should remain encrypted for future computation */
+    keepEncrypted?: boolean;
+    /** Access control — who can decrypt the result */
+    accessPolicy?: REXAccessPolicy;
+}
+interface REXAccessPolicy {
+    /** Addresses allowed to decrypt the result */
+    allowedDecryptors: string[];
+    /** Expiry timestamp (ms) for access */
+    expiresAt?: number;
+}
+interface REXTransactionResult extends TransactionResult {
+    /** Attestation proof from TEE/MPC */
+    attestation?: string;
+    /** Encrypted output (if keepEncrypted was true) */
+    encryptedOutput?: string;
+    /** Public output (if computation produced public results) */
+    publicOutput?: string;
+}
+/** REX capabilities query result */
+interface REXCapabilities {
+    supported: boolean;
+    privacyModes: REXPrivacyMode[];
+    maxInputSize: number;
+    programs: string[];
+}
+/**
+ * SfS converts staking yield into service credits that automatically
+ * pay for network costs (gas, storage, scheduled executions).
+ * Users stake RLO, set a routing fraction, and the ServicePaymaster
+ * mints credits from their yield.
+ */
+interface SfSPosition {
+    /** Position ID */
+    id: string;
+    /** Staked principal in kelvins */
+    principal: string;
+    /** Validator/pool receiving the delegation */
+    validator: string;
+    /** Fraction of yield routed to service credits (0.0 - 1.0) */
+    routingFraction: number;
+    /** Current service credit balance */
+    creditBalance: string;
+    /** Estimated credits per epoch */
+    creditsPerEpoch: string;
+    /** Position status */
+    status: 'active' | 'pending' | 'closed';
+    /** Creation timestamp */
+    createdAt: number;
+}
+interface SfSCreateParams {
+    /** Amount of RLO to stake (in kelvins) */
+    amount: string;
+    /** Validator address to delegate to */
+    validator: string;
+    /** Fraction of yield to route to service credits (0.0 - 1.0) */
+    routingFraction: number;
+}
+interface SfSUpdateParams {
+    /** Position ID to update */
+    positionId: string;
+    /** New routing fraction (0.0 - 1.0) */
+    routingFraction?: number;
+}
+interface SfSCreditBalance {
+    /** Available service credits */
+    available: string;
+    /** Credits used this epoch */
+    usedThisEpoch: string;
+    /** Total credits earned */
+    totalEarned: string;
+    /** Estimated credits per epoch */
+    estimatedPerEpoch: string;
+}
+/**
+ * Enables connecting a wallet on one device to a dApp on another device
+ * via QR code scanning. Supports bidirectional flow:
+ * - dApp shows QR → wallet scans to connect
+ * - Wallet shows QR → dApp scans to connect
+ */
+interface ScanConnectSession {
+    /** Unique session identifier */
+    sessionId: string;
+    /** Session topic for relay */
+    topic: string;
+    /** Relay server URL */
+    relay: string;
+    /** Session encryption key (hex) */
+    symmetricKey: string;
+    /** Originator: 'dapp' or 'wallet' */
+    origin: 'dapp' | 'wallet';
+    /** dApp metadata */
+    dappMetadata?: ScanConnectDAppMetadata;
+    /** Wallet metadata */
+    walletMetadata?: ScanConnectWalletMetadata;
+    /** Requested chain IDs */
+    chains: RialoChainId[];
+    /** Expiry timestamp */
+    expiresAt: number;
+}
+interface ScanConnectDAppMetadata {
     name: string;
-    rpcUrl: string;
-    wsUrl?: string;
-    explorerUrl?: string;
-    symbol: string;
-    decimals: number;
+    url: string;
+    icon?: string;
+    description?: string;
+}
+interface ScanConnectWalletMetadata {
+    name: string;
+    icon?: string;
+    version?: string;
+}
+/** URI format for scan-to-connect QR codes */
+interface ScanConnectURI {
+    /** Full URI string (rialo-wc://...) */
+    uri: string;
+    /** Parsed session info */
+    session: ScanConnectSession;
 }
 interface WalletInfo {
     id: string;
@@ -47,94 +196,213 @@ interface WalletInfo {
     icon: string;
     installed?: boolean;
     downloadUrl?: string;
+    supportsREX?: boolean;
+    supportsSfS?: boolean;
+    supportsScanConnect?: boolean;
 }
-type WalletEvent = 'connect' | 'disconnect' | 'accountsChanged' | 'networkChanged' | 'chainChanged' | 'error';
-declare const NETWORKS: Record<RialoNetwork, NetworkConfig>;
+type WalletEventType = 'connect' | 'disconnect' | 'accountsChanged' | 'networkChanged' | 'chainChanged' | 'scanConnect' | 'sfsUpdate' | 'error';
 interface RialoProvider {
     isRialo: boolean;
     isSheepWallet?: boolean;
-    name?: string;
-    walletName?: string;
     version: string;
-    icon?: string;
     connect(options?: {
         silent?: boolean;
-    }): Promise<WalletAccount[]>;
+    }): Promise<Array<string | WalletAccount>>;
     disconnect(): Promise<void>;
     isConnected(): Promise<boolean>;
-    getAccounts(): Promise<WalletAccount[]>;
+    getAccounts(): Promise<Array<string | WalletAccount>>;
     signTransaction(tx: TransactionRequest): Promise<{
         signature: string;
-        signedTransaction?: string;
         rawTransaction?: string;
     }>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signAndSendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
-    signAllTransactions?(txs: TransactionRequest[]): Promise<{
-        signedTransactions: string[];
-    }>;
     signMessage(message: string | Uint8Array): Promise<SignedMessage>;
     getNetwork(): Promise<RialoNetwork>;
     switchNetwork(network: RialoNetwork): Promise<{
         success: boolean;
     }>;
-    getChainId(): Promise<string>;
     getBalance(address?: string): Promise<BalanceResult | string>;
-    on(event: WalletEvent, callback: (data: unknown) => void): () => void;
-    off?(event: WalletEvent, callback: (data: unknown) => void): void;
-    removeListener(event: WalletEvent, callback: (data: unknown) => void): void;
-    removeAllListeners(event?: WalletEvent): void;
-    utils?: {
-        isValidAddress(address: string): boolean;
-        formatAddress(address: string, chars?: number): string;
-    };
-    features?: string[];
-    supportsFeature?(feature: string): boolean;
-    readonly connected?: boolean;
-    readonly accounts?: WalletAccount[];
-    readonly address?: string | null;
-    readonly publicKey?: string | null;
-    readonly network?: RialoNetwork;
-    readonly chainId?: string;
-}
-declare function isRialoInstalled(): boolean;
-declare function getRialoProvider(): RialoProvider | undefined;
-declare function waitForRialoProvider(timeout?: number): Promise<RialoProvider | undefined>;
-declare class RialoWallet {
-    private provider;
+    getREXCapabilities?(): Promise<REXCapabilities>;
+    submitREXTransaction?(tx: TransactionRequest): Promise<REXTransactionResult>;
+    getSfSPositions?(): Promise<SfSPosition[]>;
+    createSfSPosition?(params: SfSCreateParams): Promise<SfSPosition>;
+    updateSfSPosition?(params: SfSUpdateParams): Promise<SfSPosition>;
+    closeSfSPosition?(positionId: string): Promise<{
+        success: boolean;
+    }>;
+    getSfSCredits?(): Promise<SfSCreditBalance>;
+    createScanSession?(origin: 'wallet'): Promise<ScanConnectURI>;
+    approveScanSession?(sessionId: string): Promise<WalletAccount[]>;
+    rejectScanSession?(sessionId: string): Promise<void>;
+    on(event: WalletEventType, callback: (data: unknown) => void): () => void;
+    removeListener(event: WalletEventType, callback: (data: unknown) => void): void;
+    removeAllListeners(event?: WalletEventType): void;
+}
+declare global {
+    interface Window {
+        rialo?: RialoProvider;
+    }
+}
+
+/**
+ * @cookill/wallet-adapter v3.0.0
+ * Provider detection and access utilities
+ *
+ * CRITICAL: All provider access is non-blocking and defensive
+ */
+
+/**
+ * Check if Rialo/Sheep Wallet is installed
+ * This is synchronous and never blocks
+ */
+declare function isInstalled(): boolean;
+/**
+ * Get the provider reference (synchronous)
+ * Returns undefined if not installed
+ */
+declare function getProvider(): RialoProvider | undefined;
+/**
+ * Wait for provider to become available
+ * Uses polling + event listener, with guaranteed timeout
+ *
+ * @param timeout Maximum time to wait in ms (default 3000)
+ */
+declare function waitForProvider(timeout?: number): Promise<RialoProvider | undefined>;
+/**
+ * Promise timeout wrapper
+ * Ensures promises never hang indefinitely
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+
+/**
+ * @cookill/wallet-adapter v3.0.0
+ * Utility functions
+ */
+
+/**
+ * Format address for display (truncated)
+ */
+declare function formatAddress(address: string, chars?: number): string;
+/**
+ * Format balance from kelvins to RLO
+ */
+declare function formatBalance(kelvins: string | bigint, decimals?: number): string;
+/**
+ * Parse RLO amount to kelvins
+ */
+declare function parseBalance(rlo: string | number): bigint;
+/**
+ * Validate Rialo address format
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Convert network name to chain ID
+ */
+declare function toChainId(network: RialoNetwork): RialoChainId;
+/**
+ * Extract network from chain ID
+ */
+declare function fromChainId(chainId: RialoChainId): RialoNetwork;
+/**
+ * Normalize account data (handles both string and object formats)
+ * CRITICAL: Extension can return either string[] or WalletAccount[]
+ */
+declare function normalizeAccounts(accounts: Array<string | WalletAccount>): WalletAccount[];
+
+/**
+ * @cookill/wallet-adapter v3.1.0
+ * Pure JavaScript wallet class (no React dependency)
+ *
+ * Supports:
+ * - Standard connect/disconnect/sign operations
+ * - REX (Rialo Extended Execution) confidential transactions
+ * - SfS (Stake-for-Service) gasless transactions
+ * - Scan-to-Connect QR-based pairing
+ *
+ * Usage:
+ *   const wallet = new SheepWallet();
+ *   if (!wallet.isInstalled) { ... prompt install ... }
+ *   const accounts = await wallet.connect();
+ */
+
+declare class SheepWallet {
+    private _provider;
     private _connected;
     private _accounts;
     private _network;
-    private _listeners;
+    private _cleanupFns;
     constructor();
-    private setupEvents;
     get isInstalled(): boolean;
     get connected(): boolean;
     get accounts(): WalletAccount[];
     get activeAccount(): WalletAccount | undefined;
+    get address(): string | undefined;
     get network(): RialoNetwork;
     get chainId(): string;
     connect(): Promise<WalletAccount[]>;
     disconnect(): Promise<void>;
+    checkSession(): Promise<WalletAccount[] | null>;
     signMessage(message: string): Promise<SignedMessage>;
     signTransaction(tx: TransactionRequest): Promise<string>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signAndSendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
+    /**
+     * Check if the connected wallet/network supports REX
+     */
+    getREXCapabilities(): Promise<REXCapabilities>;
+    /**
+     * Submit a confidential transaction via REX
+     * The transaction inputs are encrypted and executed in a TEE/MPC/FHE environment
+     */
+    submitREXTransaction(tx: TransactionRequest): Promise<REXTransactionResult>;
+    /**
+     * Send a gasless transaction using Stake-for-Service credits
+     * Automatically sets tx.gasless = true
+     */
+    sendGaslessTransaction(tx: Omit<TransactionRequest, 'gasless'>): Promise<TransactionResult>;
+    /**
+     * Get all Stake-for-Service positions for the connected account
+     */
+    getSfSPositions(): Promise<SfSPosition[]>;
+    /**
+     * Create a new Stake-for-Service position
+     * Stakes RLO and routes a fraction of yield to service credits
+     */
+    createSfSPosition(params: SfSCreateParams): Promise<SfSPosition>;
+    /**
+     * Update an existing SfS position (e.g., change routing fraction)
+     */
+    updateSfSPosition(params: SfSUpdateParams): Promise<SfSPosition>;
+    /**
+     * Close an SfS position and unstake
+     */
+    closeSfSPosition(positionId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get current SfS service credit balance
+     */
+    getSfSCredits(): Promise<SfSCreditBalance>;
+    /**
+     * Generate a scan-to-connect URI from the wallet side
+     * Returns a URI that can be displayed as QR code for dApps to scan
+     */
+    createScanSession(): Promise<ScanConnectURI>;
+    /**
+     * Approve a scan-to-connect session (after wallet scans dApp QR)
+     */
+    approveScanSession(sessionId: string): Promise<WalletAccount[]>;
+    /**
+     * Reject a scan-to-connect session
+     */
+    rejectScanSession(sessionId: string): Promise<void>;
     getBalance(address?: string): Promise<string>;
     switchNetwork(network: RialoNetwork): Promise<void>;
-    on(event: WalletEvent, callback: (data: unknown) => void): () => void;
-}
-declare function formatAddress(address: string, chars?: number): string;
-declare function formatBalance(kelvins: string | bigint, decimals?: number): string;
-declare function parseBalance(rlo: string | number): bigint;
-declare function isValidAddress(address: string): boolean;
-declare function toChainId(network: RialoNetwork): RialoChain;
-declare function fromChainId(chainId: RialoChain): RialoNetwork;
-declare global {
-    interface Window {
-        rialo?: RialoProvider;
-        Rialo?: RialoProvider;
-    }
+    on(event: string, callback: (data: unknown) => void): () => void;
+    destroy(): void;
+    private _ensureConnected;
+    private _setupEvents;
 }
 
-export { type BalanceResult, NETWORKS, type NetworkConfig, type RialoChain, type RialoNetwork, type RialoProvider, RialoWallet, type SignedMessage, type TransactionRequest, type TransactionResult, type WalletAccount, type WalletEvent, type WalletInfo, RialoWallet as default, formatAddress, formatBalance, fromChainId, getRialoProvider, isRialoInstalled, isValidAddress, parseBalance, toChainId, waitForRialoProvider };
+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 };