Repository navigation
v2.3.0-sec.2-java.1
The first release of zephyr-java: Java bindings for the Zephyr wallet core (zephyr-cpp over
Zephyr's wallet2), derived from monero-java at commit 53a54543 (2023-07-10), for Android (AAR)
and for desktop and server JVMs (JAR). The native core is linked statically into one library per
platform, libzephyr-java.so, which exports only its JNI entry points.
Built from
The core is built only from the tagged commits of the zephyr-backports forks:
| Tag | Commit | Tag subject | |
|---|---|---|---|
| zephyr | v2.3.0-sec.2 |
8c6a120256b4bd887d6e7167d929d76e3507e0e5 |
zephyr v2.3.0 + 30 security backports from Monero |
| zephyr-cpp | v2.3.0-sec.1 |
3a2ee602ee28e6b7941b617ad4706349ad992641 |
zephyr-cpp master (4a99272f6d7a171cf6625016939094637459975a) + 4 security backports from monero-cpp |
These two tags belong to the zephyr-backports release set of 2026-11-07, which also names
zephyr-javascript v2.3.0-sec.1 (7b17a14280bd84ca783287f4640b3c744d25319f) and zephyr-wallet
v2.3.0-sec.1 (edef8c0ee281024de1a718aa6dce39bce75f3687); zephyr-java does not build those two.
The backports number each fork on its own: sec.<N> in this release's version is zephyr's tag
number, and the zephyr-cpp tag is named here and in manifest.json (core.zephyr-cpp.tag, next
to core.release_set and its members).
All tags are signed with the zephyr-backports release key
FB39 94F0 997C A6F0 43D7 2491 9EFF 03F5 27D2 40A1. A build against ZephyrProtocol's original
of the same release (zephyr v2.3.0 = 67c5f53b878fef41fb5e74c4382d5b7a2f37fd8a, zephyr-cpp
4a99272f6d7a171cf6625016939094637459975a) is expected to work as well.
Platforms
- Android (
io.github.loki-notfound:zephyr-java-android, AAR): minSdk 24; native libraries
forarm64-v8a,armeabi-v7aandx86_64, 16 KB page aligned, stored uncompressed; consumer
R8 rules included.armeabi-v7aneeds a CPU with VFPv4. Built with NDK r18b through Zephyr's
owncontrib/depends. The AAR is built and checked (16 KB page alignment, uncompressed native
libraries) in a throwaway consumer app; it has not yet run on a device or an emulator. - Linux (
io.github.loki-notfound:zephyr-java, JAR): the native libraries forx86_64and
arm64inside the JAR, loaded from it. Built in a Debian 12 container (glibc 2.36 or newer:
Debian 12, Ubuntu 23.04 and later, RHEL 10); everything else is linked statically. Thearm64
library is built and checked, not yet run. - macOS and Windows: no packaged natives in this release.
The dependency
Android (Gradle, Kotlin DSL):
repositories {
maven { url = uri("https://loki-notfound.github.io/myzephyr-java/maven") }
}
android {
packaging { resources.excludes += "/META-INF/DEPENDENCIES" }
}
dependencies {
implementation("io.github.loki-notfound:zephyr-java-android:2.3.0-sec.2-java.1")
}The packaging line is required in every app: three of the Apache HTTP client's jars carry a
META-INF/DEPENDENCIES file, and the app's resource merge fails on the duplicates. Both the AAR
and the JAR bring the same three dependencies: jackson-core and jackson-databind 2.13.5 (the
last Jackson line for Android below API 26) and httpclient5 5.2.1. jeromq (only for
ZephyrWalletRpc's ZMQ listener) is optional and must be added by an application that uses it.
The JAR for Maven is io.github.loki-notfound:zephyr-java:2.3.0-sec.2-java.1; see the README's
"Coordinates".
Breaking changes against monero-java
zephyr-java mirrors monero-java's API; a port changes the following. Guide chapter 7, "Coming from
monero-java", has the details and the full renaming table.
- Packages and names:
monero.*→zephyr.*,common.*→zephyr.lib.*, classes
Monero*→Zephyr*, the native librarymonero-java→zephyr-java. toAtomicUnits/fromAtomicUnits:MoneroUtils.xmrToAtomicUnits(double)is
ZephyrUtils.toAtomicUnits(double),MoneroUtils.atomicUnitsToXmr(BigInteger)is
ZephyrUtils.fromAtomicUnits(BigInteger).- Balances are per asset:
getBalance()returns aZephyrBalance;
getBalance(Integer accountIdx)returnsMap<Integer, ZephyrBalance>keyed by subaddress;
getBalance(String assetType, Integer accountIdx[, Integer subaddressIdx])returns a
BigInteger. The unlocked balance has the same shapes;ZephyrAccountandZephyrSubaddress
hold aZephyrBalance.ZephyrBalance.equalstreats an absent asset as zero. - The listener names the asset:
onBalancesChanged(BigInteger, BigInteger)became
onBalancesChanged(BigInteger, BigInteger, String assetType); the old method isfinaland
deprecated, so a ported listener that overrides it does not compile. Outputs carry the asset in
getAssetType(). - Every send names a currency pair: a
ZephyrTxConfigneedssetSourceCurrencyand
setDestinationCurrency, a plain transfer included; without them the core fails with "Must
specify source currency". The compiler does not find this one. - Addresses and constants: Zephyr's address prefixes (multi-byte varints) and network codes in
ZephyrNetworkType;ZephyrUtils.RING_SIZEis 16. Bouncy Castle and commons-codec are no
longer dependencies (own Keccak-256 and hex). - The RPC classes are a first pass:
ZephyrWalletRpcserves the base coin and rejects the
per-asset calls, reserve info and supply with a clear message. - Dependencies:
slf4j-simpleis no longer a runtime dependency (test scope only), and
jeromqis optional.
New in zephyr-java: getReserveInfo() and getCirculatingSupply() on the wallet, ZephyrAssets
with the asset names, and the pricing record on daemon block headers.
Tested
The full wallet ran on mainnet against a node with real funds: create, open, sync, balances per
asset, transfers, a ZPH → ZRS conversion and sweeps (five transactions, verified on the node).
The pure test suite has 30 tests. Conversions other than ZPH → ZRS are not tested on mainnet.
Known limitations
Guide chapter 8, Known limitations, lists them with their
status. The ones a wallet app meets first: getOutputs() reports no asset; the asset of an
unconfirmed output notification is empty; checkTxKey returns amount 0; on Android, TLS to a node
needs the app's help (the native wallet does not use Android's certificate store).
Verification
The release tag and SHA256SUMS are signed with the maintainer key
31DA 39AB 43E0 CA67 F1F3 A661 BA2A FF22 DF8A 4A13; its public key is KEYS.asc in the
repository.
gpg --import KEYS.asc
git verify-tag v2.3.0-sec.2-java.1
gpg --verify SHA256SUMS.asc && sha256sum -c SHA256SUMSThe Maven repository and the site are the archive site-<version>.tar.gz, whose hash is in
SHA256SUMS; Pages serves its contents.
Build manifest
manifest.json among the release files records the zephyr-java commit and its
SOURCE_DATE_EPOCH, both core pins (tag, commit, URL), the build-layer patches, the toolchain
(compilers, NDK, CMake, JDK, Maven, Gradle and the Android Gradle plugin, the Linux container
image and its glibc), every depends package with its sha256, and the size and sha256 of every
release file. Every artifact is built twice in the same environment, and the hashes must match
before SHA256SUMS is signed. Guide chapter 9 explains how to repeat the build.
Not affiliated with ZephyrProtocol. An independent project. Report Zephyr vulnerabilities to the
ZephyrProtocol team, not here.