Skip to main content
zephyr-ts

TypeScript wallet library for Zephyr, a lateo project

Functions

The nine functions the package exports. Every function that returns a promise rejects with a ZephyrWalletError; none throws synchronously. Configuration objects are typed unknown in the declarations and checked field by field at run time, before any native call.

Constructing wallets#

The five construction functions share these rules:

  • The first argument is a plain object; anything else rejects with INVALID_CONFIG/CONFIG_TYPE. A field with the value undefined counts as absent.
  • networkType is required: "mainnet", "testnet", "stagenet", 0, 1 or 2 (INVALID_CONFIG/NETWORK_TYPE).
  • An unknown field rejects with INVALID_CONFIG/UNKNOWN_FIELD; a field of the wrong type with INVALID_CONFIG/FIELD_TYPE.
  • Unsupported fields reject with UNSUPPORTED_CAPABILITY: a non-empty path (FILE_PATH), regtest: true (REGTEST), isMultisig: true (MULTISIG), saveCurrent: true (SAVE_CURRENT), isTrustedDaemon: false (UNTRUSTED_DAEMON), and connectionManager, fs, cmd or rejectUnauthorized (CONFIG_FIELD).
  • proxyToWorker (default true) runs the wallet in its own worker.
  • The second argument, options, is undefined or { signal } with an AbortSignal (ZephyrWalletConstructionOptions); another field rejects with INVALID_CONFIG/UNKNOWN_FIELD. An abort rejects with NATIVE_ERROR/CONSTRUCTION_ABORTED.
  • Failures to load the module reject the first construction with NATIVE_ERROR and WASM_MODULE_UNAVAILABLE, WASM_MODULE_MISMATCH, WASM_MODULE_REJECTED or WASM_MODULE_UNVERIFIED; a worker that cannot start with NATIVE_ERROR/WORKER_FAILED.
  • For full wallets, server is a daemon address (chapter 3), validated before construction (INVALID_CONFIG/DAEMON_ADDRESS, UNSUPPORTED_CAPABILITY/ DAEMON_CREDENTIALS or DAEMON_PROXY); "" means none.
  • accountLookahead and subaddressLookahead, where accepted, come as a pair (LOOKAHEAD_PAIR), each an integer from 1 (LOOKAHEAD_RANGE), each and their product at most 20,000 (LOOKAHEAD_LIMIT), all INVALID_CONFIG.

createRandomWallet#

Declaration
function createRandomWallet(raw: unknown, options?: ZephyrWalletConstructionOptions): Promise<ZephyrWallet>;

Creates a random full wallet. Accepted fields: networkType, password (default ""), language (the seed language, default English), accountLookahead, subaddressLookahead, proxyToWorker, server. With a daemon that answers the connection check, the restore height is the daemon height; otherwise it is the core's date-based estimate, about a month of blocks below the chain tip.

Rejects with: INVALID_CONFIG/CREATE_MODE when a seed or key field is present, RANDOM_RESTORE_HEIGHT when restoreHeight is given, CORE_UNKNOWN_LANGUAGE for an unknown language, SEED_OFFSET for a seedOffset; and the shared rejections above.

Guide: Creating a random wallet.

restoreWalletFromSeed#

Declaration
function restoreWalletFromSeed(raw: unknown, options?: ZephyrWalletConstructionOptions): Promise<ZephyrWallet>;

Restores a full wallet from a seed; it never falls back to a random wallet. Accepted fields: networkType, password, seed (required), seedOffset, restoreHeight (a safe integer from 0, default 0), accountLookahead, subaddressLookahead, proxyToWorker, server. Spaces in the seed are normalized.

Rejects with: INVALID_CONFIG/CREATE_MODE without a seed, SEED_AND_KEYS with key fields, SEED_LANGUAGE with a language, RESTORE_HEIGHT_RANGE; INVALID_RECOVERY_MATERIAL/SEED_EMPTY or SEED_WORD_COUNT (not 12, 13, 24 or 25 words), and INVALID_RECOVERY_MATERIAL when the core rejects the seed; and the shared rejections.

Guide: Restoring from a seed.

restoreWalletFromKeys#

Declaration
function restoreWalletFromKeys(raw: unknown, options?: ZephyrWalletConstructionOptions): Promise<ZephyrWallet>;

Restores a full wallet from keys; it never falls back to a random wallet. Accepted fields: networkType, password, primaryAddress, privateViewKey, privateSpendKey, restoreHeight, language, accountLookahead, subaddressLookahead, proxyToWorker, server. A private spend key gives a wallet that can spend; an address with a private view key gives a view-only wallet.

Rejects with: INVALID_CONFIG/CREATE_MODE without any key field or with a seed; INVALID_RECOVERY_MATERIAL with KEY_EMPTY, KEY_FORMAT (not 64 hexadecimal characters), VIEW_KEY_WITHOUT_ADDRESS, KEYS_MISSING (neither an address nor a spend key), or when the core rejects the keys (for example CORE_INVALID_KEY, CORE_INVALID_ADDRESS); and the shared rejections.

Guide: Restoring from keys.

createKeysWallet#

Declaration
function createKeysWallet(raw: unknown, options?: ZephyrWalletConstructionOptions): Promise<ZephyrWallet>;

Creates a keys-only wallet: random without recovery fields, from a seed (with an optional seedOffset), or from keys, chosen by the fields present. It has no password, restore height, lookahead, daemon or bytes. Accepted fields: networkType, seed, seedOffset, primaryAddress, privateViewKey, privateSpendKey, language, proxyToWorker, and password (accepted; a keys-only wallet has no password).

Rejects with: UNSUPPORTED_CAPABILITY/KEYS_ONLY_DAEMON for a non-empty server, KEYS_ONLY_RESTORE_HEIGHT for restoreHeight, KEYS_ONLY_LOOKAHEAD for a lookahead; the seed and key rejections of the two restore functions; and the shared rejections.

Guide: Keys-only wallets.

openWalletData#

Declaration
function openWalletData(raw: unknown, options?: ZephyrWalletConstructionOptions): Promise<ZephyrWallet>;

Opens a full wallet from its keys and cache bytes, as returned by getData. Accepted fields: networkType, password, keysData (a non-empty Uint8Array, required), cacheData (a Uint8Array, optional), proxyToWorker, server. No lookahead field: the bytes carry their own.

Rejects with: INVALID_WALLET_DATA/WALLET_BYTES for missing or non-byte data, WRONG_PASSWORD for a wrong password, INVALID_WALLET_DATA for bytes that do not open (damaged, of another network); and the shared rejections.

Guide: Saving and opening wallet bytes.

Utilities#

validateAddress#

Declaration
function validateAddress(address: unknown, networkType: ZephyrNetworkTypeInput, proxyToWorker?: boolean): Promise<void>;

Checks an address with the core's own parser for a network type. Resolves when it is valid. By default it runs in a utility worker; with proxyToWorker false in the calling context. In Node.js the utility worker keeps the process alive until terminateWorker is called.

Rejects with: INVALID_ADDRESS/ADDRESS_TYPE for an empty or non-string address, INVALID_ADDRESS (for example CORE_INVALID_ADDRESS) for a malformed address or one of another network, INVALID_CONFIG/NETWORK_TYPE, INVALID_CONFIG/FIELD_TYPE for a non-boolean third argument.

Guide: Validating an address.

setWorkerDistPath#

Declaration
function setWorkerDistPath(path: string): void;

Sets where the wallet worker script is loaded from: a URL in the browser (default: the zephyr.worker.js beside the browser entry, which a bundler emits and rewrites), a file path in Node.js (default: the file in the package). Call it before the first construction. The worker script must have the page's origin. The declaration comment says that calling it without an argument restores the default, but the declared parameter is required.

Throws nothing documented; a wrong location shows at the next construction (NATIVE_ERROR/ WORKER_FAILED).

Guide: Where the WebAssembly module and the worker come from.

setWasmModuleUrl#

Declaration
function setWasmModuleUrl(location?: string): void;

Sets where zephyr.wasm is loaded from: a URL in the browser (default: the file beside the browser entry), a file path in Node.js (default: the file in the package). Without an argument the default is restored. The module is compiled once per runtime and shared with every wallet worker; set the location before the first construction.

A missing or unusable file rejects the first construction with NATIVE_ERROR and WASM_MODULE_UNAVAILABLE, WASM_MODULE_UNVERIFIED, WASM_MODULE_MISMATCH or WASM_MODULE_REJECTED.

Guide: Serving zephyr.wasm.

terminateWorker#

Declaration
function terminateWorker(): Promise<void>;

Terminates every worker the library started in this runtime: the utility worker, running constructions and the worker of every open worker-mode wallet, and rejects queued constructions. Open worker-mode wallets lose their native state without a native close: later calls reject with WALLET_CLOSED and close() resolves. Pending constructions reject with NATIVE_ERROR/CONSTRUCTION_ABORTED, other pending calls with WALLET_CLOSED. Direct-mode wallets are not affected. Call it when the program or page shuts down.

Guide: Stopping a wallet at once.