zephyr-java user guide
This guide explains how to use zephyr-java in an application. It covers desktop and server JVMs with the JAR, and Android apps with the AAR. It assumes you know Java; it does not assume you know monero-java. The README has the coordinates and a complete quick-start program. The API reference is the Javadoc of the current release.
Not affiliated with ZephyrProtocol. An independent project.
This guide describes version 2.3.0-sec.2-java.4.
| Chapter | What it covers |
|---|---|
| 1. Getting started | what zephyr-java is and is not, requirements, the JAR and the AAR, the native library on the desktop, a first program |
| 2. Wallets | network types, create, restore, view-only, open from files, bytes or a config, the password, when to save, close, addresses and keys |
| 3. Connecting to a node | the connection and its URI, http and https, TLS and ZephyrTls, the remote-node trade-off, syncing, heights, an unreachable node |
| 4. Threads and listeners | blocking calls, the threads callbacks run on, the five callbacks, exceptions in callbacks, closing during a sync, several threads, what is not known |
| 5. Assets, accounts and balances | ZPH, ZSD, ZRS, ZYS and the V1 names, amounts and their conversion, ZephyrBalance, the four balance shapes, accounts, subaddresses and labels, locked and unlocked |
| 6. History | transactions and transfers per asset, queries, the pool, conversions in the history, notes and keys, outputs and their asset, payment checks |
| 7. Sending | the currency pair, create then relay, what to show, fees and priorities, several destinations, sweeps, failures, saving after a send |
| 8. Conversions and the reserve | the ten pairs, the reserve-ratio rules, every field of ZephyrReserveInfo, the six supply keys, building a conversion, the mint formula, converting everything, what was tested |
| 9. Errors and exceptions | ZephyrError, where messages come from, the other exception types, the messages a wallet meets, logging safely, the native log |
| 10. Android | the dependency and the packaging line, devices, ABIs and sizes, the RPC classes below API 26, the network, storage, backup, lifecycle, logs, a first test on a device, R8 rules |
| 11. The RPC classes | ZephyrDaemonRpc and the pricing record, ZephyrWalletRpc as a first pass, ZephyrRpcError, dependencies |
| 12. Coming from monero-java | the renaming rules, what is different, both libraries in one program |
| 13. Known limitations | every limitation with its status and a link, what was tested and what was not |
| 14. Building and verifying | the pins, the root certificates, the patches, the builds, reproducibility, the manifest, signatures, reproducing a release, the guide's site |
Conventions#
- Fragments. A short Java block that uses
walletmeans an openZephyrWalletFull; the block does not show how it was opened. - Compiled examples. A block whose label is "Java, compiled" on the site (info string
java examples/<Class>.javain the Markdown) is copied from that class insrc/test/java/examples/. The class is compiled with everymvn test, and the testTestExamplesfails when the block and the class differ. Other blocks are fragments and are not compiled. - Placeholders. Values you supply are written in angle brackets, such as
<version>, and explained below the block. Example hosts end in.example.invalid. - Amounts. Every amount in the API is a
BigIntegerin atomic units, 10^12 per coin for every asset. Prose names amounts in coins with the asset's ticker after the number. - Dates. Dates are absolute and in UTC. A statement about a release names that release.
Where the statements come from#
Statements about the Zephyr core come from the pinned sources and from test runs against mainnet. Those runs took place from 2026-11-06 to 2026-11-10, during the work on the releases up to 2.3.0-sec.2-java.4. Each such statement names its date where it matters.
Statements marked "observed on 2026-11-17" come from runs against a mainnet node on Linux x86_64 (Debian 13, OpenJDK 21). Most used a developer build of the 2.3.0-sec.2-java.4 sources. Those marked "with the released JAR" used zephyr-java-2.3.0-sec.2-java.4.jar and its own native library. None of those runs was made on Android. One run is an observation, not a guarantee: a run that found no failure proves no safety.
Statements marked "read in the code" come from the source of this library or of the pinned core, not from a run. Where a fact is not known, the guide says so.