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 two runtime dependencies:

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

Getting Started

Add the following dependency to your project:

Maven

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

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

Gradle

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

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

geth --rpc --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();

An example project is available at web3j-example

Further Details

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

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 data 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)

More coming soon.

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

Coming Soon

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

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