Monero Java Library

A Java library for creating Monero applications using RPC or JNI bindings to monero v0.18.5.1 'Fluorine Fermi'.

• Supports wallet and daemon RPC clients.
• Supports client-side wallets using JNI bindings.
• Supports multisig, view-only, and offline wallets.
• Wallet types are interchangeable by conforming to a common interface.
• Uses a clearly defined data model and API specification intended to be intuitive and robust.
• Query wallet transactions, transfers, and outputs by their properties.
• Fetch and process binary data from the daemon (e.g. raw blocks).
• Receive notifications when blocks are added to the chain or when wallets sync, send, or receive.
• Over 300 passing JUnit tests.

Architecture

Build Java applications using RPC or JNI bindings to monero-project/monero. Wallet implementations are interchangeable by conforming to a common interface, MoneroWallet.java.

Sample code

// connect to daemonMoneroDaemondaemon = newMoneroDaemonRpc("http://localhost:38081", "superuser", "abctesting123");
longheight = daemon.getHeight(); // 1523651List<MoneroTx> txsInPool = daemon.getTxPool(); // get transactions in the pool// create wallet from mnemonic phrase using JNI bindings to monero-projectMoneroWalletFullwalletFull = MoneroWalletFull.createWallet(newMoneroWalletConfig()
.setPath("sample_wallet_full")
.setPassword("supersecretpassword123")
.setNetworkType(MoneroNetworkType.STAGENET)
.setServerUri("http://localhost:38081")
.setServerUsername("superuser")
.setServerPassword("abctesting123")
.setSeed("hefty value scenic...")
.setRestoreHeight(573936l));
// synchronize the wallet and receive progress notificationswalletFull.sync(newMoneroWalletListener() {
@OverridepublicvoidonSyncProgress(longheight, longstartHeight, longendHeight, doublepercentDone, Stringmessage) {
// feed a progress bar?
}
});
// synchronize in the background every 5 secondswalletFull.startSyncing(5000l);
// receive notifications when funds are received, confirmed, and unlockedwalletFull.addListener(newMoneroWalletListener() {
@OverridepublicvoidonOutputReceived(MoneroOutputWalletoutput) {
BigIntegeramount = output.getAmount();
StringtxHash = output.getTx().getHash();
BooleanisConfirmed = output.getTx().isConfirmed();
BooleanisLocked = output.getTx().isLocked();
FUNDS_RECEIVED = true;
}
});
// connect to wallet RPC and open walletMoneroWalletRpcwalletRpc = newMoneroWalletRpc("http://localhost:38083", "rpc_user", "abc123");
walletRpc.openWallet("sample_wallet_rpc", "supersecretpassword123");
StringprimaryAddress = walletRpc.getPrimaryAddress(); // 555zgduFhmKd2o8rPUz...BigIntegerbalance = walletRpc.getBalance(); // 533648366742List<MoneroTxWallet> txs = walletRpc.getTxs(); // get transactions containing transfers to/from the wallet// send funds from RPC wallet to full walletMoneroTxWalletcreatedTx = walletRpc.createTx(newMoneroTxConfig()
.setAccountIndex(0)
.setAddress(walletFull.getAddress(1, 0))
.setAmount("250000000000") // send 0.25 XMR (denominated in atomic units)
.setRelay(false)); // create transaction and relay to the network if trueBigIntegerfee = createdTx.getFee(); // "Are you sure you want to send... ?"walletRpc.relayTx(createdTx); // relay the transaction// recipient receives unconfirmed funds within 5 secondsTimeUnit.SECONDS.sleep(5);
assertTrue(FUNDS_RECEIVED);
// save and close walletwalletFull.close(true);

Documentation

• Javadoc
• API and model overview with visual diagrams
• JUnit tests
• Using TOR
• monero-ts documentation provides additional documentation which translates to monero-java

Using monero-java in your project

For Gradle, add to build.gradle:

compile 'io.github.woodser:monero-java:0.8.50'

For Maven, add to pom.xml:

<dependency>
<groupId>io.github.woodser</groupId>
<artifactId>monero-java</artifactId>
<version>0.8.50</version>
</dependency>

If using RPC servers:

1. Download and install Monero CLI.
2. Start monerod, e.g.: ./monerod --stagenet (or use a remote daemon).
3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38083 --rpc-login rpc_user:abc123 --wallet-dir ./

Note

On Windows, if you want to use native wallets instead of monero-wallet-rpc, or if you want to process binary data, first install MSYS2:

1. Install MSYS2.
2. Environment variables > System variables > Path > Edit > New > C:\msys64\mingw64\bin

Building native libraries from source

If you want to use native wallets instead of monero-wallet-rpc, or if you want to process binary data, native libraries must be used for your specific platform.

For convenience, native libraries for Linux, macOS, and Windows are distributed with monero-java, but they can be built independently from source:

Linux and macOS

1. Install maven for your system.
2. Install a Java JDK for your system, for example:
   

   curl -s "https://get.sdkman.io" | bash
   sdk install java 21.0.2.fx-librca
   

3. Clone the project repository: git clone --recurse-submodules https://github.com/woodser/monero-java.git
4. cd ./monero-java
5. Install Maven dependencies: mvn install
6. Build the monero-cpp submodule (located at ./external/monero-cpp) as a native library by following instructions for your system.
7. Build native libraries to ./build/: ./bin/build_libmonero_java.sh

Windows

1. Install MSYS2.

2. Install Maven:

   a. Download binary zip archive from https://maven.apache.org/download.cgi
   b. Unpack to C:\msys64\usr\local

3. Environment variables > System variables > Path > Edit > New > C:\msys64\mingw64\bin

4. Start MSYS2 MINGW64 or MSYS MINGW32 depending on your system and use for the following steps.

5. Update packages: pacman -Syu and confirm at the prompts.

6. Install dependencies. During installation, use default=all by leaving the input blank and pressing enter.

   64-bit: pacman -S mingw-w64-x86_64-toolchain make mingw-w64-x86_64-cmake git mingw-w64-x86_64-icu zip unzip

   32-bit: pacman -S mingw-w64-i686-toolchain make mingw-w64-i686-cmake git mingw-w64-i686-icu

7. Install Java JDK:

   curl -s "https://get.sdkman.io" | bash
   sdk install java 21.0.2.fx-librca
   

8. Set environment variables (replace with your paths):

   export MAVEN_HOME=/usr/local/apache-maven-3.x.x/
   export PATH=$PATH:$JAVA_HOME/bin/:$MAVEN_HOME/bin/
   

9. Clone the project repository: git clone --recurse-submodules https://github.com/woodser/monero-java.git

10. cd ./monero-java

11. Install Maven dependencies: mvn install

12. Build the monero-cpp submodule (located at ./external/monero-cpp) as a native library by following instructions for Windows.

13. Build native libraries to ./build/: ./bin/build_libmonero_java.sh

Loading native libraries

After building the native library to the ./build folder, add it to PATH, your application's classpath, or explictly load it in Java by calling:

System.load(/absolute/path/to/libmonero-java.dll);

Alternatively, you can bundle the libraries into monero-java's JAR:

1. Download the monero-java-native-libs artifact from the CI Build run and stage it into ./lib: ./bin/stage_native_libs.sh <path-to-zip>.
2. mvn install
3. Force update Maven snapshots: mvn clean install -U

You can verify the native libraries are working by running TestMoneroUtils.java.

Memory Growth

If you see unrestricted memory growth using native bindings, consider applying jemalloc to improve memory management with malloc. In many cases, this can completely resolve the memory growth.

For example: export LD_PRELOAD=/path/to/libjemalloc.a then run your app.

Running JUnit tests

1. Clone the project repository: git clone --recurse-submodules https://github.com/woodser/monero-java.git
2. cd monero-java
3. Start RPC servers:
   1. Download and install Monero CLI.
   2. Start monerod, e.g.: ./monerod --stagenet (or use a remote daemon).
   3. Start monero-wallet-rpc, e.g.: ./monero-wallet-rpc --daemon-address http://localhost:38081 --stagenet --rpc-bind-port 38083 --rpc-login rpc_user:abc123 --wallet-dir ./
4. Configure the appropriate RPC endpoints, authentication, and other settings in TestUtils.java.
5. Run all *.java files in src/test/java as JUnits.

Related projects

• monero-ts
• monero-cpp
• Haveno

License

This project is licensed under MIT.

Donations

If this library has been valuable to you, please consider donating to support its continued development.

46FR1GKVqFNQnDiFkH7AuzbUBrGQwz2VdaXTDD4jcjRE8YkkoTYTmZ2Vohsz9gLSqkj5EM6ai9Q7sBoX4FPPYJdGKQQXPVz