Skip to main content
zephyr-java

Java wallet library for Zephyr, a lateo project

13. Known limitations

These are the limits a wallet app runs into with 2.3.0-sec.2-java.4. Most come from the Zephyr core (zephyr-cpp and wallet2), which zephyr-java builds unchanged. The backports change the core only for security fixes, so functional gaps stay until the core itself changes. Each row says what happens, its status, and where the details are. The rest of the guide explains each one where its topic is.

Status words:

  • core: behaviour of the Zephyr core;
  • open: not fixed;
  • observed: the run that showed it, with its date;
  • not tested: nobody ran it against Zephyr.

The core#

LimitationStatusDetails
checkTxKey and checkTxProof return amount 0 for every current transactioncore, open; confirmed on mainnet on 2026-11-07checkTxKey returns amount 0
getOutputs() reports no assetcore, open; getOutputAssetType from java.2 takes it from the transactiongetOutputs() reports no asset
getOutputAssetType reads a split conversion to one's own account as the source assetcore, opengetOutputs() reports no asset
the asset of an output notification in the pool is emptycore, stays; observed on mainnet on 2026-11-07Outputs in the pool carry no asset
changePassword fails for a wallet opened from bytescore; confirmed on mainnetThe password
save() and close(true) write nothing for a wallet without a path, and report no errorcore, read in the codeWallet bytes
sweepOutput validates with ZEPH and is most likely unusablecore, read in the code; not testedSweeping
sweepUnlocked without an account index sweeps every account with an unlocked balance in the source assetcore, read in the codeSweeping
every node is treated as trusted (monero's trusted-daemon mode), and its error text can reach exception messagescore, read in the codeA remote node
sync() against a node that is still syncing returns 0 blocks without an errorcore, read in the code; not runSyncing
background syncing reports no errors to the appcore, read in the codeBackground sync
a conversion's pricing record must be at most 10 blocks old when the chain includes itnetwork rule, read in the codeBuilding a conversion
testnet and stagenet never reach the V2 rulescore network tablesNetwork types
no certificate pinning; the host name must match; the Network Security Configuration does not applyneeds the coreWhat TLS cannot do

zephyr-java#

LimitationStatusDetails
close() from another thread during sync() crashes the processobserved on 2026-11-17 with the released JAR, 4 of 4 runs; openClosing a wallet that syncs
close() while background syncing scans leaves a native thread attached; the JVM does not exit, also with stopSyncing() right beforeobserved on 2026-11-17 with the released JAR, 3 of 3 and 2 of 2 runs; openClosing a wallet that syncs
no call reports whether a background scan is still running; stopSyncing() lets the batch in progress finishread in the code; openClosing a wallet that syncs
onOutputReceived and onOutputSpent repeat at confirmation and unlock; the spent notification at unlock is a summaryby design, in the Javadoc and the core's codeThe five callbacks
an exception from a callback during background syncing leaves a native thread attached; the JVM does not exitobserved on 2026-11-17 with the released JAR, 3 of 3 runs; openAn exception thrown in a callback
an exception from a callback during sync() is printed and swallowed, and skips the rest of that block's notificationsobserved on 2026-11-17An exception thrown in a callback
calls from several threads on one wallet are not known to be safenot establishedCalls from several threads
a wrong password in openWallet throws java.lang.Exception, not ZephyrErrorobserved on 2026-11-17, also with the released JAR; openWhere messages come from
many wallet calls, among them the balance calls, save and the account calls, let the core's java.lang.Exception throughread in the source; openCalls that let the core's exception through
an invalid account or subaddress index may end the process: some native calls do not catch the core's failureread in the code; not runCalls that let the core's exception through
close(true) does not catch a failing save in native coderead in the code; not runClosing
at FINE and from setLogLevel(2) the library logs transaction keys, passwords and mnemonicsread in the sourceLogging safely
ZephyrUtils.toAtomicUnits(double) throws below 0.001 and from 10^7, and truncates silentlyspecified Java behaviour; run on 2026-11-17Amounts
ZephyrRpcError.toString() prints the request parameters, which can hold passwordsopen in 2.3.0-sec.2-java.4; later releases redact themLogging safely
the RPC classes are a first pass: ZephyrWalletRpc serves the base coin onlyplanned workZephyrWalletRpc
the RPC classes need API 26, or core library desugaring on API 24 and 25by design of the HTTP clientThe RPC classes below API 26
the areas inherited from monero-java listed in chapter 1not testedWhat zephyr-java does and does not do

Wallets and their data#

LimitationStatusDetails
a view-only wallet's balance counts everything ever received once the wallet has spentobserved on 2026-11-17View-only wallets
the native log, when switched on, records the primary address, the wallet path, amounts and transaction hashes, and grows by a line per block with a listenerobserved on 2026-11-17 on the desktop, the content also with the released JARThe native log

Platforms, building and packaging#

LimitationStatusDetails
no packaged native libraries for macOS and Windowsnot packaged in 2.3.0-sec.2-java.4The native library
the Linux JAR needs glibc 2.36 or newerrelease natives built on Debian 12Linux: the glibc floor
the armeabi-v7a library needs a CPU with VFPv4; there is no 32-bit x86 librarybuild choiceDevices
the Android natives are reproducible at the same build path onlyNDK r18bReproducibility

What was tested#

  • On mainnet with real funds, on the desktop: create, open, sync, balances per asset, transfers, a ZPH → ZRS conversion and sweeps. Five transactions were verified on the node. Conversions other than ZPH → ZRS were not run (What was tested).
  • On the Android emulator: see below.
  • On Linux x86_64 on 2026-11-17, with a developer build of the 2.3.0-sec.2-java.4 sources: listener exceptions, closing during a sync and reads from several threads. Also the messages of createTxs, the native log, a view-only wallet, moveTo, the heights and the amount helpers. The closing runs, the listener exceptions under background syncing, the wrong password and the native log's content were repeated that day with the released JAR.
  • The coexistence with monero-java in one JVM (Both libraries in one program).

Where it has run. The x86_64 library ran on the Android emulator as a release check. It ran on API 24 and on API 35 with 16 KB pages, in debug builds (so under ART's CheckJNI). There:

  • the native library loads, and an offline wallet works;
  • a wallet restored from its mnemonic syncs against a mainnet node and opens again from its bytes;
  • ZephyrDaemonRpc reads the node (on API 24 with desugaring);
  • https:// to a mainnet node with a publicly signed certificate works without setup (the shipped root certificates), on API 24 and on API 35 with 16 KB pages;
  • with the system store alone it works on API 35 and fails on API 24, which lacks ISRG Root X1.

The arm64-v8a and armeabi-v7a libraries are built and checked the same way (exports, page alignment, packaging). They had not run on hardware by release 2.3.0-sec.2-java.4 (2026-11-10).

What was not tested#

  • the conversions other than ZPH → ZRS on mainnet;
  • the ARM libraries for Android on hardware;
  • the Linux arm64 library, which is built and checked but has not been run;
  • any of the observations of 2026-11-17 on Android, and configureNativeLogging on Android;
  • the areas inherited from monero-java listed in What zephyr-java does and does not do;
  • a node that refuses a relayed transaction, and the message for funds that are not unlocked;
  • a large history, and a first sync over the internet from an old restore height.