Replace magic string error matching with typed/structured errors

[arkanaai]

Problem

SDK methods currently throw errors with plain string messages, and callers are expected to match against those strings to identify error types. This is fragile and creates several footguns:

• Any change to an error message string is a silent breaking change for downstream consumers
• Localization of SDK error messages would be impossible without breaking all consumers who do string matching
• No IDE/TypeScript support for discovering what errors a method can throw

What We Want

Replace plain Error/string throws with typed error classes (or discriminated union error objects) so callers can do:

// Instead of:
if (err.message === 'no vtxos') { ... }

// Callers can do:
if (err instanceof NoVtxosError) { ... }
// or
if (err.code === 'NO_VTXOS') { ... }

Notes

• Changing public method throw signatures qualifies as a breaking change — needs a semver major or at minimum a deprecation path
• Related: PR #350 reduces spurious error logging for non-error conditions (no vtxos / below dust) — same area

References

Raised in #ark-js Slack discussion (2026-03-16)