web3j: Web3 Java Ðapp API

web3j is a lightweight Java library for integrating with clients (nodes) on the Ethereum network.

[ JVM application ] + [ web3j ] <---> [ Ethereum node ]

It only has three runtime dependencies:

• Apache HTTP Client
• Jackson Core for fast JSON serialisation/deserialisation
• Bouncy Castle for crypto

Getting Started

Add the following dependency to your project:

Maven

<repositories>
  <repository>
    <id>oss.jfrog.org</id>
    <value>Repository from Bintray</value>
    <url>http://dl.bintray.com/web3j/maven</url>
  </repository>
</repositories>

<dependency>
  <groupId>org.web3j</groupId>
  <artifactId>core</artifactId>
  <version>0.2.0</version>
</dependency>

Gradle

repositories {
   maven {url "http://dl.bintray.com/web3j/maven"}
}
compile ("org.web3j:core:0.2.0")

Start up an Ethereum client if you don't already have one running, such as Geth:

geth --rpcapi personal,db,eth,net,web3 --rpc --testnet

Or Parity

parity --chain testnet

To send asynchronous requests using a Future:

Web3j web3 = Web3j.build(new HttpService());  // defaults to http://localhost:8545/
Web3ClientVersion web3ClientVersion = web3.web3ClientVersion().sendAsync().get();
String clientVersion = web3ClientVersion.getWeb3ClientVersion();

To send synchronous requests:

Web3j web3 = Web3j.build(new HttpService());  // defaults to http://localhost:8545/
Web3ClientVersion web3ClientVersion = web3.web3ClientVersion().send();
String clientVersion = web3ClientVersion.getWeb3ClientVersion();

To use Parity commands:

Parity parity = Parity.build(new HttpService());  // defaults to http://localhost:8545/
PersonalUnlockAccount personalUnlockAccount = parity.personalUnlockAccount("0x000...", "a password").sendAsync().get();
if (personalUnlockAccount.accountUnlocked()) {
    // send a transaction, or use parity.personalSignAndSendTransaction() to do it all in one
}

An example project is available at web3j-example

Further Details

web3j is based on specifications from the JSON-RPC and web3.js projects.

Parity's Personal JSON-RPC module is supported for managing accounts, and creating transactions.

It provides type safe access to all responses. Optional or null responses are wrapped in Java 8's Optional type.

Async requests are handled using Java 8's CompletableFutures.

Quantity payload types are returned as BigInteger's. For simple results, you can obtain the quantity as a String via org.web3j.protocol.jsonrpc20.Response.getResult().

Tested clients

Geth

• 1.4.10-stable-5f55d95a (in progress)

Parity

• v1.2.4-stable-77ecf4d-20160905 (in progress)

More coming soon.

You can run the integration test class org.web3j.protocol.jsonrpc20.ProtocolIT to verify clients.

Coming Soon

• Geth & Parity Management API support
• Offline transaction signing
• IPC interface support
• WebSocket interface support

Related projects

For a .NET implementation, check out Nethereum.

For a pure Java implementation of the Ethereum client, check out EthereumJ and the work of Ether.Camp.

Build instructions

web3j includes integration tests for running against a live Ethereum client. If you do not have a client running, you can exclude their execution as per the below instructions.

To run a full build including integration tests:

./gradlew check

To run excluding integration tests:

./gradlew -x integrationTest check 

Thanks and Credits

• The Nethereum project for the inspiration
• Othera for the great things they are building on the platform
• The Finhaus guys for putting me onto Nethereum
• Everyone involved in the Ethererum project and its surrounding ecosystem