Error Handling

This guide covers error handling patterns in the SIP SDK, including error types, recovery strategies, debugging tips, and solutions to common issues.

Error Hierarchy

All SIP errors extend the base SIPError class, which provides machine-readable error codes, debugging context, and cause preservation.

Base Error Class

import { SIPError, ErrorCode, isSIPError } from '@sip-protocol/sdk'

try {
  await sip.execute(intent, quote)
} catch (e) {
  if (isSIPError(e)) {
    console.log(`Error ${e.code}: ${e.message}`)
    console.log('Context:', e.context)
    if (e.cause) console.log('Caused by:', e.cause)
  }
}

All SIP errors include:

• code: Machine-readable error code (e.g., SIP_2001)
• message: Human-readable description
• context: Additional debugging information
• cause: Original error if wrapped
• timestamp: When the error occurred

Error Types

| Error Class | Description | Use Case | |------------|-------------|----------| | ValidationError | Input validation failures | Invalid amounts, chains, addresses | | CryptoError | Cryptographic operation failures | Encryption, decryption, commitments | | ProofError | ZK proof operation failures | Proof generation, verification | | IntentError | Intent lifecycle errors | Expired intents, invalid state | | NetworkError | External service failures | RPC calls, API requests | | WalletError | Wallet interaction failures | Connection, signing, transactions |

Error Codes Reference

General (1xxx)

| Code | Description | When It Occurs | |------|-------------|---------------| | SIP_1000 | Unknown error | Unexpected failures | | SIP_1001 | Internal error | SDK internal failures | | SIP_1002 | Not implemented | Feature not available |

Validation (2xxx)

| Code | Description | Recovery | |------|-------------|----------| | SIP_2000 | Validation failed | Check input parameters | | SIP_2001 | Invalid input | Verify data format and type | | SIP_2002 | Invalid chain | Use supported chain ID | | SIP_2003 | Invalid privacy level | Use: transparent, shielded, or compliant | | SIP_2004 | Invalid amount | Ensure positive bigint value | | SIP_2005 | Invalid hex string | Check hex format (0x prefix) | | SIP_2006 | Invalid key | Verify key length and format | | SIP_2007 | Invalid address | Check address format for chain | | SIP_2008 | Missing required field | Provide all required parameters | | SIP_2009 | Value out of range | Check min/max constraints |

Example:

try {
  const intent = sip.intent()
    .input('invalid_chain', 'SOL', 100n) // ❌ Invalid chain
} catch (e) {
  if (hasErrorCode(e, ErrorCode.INVALID_CHAIN)) {
    // Retry with valid chain
    const intent = sip.intent()
      .input('solana', 'SOL', 100n) // ✅ Valid
  }
}

Cryptographic (3xxx)

| Code | Description | Recovery | |------|-------------|----------| | SIP_3000 | Crypto operation failed | Retry or check inputs | | SIP_3001 | Encryption failed | Verify key and data | | SIP_3002 | Decryption failed | Check key matches encryption key | | SIP_3003 | Key derivation failed | Verify seed/path parameters | | SIP_3004 | Commitment failed | Check value and blinding | | SIP_3005 | Signature failed | Verify signing key | | SIP_3006 | Invalid curve point | Check point coordinates | | SIP_3007 | Invalid scalar | Verify scalar is in valid range | | SIP_3008 | Invalid key size | Check key is 32 bytes | | SIP_3009 | Invalid encrypted data | Verify ciphertext integrity | | SIP_3010 | Invalid commitment | Check commitment format |

Example:

import { generateViewingKey, encryptForViewing, decryptWithViewing, CryptoError } from '@sip-protocol/sdk'

const viewingKey = generateViewingKey('/compliance/auditor')
const data = { sender: '0x...', amount: '100', timestamp: Date.now() }

try {
  const encrypted = encryptForViewing(data, viewingKey)
  const decrypted = decryptWithViewing(encrypted, viewingKey)
} catch (e) {
  if (e instanceof CryptoError) {
    console.error('Crypto operation failed:', e.operation, e.code)
    // Check if ciphertext was corrupted
    // Verify viewing key is correct
  }
}

Proof (4xxx)

| Code | Description | Recovery | |------|-------------|----------| | SIP_4000 | Proof operation failed | Check inputs and retry | | SIP_4001 | Proof generation failed | Verify proof parameters | | SIP_4002 | Proof verification failed | Check proof and public inputs | | SIP_4003 | Proof not implemented | Use mock provider or wait for implementation | | SIP_4004 | Proof provider not ready | Call provider.initialize() first | | SIP_4005 | Invalid proof params | Verify all required fields |

Example:

import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'

const provider = new NoirProofProvider({ wasmPath: '/noir' })

try {
  // ❌ Provider not initialized
  await provider.generateFundingProof(params)
} catch (e) {
  if (hasErrorCode(e, ErrorCode.PROOF_PROVIDER_NOT_READY)) {
    // ✅ Initialize first
    await provider.initialize()
    const result = await provider.generateFundingProof(params)
  }
}

Intent (5xxx)

| Code | Description | Recovery | |------|-------------|----------| | SIP_5000 | Intent operation failed | Check intent state and retry | | SIP_5001 | Intent expired | Create new intent with longer TTL | | SIP_5002 | Intent cancelled | Cannot recover, create new intent | | SIP_5003 | Intent not found | Verify intent ID | | SIP_5004 | Invalid intent state | Check intent lifecycle | | SIP_5005 | Proofs required | Generate required proofs | | SIP_5006 | Quote expired | Request new quote |

Example:

import { isExpired } from '@sip-protocol/sdk'

const intent = await sip.intent()
  .input('solana', 'SOL', 1_000_000_000n)
  .output('zcash', 'ZEC', 50_000_000n)
  .ttl(300) // 5 minutes
  .build()

// Before execution, check expiry
if (isExpired(intent)) {
  throw new IntentError('Intent expired', ErrorCode.INTENT_EXPIRED, {
    context: {
      expiry: intent.expiry,
      now: Math.floor(Date.now() / 1000)
    }
  })
}

Network (6xxx)

| Code | Description | Recovery | |------|-------------|----------| | SIP_6000 | Network operation failed | Check connectivity and retry | | SIP_6001 | Network timeout | Increase timeout or check connection | | SIP_6002 | Network unavailable | Wait and retry with backoff | | SIP_6003 | RPC error | Check RPC endpoint and params | | SIP_6004 | API error | Check API credentials and quota | | SIP_6005 | Rate limited | Wait before retrying |

Example:

async function executeWithRetry(intent: ShieldedIntent, quote: Quote, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await sip.execute(intent, quote)
    } catch (e) {
      if (e instanceof NetworkError) {
        if (hasErrorCode(e, ErrorCode.RATE_LIMITED)) {
          // Exponential backoff
          await delay(1000 * Math.pow(2, i))
          continue
        }
        if (hasErrorCode(e, ErrorCode.NETWORK_TIMEOUT)) {
          // Just retry
          continue
        }
      }
      throw e
    }
  }
  throw new Error('Max retries exceeded')
}

Wallet (7xxx)

| Code | Value | Description | Recovery | |------|-------|-------------|----------| | SIP_7000 | WALLET_UNKNOWN_ERROR | Generic wallet error | Check wallet state | | SIP_7001 | WALLET_NOT_CONNECTED | Wallet not connected | Call wallet.connect() | | SIP_7002 | WALLET_CONNECTION_FAILED | Connection failed | Check wallet installation | | SIP_7003 | WALLET_SIGNING_FAILED | Signing failed | Retry signing | | SIP_7004 | WALLET_TRANSACTION_FAILED | Transaction failed | Check gas and balance |

Wallet-Specific Error Codes

The WalletError class includes additional wallet-specific codes:

| Code | Description | Recovery | |------|-------------|----------| | WALLET_NOT_INSTALLED | Wallet extension not found | Install wallet browser extension | | WALLET_CONNECTION_REJECTED | User rejected connection | Ask user to approve | | WALLET_SIGNING_REJECTED | User rejected signing | Ask user to approve | | WALLET_TRANSACTION_REJECTED | User rejected transaction | Ask user to approve | | WALLET_INSUFFICIENT_FUNDS | Not enough balance | Add funds to wallet | | WALLET_UNSUPPORTED_CHAIN | Chain not supported | Switch to supported chain | | WALLET_CHAIN_SWITCH_REJECTED | User rejected chain switch | Ask user to approve | | WALLET_STEALTH_NOT_SUPPORTED | Stealth addresses not supported | Use different wallet | | WALLET_VIEWING_KEY_NOT_SUPPORTED | Viewing keys not supported | Use different wallet |

Example:

import { WalletError } from '@sip-protocol/sdk'

try {
  await wallet.connect()
  const signature = await wallet.signMessage(message)
} catch (e) {
  if (e instanceof WalletError) {
    if (e.isConnectionError()) {
      // Handle connection errors
      console.error('Connection failed:', e.walletCode)
    }
    if (e.isUserRejection()) {
      // User rejected - don't retry automatically
      console.log('User rejected the request')
    }
    if (e.isPrivacyError()) {
      // Privacy features not supported
      console.log('Wallet does not support privacy features')
    }
  }
}

Recovery Strategies

Retry with Exponential Backoff

For transient network errors:

async function withExponentialBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5,
  baseDelay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (e) {
      if (i === maxRetries - 1) throw e

      if (e instanceof NetworkError) {
        const delay = baseDelay * Math.pow(2, i)
        const jitter = Math.random() * 1000
        await sleep(delay + jitter)
        continue
      }

      throw e // Non-retryable error
    }
  }
  throw new Error('Unreachable')
}

// Usage
const quotes = await withExponentialBackoff(() => sip.getQuotes(intent))

Fallback to Alternative Provider

For proof generation failures:

import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'
import { MockProofProvider } from '@sip-protocol/sdk'

const providers = [
  new NoirProofProvider({ wasmPath: '/noir' }),
  new MockProofProvider(), // Fallback for testing
]

async function generateProofWithFallback(params: FundingProofParams) {
  for (const provider of providers) {
    try {
      await provider.initialize()
      return await provider.generateFundingProof(params)
    } catch (e) {
      console.warn(`Provider ${provider.constructor.name} failed:`, e)
      continue
    }
  }
  throw new ProofError('All proof providers failed', ErrorCode.PROOF_GENERATION_FAILED)
}

Circuit Breaker Pattern

Prevent cascading failures:

class CircuitBreaker {
  private failures = 0
  private lastFailTime = 0
  private readonly threshold = 5
  private readonly timeout = 60000 // 1 minute

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.isOpen()) {
      throw new NetworkError('Circuit breaker open', ErrorCode.NETWORK_UNAVAILABLE)
    }

    try {
      const result = await fn()
      this.reset()
      return result
    } catch (e) {
      this.recordFailure()
      throw e
    }
  }

  private isOpen(): boolean {
    if (this.failures >= this.threshold) {
      if (Date.now() - this.lastFailTime < this.timeout) {
        return true
      }
      this.reset()
    }
    return false
  }

  private recordFailure() {
    this.failures++
    this.lastFailTime = Date.now()
  }

  private reset() {
    this.failures = 0
  }
}

const breaker = new CircuitBreaker()
const result = await breaker.execute(() => sip.execute(intent, quote))

Graceful Degradation

For optional features:

import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'

async function createIntent(withProofs = true) {
  const builder = sip.intent()
    .input('solana', 'SOL', 1_000_000_000n)
    .output('zcash', 'ZEC', 50_000_000n)
    .privacy(PrivacyLevel.SHIELDED)

  if (withProofs) {
    try {
      // Try to generate proofs
      const proofProvider = new NoirProofProvider({ wasmPath: '/noir' })
      await proofProvider.initialize()
      builder.withProvider(proofProvider)
    } catch (e) {
      console.warn('Proof generation not available, continuing without proofs:', e)
      // Continue without proofs (for development)
    }
  }

  return builder.build()
}

Debugging

Enable Debug Logging

The SDK doesn’t include built-in debug logging by default, but you can wrap operations:

function withLogging<T>(
  fn: () => Promise<T>,
  operation: string
): Promise<T> {
  console.log(`[DEBUG] Starting: ${operation}`)
  const start = Date.now()

  return fn()
    .then(result => {
      console.log(`[DEBUG] Success: ${operation} (${Date.now() - start}ms)`)
      return result
    })
    .catch(e => {
      console.error(`[DEBUG] Failed: ${operation} (${Date.now() - start}ms)`, e)
      throw e
    })
}

// Usage
const intent = await withLogging(
  () => sip.intent()
    .input('solana', 'SOL', 1_000_000_000n)
    .output('zcash', 'ZEC', 50_000_000n)
    .build(),
  'intent creation'
)

Inspect Error Context

All SIP errors include context for debugging:

try {
  await sip.execute(intent, quote)
} catch (e) {
  if (isSIPError(e)) {
    console.log('Error Details:', {
      code: e.code,
      message: e.message,
      context: e.context,
      timestamp: e.timestamp,
      stack: e.stack,
    })

    // Serialize for logging
    const serialized = e.toJSON()
    await logToService(serialized)
  }
}

Viewing Key Debugging

Use viewing keys to debug privacy transactions:

import { generateViewingKey, encryptForViewing, decryptWithViewing } from '@sip-protocol/sdk'

// Create auditor viewing key
const auditorKey = generateViewingKey('/compliance/auditor')

// Encrypt transaction details
const txDetails = {
  sender: stealthAddress.spendingKey,
  recipient: recipientAddress,
  amount: '1000000000',
  timestamp: Date.now(),
}

const encrypted = encryptForViewing(txDetails, auditorKey)

// Later, auditor can decrypt
try {
  const decrypted = decryptWithViewing(encrypted, auditorKey)
  console.log('Transaction details:', decrypted)
} catch (e) {
  console.error('Failed to decrypt with viewing key:', e)
  // Wrong viewing key or corrupted data
}

Test Error Scenarios

Use mock components to test error handling:

import { createMockSolanaAdapter } from '@sip-protocol/sdk'

// Test connection rejection
const rejectingWallet = createMockSolanaAdapter({
  shouldFailConnect: true,
})

try {
  await rejectingWallet.connect()
} catch (e) {
  expect(e).toBeInstanceOf(WalletError)
  expect(e.walletCode).toBe('WALLET_CONNECTION_FAILED')
}

// Test signing rejection
const rejectingWallet2 = createMockSolanaAdapter({
  shouldFailSign: true,
})
await rejectingWallet2.connect()

try {
  await rejectingWallet2.signMessage(new Uint8Array([1, 2, 3]))
} catch (e) {
  expect(e).toBeInstanceOf(WalletError)
  expect(e.walletCode).toBe('WALLET_SIGNING_FAILED')
}

Common Issues

Issue: Transaction Failed

Symptoms:

• Error code: SIP_5000 or SIP_7004
• Message: “Transaction failed” or “Intent execution failed”

Causes:

1. Insufficient funds in sender wallet
2. Slippage tolerance too low
3. Quote expired before execution
4. Network congestion causing timeout
5. Invalid intent state

Solutions:

// 1. Check wallet balance before execution
const balance = await wallet.getBalance()
if (balance < intent.inputAmount) {
  throw new ValidationError('Insufficient funds', 'input.amount', {
    required: intent.inputAmount,
    available: balance,
  })
}

// 2. Increase slippage tolerance on the intent itself (1% = .slippage(1))
const intentWithSlippage = await sip.intent()
  .input('solana', 'SOL', 1_000_000_000n)
  .output('zcash', 'ZEC', 50_000_000n)
  .slippage(1) // 1%
  .build()
const quote = await sip.getQuotes(intentWithSlippage)

// 3. Check quote expiry
const now = Math.floor(Date.now() / 1000)
if (quote.expiry < now) {
  // Get new quote
  const newQuote = await sip.getQuotes(intent)
}

// 4. Set longer timeout
const result = await Promise.race([
  sip.execute(intent, quote),
  new Promise((_, reject) =>
    setTimeout(() => reject(new NetworkError('Timeout', ErrorCode.NETWORK_TIMEOUT)), 60000)
  )
])

// 5. Verify intent state
if (isExpired(intent)) {
  throw new IntentError('Intent expired', ErrorCode.INTENT_EXPIRED)
}

Issue: Invalid Stealth Address

Symptoms:

• Error code: SIP_2007
• Message: “Validation failed for ‘stealthAddress’: Invalid format”

Causes:

1. Incorrect address format (missing prefix or invalid encoding)
2. Wrong chain specified
3. Corrupted keys during generation
4. Using regular address instead of stealth address

Solutions:

import {
  generateStealthMetaAddress,
  encodeStealthMetaAddress,
  decodeStealthMetaAddress,
} from '@sip-protocol/sdk'

// ✅ Generate valid stealth meta-address (chain is required)
const keys = generateStealthMetaAddress('solana')
const encoded = encodeStealthMetaAddress(keys.metaAddress)

// Validate format: sip:solana:<spendingKey>:<viewingKey>
if (!encoded.startsWith('sip:solana:')) {
  throw new ValidationError('Invalid stealth address format')
}

// ✅ Decode safely — decodeStealthMetaAddress validates the keys and
// throws a ValidationError if the format or curve is wrong
try {
  const decoded = decodeStealthMetaAddress(encoded)
  console.log('Valid stealth address:', decoded)
} catch (e) {
  throw new ValidationError('Invalid stealth address for chain', 'stealthAddress')
}

Issue: Proof Verification Failed

Symptoms:

• Error code: SIP_4002
• Message: “Proof verification failed”

Causes:

1. Proof generated with wrong parameters
2. Public inputs don’t match private inputs
3. Proof provider not initialized
4. Circuit mismatch (wrong version)

Troubleshooting:

import { NoirProofProvider } from '@sip-protocol/sdk/proofs/noir'
import { commit, generateRandomBytes } from '@sip-protocol/sdk'

const provider = new NoirProofProvider({ wasmPath: '/noir' })

// 1. Always initialize first
await provider.initialize()

// 2. Generate proof with correct parameters
const balance = 1000n
const blindingFactor = generateRandomBytes(32) // 32-byte Uint8Array
const proofResult = await provider.generateFundingProof({
  balance,
  minimumRequired: 100n,
  blindingFactor, // Use same blinding as commitment
  assetId: 'SOL',
  userAddress: wallet.address,
  ownershipSignature, // Signature over userAddress
})

// 3. Verify proof with matching public inputs
const publicInputs = {
  commitment: commit(balance, blindingFactor).commitment, // Must match!
  minimumRequired: 100n,
  assetId: 'SOL',
}

const isValid = await provider.verifyFundingProof(
  proofResult.proof,
  publicInputs
)

if (!isValid) {
  // Debug: Check each public input
  console.log('Public inputs:', publicInputs)
  console.log('Proof data:', proofResult)
  // Likely cause: Commitment doesn't match balance+blinding
}

Issue: Wallet Not Connected

Symptoms:

• Error code: SIP_7001
• Message: “Wallet not connected. Call connect() first.”

Causes:

1. Forgot to call wallet.connect()
2. User rejected connection
3. Wallet extension not installed
4. Wallet disconnected after initial connection

Solutions:

import { WalletError } from '@sip-protocol/sdk'

async function ensureConnected(wallet: WalletAdapter) {
  if (wallet.isConnected()) {
    return // Already connected
  }

  try {
    await wallet.connect()
  } catch (e) {
    if (e instanceof WalletError) {
      switch (e.walletCode) {
        case 'WALLET_NOT_INSTALLED':
          throw new Error('Please install a compatible wallet extension')

        case 'WALLET_CONNECTION_REJECTED':
          throw new Error('Please approve the wallet connection request')

        case 'WALLET_CONNECTION_FAILED':
          // Retry once
          await wallet.connect()
          break

        default:
          throw e
      }
    }
    throw e
  }
}

// Usage
await ensureConnected(wallet)
const signature = await wallet.signMessage(message)

Issue: Commitment Verification Failed

Symptoms:

• Error code: SIP_3010
• Message: “Invalid commitment” or “Commitment verification failed”

Causes:

1. Using different blinding factor for verification
2. Homomorphic addition done incorrectly
3. Amount overflow (exceeds curve order)
4. Corrupted commitment data

Solutions:

import { commit, verifyOpening, addCommitments, addBlindings } from '@sip-protocol/sdk'

// ✅ Store blinding factor with commitment
const amount = 1000n
const { commitment, blinding } = commit(amount)

// Save both for later verification
const stored = {
  commitment,
  blinding: blinding, // Must save this!
  amount,
}

// ✅ Verify with saved blinding
const isValid = verifyOpening(
  stored.commitment,
  stored.amount,
  stored.blinding
)

console.assert(isValid, 'Verification should succeed')

// ✅ Homomorphic addition
const c1 = commit(100n)
const c2 = commit(200n)
const sum = addCommitments(c1.commitment, c2.commitment)

// Verify sum (must use sum of blindings — addBlindings sums them mod the curve order)
const totalBlinding = addBlindings(c1.blinding, c2.blinding)
verifyOpening(sum.commitment, 300n, totalBlinding) // ✅

Tip

Always serialize errors for logging using error.toJSON() to capture all debugging context.

Caution

Never retry operations that the user explicitly rejected (connection, signing, transactions). Only retry transient errors like network timeouts.

Error Utilities

Wrapping Errors

Convert unknown errors to SIPError:

import { wrapError, ErrorCode } from '@sip-protocol/sdk'

async function riskyOperation() {
  try {
    await externalLibrary.doSomething()
  } catch (e) {
    throw wrapError(
      e,
      'External operation failed',
      ErrorCode.INTERNAL,
      { operation: 'doSomething' }
    )
  }
}

Type Guards

Check error types safely:

import { isSIPError, hasErrorCode, ErrorCode } from '@sip-protocol/sdk'

try {
  await sip.execute(intent, quote)
} catch (e) {
  if (isSIPError(e)) {
    // TypeScript knows e is SIPError
    console.log(e.code, e.context)
  }

  if (hasErrorCode(e, ErrorCode.INTENT_EXPIRED)) {
    // Handle specific error code
    console.log('Intent expired, creating new one')
  }
}

Extract Error Message

Safely extract message from unknown errors:

import { getErrorMessage } from '@sip-protocol/sdk'

try {
  await operation()
} catch (e) {
  // Works for Error, SIPError, or any unknown type
  const message = getErrorMessage(e)
  console.error('Operation failed:', message)
}

Best Practices

1. Always check error types before handling - use instanceof or hasErrorCode()
2. Preserve error causes - use the cause option when wrapping errors
3. Add context - include relevant debugging information in context field
4. Don’t retry user rejections - only retry transient errors (network, timeout)
5. Use circuit breakers - prevent cascading failures to external services
6. Log serialized errors - use error.toJSON() for structured logging
7. Test error paths - use mock adapters to test error handling
8. Provide recovery steps - give users actionable error messages
9. Validate early - check inputs before expensive operations
10. Use graceful degradation - fall back to safe defaults when possible

Next Steps

• API Reference - Complete API documentation
• Integration Guide - Building solvers with error handling
• Testing Guide - Testing error scenarios
• Deployment Guide - Production error monitoring