Skip to content

v2.3.0-sec.2-java.1

Choose a tag to compare

@loki-notfound loki-notfound released this 08 Nov 02:40
· 58 commits to main since this release
v2.3.0-sec.2-java.1
1d4cf76

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
    for arm64-v8a, armeabi-v7a and x86_64, 16 KB page aligned, stored uncompressed; consumer
    R8 rules included. armeabi-v7a needs a CPU with VFPv4. Built with NDK r18b through Zephyr's
    own contrib/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 for x86_64 and
    arm64 inside 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. The arm64
    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 library monero-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 a ZephyrBalance;
    getBalance(Integer accountIdx) returns Map<Integer, ZephyrBalance> keyed by subaddress;
    getBalance(String assetType, Integer accountIdx[, Integer subaddressIdx]) returns a
    BigInteger. The unlocked balance has the same shapes; ZephyrAccount and ZephyrSubaddress
    hold a ZephyrBalance. ZephyrBalance.equals treats an absent asset as zero.
  • The listener names the asset: onBalancesChanged(BigInteger, BigInteger) became
    onBalancesChanged(BigInteger, BigInteger, String assetType); the old method is final and
    deprecated, so a ported listener that overrides it does not compile. Outputs carry the asset in
    getAssetType().
  • Every send names a currency pair: a ZephyrTxConfig needs setSourceCurrency and
    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_SIZE is 16. Bouncy Castle and commons-codec are no
    longer dependencies (own Keccak-256 and hex).
  • The RPC classes are a first pass: ZephyrWalletRpc serves the base coin and rejects the
    per-asset calls, reserve info and supply with a clear message.
  • Dependencies: slf4j-simple is no longer a runtime dependency (test scope only), and
    jeromq is 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 SHA256SUMS

The 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.