Changelog

All notable changes to the Wraith Protocol SDK will be documented in this file.

Upcoming: 2.0.0

Stellar Chain Module Cryptographic Audit Fixes: Applied all findings from independent cryptographic audit (issue #55). Breaking changes:
- scanAnnouncements() now skips candidates with zero derived scalars (cryptographically required, probability ~1 in 2^255).
- View-tag computation optimized using ephemeralPubKey ⊕ viewingPubKey prefilter (1.5–2x faster, functionally identical).
- See MIGRATING.md § Stellar Audit Fixes for details.

Typed Error Taxonomy & Hierarchy: Introduced a robust, typed error hierarchy under src/errors.ts (exported from the SDK root entry point) to allow consumers to programmatically handle different error categories without brittle string matching on error.message.
- Base Errors: WraithError (abstract base), WraithInputError, WraithCryptoError, WraithNetworkError, WraithContractError, WraithBuilderError.
- Subclass Errors:
  - Inputs: InvalidMetaAddressError, InvalidNameError, InvalidSignatureError, InvalidScalarError.
  - Cryptography: KeyDerivationFailedError, ViewTagMismatchError, ECDHFailedError.
  - Network: RPCRequestError, RPCRetryExhaustedError, RetentionExceededError.
  - Smart Contracts: NameNotFoundError, NameAlreadyRegisteredError, InsufficientAuthError, ContractRevertError.
  - Builders: InsufficientBalanceError, UnsupportedAssetError.
Serialization Support: Custom error classes implement toJSON() and carry enumerable, public structured context fields, guaranteeing that JSON.stringify(error) preserves the stable code constants (e.g. "WRAITH/CRYPTO/VIEW_TAG_MISMATCH"), names, messages, and docs links.
Reference Documentation Links: Every error instance now automatically includes a docsLink property pointing directly to the detailed error reference page on https://docs.wraith.dev/sdk/errors, which is also appended to the human-readable message.

Codebase-wide Custom Error Migration: Replaced generic JavaScript Error instances throughout the codebase (in EVM, Stellar, Solana, and CKB modules) with appropriate typed exceptions.
JSDoc Annotations: Updated JSDoc @throws annotations across primary functions to reflect the precise custom error types thrown.

Runtime Non-Breaking: This release is fully backwards-compatible at a runtime level for applications that catch errors as generic JS Error instances, since all custom exceptions extend the native Error class.
Typing-Breaking for Brittle Matchers: If your application catch blocks rely on exact substring matching against error.message (e.g. if (e.message.includes('Expected 65-byte signature'))), this change will break those assertions. See MIGRATING.md § Error Handling for detailed migration steps and code examples.

Quick example:
```
import { InvalidSignatureError } from '@wraith-protocol/sdk';

try {
  // ...
} catch (e) {
  if (e instanceof InvalidSignatureError) {
    // Handle invalid signature specifically with rich structured context
    console.log(e.context.expectedLength);
  }
}
```
React Native: New applications targeting React Native must call installReactNativePolyfills() at startup. See MIGRATING.md § React Native for integration instructions.