Skip to main content
zephyr-ts

TypeScript wallet library for Zephyr, a lateo project

Errors

The error class, its codes and its diagnostics. Chapter 8 explains how a wallet handles them.

ZephyrWalletError#

Declaration
class ZephyrWalletError extends Error

Every failure of the library is a ZephyrWalletError. It extends Error; its name is "ZephyrWalletError" and its message a fixed text per code (below). It carries no native text, no daemon text, no request text, no stack of another error and no cause. Only the code and the diagnostic cross the worker boundary.

constructor#

Declaration
constructor(code: ZephyrWalletErrorCode, diagnostic?: ZephyrWalletErrorDiagnostic);

Creates an error. An unknown code becomes NATIVE_ERROR, and a diagnostic outside the list is dropped. Applications rarely create one; it is useful in tests.

code#

Declaration
readonly code: ZephyrWalletErrorCode;

One of the thirteen codes.

diagnostic#

Declaration
readonly diagnostic: ZephyrWalletErrorDiagnostic | undefined;

One of the diagnostics, or undefined.

isCode#

Declaration
static isCode(value: unknown): value is ZephyrWalletErrorCode;

Whether a value is one of the codes.

isDiagnostic#

Declaration
static isDiagnostic(value: unknown): value is ZephyrWalletErrorDiagnostic;

Whether a value is one of the diagnostics.

unsupported#

Declaration
static unsupported(diagnostic: ZephyrWalletErrorDiagnostic): ZephyrWalletError;

Creates an UNSUPPORTED_CAPABILITY error with the diagnostic. Used by the library.

walletClosed#

Declaration
static walletClosed(): ZephyrWalletError;

Creates a WALLET_CLOSED error. Used by the library.

fromBridge#

Declaration
static fromBridge(context: ZephyrNativeErrorContext, identifier: ZephyrBridgeErrorIdentifier): ZephyrWalletError;

Maps a fixed identifier of the native bridge, in a call context, to its error. Used by the library; its parameter types are not exported.

fromBridgeResult#

Declaration
static fromBridgeResult(context: ZephyrNativeErrorContext, result: unknown): ZephyrWalletError;

Maps a native result that reported a failure to its error; never throws. Used by the library.

checkBridgeResult#

Declaration
static checkBridgeResult<T>(context: ZephyrNativeErrorContext, result: T): T;

Throws the error of a native failure result, or returns the result unchanged. Used by the library.

fromUnknown#

Declaration
static fromUnknown(context: ZephyrNativeErrorContext, err: unknown): ZephyrWalletError;

Returns a ZephyrWalletError unchanged and maps any other value to the fixed error of its context (diagnostic UNCLASSIFIED_ERROR) without reading its message, stack, cause or fields. Used by the library.

toEnvelope#

Declaration
toEnvelope(): ZephyrWalletErrorEnvelope;

The plain object { type: "ZephyrWalletError", code, diagnostic? } that crosses the worker boundary. Used by the library; the envelope type is not exported.

isEnvelope#

Declaration
static isEnvelope(value: unknown): value is ZephyrWalletErrorEnvelope;

Whether a received value is exactly a valid envelope. Used by the library.

fromEnvelope#

Declaration
static fromEnvelope(value: unknown): ZephyrWalletError;

Rebuilds an error from an envelope; anything that is not exactly a valid envelope becomes MALFORMED_MESSAGE/MESSAGE_SHAPE. Used by the library.

Error types#

ZephyrWalletErrorCode#

Declaration
type ZephyrWalletErrorCode = "UNSUPPORTED_CAPABILITY" | "INVALID_CONFIG" | "INVALID_RECOVERY_MATERIAL" | "WRONG_PASSWORD" | "INVALID_WALLET_DATA" | "INVALID_ADDRESS" | "WALLET_CLOSED" | "MALFORMED_MESSAGE" | "NATIVE_ERROR" | "DAEMON_ERROR" | "TX_NOT_POSSIBLE" | "TX_REJECTED" | "RELAY_UNKNOWN";

The thirteen codes, listed below.

ZephyrWalletErrorDiagnostic#

Declaration
type ZephyrWalletErrorDiagnostic = typeof ZEPHYR_WALLET_ERROR_DIAGNOSTICS[number];

The union of the diagnostics listed below. The constant it is derived from is not exported by the package entry.

Codes#

CodeMessageMeaning
UNSUPPORTED_CAPABILITYUnsupported capabilityoutside the supported surface, or not available for this kind of wallet; raised before any native code runs
INVALID_CONFIGInvalid wallet configuration or argumenta configuration or argument was rejected, also an index, a transaction or a token the wallet does not have
INVALID_RECOVERY_MATERIALRecovery material was rejecteda seed or keys were rejected
WRONG_PASSWORDWrong wallet passwordthe password does not open the bytes, or the old password is wrong
INVALID_WALLET_DATAWallet data could not be openedthe wallet bytes could not be opened
INVALID_ADDRESSInvalid addressan address is malformed, of another network or not of this wallet
WALLET_CLOSEDWallet is closedthe wallet was closed or stopped
MALFORMED_MESSAGEMalformed worker messagea worker message did not have the expected form
NATIVE_ERRORNative wallet operation faileda native operation, the module or a worker failed
DAEMON_ERRORDaemon request faileda daemon request failed
TX_NOT_POSSIBLETransaction not possiblethe wallet's funds or the chain's state do not allow the transaction
TX_REJECTEDTransaction rejected by the daemonthe daemon refused a relayed transaction
RELAY_UNKNOWNRelay outcome unknowna relay request was sent and no usable answer came

Diagnostics#

Each diagnostic is a fixed identifier chosen by the library. The code column gives the code it comes with. A diagnostic of the core or the bridge without a fixed meaning takes the code of the call instead: INVALID_WALLET_DATA when opening bytes, INVALID_RECOVERY_MATERIAL when restoring, INVALID_ADDRESS for an address call, NATIVE_ERROR otherwise.

Unsupported capabilities#

DiagnosticCodeMeaning
FILE_PATHUNSUPPORTED_CAPABILITYa file path; wallets have no files
DAEMON_CONNECTIONUNSUPPORTED_CAPABILITYa daemon field where the core's configuration takes none
UNTRUSTED_DAEMONUNSUPPORTED_CAPABILITYtrusted: false or isTrustedDaemon: false; every daemon is trusted
REGTESTUNSUPPORTED_CAPABILITYregtest: true
MULTISIGUNSUPPORTED_CAPABILITYisMultisig: true, or a multisig wallet at build time
SAVE_CURRENTUNSUPPORTED_CAPABILITYsaveCurrent: true
CONFIG_FIELDUNSUPPORTED_CAPABILITYconnectionManager, fs, cmd or rejectUnauthorized
KEYS_ONLY_RESTORE_HEIGHTUNSUPPORTED_CAPABILITYa restore height for, or asked of, a keys-only wallet
KEYS_ONLY_LOOKAHEADUNSUPPORTED_CAPABILITYa lookahead for a keys-only wallet
KEYS_ONLY_DATAUNSUPPORTED_CAPABILITYgetData of a keys-only wallet
KEYS_ONLY_PASSWORDUNSUPPORTED_CAPABILITYa password change of a keys-only wallet
KEYS_ONLY_NETWORK_TYPEUNSUPPORTED_CAPABILITYgetNetworkType of a keys-only wallet
KEYS_ONLY_DAEMONUNSUPPORTED_CAPABILITYa daemon, balance or pool call of a keys-only wallet
KEYS_ONLY_ACCOUNTSUNSUPPORTED_CAPABILITYan account or subaddress call of a keys-only wallet
KEYS_ONLY_HISTORYUNSUPPORTED_CAPABILITYa history call of a keys-only wallet
KEYS_ONLY_TXUNSUPPORTED_CAPABILITYa build or relay call of a keys-only wallet
VIEW_ONLY_TXUNSUPPORTED_CAPABILITYa build or relay call of a view-only wallet
NETWORK_REQUESTUNSUPPORTED_CAPABILITYa request outside the configured daemon routes, refused by the transport
WORKER_FUNCTIONUNSUPPORTED_CAPABILITYa worker function outside the supported set
WALLET_KINDUNSUPPORTED_CAPABILITYa worker function not available for the wallet's kind
NATIVE_EXPORTUNSUPPORTED_CAPABILITYa native function that is not built into the module
LISTENERUNSUPPORTED_CAPABILITYa listener
LISTENERSUNSUPPORTED_CAPABILITYaddListener
SAVE_ON_CLOSEUNSUPPORTED_CAPABILITYsaving on close
BALANCEUNSUPPORTED_CAPABILITYthe asset-less getBalance(accountIdx, subaddressIdx)
SYNCUNSUPPORTED_CAPABILITYbackground synchronization, or sync with more than one argument
TRANSACTIONSUNSUPPORTED_CAPABILITYthe inherited transaction creation (createTxs)
DAEMON_SETTINGSUNSUPPORTED_CAPABILITYrescans and key image import
RESERVE_PROOFUNSUPPORTED_CAPABILITYreserve proofs
CONVERSIONUNSUPPORTED_CAPABILITYa destinationAsset other than asset in a transfer
INTEGRATED_ADDRESSUNSUPPORTED_CAPABILITYan integrated address as a destination
TERMINATEUNSUPPORTED_CAPABILITYterminate of a direct-mode wallet
DAEMON_CREDENTIALSUNSUPPORTED_CAPABILITYa user name or password for the daemon
DAEMON_PROXYUNSUPPORTED_CAPABILITYa proxy for the daemon
RELAY_REQUESTUNSUPPORTED_CAPABILITY, NATIVE_ERRORa submit or relay request refused by the transport: outside a relay call UNSUPPORTED_CAPABILITY; during relayPrepared NATIVE_ERROR, nothing sent

Configuration and arguments#

DiagnosticCodeMeaning
CONFIG_TYPEINVALID_CONFIGa configuration, query or options value that is not a plain object of own data properties
UNKNOWN_FIELDINVALID_CONFIGan unknown field
FIELD_TYPEINVALID_CONFIGa field or argument of the wrong type, or too many arguments
NETWORK_TYPEINVALID_CONFIGa missing or unknown network type
CREATE_MODEINVALID_CONFIGrecovery fields that do not fit the construction function
SEED_AND_KEYSINVALID_CONFIGa seed together with keys
SEED_OFFSETINVALID_CONFIGa seed offset without a seed
SEED_LANGUAGEINVALID_CONFIGa language with a seed
RANDOM_RESTORE_HEIGHTINVALID_CONFIGa restore height for a random wallet
RESTORE_HEIGHT_RANGEINVALID_CONFIGa restore height that is not a safe integer from 0
LOOKAHEAD_PAIRINVALID_CONFIGonly one of the two lookahead values
LOOKAHEAD_RANGEINVALID_CONFIGa lookahead value outside 1 to 2^32-1
LOOKAHEAD_LIMITINVALID_CONFIGa lookahead value or their product above 20,000
CORE_LOOKAHEADINVALID_CONFIGa lookahead the core rejected
CORE_UNKNOWN_LANGUAGEINVALID_CONFIGa seed language the core does not know
LOG_LEVEL_RANGEINVALID_CONFIGa native log level out of range (not offered by the entry)
PASSWORD_TYPEINVALID_CONFIGa password that is not a string
ADDRESS_INDEX_RANGEINVALID_CONFIGan account or subaddress index outside 0 to 2^32-1
DAEMON_ADDRESSINVALID_CONFIGa malformed daemon address
SYNC_START_HEIGHTINVALID_CONFIGa sync start height that is not a safe integer from 0
ASSET_TYPEINVALID_CONFIGan asset name that is malformed, or not one the call accepts
ACCOUNT_NOT_FOUNDINVALID_CONFIGan account the wallet does not have
SUBADDRESS_NOT_FOUNDINVALID_CONFIGa subaddress the wallet does not have
LABEL_TYPEINVALID_CONFIGa label that is not a string
LABEL_LENGTHINVALID_CONFIGa label longer than 255 UTF-8 bytes
LABEL_CHARACTERSINVALID_CONFIGa label with a control character or an unpaired surrogate
SUBADDRESS_INDICESINVALID_CONFIGsubaddress indices that are not a non-empty array of distinct indices
LISTING_LIMITINVALID_CONFIGa listing or selection above the per-call bounds
TX_HASHINVALID_CONFIGa transaction hash that is not 64 lowercase hexadecimal characters
TX_HASHESINVALID_CONFIGhashes that are not a non-empty array of distinct hashes, at most 1,000
HEIGHT_RANGEINVALID_CONFIGheights that are not safe integers from low to high
QUERY_ACCOUNT_REQUIREDINVALID_CONFIGa subaddress filter without an account
TX_NOT_FOUNDINVALID_CONFIGa transaction the wallet has no record of
TX_ASSETINVALID_CONFIGa V1 asset for a transaction
DESTINATIONSINVALID_CONFIGdestinations that are not a non-empty array
TOO_MANY_DESTINATIONSINVALID_CONFIGmore than 15 destinations
AMOUNT_ZEROINVALID_CONFIGan amount of zero
AMOUNT_RANGEINVALID_CONFIGan amount, or the sum of the amounts, outside 1 to 2^64-1
TX_PRIORITYINVALID_CONFIGa priority other than the four
CONVERSION_PAIRINVALID_CONFIGassets that are not one of the six conversion pairs
CONVERSION_DESTINATIONSINVALID_CONFIGa conversion destination that is not exactly one object
AMOUNT_PRECISIONINVALID_CONFIGa conversion amount with more than four decimals
RELAY_TOKENINVALID_CONFIGa value that is not a relay token
RELAY_TOKEN_VOIDINVALID_CONFIGa token that names no kept build (unknown, used or void)

Recovery material, wallet data and addresses#

DiagnosticCodeMeaning
SEED_EMPTYINVALID_RECOVERY_MATERIALan empty seed
SEED_WORD_COUNTINVALID_RECOVERY_MATERIALa seed that does not have 12, 13, 24 or 25 words
KEY_EMPTYINVALID_RECOVERY_MATERIALan empty key or address
KEY_FORMATINVALID_RECOVERY_MATERIALa private key that is not 64 hexadecimal characters
VIEW_KEY_WITHOUT_ADDRESSINVALID_RECOVERY_MATERIALa private view key without an address
KEYS_MISSINGINVALID_RECOVERY_MATERIALneither an address nor a private spend key
CORE_INVALID_MNEMONICthe call'sa seed the core cannot decode
CORE_INVALID_KEYthe call'sa key the core rejected
WALLET_BYTESINVALID_WALLET_DATAwallet bytes that are missing, empty or not a Uint8Array
CORE_WALLET_DATAthe call'swallet bytes the core could not open
CORE_INVALID_PASSWORDWRONG_PASSWORDa password the core rejected
ADDRESS_TYPEINVALID_ADDRESSan address that is not a non-empty string of the expected form
CORE_INVALID_ADDRESSINVALID_ADDRESSan address the core's parser rejects, or of another network
ADDRESS_NETWORKINVALID_ADDRESSa valid address of another network as a destination
ADDRESS_NOT_IN_WALLETINVALID_ADDRESSan address of another wallet

Daemon#

DiagnosticCodeMeaning
DAEMON_NOT_CONNECTEDDAEMON_ERRORno daemon configured or connected; also a browser request blocked by CORS or a policy
DAEMON_UNREACHABLEDAEMON_ERRORno answer: unreachable, refused or timed out; at relay, nothing was sent
DAEMON_RESPONSEDAEMON_ERRORan answer the core could not use: an error, an HTTP status, a body, a redirect
DAEMON_BUSYDAEMON_ERRORat relay, the daemon did not process the transaction
SYNC_FAILEDNATIVE_ERRORanother failure of a sync

Building, conversions and relay#

DiagnosticCodeMeaning
NOT_ENOUGH_UNLOCKEDTX_NOT_POSSIBLEthe unlocked balance of the asset does not cover the amounts
NOT_ENOUGH_MONEYTX_NOT_POSSIBLEeven the balance with locked outputs does not cover the amounts
NOT_ENOUGH_FOR_FEETX_NOT_POSSIBLEthe fee cannot be covered
NOT_ENOUGH_OUTS_TO_MIXTX_NOT_POSSIBLEthe chain has too few outputs for the rings
TX_TOO_LARGETX_NOT_POSSIBLEthe transaction would be too large
RESERVE_RATIOTX_NOT_POSSIBLEthe reserve ratio does not allow the conversion pair
PRICING_RECORDTX_NOT_POSSIBLEno usable pricing record, also when it could not be read
CONVERSION_SPLITTX_NOT_POSSIBLEthe conversion would need more than one transaction
CONVERSION_AMOUNTTX_NOT_POSSIBLEthe converted amount would be zero
PRICING_RECORD_AGETX_NOT_POSSIBLEa kept conversion's pricing record has aged; the token is void
TX_BUILD_FAILEDNATIVE_ERRORanother failure of the core's build
RELAY_HASH_MISMATCHNATIVE_ERRORa kept transaction does not hash to the described hash; nothing sent, the token is void
RELAY_FAILEDNATIVE_ERRORthe core's commit failed before any request; the token is void
RELAY_RECORD_FAILEDNATIVE_ERRORon an accepted entry: the daemon has the transaction, the wallet could not record it
LOW_RING_SIZETX_REJECTEDthe daemon refused it: ring size too low
DOUBLE_SPENDTX_REJECTEDthe daemon refused it: a double spend
INVALID_INPUTTX_REJECTEDthe daemon refused it: an invalid input
INVALID_OUTPUTTX_REJECTEDthe daemon refused it: an invalid output
TOO_BIGTX_REJECTEDthe daemon refused it: too big
OVERSPENDTX_REJECTEDthe daemon refused it: overspend
FEE_TOO_LOWTX_REJECTEDthe daemon refused it: fee too low
TOO_FEW_OUTPUTSTX_REJECTEDthe daemon refused it: too few outputs
TX_EXTRA_TOO_BIGTX_REJECTEDthe daemon refused it: extra field too big
SANITY_CHECK_FAILEDTX_REJECTEDthe daemon refused it: its sanity check failed
NOT_RELAYEDTX_REJECTEDthe daemon refused it with the not-relayed flag
REJECTEDTX_REJECTEDthe daemon refused it without a known flag
NO_ANSWERRELAY_UNKNOWNsent; no answer came
HTTP_STATUSRELAY_UNKNOWNsent; the answer was an HTTP error
ANSWER_UNREADABLERELAY_UNKNOWNsent; the answer could not be read

Module, workers and wallet state#

DiagnosticCodeMeaning
WASM_MODULE_UNAVAILABLENATIVE_ERRORzephyr.wasm could not be read or fetched (in Firefox also a worker policy without 'wasm-unsafe-eval')
WASM_MODULE_REJECTEDNATIVE_ERRORthe module did not compile or instantiate, for example under a policy without 'wasm-unsafe-eval'
WASM_MODULE_MISMATCHNATIVE_ERRORnot the zephyr.wasm whose SHA-256 the build embedded
WASM_MODULE_UNVERIFIEDNATIVE_ERRORno Web Crypto digest in this runtime, so the module cannot be checked
CONSTRUCTION_ABORTEDNATIVE_ERRORa construction was aborted by its signal or by terminateWorker
WORKER_FAILEDNATIVE_ERRORa worker could not start, reported an uncaught error or exited unexpectedly
WALLET_TERMINATEDWALLET_CLOSEDthe wallet was stopped with terminate or terminateWorker
CORE_CLOSE_FAILEDNATIVE_ERRORthe native close failed; close can be retried
PASSWORD_CHANGED_WITH_ERRORNATIVE_ERRORa failed password change that adopted the new password
PASSWORD_STATE_UNKNOWNNATIVE_ERRORthe password state is unknown; every call but close rejects
CORE_UNCLASSIFIEDthe call'sa core failure without a more specific identifier
UNCLASSIFIED_ERRORthe call'sa failure that is neither a wallet error nor a bridge result
UNEXPECTED_RESULTNATIVE_ERRORa native result that did not have the expected form
UNEXPECTED_ASSET_TYPENATIVE_ERRORa balance key outside the core's asset types
RESTORE_HEIGHT_UNREPRESENTABLENATIVE_ERRORa restore height above Number.MAX_SAFE_INTEGER
BUFFER_ALLOCATION_FAILEDthe call'sthe bridge could not allocate a byte buffer
NATIVE_BUFFER_FAILEDthe call'sthe bridge could not provide a byte buffer
BUFFER_FORMAT_FAILEDthe call'sthe bridge could not format a byte buffer
BUFFER_TOO_LARGEthe call'sa byte buffer is too large
BUFFER_EMPTYNATIVE_ERRORa byte buffer is empty
BUFFER_COPY_FAILEDNATIVE_ERRORa byte buffer could not be copied
BUFFER_RESULTNATIVE_ERRORa byte buffer result did not have the expected form
MESSAGE_SHAPEMALFORMED_MESSAGEa worker message or error envelope of the wrong shape
ARGUMENT_COUNTMALFORMED_MESSAGEa worker call with the wrong number of arguments
ARGUMENT_TYPEMALFORMED_MESSAGEa worker call argument of the wrong type
WALLET_IDMALFORMED_MESSAGEa malformed or unknown wallet identifier in a worker message
DUPLICATE_WALLET_IDMALFORMED_MESSAGEa wallet identifier used twice in a worker