Error Handling

/**
 * Main Solana error class with structured error codes
 */
class SolanaError extends Error {
  /** Specific error code for programmatic handling */
  readonly code: SolanaErrorCode;
  /** Additional context information */
  readonly context?: ErrorContext;
  /** Original error that caused this error */
  readonly cause?: Error;
  
  constructor(code: SolanaErrorCode, message?: string, options?: {
    context?: ErrorContext;
    cause?: Error;
  });
}

/**
 * Union type of all possible error codes
 */
type SolanaErrorCode = 
  | RpcErrorCode
  | AddressErrorCode  
  | AccountErrorCode
  | TransactionErrorCode
  | CryptoErrorCode
  | CodecErrorCode
  | SignerErrorCode
  | InstructionErrorCode;

/**
 * Error context for additional debugging information
 */
interface ErrorContext {
  /** Human-readable context */
  [key: string]: unknown;
}

/**
 * RPC error codes (range: -32768 to -32000, 8100000-8190999)
 */
type RpcErrorCode =
  // JSON-RPC standard errors
  | -32700  // Parse error
  | -32600  // Invalid request  
  | -32601  // Method not found
  | -32602  // Invalid params
  | -32603  // Internal error
  | -32000  // Server error
  // Solana RPC specific errors
  | 8100000  // RPC endpoint not available
  | 8100001  // RPC request timeout
  | 8100002  // RPC response parse error
  | 8100003  // RPC transport error
  | 8100004  // RPC rate limit exceeded
  | 8100005; // RPC invalid response format

/**
 * Check if error is an RPC error
 * @param error - Error to check
 * @returns True if error is RPC-related
 */
function isRpcError(error: unknown): error is SolanaError & { code: RpcErrorCode };

/**
 * Address error codes (range: 2800000-2800999)
 */
type AddressErrorCode =
  | 2800000  // Invalid address format
  | 2800001  // Address decode failed
  | 2800002  // PDA derivation failed
  | 2800003  // Invalid PDA seeds
  | 2800004  // PDA bump out of range
  | 2800005  // Address not on curve
  | 2800006; // Invalid seed length

/**
 * Check if error is an address error
 * @param error - Error to check
 * @returns True if error is address-related
 */
function isAddressError(error: unknown): error is SolanaError & { code: AddressErrorCode };

/**
 * Account error codes (range: 3230000-3230999)
 */
type AccountErrorCode =
  | 3230000  // Account not found
  | 3230001  // Account decode failed
  | 3230002  // Account data invalid
  | 3230003  // Account size mismatch
  | 3230004  // Account owner mismatch
  | 3230005  // Account not executable
  | 3230006; // Account rent exempt check failed

/**
 * Check if error is an account error
 * @param error - Error to check
 * @returns True if error is account-related
 */
function isAccountError(error: unknown): error is SolanaError & { code: AccountErrorCode };

/**
 * Crypto error codes (range: 3610000-3611050)
 */
type CryptoErrorCode =  
  | 3610000  // SubtleCrypto not available
  | 3610001  // Key generation failed
  | 3610002  // Invalid key format
  | 3610003  // Signature creation failed
  | 3610004  // Signature verification failed
  | 3610005  // Key derivation failed
  | 3610006; // Unsupported crypto operation

/**
 * Check if error is a crypto error
 * @param error - Error to check
 * @returns True if error is crypto-related
 */
function isCryptoError(error: unknown): error is SolanaError & { code: CryptoErrorCode };

/**
 * Transaction error codes (range: 5663000+, 7050000-7050999)
 */
type TransactionErrorCode =
  | 5663000  // Transaction build failed
  | 5663001  // Transaction compile failed
  | 5663002  // Transaction sign failed
  | 5663003  // Transaction send failed
  | 5663004  // Transaction confirmation failed
  | 7050000  // Blockhash expired
  | 7050001  // Fee payer insufficient funds
  | 7050002; // Transaction too large

/**
 * Check if error is a transaction error
 * @param error - Error to check
 * @returns True if error is transaction-related
 */
function isTransactionError(error: unknown): error is SolanaError & { code: TransactionErrorCode };

/**
 * Instruction error codes (range: 4128000+, 4615000-4615999)
 */
type InstructionErrorCode =
  | 4128000  // Invalid instruction
  | 4128001  // Instruction data invalid
  | 4128002  // Insufficient accounts
  | 4128003  // Account permission denied
  | 4615000  // Program execution failed
  | 4615001; // Custom program error

/**
 * Check if error is an instruction error
 * @param error - Error to check
 * @returns True if error is instruction-related
 */
function isInstructionError(error: unknown): error is SolanaError & { code: InstructionErrorCode };

/**
 * Signer error codes (range: 5508000-5508999)
 */
type SignerErrorCode =
  | 5508000  // Signer not found
  | 5508001  // Insufficient signers
  | 5508002  // Invalid signer
  | 5508003  // Signing failed
  | 5508004  // Multi-sig validation failed
  | 5508005; // Signer permission denied

/**
 * Check if error is a signer error
 * @param error - Error to check
 * @returns True if error is signer-related
 */
function isSignerError(error: unknown): error is SolanaError & { code: SignerErrorCode };

/**
 * Codec error codes (range: 8078000-8078999)
 */
type CodecErrorCode =
  | 8078000  // Encode failed
  | 8078001  // Decode failed
  | 8078002  // Invalid data format
  | 8078003  // Data size mismatch
  | 8078004  // Unsupported encoding
  | 8078005; // Codec not found

/**
 * Check if error is a codec error
 * @param error - Error to check
 * @returns True if error is codec-related
 */
function isCodecError(error: unknown): error is SolanaError & { code: CodecErrorCode };

/**
 * Create a Solana error with specific code
 * @param code - Error code
 * @param message - Error message
 * @param context - Additional context
 * @returns New SolanaError instance
 */
function createSolanaError(
  code: SolanaErrorCode,
  message?: string,
  context?: ErrorContext
): SolanaError;

/**
 * Wrap an existing error as SolanaError
 * @param error - Original error
 * @param code - Solana error code
 * @param context - Additional context
 * @returns Wrapped SolanaError
 */
function wrapError(
  error: Error,
  code: SolanaErrorCode,
  context?: ErrorContext
): SolanaError;

/**
 * Check if error is a SolanaError
 * @param error - Error to check
 * @returns True if error is SolanaError
 */
function isSolanaError(error: unknown): error is SolanaError;

/**
 * Get error category from error code
 * @param code - Error code
 * @returns Error category string
 */
function getErrorCategory(code: SolanaErrorCode): string;

/**
 * Get human-readable error description
 * @param code - Error code
 * @returns Error description
 */
function getErrorDescription(code: SolanaErrorCode): string;

import { 
  SolanaError,
  createSolanaError,
  isRpcError,
  isAddressError,
  wrapError
} from "@solana/web3.js";

// Create specific error
const rpcError = createSolanaError(
  8100001, // RPC timeout
  "RPC request timed out after 30 seconds",
  { 
    endpoint: "https://api.devnet.solana.com",
    method: "getAccountInfo",
    timeout: 30000 
  }
);

// Handle different error types
try {
  await someOperation();
} catch (error) {
  if (isRpcError(error)) {
    console.error("RPC error:", error.message);
    console.error("Endpoint:", error.context?.endpoint);
  } else if (isAddressError(error)) {
    console.error("Address error:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}

// Wrap existing errors
try {
  JSON.parse(invalidJson);
} catch (error) {
  throw wrapError(
    error as Error,
    8100002, // RPC response parse error
    { data: invalidJson }
  );
}

/**
 * Retry configuration
 */
interface RetryConfig {
  /** Maximum number of retries */
  maxRetries: number;
  /** Base delay in milliseconds */
  baseDelay: number;
  /** Exponential backoff multiplier */
  backoffMultiplier?: number;
  /** Maximum delay in milliseconds */
  maxDelay?: number;
  /** Error codes that should trigger retry */
  retryableErrors?: SolanaErrorCode[];
}

/**
 * Check if error is retryable
 * @param error - Error to check
 * @param retryableErrors - Error codes that can be retried
 * @returns True if error can be retried
 */
function isRetryableError(
  error: unknown,
  retryableErrors?: SolanaErrorCode[]
): boolean;

/**
 * Execute function with retry logic
 * @param fn - Function to execute
 * @param config - Retry configuration
 * @returns Promise resolving to function result
 */
function withRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig
): Promise<T>;

/**
 * Create error handler with logging
 * @param logger - Logging function
 * @returns Error handler function
 */
function createErrorHandler(
  logger?: (error: SolanaError) => void
): (error: unknown) => never;

/**
 * Extract stack trace from error
 * @param error - Error to analyze
 * @returns Stack trace information
 */
function getErrorStackTrace(error: Error): {
  stack: string[];
  source?: string;
  line?: number;
  column?: number;
};

/**
 * Format error for logging
 * @param error - Error to format
 * @param includeContext - Whether to include context
 * @returns Formatted error string
 */
function formatError(error: SolanaError, includeContext?: boolean): string;

/**
 * Create error with enhanced debugging info
 * @param code - Error code
 * @param message - Error message
 * @param options - Error options
 * @returns Enhanced error with debugging info
 */
function createDebugError(
  code: SolanaErrorCode,
  message: string,
  options?: {
    context?: ErrorContext;
    cause?: Error;
    captureStackTrace?: boolean;
  }
): SolanaError;

import {
  withRetry,
  isRetryableError,
  createErrorHandler,
  formatError
} from "@solana/web3.js";

// Retry RPC calls with exponential backoff
const retryConfig = {
  maxRetries: 3,
  baseDelay: 1000,
  backoffMultiplier: 2,
  maxDelay: 10000,
  retryableErrors: [8100001, 8100003, 8100004] // Timeout, transport, rate limit
};

const accountInfo = await withRetry(async () => {
  return await rpc.getAccountInfo(address).send();
}, retryConfig);

// Global error handler
const handleError = createErrorHandler((error) => {
  console.error("Solana Error:", formatError(error, true));
});

try {
  await riskyOperation();
} catch (error) {
  handleError(error);
}

// Check if specific operation should be retried
if (isRetryableError(error, [8100001, 8100003])) {
  console.log("Retrying operation...");
  await delay(1000);
  await retryOperation();
}