Labels: Stellar Wave, dx, feature, drips, help-wanted
Tier: M (2–4 days)
Type: feature / dx
Context
The SDK throws plain Error instances everywhere. A consumer catching one cannot programmatically distinguish "invalid meta-address format" from "RPC unreachable" from "view tag mismatch" — they have to substring-match on the message, which is brittle and breaks across versions.
We want a typed error hierarchy so consumers can catch (e) { if (e instanceof WraithNameNotFoundError) ... }.
Scope
Define a hierarchy at sdk/src/errors.ts:
WraithError (abstract base)
├── WraithInputError
│ ├── InvalidMetaAddressError
│ ├── InvalidNameError
│ ├── InvalidSignatureError
│ └── InvalidScalarError
├── WraithCryptoError
│ ├── KeyDerivationFailedError
│ ├── ViewTagMismatchError
│ └── ECDHFailedError
├── WraithNetworkError
│ ├── RPCRequestError (carries status code)
│ ├── RPCRetryExhaustedError
│ └── RetentionExceededError
├── WraithContractError
│ ├── NameNotFoundError
│ ├── NameAlreadyRegisteredError
│ ├── InsufficientAuthError
│ └── ContractRevertError (carries decoded reason)
└── WraithBuilderError
├── InsufficientBalanceError
└── UnsupportedAssetError
Each subclass:
- Has a
name matching the class name.
- Carries domain-specific structured data on the instance (not just in the message).
- Has a stable
code constant string for serialization across runtime boundaries (e.g., "WRAITH/CRYPTO/VIEW_TAG_MISMATCH").
- Includes a human-readable
message with a docs link.
Migration
- Sweep the codebase replacing
throw new Error(...) with the correct typed throw.
- Update JSDoc
@throws annotations (coordinate with issue #10).
- Add a
CHANGELOG.md entry noting the migration is non-breaking at runtime (subclasses extend Error) but typing-breaking for try { } catch (e: any) { e.message } patterns that assume the specific message format.
Tests
- One unit test per error class verifying
instanceof correctness across both ESM and CJS builds.
- A check that JSON-serializing an error preserves
code.
Acceptance criteria
Why this matters
Good error types are the difference between a library that integrators can build around and one that they have to monkey-patch. Every Spectre / demo / console error-handling branch becomes more robust the moment this lands.
Labels:
Stellar Wave,dx,feature,drips,help-wantedTier: M (2–4 days)
Type: feature / dx
Context
The SDK throws plain
Errorinstances everywhere. A consumer catching one cannot programmatically distinguish "invalid meta-address format" from "RPC unreachable" from "view tag mismatch" — they have to substring-match on the message, which is brittle and breaks across versions.We want a typed error hierarchy so consumers can
catch (e) { if (e instanceof WraithNameNotFoundError) ... }.Scope
Define a hierarchy at
sdk/src/errors.ts:Each subclass:
namematching the class name.codeconstant string for serialization across runtime boundaries (e.g.,"WRAITH/CRYPTO/VIEW_TAG_MISMATCH").messagewith a docs link.Migration
throw new Error(...)with the correct typed throw.@throwsannotations (coordinate with issue #10).CHANGELOG.mdentry noting the migration is non-breaking at runtime (subclasses extendError) but typing-breaking fortry { } catch (e: any) { e.message }patterns that assume the specific message format.Tests
instanceofcorrectness across both ESM and CJS builds.code.Acceptance criteria
@throwsannotations updated.instanceof+ serialization.Why this matters
Good error types are the difference between a library that integrators can build around and one that they have to monkey-patch. Every Spectre / demo / console error-handling branch becomes more robust the moment this lands.