Skip to main content
zephyr-ts

TypeScript wallet library for Zephyr, a lateo project

10. Coming from monero-ts

zephyr-ts is a port of monero-ts v0.11.22 (commit f6569ca616c4723645a7bfae3a843a0358f5fca9), and the git history of monero-ts is kept in its repository. Unlike a rename, though, the package exports a small, new entry: one wallet class, a few functions and plain result types. This chapter lists what stays the same, what was renamed or reshaped, and what is not ported.

What is the same#

  • The core and its rules. Keys, seeds, addresses, wallet bytes, fees, ring sizes and synchronization are decided by the wallet core (wallet2), as in monero-ts, here Zephyr's.
  • Wallet bytes. getData() returns the keys and cache bytes and openWalletData opens them, like openWalletFull({ keysData, cacheData }).
  • Workers and WebAssembly. Wallets run in workers by default (proxyToWorker), and the module is WebAssembly.
  • Familiar names for the wallet getters: getPrimaryAddress, getAddress, getSeed, getSeedLanguage, getPrivateViewKey, getPrivateSpendKey, getPublicViewKey, getPublicSpendKey, isViewOnly, getNetworkType, getRestoreHeight, getHeight, getDaemonHeight, isConnectedToDaemon, setDaemonConnection, sync, changePassword, close, getAccounts, getAccount, createAccount, getSubaddresses, getSubaddress, createSubaddress, setSubaddressLabel, getAddressIndex, getTxs, getTransfers, getTx. Their arguments and results differ in many cases (below).
  • Amounts are bigint in atomic units, 10^12 per coin.
  • The construction configuration keeps the field names of MoneroWalletConfig that it supports: networkType, password, seed, seedOffset, primaryAddress, privateViewKey, privateSpendKey, restoreHeight, language, accountLookahead, subaddressLookahead, proxyToWorker, server, keysData, cacheData.

What was renamed or reshaped#

monero-tszephyr-ts
moneroTs.createWalletFull(config)createRandomWallet, restoreWalletFromSeed or restoreWalletFromKeys: one function per intent; the wrong fields reject
moneroTs.openWalletFull({ keysData, cacheData })openWalletData({ keysData, cacheData }); no path
moneroTs.createWalletKeys(config)createKeysWallet(config)
MoneroWalletFull, MoneroWalletKeysone class, ZephyrWallet, with kind "full" or "keys"
MoneroErrorZephyrWalletError with a fixed code and diagnostic, no native text
MoneroUtils.validateAddress(address, networkType)validateAddress(address, networkType)
LibraryUtils.setWorkerDistPath(path)setWorkerDistPath(path), and setWasmModuleUrl(location) for the separate module
moneroTs.shutdown()terminateWorker()
MoneroNetworkType.MAINNET"mainnet" or 0
getBalance(accountIdx?, subaddressIdx?): one bigintgetBalance(): a map by asset; getBalance(accountIdx): a map by subaddress index; getBalance(asset, accountIdx, subaddressIdx?): one bigint
getTxs(query) with MoneroTxQuery, results MoneroTxWalletgetTxs(query) with ZephyrHistoryQuery, results frozen plain objects
MoneroAccount, MoneroSubaddress model classesZephyrAccount, ZephyrSubaddress plain objects with balance maps
sync(listener?, startHeight?)sync(startHeight?); no listener
createTx(config) and relayTx(...)buildTransfer(config) to inspect; prepareTransfer(config) and relayPrepared(token) to send
getDaemonConnection(): a connection objectgetDaemonConnection(): { uri, trusted: true }, without a request
one shared worker for all walletsone worker per wallet, with terminate() for one wallet

The package has named exports only. import * as zephyr from "@loki-notfound/zephyr-ts" works; there is no moneroTs-style default object with model classes.

Differences that are not renames:

  • Balances are per asset. Every balance is a map or names an asset; the asset-less two-number form rejects with UNSUPPORTED_CAPABILITY/BALANCE (chapter 4).
  • No file system. There is no path and no fs; a file path rejects with UNSUPPORTED_CAPABILITY/FILE_PATH. close() takes no argument and never saves.
  • Strict configurations. The core's configuration parser ignores keys it does not know, and an empty seed without keys makes it create a random wallet. zephyr-ts checks every field first: an unknown field rejects with INVALID_CONFIG/UNKNOWN_FIELD, and a restore never falls back to a random wallet.
  • A different transport. The daemon address takes no user name, password, proxy or certificate setting; redirects are not followed; every daemon is trusted by the core (chapter 3).
  • Errors carry no text. Code that matched on err.message must match on err.code and err.diagnostic instead (chapter 8).
  • Sending is two steps. There is no relay: true and no build-and-send call. A transaction is relayed only by relayPrepared with the token of a prepared build.
  • Assets and conversions. Transfers name an asset; conversions are their own calls (buildConversion, prepareConversion).

What is not ported#

Everything else inherited from monero-ts stays in the repository's source as unported classes and is not exported by the package:

  • the daemon and wallet RPC clients (connectToDaemonRpc, connectToWalletRpc, MoneroDaemonRpc, MoneroWalletRpc) and the connection manager;
  • listeners (addListener) and background synchronization (startSyncing);
  • the inherited query-based history model, transaction creation, its relay and sweeps;
  • outputs, key images, rescans, proofs and multisig;
  • file-system wallets.

A few inherited method names remain on ZephyrWallet and reject with UNSUPPORTED_CAPABILITY, so that a port finds them: startSyncing, createTxs, addListener, getReserveProofWallet, rescanSpent and importKeyImages.

TypeScript, checked and run offline
import { createRandomWallet, ZephyrWalletError } from "@loki-notfound/zephyr-ts";

const wallet = await createRandomWallet({ networkType: "mainnet", password: "a long passphrase" });
for (const call of [() => wallet.startSyncing(), () => wallet.createTxs(), () => wallet.addListener()]) {
  try {
    await call();
  } catch (err) {
    if (!(err instanceof ZephyrWalletError) || err.code !== "UNSUPPORTED_CAPABILITY") throw err;
    console.log(err.code, err.diagnostic);
  }
}
await wallet.close();

The repository's README, section "Not ported", names the source directories.