Monero Java Library

A Java library for creating Monero applications using RPC and JNI bindings to monero v0.17.2.0 'Oxygen Orion'.

• 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 280 passing JUnit tests.

Table of contents

• Architecture
• Sample code
• Documentation
• Using monero-java in your project
• Building JNI shared libraries from source
• Running JUnit tests
• Related projects
• License
• Donations

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 daemon
MoneroDaemon daemon = new MoneroDaemonRpc("http://localhost:38081", "superuser", "abctesting123");
long height = daemon.getHeight();                       // 1523651
BigInteger feeEstimate = daemon.getFeeEstimate();       // 1014313512
List<MoneroTx> txsInPool = daemon.getTxPool();          // get transactions in the pool

// open wallet on monero-wallet-rpc
MoneroWalletRpc walletRpc = new MoneroWalletRpc("http://localhost:38083", "rpc_user", "abc123");
walletRpc.openWallet("sample_wallet_rpc", "supersecretpassword123");
String primaryAddress = walletRpc.getPrimaryAddress();  // 555zgduFhmKd2o8rPUz...
BigInteger balance = walletRpc.getBalance();            // 533648366742
List<MoneroTxWallet> txs = walletRpc.getTxs();          // get transactions containing transfers to/from the wallet

// create wallet from mnemonic phrase using JNI bindings to monero-project
MoneroWalletFull walletFull = MoneroWalletFull.createWallet(new MoneroWalletConfig()
        .setPath("sample_wallet_full")
        .setPassword("supersecretpassword123")
        .setNetworkType(MoneroNetworkType.STAGENET)
        .setServerUri("http://localhost:38081")
        .setServerUsername("superuser")
        .setServerPassword("abctesting123")
        .setMnemonic("hefty value scenic...")
        .setRestoreHeight(573936l));

// synchronize the wallet and receive progress notifications
walletFull.sync(new MoneroWalletListener() {
  @Override
  public void onSyncProgress(long height, long startHeight, long endHeight, double percentDone, String message) {
    // feed a progress bar?
  }
});

// synchronize in the background every 5 seconds
walletFull.startSyncing(5000l);

// receive notifications when funds are received, confirmed, and unlocked
walletFull.addListener(new MoneroWalletListener() {
  @Override
  public void onOutputReceived(MoneroOutputWallet output) {
    BigInteger amount = output.getAmount();
    String txHash = output.getTx().getHash();
    Boolean isConfirmed = output.getTx().isConfirmed();
    Boolean isLocked = output.getTx().isLocked();
    FUNDS_RECEIVED = true;
  }
});

// send funds from RPC wallet to full wallet
MoneroTxWallet createdTx = walletRpc.createTx(new MoneroTxConfig()
        .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 true
BigInteger fee = createdTx.getFee(); // "Are you sure you want to send... ?"
walletRpc.relayTx(createdTx); // relay the transaction

// recipient receives unconfirmed funds within 5 seconds
TimeUnit.SECONDS.sleep(5);
assertTrue(FUNDS_RECEIVED);

// save and close wallet
walletFull.close(true);

Documentation

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

Using monero-java in your project

For Maven, add to pom.xml:

<dependency>
  <groupId>io.github.monero-ecosystem</groupId>
  <artifactId>monero-java</artifactId>
  <version>0.5.3</version>
</dependency>

For Gradle, add to build.gradle:

compile 'io.github.monero-ecosystem:monero-java:0.5.3'

You are now ready to use this library with monero-daemon-rpc and monero-wallet-rpc endpoints.

If you want to use client-side wallets via native JNI bindings, first build the JNI shared libraries.

If using RPC servers:

1. Download and install Monero CLI.
2. Start monero-daemon-rpc, 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 ./

Building JNI shared libraries from source

If you want to process binary data or use a client-side wallet instead of RPC, shared libraries must be built for your specific platform for this Java library to use. This project uses a C++ counterpart library, monero-cpp, to support JNI, which is included as a submodule in ./external/monero-cpp.

1. Install maven and Java JDK for your system
   Ubuntu: sudo apt-get install maven default-jdk
   Mac: brew install maven openjdk
2. export JAVA_HOME=/path/to/jdk, for example:
   Ubuntu: export JAVA_HOME=/usr/lib/jvm/default-java
   Mac: export JAVA_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home
3. Clone the project repository: git clone https://github.com/monero-ecosystem/monero-java.git
4. cd ./monero-java
5. Install Maven dependencies: mvn install
6. Update submodules: ./bin/update_submodules.sh
7. Build ./external/monero-cpp as a shared library.
8. Build shared libraries to ./build/: ./bin/build_libmonero_java.sh
9. Run TestMoneroUtils.java JUnit tests to verify the shared libraries are working with Java JNI.
10. Add the shared libraries within ./build/ to your application's classpath.

Running JUnit tests

1. Clone the project repository: git clone https://github.com/monero-ecosystem/monero-java.git
2. cd monero-java
3. If using JNI, build JNI shared libraries from source.
4. Start RPC servers:
   1. Download and install Monero CLI.
   2. Start monero-daemon-rpc, 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 ./
5. Configure the appropriate RPC endpoints, authentication, and other settings in TestUtils.java.
6. Run all *.java files in src/main/test as JUnits.

Related projects

• monero-javascript
• monero-cpp

License

This project is licensed under MIT.

Donations

If this library brings you value, please consider donating.

46FR1GKVqFNQnDiFkH7AuzbUBrGQwz2VdaXTDD4jcjRE8YkkoTYTmZ2Vohsz9gLSqkj5EM6ai9Q7sBoX4FPPYJdGKQQXPVz