Skip to content

errors.md

Latest commit

 

History

History
185 lines (140 loc) · 3.98 KB

errors.md

File metadata and controls

185 lines (140 loc) · 3.98 KB

Errors

@bsv/simple provides a hierarchy of error classes for domain-specific error handling. All errors extend the base SimpleError.

Source: src/core/errors.ts

Error Hierarchy

SimpleError (base)
├── WalletError
├── TransactionError
├── MessageBoxError
├── CertificationError
├── DIDError
└── CredentialError

SimpleError

Base class for all library errors.

class SimpleError extends Error {
  code?: string
  constructor(message: string, code?: string)
}
Property Type Description
message string Human-readable error description
code string? Machine-readable error code
name string 'SimpleError'

WalletError

Wallet initialization and connection errors.

class WalletError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'WalletError'
code 'WALLET_ERROR'

Example triggers:

  • Failed to connect to wallet extension
  • Invalid identity key
  • Client not available

TransactionError

Transaction creation and signing errors.

class TransactionError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'TransactionError'
code 'TRANSACTION_ERROR'

Example triggers:

  • createAction() fails
  • signAction() fails
  • Output parsing errors

MessageBoxError

MessageBox P2P messaging errors.

class MessageBoxError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'MessageBoxError'
code 'MESSAGEBOX_ERROR'

Example triggers:

  • Failed to anoint MessageBox host
  • Payment send/receive failures
  • Identity registry communication errors

CertificationError

Certificate issuance and management errors.

class CertificationError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'CertificationError'
code 'CERTIFICATION_ERROR'

Example triggers:

  • Certificate issuance fails
  • Certificate acquisition from remote server fails
  • Relinquish fails

DIDError

DID parsing and registration errors.

class DIDError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'DIDError'
code 'DID_ERROR'

Example triggers:

  • Invalid DID format (not did:bsv: prefix)
  • Invalid identity key in DID string
  • DID registration failure

CredentialError

Verifiable Credential errors.

class CredentialError extends SimpleError {
  constructor(message: string)
}
Property Value
name 'CredentialError'
code 'CREDENTIAL_ERROR'

Example triggers:

  • Unknown schema ID
  • Field validation failure
  • Revocation enabled but no wallet provided
  • Revocation UTXO creation failure
  • Certificate already revoked

Catching Errors

import { SimpleError, WalletError, CredentialError } from '@bsv/simple/browser'

try {
  await wallet.pay({ to: key, satoshis: 1000 })
} catch (error) {
  if (error instanceof WalletError) {
    console.error('Wallet issue:', error.message)
  } else if (error instanceof SimpleError) {
    console.error(`${error.code}: ${error.message}`)
  } else {
    console.error('Unexpected:', error)
  }
}

Note on Module Errors

Many module methods (tokens, inscriptions, messagebox, overlay) wrap errors in plain Error instances with descriptive prefixes rather than using the typed error classes:

throw new Error(`Token creation failed: ${originalError.message}`)
throw new Error(`Payment failed: ${originalError.message}`)

The typed error classes (DIDError, CredentialError) are used primarily by the DID and credentials modules. You can catch these specifically or catch the generic Error type for other modules.