Skip to main content
zephyr-java

Java wallet library for Zephyr, a lateo project

12. Coming from monero-java

zephyr-java is derived from monero-java at commit 53a54543 (2023-07-10), the API era that matches the Zephyr core. If you know monero-java, or monero-ts and its documentation, you know most of zephyr-java: the classes, the methods and the model are the same, renamed once. This chapter lists the renaming rules, the differences that are not renames, and how to use both libraries in one program.

Monero additions to monero-java after 53a54543 are not in zephyr-java: they need parts of the native core that Zephyr's core does not have. The same goes for upstream's "subtract fee from destinations", which the Zephyr core would ignore without an error.

The renaming rules#

The rename was done once, mechanically, over the whole source tree:

monero-javazephyr-java
package monero.*package zephyr.*
package common.*package zephyr.lib.*
class Monero*class Zephyr*
MoneroUtils.xmrToAtomicUnits(double)ZephyrUtils.toAtomicUnits(double)
MoneroUtils.atomicUnitsToXmr(BigInteger)ZephyrUtils.fromAtomicUnits(BigInteger)
native library monero-javanative library zephyr-java
Maven io.github.monero-ecosystem:monero-java (now io.github.woodser:monero-java)Maven io.github.loki-notfound:zephyr-java

Everything else keeps its name: method names, parameters, the model's fields and the query classes. So a monero-ts example ports by renaming its types.

The twenty classes you meet first:

monero-javazephyr-java
monero.wallet.MoneroWalletFullzephyr.wallet.ZephyrWalletFull
monero.wallet.MoneroWalletzephyr.wallet.ZephyrWallet
monero.wallet.MoneroWalletRpczephyr.wallet.ZephyrWalletRpc
monero.daemon.MoneroDaemonRpczephyr.daemon.ZephyrDaemonRpc
monero.common.MoneroUtilszephyr.common.ZephyrUtils
monero.common.MoneroRpcConnectionzephyr.common.ZephyrRpcConnection
monero.common.MoneroConnectionManagerzephyr.common.ZephyrConnectionManager
monero.common.MoneroErrorzephyr.common.ZephyrError
monero.daemon.model.MoneroNetworkTypezephyr.daemon.model.ZephyrNetworkType
monero.wallet.model.MoneroWalletConfigzephyr.wallet.model.ZephyrWalletConfig
monero.wallet.model.MoneroWalletListenerzephyr.wallet.model.ZephyrWalletListener
monero.wallet.model.MoneroTxConfigzephyr.wallet.model.ZephyrTxConfig
monero.wallet.model.MoneroTxWalletzephyr.wallet.model.ZephyrTxWallet
monero.wallet.model.MoneroTxQueryzephyr.wallet.model.ZephyrTxQuery
monero.wallet.model.MoneroTransferzephyr.wallet.model.ZephyrTransfer
monero.wallet.model.MoneroIncomingTransferzephyr.wallet.model.ZephyrIncomingTransfer
monero.wallet.model.MoneroOutgoingTransferzephyr.wallet.model.ZephyrOutgoingTransfer
monero.wallet.model.MoneroOutputWalletzephyr.wallet.model.ZephyrOutputWallet
monero.wallet.model.MoneroAccountzephyr.wallet.model.ZephyrAccount
monero.wallet.model.MoneroDestinationzephyr.wallet.model.ZephyrDestination

A helper from common.utils, such as common.utils.GenUtils, is now zephyr.lib.utils.GenUtils.

What is different#

These are the changes a port has to make by hand. The compiler finds all of them except the currency pair and the two results that differ.

Balances are per asset. monero-java's six balance methods return a BigInteger. In zephyr-java:

monero-javazephyr-java
BigInteger getBalance()ZephyrBalance getBalance()
BigInteger getBalance(Integer accountIdx)Map<Integer, ZephyrBalance> getBalance(Integer accountIdx), keyed by subaddress
BigInteger getBalance(Integer accountIdx, Integer subaddressIdx)BigInteger getBalance(String assetType, Integer accountIdx, Integer subaddressIdx)
—BigInteger getBalance(String assetType, Integer accountIdx)

The unlocked balance has the same four shapes, and ZephyrAccount and ZephyrSubaddress hold a ZephyrBalance instead of a BigInteger. Assets, accounts and balances explains them.

The listener names the asset. onBalancesChanged(BigInteger, BigInteger) became onBalancesChanged(BigInteger, BigInteger, String assetType). The old method still exists in ZephyrWalletListener but is final and deprecated, so a ported listener that overrides it does not compile, rather than compiling and never being called. The listener's outputs carry the asset in getAssetType(), which is empty for unconfirmed outputs (Outputs in the pool carry no asset).

Every send names a currency pair. A ZephyrTxConfig without setSourceCurrency and setDestinationCurrency fails with "Must specify source currency", a plain transfer included. The compiler does not find this one; The ten pairs lists the pairs.

New calls. getReserveInfo() and getCirculatingSupply() on the wallet (Reserve info), ZephyrAssets with the asset names, getOutputAssetType for the asset of an output, and the pricing record on daemon block headers.

Two results differ without a compile error. Code that works in monero-java compiles and runs, but reads something the Zephyr core does not deliver:

  • checkTxKey (and checkTxProof): monero-java returns the received amount. In zephyr-java's full wallet the amount is 0, and the amount comes from the transaction in getTxs(hash) (checkTxKey returns amount 0).
  • getOutputs(): monero-java's outputs have no asset concept. zephyr-java's outputs have an assetType field, but getOutputs() leaves it null. The asset comes from the output's transaction, through getOutputAssetType(output) (getOutputs() reports no asset).

Addresses and constants. Address decoding stays pure Java (no native library needed) but knows Zephyr's prefixes, which are multi-byte varints: on mainnet, primary addresses start with ZEPHYR, subaddresses with ZEPHs and integrated addresses with ZEPHii. ZephyrNetworkType carries Zephyr's codes. ZephyrUtils.RING_SIZE is 16, the network rule of the Zephyr core, not Monero's 12. Keccak-256 and hex are the library's own code (Keccak256, GenUtils), so there is no dependency on Bouncy Castle or Apache commons-codec.

Amounts. ZephyrUtils.toAtomicUnits(double) converts through a double and fails or truncates for some values; use BigDecimal (Amounts).

The RPC classes are a first pass, for the base coin only (The RPC classes).

Both libraries in one program#

zephyr-java was built so that it can sit next to monero-java in one JVM or one app: a wallet that supports both coins needs both.

  • No class clashes. The packages differ (zephyr.* against monero.* and common.*).
  • No native clashes. Each library is its own shared object (libzephyr-java.so, libmonero-java.so), and zephyr-java's exports only JNI symbols. The one name both libraries export is JNI_OnLoad, which the JVM looks up per library, so it is no conflict.
  • Tested. The coexistence test loads monero-java 0.8.65 from Maven Central and zephyr-java in one JVM. It validates a Zephyr address in Java and natively and a Monero address with monero-java. It checks that the two dynamic symbol sets share exactly {JNI_OnLoad} and no Java_* name.

Jackson decides the versions. monero-java 0.8.65 needs Jackson 2.15 or newer (it uses StreamReadConstraints); zephyr-java declares 2.13.5. A build tool resolves one Jackson for the whole program, normally the highest; with Maven's nearest-wins rule you may have to pin it yourself. The coexistence test runs both libraries on Jackson 2.21.7, which shows that zephyr-java works on the 2.21 line. On Android, Jackson 2.14 and newer need minSdk 26 (Jackson on API 24 and 25).

The coexistence test lives in src/test/java/test/TestCoexistence.java and runs with mvn -Pcoexistence test; the default build does not compile it, because it needs monero-java on the class path.