@karn_lat/protocol-sdk 0.1.0-alpha.1

package/src/utils/polling.ts

@@ -0,0 +1,193 @@
+import { rpc } from '@stellar/stellar-sdk';
+
+export interface PollingOptions {
+  /**
+   * Maximum number of polling attempts
+   * @default 30
+   */
+  maxAttempts?: number;
+
+  /**
+   * Interval between polling attempts in milliseconds
+   * @default 1000 (1 second)
+   */
+  intervalMs?: number;
+
+  /**
+   * Whether to use exponential backoff
+   * @default true
+   */
+  exponentialBackoff?: boolean;
+
+  /**
+   * Maximum interval between attempts when using exponential backoff (ms)
+   * @default 10000 (10 seconds)
+   */
+  maxIntervalMs?: number;
+
+  /**
+   * Callback function called on each polling attempt
+   */
+  onAttempt?: (attempt: number, status: string) => void;
+}
+
+export interface PollingResult<T> {
+  /**
+   * Whether the operation succeeded
+   */
+  success: boolean;
+
+  /**
+   * The final transaction response (if successful)
+   */
+  response?: T;
+
+  /**
+   * Error message (if failed)
+   */
+  error?: string;
+
+  /**
+   * Number of attempts made
+   */
+  attempts: number;
+
+  /**
+   * Total time elapsed in milliseconds
+   */
+  elapsedMs: number;
+}
+
+/**
+ * Poll for a transaction result with exponential backoff
+ *
+ * @param server - Stellar RPC server instance
+ * @param transactionHash - The transaction hash to poll for
+ * @param options - Polling configuration options
+ * @returns Promise resolving to polling result
+ */
+
+export async function pollTransactionResult(
+  server: rpc.Server,
+  transactionHash: string,
+  options: PollingOptions = {}
+): Promise<PollingResult<rpc.Api.GetTransactionResponse>> {
+  const {
+    maxAttempts = 30,
+    intervalMs = 1000,
+    exponentialBackoff = true,
+    maxIntervalMs = 10000,
+    onAttempt,
+  } = options;
+
+  const startTime = Date.now();
+  let attempts = 0;
+  let currentInterval = intervalMs;
+
+  while (attempts < maxAttempts) {
+    attempts++;
+
+    try {
+      const response = await server.getTransaction(transactionHash);
+
+      const status = response.status as string;
+      onAttempt?.(attempts, status);
+
+      // SUCCESS - Transaction confirmed
+      if (response.status === rpc.Api.GetTransactionStatus.SUCCESS) {
+        return {
+          success: true,
+          response,
+          attempts,
+          elapsedMs: Date.now() - startTime,
+        };
+      }
+
+      // FAILED - Transaction failed permanently
+      if (response.status === rpc.Api.GetTransactionStatus.FAILED) {
+        return {
+          success: false,
+          error: `Transaction failed: ${JSON.stringify(response)}`,
+          attempts,
+          elapsedMs: Date.now() - startTime,
+        };
+      }
+
+      // NOT_FOUND - Still pending, continue polling
+      if (response.status === rpc.Api.GetTransactionStatus.NOT_FOUND) {
+        // Wait before next attempt
+        if (attempts < maxAttempts) {
+          await sleep(currentInterval);
+
+          // Exponential backoff: double interval each time, up to max
+          if (exponentialBackoff) {
+            currentInterval = Math.min(currentInterval * 2, maxIntervalMs);
+          }
+        }
+        continue;
+      }
+
+      // Unknown status (shouldn't reach here, but handle gracefully)
+      return {
+        success: false,
+        error: `Unknown transaction status: ${status}`,
+        attempts,
+        elapsedMs: Date.now() - startTime,
+      };
+    } catch (err) {
+      // Network error or RPC error
+      if (attempts >= maxAttempts) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : 'Unknown error during polling',
+          attempts,
+          elapsedMs: Date.now() - startTime,
+        };
+      }
+
+      // Retry on error
+      await sleep(currentInterval);
+      if (exponentialBackoff) {
+        currentInterval = Math.min(currentInterval * 2, maxIntervalMs);
+      }
+    }
+  }
+
+  // Max attempts reached
+  return {
+    success: false,
+    error: `Transaction polling timed out after ${attempts} attempts (${Date.now() - startTime}ms)`,
+    attempts,
+    elapsedMs: Date.now() - startTime,
+  };
+}
+
+/**
+ * Wait for a specified duration
+ *
+ * @param ms - Duration to wait in milliseconds
+ * @returns Promise that resolves after the duration
+ */
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Poll for multiple transactions in parallel
+ *
+ * @param server - Stellar RPC server instance
+ * @param transactionHashes - Array of transaction hashes to poll
+ * @param options - Polling configuration options
+ * @returns Promise resolving to array of polling results
+ */
+
+export async function pollMultipleTransactions(
+  server: rpc.Server,
+  transactionHashes: string[],
+  options: PollingOptions = {}
+): Promise<PollingResult<rpc.Api.GetTransactionResponse>[]> {
+  return Promise.all(
+    transactionHashes.map((hash) => pollTransactionResult(server, hash, options))
+  );
+}

package/src/utils/simulation.ts

@@ -0,0 +1,136 @@
+import { rpc } from '@stellar/stellar-sdk';
+import type { AssembledTransaction } from '@stellar/stellar-sdk/contract';
+
+export interface SimulationResult<T> {
+  /**
+   * Whether the simulation succeeded
+   */
+  success: boolean;
+
+  /**
+   * The decoded result value (if successful)
+   */
+  result?: T;
+
+  /**
+   * Error message (if failed)
+   */
+  error?: string;
+
+  /**
+   * Estimated resource fees in stroops
+   */
+  fee?: number;
+
+  /**
+   * Raw simulation response from RPC
+   */
+  raw?: rpc.Api.SimulateTransactionResponse;
+}
+
+/**
+ * Simulate a transaction and extract the result
+ *
+ * @param tx - AssembledTransaction to simulate
+ * @returns Promise resolving to simulation result
+ */
+export async function simulateTransaction<T>(
+  tx: AssembledTransaction<T>
+): Promise<SimulationResult<T>> {
+  try {
+    // AssembledTransaction has `result` property if already simulated
+    // The simulation happens automatically by default in generated clients
+
+    // Try to get the result directly (already simulated)
+    if (tx.result !== undefined) {
+      return {
+        success: true,
+        result: tx.result,
+        fee: 0, // Fee info not available without raw simulation
+      };
+    }
+
+    // If result not available, transaction likely failed or wasn't simulated
+    return {
+      success: false,
+      error: 'Transaction simulation not available',
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : 'Unknown simulation error',
+    };
+  }
+}
+
+/**
+ * Check if a transaction needs restoration (contract data needs to be restored)
+ *
+ * @param tx - AssembledTransaction to check
+ * @returns Promise resolving to boolean indicating if restoration is needed
+ */
+export async function needsRestoration<T>(
+  tx: AssembledTransaction<T>
+): Promise<boolean> {
+  // For generated clients, restoration info is not directly accessible
+  // Return false as default - users should check simulation errors
+  return false;
+}
+
+/**
+ * Estimate the total fee for a transaction (base fee + resource fee)
+ *
+ * @param tx - AssembledTransaction to estimate
+ * @returns Promise resolving to estimated fee in stroops
+ */
+export async function estimateFee<T>(
+  tx: AssembledTransaction<T>
+): Promise<number> {
+  // Return a default estimate since simulation details not directly accessible
+  // Users should check actual fee after building transaction
+  return 100000; // Default estimate: 100,000 stroops (~0.01 XLM)
+}
+
+/**
+ * Simulate multiple transactions in parallel
+ *
+ * @param transactions - Array of AssembledTransactions to simulate
+ * @returns Promise resolving to array of simulation results
+ */
+export async function simulateMultiple<T>(
+  transactions: AssembledTransaction<T>[]
+): Promise<SimulationResult<T>[]> {
+  return Promise.all(transactions.map((tx) => simulateTransaction(tx)));
+}
+
+/**
+ * Extract error details from a failed simulation
+ *
+ * @param simulation - The simulation response
+ * @returns Human-readable error message
+ */
+export function getSimulationError(
+  simulation: rpc.Api.SimulateTransactionResponse
+): string {
+  if (rpc.Api.isSimulationError(simulation)) {
+    return simulation.error || 'Unknown simulation error';
+  }
+
+  if (rpc.Api.isSimulationRestore(simulation)) {
+    return 'Contract requires restoration';
+  }
+
+  return 'Simulation did not succeed';
+}
+
+/**
+ * Check if a simulation result indicates success
+ *
+ * @param simulation - The simulation response
+ * @returns True if simulation succeeded
+ */
+export function isSimulationSuccess(
+  simulation: rpc.Api.SimulateTransactionResponse
+): boolean {
+  return rpc.Api.isSimulationSuccess(simulation);
+}

package/src/wallet/WalletManager.ts

@@ -0,0 +1,360 @@
+/**
+ * Manages wallet selection, connection state, and provides unified API
+ * for interacting with any supported Stellar wallet.
+ */
+
+import {
+  WalletAdapter,
+  WalletType,
+  WalletState,
+  WalletMetadata,
+  WalletConnection,
+  WalletEvent,
+  WalletEventPayload,
+  WalletEventListener,
+  SignTransactionOptions,
+  WalletError,
+  WalletErrorCode,
+} from './types.js';
+
+import { FreighterAdapter } from './adapters/FreighterAdapter.js';
+import { AlbedoAdapter } from './adapters/AlbedoAdapter.js';
+import { LobstrAdapter } from './adapters/LobstrAdapter.js';
+import { XBullAdapter } from './adapters/xBullAdapter.js';
+import { RabetAdapter } from './adapters/RabetAdapter.js';
+
+export class WalletManager {
+  private adapters: Map<WalletType, WalletAdapter>;
+  private currentAdapter: WalletAdapter | null = null;
+  private state: WalletState;
+  private eventListeners: Map<WalletEvent, Set<WalletEventListener>>;
+
+  constructor() {
+    // Initialize all wallet adapters
+    this.adapters = new Map([
+      [WalletType.FREIGHTER, new FreighterAdapter() as WalletAdapter],
+      [WalletType.ALBEDO, new AlbedoAdapter() as WalletAdapter],
+      [WalletType.LOBSTR, new LobstrAdapter() as WalletAdapter],
+      [WalletType.XBULL, new XBullAdapter() as WalletAdapter],
+      [WalletType.RABET, new RabetAdapter() as WalletAdapter],
+    ]);
+
+    // Initialize state
+    this.state = {
+      isConnected: false,
+      address: null,
+      walletType: null,
+      isConnecting: false,
+      error: null,
+      walletName: null,
+    };
+
+    // Initialize event listeners
+    this.eventListeners = new Map([
+      [WalletEvent.CONNECT, new Set()],
+      [WalletEvent.DISCONNECT, new Set()],
+      [WalletEvent.ACCOUNT_CHANGED, new Set()],
+      [WalletEvent.NETWORK_CHANGED, new Set()],
+    ]);
+
+    // Try to restore previous connection from localStorage
+    this.restoreConnection();
+  }
+
+  /**
+   * Get all available (installed) wallets
+   */
+  async getAvailableWallets(): Promise<WalletMetadata[]> {
+    const available: WalletMetadata[] = [];
+
+    for (const adapter of this.adapters.values()) {
+      if (await adapter.isAvailable()) {
+        available.push(adapter.metadata);
+      }
+    }
+
+    return available;
+  }
+
+  /**
+   * Get all wallet metadata (including unavailable wallets)
+   */
+  getAllWallets(): WalletMetadata[] {
+    return Array.from(this.adapters.values()).map((adapter) => adapter.metadata);
+  }
+
+  /**
+   * Get current wallet state
+   */
+  getState(): WalletState {
+    return { ...this.state };
+  }
+
+  /**
+   * Connect to a specific wallet
+   */
+  async connect(walletType: WalletType): Promise<WalletConnection> {
+    const adapter = this.adapters.get(walletType);
+
+    if (!adapter) {
+      throw new WalletError(
+        `Wallet type ${walletType} is not supported`,
+        WalletErrorCode.UNSUPPORTED_METHOD
+      );
+    }
+
+    // Check if wallet is available
+    const isAvailable = await adapter.isAvailable();
+    if (!isAvailable) {
+      throw new WalletError(
+        `${adapter.metadata.name} is not installed`,
+        WalletErrorCode.NOT_INSTALLED,
+        walletType
+      );
+    }
+
+    // Disconnect any existing connection
+    if (this.currentAdapter) {
+      await this.disconnect();
+    }
+
+    // Update state
+    this.state.isConnecting = true;
+    this.state.error = null;
+
+    try {
+      // Connect to wallet
+      const address = await adapter.connect();
+
+      // Update state
+      this.currentAdapter = adapter;
+      this.state.isConnected = true;
+      this.state.address = address;
+      this.state.walletType = walletType;
+      this.state.walletName = adapter.metadata.name;
+      this.state.isConnecting = false;
+
+      // Save to localStorage for auto-reconnect
+      this.saveConnection(walletType, address);
+
+      // Emit connect event
+      this.emitEvent(WalletEvent.CONNECT, { walletType, address });
+
+      return {
+        walletType,
+        address,
+        adapter,
+      };
+    } catch (error: any) {
+      this.state.isConnecting = false;
+      this.state.error = error.message;
+
+      if (error instanceof WalletError) {
+        throw error;
+      }
+
+      throw new WalletError(
+        `Failed to connect to ${adapter.metadata.name}: ${error.message}`,
+        WalletErrorCode.UNKNOWN_ERROR,
+        walletType
+      );
+    }
+  }
+
+  /**
+   * Disconnect from current wallet
+   */
+  async disconnect(): Promise<void> {
+    if (!this.currentAdapter) {
+      return;
+    }
+
+    const walletType = this.state.walletType;
+
+    try {
+      await this.currentAdapter.disconnect();
+    } catch (error) {
+      // Ignore disconnect errors
+      console.warn('Error during disconnect:', error);
+    }
+
+    // Clear state
+    this.currentAdapter = null;
+    this.state.isConnected = false;
+    this.state.address = null;
+    this.state.walletType = null;
+    this.state.walletName = null;
+    this.state.error = null;
+
+    // Clear localStorage
+    this.clearConnection();
+
+    // Emit disconnect event
+    if (walletType) {
+      this.emitEvent(WalletEvent.DISCONNECT, { walletType });
+    }
+  }
+
+  /**
+   * Get current connected address
+   */
+  async getAddress(): Promise<string | null> {
+    if (!this.currentAdapter) {
+      return null;
+    }
+
+    return await this.currentAdapter.getAddress();
+  }
+
+  /**
+   * Check if wallet is connected
+   */
+  async isConnected(): Promise<boolean> {
+    if (!this.currentAdapter) {
+      return false;
+    }
+
+    return await this.currentAdapter.isConnected();
+  }
+
+  /**
+   * Sign a transaction with current wallet
+   */
+  async signTransaction(
+    xdr: string,
+    options?: SignTransactionOptions
+  ): Promise<string> {
+    if (!this.currentAdapter) {
+      throw new WalletError(
+        'No wallet connected',
+        WalletErrorCode.NOT_CONNECTED
+      );
+    }
+
+    return await this.currentAdapter.signTransaction(xdr, options);
+  }
+
+  /**
+   * Sign a message (if supported by wallet)
+   */
+  async signMessage(message: string): Promise<string> {
+    if (!this.currentAdapter) {
+      throw new WalletError(
+        'No wallet connected',
+        WalletErrorCode.NOT_CONNECTED
+      );
+    }
+
+    if (!this.currentAdapter.signMessage) {
+      throw new WalletError(
+        `${this.state.walletName} does not support message signing`,
+        WalletErrorCode.UNSUPPORTED_METHOD,
+        this.state.walletType || undefined
+      );
+    }
+
+    return await this.currentAdapter.signMessage(message);
+  }
+
+  /**
+   * Get current network (if supported by wallet)
+   */
+  async getNetwork(): Promise<string> {
+    if (!this.currentAdapter) {
+      throw new WalletError(
+        'No wallet connected',
+        WalletErrorCode.NOT_CONNECTED
+      );
+    }
+
+    if (!this.currentAdapter.getNetwork) {
+      throw new WalletError(
+        `${this.state.walletName} does not support network detection`,
+        WalletErrorCode.UNSUPPORTED_METHOD,
+        this.state.walletType || undefined
+      );
+    }
+
+    return await this.currentAdapter.getNetwork();
+  }
+
+  /**
+   * Add event listener
+   */
+  on(event: WalletEvent, listener: WalletEventListener): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.add(listener);
+    }
+  }
+
+  /**
+   * Remove event listener
+   */
+  off(event: WalletEvent, listener: WalletEventListener): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+  }
+
+  /**
+   * Emit event to all listeners
+   */
+  private emitEvent(event: WalletEvent, payload: WalletEventPayload): void {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.forEach((listener) => listener(payload));
+    }
+  }
+
+  /**
+   * Save connection to localStorage for auto-reconnect
+   */
+  private saveConnection(walletType: WalletType, address: string): void {
+    if (typeof window === 'undefined') return;
+
+    try {
+      localStorage.setItem(
+        'karn_wallet_connection',
+        JSON.stringify({ walletType, address })
+      );
+    } catch (error) {
+      console.warn('Failed to save wallet connection:', error);
+    }
+  }
+
+  /**
+   * Clear connection from localStorage
+   */
+  private clearConnection(): void {
+    if (typeof window === 'undefined') return;
+
+    try {
+      localStorage.removeItem('karn_wallet_connection');
+    } catch (error) {
+      console.warn('Failed to clear wallet connection:', error);
+    }
+  }
+
+  /**
+   * Restore previous connection from localStorage
+   */
+  private async restoreConnection(): Promise<void> {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const saved = localStorage.getItem('karn_wallet_connection');
+      if (!saved) return;
+
+      const { walletType } = JSON.parse(saved);
+
+      // Try to reconnect silently
+      await this.connect(walletType);
+    } catch (error) {
+      // Silent fail - user can manually reconnect
+      console.debug('Failed to restore wallet connection:', error);
+      this.clearConnection();
+    }
+  }
+}