web3j: Web3 Java Ðapp API

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

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

It can generate Java smart contract wrappers so you can interact with a smart contract like it's native Java code.

It only has four runtime dependencies:

• Apache HTTP Client
• Jackson Core for fast JSON serialisation/deserialisation
• Bouncy Castle for crypto
• JavaPoet for generating smart contract wrappers

Project documentation is available here

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.5.1</version>
</dependency>

Gradle

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

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.core.Response.getResult().

Generating smart contract wrappers in Java

The library also supports the auto-generation of smart contract function wrappers in Java from Solidity ABI files.

This can be achieved by running:

org.web3j.codegen.SolidityFunctionWrapperGenerator /path/to/<smart-contract>.abi -o /path/to/src/dir/java -p com.your.organisation.name

See org.web3j.protocol.scenarios.FunctionWrappersIT for an example of using a generated smart contract Java wrapper.

Working with filters

See org.web3j.protocol.scenarios.EventFilterIT for an example.

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.core.CoreIT to verify clients.

Coming Soon

• External key
• 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
• And of course the users of the library, who've provided valuable input & feedback - @ice09, @adridadou, @nickmelis, @basavk