ZephyrWallet
class ZephyrWallet
The wallet class. Instances come from the construction functions (functions); the constructor is private. Every method that returns a promise rejects with a ZephyrWalletError. Rules that hold for all of them:
- After
close()orterminate(), every call rejects withWALLET_CLOSED(after a forced stop with the diagnosticWALLET_TERMINATED). - A wallet's calls run one at a time, in order. Arguments are checked before anything is dispatched.
- Calls that need a full wallet reject on a keys-only wallet with
UNSUPPORTED_CAPABILITYand the diagnostic named in the entry (KEYS_ONLY_*). - Account and subaddress indices are integers from 0 to 2^32-1 (
INVALID_CONFIG/ADDRESS_INDEX_RANGE). - Results are frozen plain objects and arrays; amounts are
bigintin atomic units.
Properties#
kind#
readonly kind: "full" | "keys";
"full" for a wallet from createRandomWallet, restoreWalletFromSeed, restoreWalletFromKeys or openWalletData; "keys" for one from createKeysWallet. Guide: Kinds of wallets.
proxied#
readonly proxied: boolean;
true when the wallet runs in its own worker (proxyToWorker, the default). Guide: One worker per wallet.
wrap#
static wrap(inner: InnerWallet, kind: "full" | "keys", proxied: boolean, daemon?: ZephyrDaemonRoute): ZephyrWallet;
Marked @internal in the declarations: the construction functions use it to create the facade. Its parameter types are not exported. Applications do not call it.
Lifecycle#
isClosed#
isClosed(): boolean;
Whether close() or terminate() was called. Synchronous; never throws. Guide: Closing a wallet.
close#
close(): Promise<void>;
Idempotent close. New calls reject with WALLET_CLOSED from the moment it is called; queued calls that have not started reject with WALLET_CLOSED; a running call finishes first. Concurrent calls share one attempt. It does not save. Resolves after a forced stop.
Rejects with: NATIVE_ERROR/CORE_CLOSE_FAILED when the native close fails; the wallet stays closed to new work and a later close() retries. Guide: Closing a wallet.
terminate#
terminate(): Promise<void>;
Forced stop of a worker-mode wallet: its worker is ended at once, without a native close and without waiting for a running call. Unsaved state is lost. Every pending and later call rejects with WALLET_CLOSED/WALLET_TERMINATED; close() resolves. Idempotent; after a completed close it does nothing.
Rejects with: UNSUPPORTED_CAPABILITY/TERMINATE in direct mode. Guide: Stopping a wallet at once.
getData#
getData(): Promise<ZephyrWalletData>;
The wallet's keys and cache bytes, encrypted with the wallet password, for you to store. No file is written. Encrypts afresh on every call.
Rejects with: UNSUPPORTED_CAPABILITY/KEYS_ONLY_DATA. Guide: Saving and opening wallet bytes.
changePassword#
changePassword(oldPassword: string, newPassword: string): Promise<void>;
Re-encrypts in memory; the next getData() carries the new password. The library verifies the old password. Changes issued without awaiting run in order. Voids a kept build.
Rejects with: INVALID_CONFIG/PASSWORD_TYPE for a non-string; WRONG_PASSWORD for a wrong old password (nothing changes); NATIVE_ERROR/PASSWORD_CHANGED_WITH_ERROR (the new password was adopted); NATIVE_ERROR/PASSWORD_STATE_UNKNOWN, after which every call but close rejects with that diagnostic; UNSUPPORTED_CAPABILITY/KEYS_ONLY_PASSWORD. Guide: The password.
Keys and addresses#
getPrimaryAddress#
getPrimaryAddress(): Promise<string>;
The address of account 0, subaddress 0. Full and keys-only wallets. Guide: A first program in Node.js.
getAddress#
getAddress(accountIdx: number, subaddressIdx: number): Promise<string>;
The address of a subaddress. Full and keys-only wallets.
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE. Guide: Accounts and subaddresses.
getAddressIndex#
getAddressIndex(address: string): Promise<ZephyrAddressIndex>;
The account and subaddress an address of this wallet belongs to; also subaddresses of the lookahead window that were not created yet.
Rejects with: INVALID_ADDRESS/ADDRESS_TYPE (not a string, empty or longer than 256), INVALID_ADDRESS/CORE_INVALID_ADDRESS (malformed or another network), INVALID_ADDRESS/ADDRESS_NOT_IN_WALLET, UNSUPPORTED_CAPABILITY/KEYS_ONLY_ACCOUNTS. Guide: Accounts and subaddresses.
getNetworkType#
getNetworkType(): Promise<number>;
0 (mainnet), 1 (testnet) or 2 (stagenet).
Rejects with: UNSUPPORTED_CAPABILITY/KEYS_ONLY_NETWORK_TYPE. Guide: Network types.
getSeed#
getSeed(): Promise<string>;
The 25-word seed. Full and keys-only wallets. A view-only wallet has no seed; with the release package the promise resolves to undefined in that case. Guide: Creating a random wallet.
getSeedLanguage#
getSeedLanguage(): Promise<string>;
The language of the seed, for example "English". Full and keys-only wallets.
getPrivateViewKey#
getPrivateViewKey(): Promise<string>;
The private view key, 64 hexadecimal characters. Full and keys-only wallets. Guide: Restoring from keys.
getPrivateSpendKey#
getPrivateSpendKey(): Promise<string>;
The private spend key, 64 hexadecimal characters. Full and keys-only wallets. A view-only wallet has none; with the release package the promise resolves to undefined in that case. Guide: Restoring from keys.
getPublicViewKey#
getPublicViewKey(): Promise<string>;
The public view key, 64 hexadecimal characters. Full and keys-only wallets.
getPublicSpendKey#
getPublicSpendKey(): Promise<string>;
The public spend key, 64 hexadecimal characters. Full and keys-only wallets.
isViewOnly#
isViewOnly(): Promise<boolean>;
Whether the wallet has no private spend key. Guide: Kinds of wallets.
getRestoreHeight#
getRestoreHeight(): Promise<number>;
The height the first sync starts from, as a safe integer.
Rejects with: UNSUPPORTED_CAPABILITY/KEYS_ONLY_RESTORE_HEIGHT; NATIVE_ERROR/ RESTORE_HEIGHT_UNREPRESENTABLE for a height above Number.MAX_SAFE_INTEGER. Guide: Creating a random wallet.
Daemon#
All daemon methods are for full wallets; keys-only wallets reject with UNSUPPORTED_CAPABILITY/KEYS_ONLY_DAEMON. Daemon failures reject with DAEMON_ERROR and DAEMON_NOT_CONNECTED, DAEMON_UNREACHABLE or DAEMON_RESPONSE.
setDaemonConnection#
setDaemonConnection(address?: string | {
uri: string;
trusted?: boolean;
}): Promise<void>;
Sets the daemon, or clears it with undefined. Resolves when the core holds the address; an unreachable daemon is not an error here. A kept build survives it.
Rejects with: INVALID_CONFIG/DAEMON_ADDRESS, CONFIG_TYPE, FIELD_TYPE, UNKNOWN_FIELD; UNSUPPORTED_CAPABILITY/DAEMON_CREDENTIALS, DAEMON_PROXY, UNTRUSTED_DAEMON (trusted: false), CONFIG_FIELD (rejectUnauthorized). Guide: Setting the daemon.
getDaemonConnection#
getDaemonConnection(): ZephyrDaemonConnection | undefined;
The daemon address the library holds, normalized, with trusted: true, or undefined. Synchronous; no request; never throws.
isConnectedToDaemon#
isConnectedToDaemon(): Promise<boolean>;
Whether the core reaches the configured daemon now; a request. false without a daemon or when it is unreachable. Guide: Setting the daemon.
getDaemonHeight#
getDaemonHeight(): Promise<number>;
The daemon's height; a request. Guide: Heights.
isDaemonSynced#
isDaemonSynced(): Promise<boolean>;
Whether the daemon reports itself synchronized with the network (its height is at least the highest height of its peers, and above 1); a request. A daemon that is not synchronized makes a sync fetch nothing. Guide: Synchronizing.
getHeight#
getHeight(): Promise<number>;
The wallet's height; no request. Guide: Heights.
sync#
sync(startHeight?: number): Promise<ZephyrWalletSyncResult>;
One blocking synchronization, from startHeight or from the core's default start. Other calls of the wallet wait for it. A kept build is voided if the wallet's height afterwards differs from the height at the build by more than 10 blocks.
Rejects with: INVALID_CONFIG/SYNC_START_HEIGHT (not a safe integer from 0), UNSUPPORTED_CAPABILITY/SYNC (more than one argument), DAEMON_ERROR, NATIVE_ERROR/SYNC_FAILED. Guide: Synchronizing.
refreshPool#
refreshPool(): Promise<number>;
Asks the daemon for its pool and updates the wallet's view of its incoming unconfirmed transfers; resolves with the number of incoming pool transactions the wallet holds (at most 1,000). Requests /get_transaction_pool_hashes.bin and /gettransactions.
Rejects with: INVALID_CONFIG/FIELD_TYPE (an argument), INVALID_CONFIG/LISTING_LIMIT, DAEMON_ERROR, UNSUPPORTED_CAPABILITY/KEYS_ONLY_DAEMON. Guide: Incoming transfers in the pool.
Balances#
getBalance#
getBalance(): Promise<ZephyrAssetBalances>;
getBalance(accountIdx: number): Promise<ZephyrAccountBalances>;
getBalance(assetType: string, accountIdx: number, subaddressIdx?: number): Promise<bigint>;
The wallet's balance by asset (the core's keys, zeros included); an account's balances by subaddress index (only what the core reports); or one asset's balance in an account or subaddress. No request.
Rejects with: INVALID_CONFIG/ASSET_TYPE, ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, SUBADDRESS_NOT_FOUND, FIELD_TYPE (other argument shapes); UNSUPPORTED_CAPABILITY/BALANCE for the asset-less (accountIdx, subaddressIdx) form; UNSUPPORTED_CAPABILITY/KEYS_ONLY_DAEMON. Guide: Balances.
getUnlockedBalance#
getUnlockedBalance(): Promise<ZephyrAssetBalances>;
getUnlockedBalance(accountIdx: number): Promise<ZephyrAccountBalances>;
getUnlockedBalance(assetType: string, accountIdx: number, subaddressIdx?: number): Promise<bigint>;
The spendable balance, in the same three shapes and with the same rejections as getBalance. Guide: Unlocked balance.
Accounts and subaddresses#
Full wallets only; keys-only wallets reject with UNSUPPORTED_CAPABILITY/KEYS_ONLY_ACCOUNTS. Labels are strings of at most 255 UTF-8 bytes without control characters or unpaired surrogates (INVALID_CONFIG: LABEL_TYPE, LABEL_LENGTH, LABEL_CHARACTERS). Guide: Accounts and subaddresses.
getAccounts#
getAccounts(options?: ZephyrAccountOptions): Promise<ReadonlyArray<ZephyrAccount>>;
Every account in index order; with { includeSubaddresses: true } each with its subaddresses.
Rejects with: INVALID_CONFIG/LISTING_LIMIT (more than 1,000 accounts, or more than 1,000 subaddresses in total), and INVALID_CONFIG for malformed options.
getAccount#
getAccount(accountIdx: number, options?: ZephyrAccountOptions): Promise<ZephyrAccount>;
One account; with { includeSubaddresses: true } its subaddresses (at most 1,000).
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, LISTING_LIMIT.
createAccount#
createAccount(label?: string): Promise<ZephyrAccount>;
Creates one account with an optional label (default "") and returns it.
Rejects with: the label rejections.
getSubaddresses#
getSubaddresses(accountIdx: number, subaddressIndices?: readonly number[]): Promise<ReadonlyArray<ZephyrSubaddress>>;
Every subaddress of an account in index order (at most 1,000), or the given indices in the given order: a non-empty array of at most 1,000 distinct indices.
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, SUBADDRESS_NOT_FOUND, SUBADDRESS_INDICES, LISTING_LIMIT.
getSubaddress#
getSubaddress(accountIdx: number, subaddressIdx: number): Promise<ZephyrSubaddress>;
One subaddress.
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, SUBADDRESS_NOT_FOUND.
createSubaddress#
createSubaddress(accountIdx: number, label?: string): Promise<ZephyrSubaddress>;
Creates one subaddress of an account with an optional label (default "") and returns it.
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, the label rejections.
setSubaddressLabel#
setSubaddressLabel(accountIdx: number, subaddressIdx: number, label: string): Promise<void>;
Sets, or with "" clears, the label of a subaddress; subaddress 0 carries the account's label.
Rejects with: INVALID_CONFIG/ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, SUBADDRESS_NOT_FOUND, the label rejections.
History#
Full wallets only; keys-only wallets reject with UNSUPPORTED_CAPABILITY/KEYS_ONLY_HISTORY. No request is sent. Guide: History.
getTxs#
getTxs(query?: ZephyrHistoryQuery): Promise<ReadonlyArray<ZephyrWalletTx>>;
The wallet's transactions: confirmed by height then hash, unconfirmed after them. With transfer filters, the transactions with at least one matching transfer, each with all of its transfers.
Rejects with: INVALID_CONFIG and CONFIG_TYPE, UNKNOWN_FIELD, FIELD_TYPE, ASSET_TYPE, ADDRESS_INDEX_RANGE, QUERY_ACCOUNT_REQUIRED, HEIGHT_RANGE, TX_HASHES, TX_HASH, TX_NOT_FOUND, LISTING_LIMIT (more than 1,000 transactions or 2,000 transfers). Guide: The query.
getTransfers#
getTransfers(query?: ZephyrHistoryQuery): Promise<ReadonlyArray<ZephyrWalletTransfer>>;
The transfers that match the query; per transaction the outgoing transfer first, then the incoming ones. Same rejections as getTxs. Guide: Transfers.
getTx#
getTx(hash: string): Promise<ZephyrWalletTx>;
One transaction by its hash.
Rejects with: INVALID_CONFIG/TX_HASH (not 64 lowercase hexadecimal characters), INVALID_CONFIG/TX_NOT_FOUND (also for an incoming pool transaction the last refreshPool did not see). Guide: The query.
Building and relaying#
Full wallets with spend keys only: keys-only wallets reject with UNSUPPORTED_CAPABILITY/KEYS_ONLY_TX, view-only wallets with UNSUPPORTED_CAPABILITY/VIEW_ONLY_TX. A second argument rejects with INVALID_CONFIG/FIELD_TYPE.
buildTransfer#
buildTransfer(config: ZephyrTransferConfig): Promise<ZephyrTransferBuild>;
Builds the transactions of a same-asset transfer, describes them and discards them. Nothing is relayed or stored.
Rejects with: INVALID_CONFIG (CONFIG_TYPE, UNKNOWN_FIELD, FIELD_TYPE, ASSET_TYPE, TX_ASSET, DESTINATIONS, TOO_MANY_DESTINATIONS, AMOUNT_ZERO, AMOUNT_RANGE, ADDRESS_INDEX_RANGE, ACCOUNT_NOT_FOUND, SUBADDRESS_INDICES, SUBADDRESS_NOT_FOUND, TX_PRIORITY); INVALID_ADDRESS (ADDRESS_TYPE, CORE_INVALID_ADDRESS, ADDRESS_NETWORK); UNSUPPORTED_CAPABILITY (CONVERSION, INTEGRATED_ADDRESS); TX_NOT_POSSIBLE (NOT_ENOUGH_UNLOCKED, NOT_ENOUGH_MONEY, NOT_ENOUGH_FOR_FEE, NOT_ENOUGH_OUTS_TO_MIX, TX_TOO_LARGE); DAEMON_ERROR; NATIVE_ERROR/TX_BUILD_FAILED. Guide: Building to inspect.
buildConversion#
buildConversion(config: ZephyrConversionConfig): Promise<ZephyrConversionBuild>;
Builds the one transaction of a conversion between two V2 assets, describes it and discards it.
Rejects with: the configuration rejections of buildTransfer as they apply, INVALID_CONFIG/ CONVERSION_PAIR, CONVERSION_DESTINATIONS, AMOUNT_PRECISION; TX_NOT_POSSIBLE (RESERVE_RATIO, PRICING_RECORD, CONVERSION_SPLIT, CONVERSION_AMOUNT, and the build failures of buildTransfer); DAEMON_ERROR; NATIVE_ERROR/TX_BUILD_FAILED. Guide: What a conversion build describes.
prepareTransfer#
prepareTransfer(config: ZephyrTransferConfig): Promise<ZephyrPreparedTransfer>;
As buildTransfer, but keeps the built transactions in the wallet's one slot under a new token; the previous kept build is voided, also when this prepare fails. Nothing is relayed. Same rejections as buildTransfer. Guide: Preparing and relaying.
prepareConversion#
prepareConversion(config: ZephyrConversionConfig): Promise<ZephyrPreparedConversion>;
As buildConversion, but keeps the built transaction under a new token. Same rejections as buildConversion. Guide: Relaying a conversion.
relayPrepared#
relayPrepared(token: string): Promise<ZephyrRelayResult>;
Relays exactly the kept build the token names, one POST /sendrawtransaction per transaction to the wallet's configured daemon. Resolves when at least one transaction was accepted in this call.
Rejects with: INVALID_CONFIG/RELAY_TOKEN (not a token), RELAY_TOKEN_VOID; TX_NOT_POSSIBLE/PRICING_RECORD_AGE; TX_REJECTED with the daemon's first reason; DAEMON_ERROR/DAEMON_BUSY, DAEMON_UNREACHABLE; RELAY_UNKNOWN/NO_ANSWER, HTTP_STATUS, ANSWER_UNREADABLE; NATIVE_ERROR/RELAY_HASH_MISMATCH, RELAY_REQUEST, RELAY_FAILED. Guide: Outcomes of a relay.
discardPrepared#
discardPrepared(token: string): Promise<boolean>;
Voids the kept build the token names (wiped and released inside the module); false when it named none.
Rejects with: INVALID_CONFIG/RELAY_TOKEN. Guide: The life of a kept build.
Unsupported inherited calls#
These names remain from monero-ts so that a port finds them. Each rejects with UNSUPPORTED_CAPABILITY before any native code runs. Guide: What is not ported.
startSyncing#
startSyncing(): Promise<never>;
Background synchronization. Rejects with UNSUPPORTED_CAPABILITY/SYNC.
createTxs#
createTxs(): Promise<never>;
The inherited transaction creation. Rejects with UNSUPPORTED_CAPABILITY/TRANSACTIONS.
addListener#
addListener(): Promise<never>;
Listeners. Rejects with UNSUPPORTED_CAPABILITY/LISTENERS.
getReserveProofWallet#
getReserveProofWallet(): Promise<never>;
Reserve proofs. Rejects with UNSUPPORTED_CAPABILITY/RESERVE_PROOF.
rescanSpent#
rescanSpent(): Promise<never>;
Spent-output rescans. Rejects with UNSUPPORTED_CAPABILITY/DAEMON_SETTINGS.
importKeyImages#
importKeyImages(): Promise<never>;
Key image import. Rejects with UNSUPPORTED_CAPABILITY/DAEMON_SETTINGS.