chain3j

null

License

License

Categories

Categories

MOA Business Logic Libraries Machine Learning OACC Security
GroupId

GroupId

io.github.moacchain
ArtifactId

ArtifactId

console
Last Version

Last Version

0.1.0
Release Date

Release Date

Type

Type

zip
Description

Description

chain3j
null
Project URL

Project URL

https://github.com/mdranger/chain3j
Source Code Management

Source Code Management

https://github.com/mdranger/chain3j.git

Download console

Dependencies

compile (1)

Group / Artifact Type Version
io.github.moacchain : codegen jar 0.1.0

runtime (1)

Group / Artifact Type Version
org.slf4j : slf4j-nop jar 1.7.25

test (6)

Group / Artifact Type Version
junit : junit jar 4.11
org.mockito : mockito-core jar 1.10.19
io.github.moacchain : crypto jar 0.1.0
io.github.moacchain : crypto jar 0.1.0
io.github.moacchain : core jar 0.1.0
io.github.moacchain : core jar 0.1.0

Project Modules

There are no modules declared in this project.

chain3j: Chain3 Java MOAC Ðapp API

chain3j is a lightweight, highly modular, reactive, type safe Java and Android library for working with Smart Contracts and integrating with clients (nodes) on the MOAC network:

This allows you to work with the MOAC blockchain, without the additional overhead of having to write your own integration code for the platform.

This project is developed based on the The Java and the Blockchain talk provides an overview of blockchain, Ethereum and chain3j.

Features

  • Complete implementation of MOAC's JSON-RPC client API over HTTP and IPC
  • Auto-generation of Java smart contract wrappers to create, deploy, transact with and call smart contracts from native Java code (Solidity and Truffle definition formats supported)
  • Reactive-functional API for working with filters
  • Support for MOAC gateway, so you don't have to run an MOAC client yourself
  • Comprehensive integration tests demonstrating a number of the above scenarios
  • Command line tools
  • Android compatible

It has five runtime dependencies:

It also uses JavaPoet for generating smart contract wrappers.

Full project documentation is available at docs.chain3j.io.

Commercial support and training

Commercial support and training is available from moac.io.

Quickstart

A chain3j sample project is available that demonstrates a number of core features of Ethereum with chain3j, including:

  • Connecting to a node on the MOAC network
  • Loading an MOAC keystore file
  • Sending Moac from one address to another
  • Deploying a smart contract to the network
  • Reading a value from the deployed smart contract
  • Updating a value in the deployed smart contract
  • Viewing an event logged by the smart contract

Getting started

Typically your application should depend on release versions of chain3j, but you may also use snapshot dependencies for early access to features and fixes, refer to the Snapshot Dependencies section.

Add the relevant dependency to your project:

Maven

Java 8:

<dependency>
  <groupId>org.chain3j</groupId>
  <artifactId>core</artifactId>
  <version>3.5.0</version>
</dependency>

Android:

<dependency>
  <groupId>org.chain3j</groupId>
  <artifactId>core</artifactId>
  <version>3.3.1-android</version>
</dependency>

Gradle

Java 8:

compile ('org.chain3j:core:3.5.0')

Android:

compile ('org.chain3j:core:3.3.1-android')

Start a client

Start up an MOAC client if you don't already have one running, check _:

$ ./moac --rpcapi personal,mc,net,chain3 --rpc --testnet
Chain3j chain3 = Chain3j.build(new HttpService("https://ropsten.infura.io/your-token"));

For further information refer to Using Infura with chain3j

Instructions on obtaining Mc to transact on the network can be found in the testnet section of the docs.

Start sending requests

To send synchronous requests:

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
Web3ClientVersion chain3ClientVersion = chain3.chain3ClientVersion().send();
String clientVersion = chain3ClientVersion.getWeb3ClientVersion();

To send asynchronous requests using a CompletableFuture (Future on Android):

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
Web3ClientVersion chain3ClientVersion = chain3.chain3ClientVersion().sendAsync().get();
String clientVersion = chain3ClientVersion.getWeb3ClientVersion();

To use an RxJava Observable:

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
chain3.chain3ClientVersion().observable().subscribe(x -> {
    String clientVersion = x.getWeb3ClientVersion();
    ...
});

Note: for Android use:

Chain3j chain3 = Chain3jFactory.build(new HttpService());  // defaults to http://localhost:8545/
...

IPC

chain3j also supports fast inter-process communication (IPC) via file sockets to clients running on the same host as chain3j. To connect simply use the relevant IpcService implementation instead of HttpService when you create your service:

// OS X/Linux/Unix:
Chain3j chain3 = Chain3j.build(new UnixIpcService("/path/to/socketfile"));
...

// Windows
Chain3j chain3 = Chain3j.build(new WindowsIpcService("/path/to/namedpipefile"));
...

Note: IPC is not currently available on chain3j-android.

Working with smart contracts with Java smart contract wrappers

chain3j can auto-generate smart contract wrapper code to deploy and interact with smart contracts without leaving the JVM.

To generate the wrapper code, compile your smart contract:

$ solc <contract>.sol --bin --abi --optimize -o <output-dir>/

Then generate the wrapper code using chain3j's Command line tools:

chain3j solidity generate /path/to/<smart-contract>.bin /path/to/<smart-contract>.abi -o /path/to/src/main/java -p com.your.organisation.name

Now you can create and deploy your smart contract:

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
Credentials credentials = WalletUtils.loadCredentials("password", "/path/to/walletfile");

YourSmartContract contract = YourSmartContract.deploy(
        <chain3j>, <credentials>,
        GAS_PRICE, GAS_LIMIT,
        <param1>, ..., <paramN>).send();  // constructor params

Alternatively, if you use Truffle, you can make use of its .json output files:

# Inside your Truffle project
$ truffle compile
$ truffle deploy

Then generate the wrapper code using chain3j's Command line tools:

$ cd /path/to/your/chain3j/java/project
$ chain3j truffle generate /path/to/<truffle-smart-contract-output>.json -o /path/to/src/main/java -p com.your.organisation.name

Whether using Truffle or solc directly, either way you get a ready-to-use Java wrapper for your contract.

So, to use an existing contract:

YourSmartContract contract = YourSmartContract.load(
        "0x<address>|<ensName>", <chain3j>, <credentials>, GAS_PRICE, GAS_LIMIT);

To transact with a smart contract:

TransactionReceipt transactionReceipt = contract.someMethod(
             <param1>,
             ...).send();

To call a smart contract:

Type result = contract.someMethod(<param1>, ...).send();

To fine control your gas price:

contract.setGasProvider(new DefaultGasProvider() {
        ...
        });

For more information refer to Smart Contracts.

Filters

chain3j functional-reactive nature makes it really simple to setup observers that notify subscribers of events taking place on the blockchain.

To receive all new blocks as they are added to the blockchain:

Subscription subscription = chain3j.blockObservable(false).subscribe(block -> {
    ...
});

To receive all new transactions as they are added to the blockchain:

Subscription subscription = chain3j.transactionObservable().subscribe(tx -> {
    ...
});

To receive all pending transactions as they are submitted to the network (i.e. before they have been grouped into a block together):

Subscription subscription = chain3j.pendingTransactionObservable().subscribe(tx -> {
    ...
});

Or, if you'd rather replay all blocks to the most current, and be notified of new subsequent blocks being created:

There are a number of other transaction and block replay Observables described in the docs.

Topic filters are also supported:

McFilter filter = new McFilter(DefaultBlockParameterName.EARLIEST,
        DefaultBlockParameterName.LATEST, <contract-address>)
             .addSingleTopic(...)|.addOptionalTopics(..., ...)|...;
chain3j.ethLogObservable(filter).subscribe(log -> {
    ...
});

Subscriptions should always be cancelled when no longer required:

subscription.unsubscribe();

Note: filters are not supported on Infura.

For further information refer to Filters and Events and the Chain3jRx interface.

Transactions

chain3j provides support for both working with Ethereum wallet files (recommended) and Ethereum client admin commands for sending transactions.

To send Mc to another party using your Ethereum wallet file:

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
Credentials credentials = WalletUtils.loadCredentials("password", "/path/to/walletfile");
TransactionReceipt transactionReceipt = Transfer.sendFunds(
        chain3, credentials, "0x<address>|<ensName>",
        BigDecimal.valueOf(1.0), Convert.Unit.MC)
        .send();

Or if you wish to create your own custom transaction:

Chain3j chain3 = Chain3j.build(new HttpService());  // defaults to http://localhost:8545/
Credentials credentials = WalletUtils.loadCredentials("password", "/path/to/walletfile");

// get the next available nonce
EthGetTransactionCount ethGetTransactionCount = chain3j.ethGetTransactionCount(
             address, DefaultBlockParameterName.LATEST).sendAsync().get();
BigInteger nonce = ethGetTransactionCount.getTransactionCount();

// create our transaction
RawTransaction rawTransaction  = RawTransaction.createMcTransaction(
             nonce, <gas price>, <gas limit>, <toAddress>, <value>);

// sign & send our transaction
byte[] signedMessage = TransactionEncoder.signMessage(rawTransaction, credentials);
String hexValue = Hex.toHexString(signedMessage);
EthSendTransaction ethSendTransaction = chain3j.ethSendRawTransaction(hexValue).send();
// ...

Although it's far simpler using chain3j's Transfer for transacting with Mc.

Using an Ethereum client's admin commands (make sure you have your wallet in the client's keystore):

Admin chain3j = Admin.build(new HttpService());  // defaults to http://localhost:8545/
PersonalUnlockAccount personalUnlockAccount = chain3j.personalUnlockAccount("0x000...", "a password").sendAsync().get();
if (personalUnlockAccount.accountUnlocked()) {
    // send a transaction
}

If you want to make use of Parity's Personal or Trace, or Geth's Personal client APIs, you can use the org.chain3j:parity and org.chain3j:geth modules respectively.

Command line tools

A chain3j fat jar is distributed with each release providing command line tools. The command line tools allow you to use some of the functionality of chain3j from the command line:

  • Wallet creation
  • Wallet password management
  • Transfer of funds from one wallet to another
  • Generate Solidity smart contract function wrappers

Please refer to the documentation for further information.

Further details

In the Java 8 build:

  • chain3j provides type safe access to all responses. Optional or null responses are wrapped in Java 8's Optional type.
  • Asynchronous requests are wrapped in a Java 8 CompletableFutures. chain3j provides a wrapper around all async requests to ensure that any exceptions during execution will be captured rather then silently discarded. This is due to the lack of support in CompletableFutures for checked exceptions, which are often rethrown as unchecked exception causing problems with detection. See the Async.run() and its associated test for details.

In both the Java 8 and Android builds:

  • Quantity payload types are returned as BigIntegers. For simple results, you can obtain the quantity as a String via Response.getResult().
  • It's also possible to include the raw JSON payload in responses via the includeRawResponse parameter, present in the HttpService and IpcService classes.

Tested clients

  • Geth
  • Parity

You can run the integration test class CoreIT to verify clients.

Related projects

For a .NET implementation, check out Nethereum.

For a pure Java implementation of the Ethereum client, check out EthereumJ and Ethereum Harmony.

Projects using chain3j

Please submit a pull request if you wish to include your project on the list:

Companies using chain3j

Please submit a pull request if you wish to include your company on the list:

Build instructions

chain3j 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 (excluding integration tests):

$ ./gradlew check

To run the integration tests:

$ ./gradlew  -Pintegration-tests=true :integration-tests:test

Snapshot Dependencies

Snapshot versions of chain3j follow the <major>.<minor>.<build>-SNAPSHOT convention, for example: 3.6.0-SNAPSHOT.

If you would like to use snapshots instead please add a new maven repository pointing to:
https://oss.sonatype.org/content/repositories/snapshots

Please refer to the maven or gradle documentation for further detail.

Sample gradle configuration:

repositories {
   maven {
      url "https://oss.sonatype.org/content/repositories/snapshots"
   }
}

Sample maven configuration:

<repositories>
  <repository>
    <id>sonatype-snasphots</id>
    <name>Sonatype snapshots repo</name>
    <url>https://oss.sonatype.org/content/repositories/snapshots</url>
  </repository>
</repositories>

Thanks and credits

  • The Nethereum project for the inspiration
  • Othera for the great things they are building on the platform
  • Finhaus guys for putting me onto Nethereum
  • bitcoinj for the reference Elliptic Curve crypto implementation
  • Everyone involved in the Ethererum project and its surrounding ecosystem
  • And of course the users of the library, who've provided valuable input & feedback

Versions

Version
0.1.0