web3j Integration for Corda

Introduction

web3j-corda is a lightweight client library for working with CorDapps and interacting with different nodes on Corda networks.

Features

• Connect to a Corda node
• Query the available CorDapps on the node
• Generate CorDapp client wrappers to interact with the deployed CorDapps
• Generate integration tests using Docker containers to verify CorDapps in real Corda networks
• Generate sample projects with a CorDapp contract, workflow and client modules

Requirements

• Java SDK 1.8
• Docker (for integration tests)

Quick start

Using the web3j-corda CLI

There is a web3j-corda binary that allows you to easily:

• Generate a template CorDapp project and the respective client wrappers
• Generate client wrappers for existing CorDapps

You can install web3j-corda by running the following command in your terminal:

curl -L https://raw.githubusercontent.com/web3j/corda/master/scripts/installer.sh | bash

Create a template CorDapp project

To generate a template CorDapp project with the client wrappers:

web3j-corda new --name=<corDappName> --output-dir=<output-dir> --package-name=<packageName>

Create CorDapp client wrappers

To generate a web3j-corda client wrappers to existing CorDapps:

web3j-corda generate (--url=<openApiUrl> | --cordapps-dir=<corDapps-dir>) --output-dir=<output-dir> --package-name=<packageName>

For further instructions, head to the Examples section in the docs.

Getting started

Add the relevant dependency to your project:

Maven

<dependency>
    <groupId>org.web3j.corda</groupId>
    <artifactId>web3j-corda-core</artifactId>
    <version>0.2.8</version>
</dependency>

Gradle

dependencies {
    implementation 'org.web3j.corda:web3j-corda-core:0.2.8'
}

Connect to a Corda Node

Initialise a connection, and create our Corda client service:

val service = CordaService("http://localhost:9000/") // URL exposed by Corda OpenAPI connector
val corda = Corda.build(service)

Obtain all the nodes connected to the current node:

val nodes = corda.api.network.nodes.findAll()

To query the list of all running CorDapps:

val corDapps = corda.api.corDapps.findAll()

To start a flow there are two option depending on whether you want to use a generated CorDapp wrapper or just the Corda API directly:

Using Corda API

This way works but is not type-safe, so can lead to runtime exceptions:

// Initialise the parameters of the flow 
val params = InitiatorParameters("$1", "O=PartyA, L=London, C=GB", false)

val issue = corda.api
    .corDapps.findById("obligation-cordapp")
    .flows.findById("issue-obligation")

// Type-conversions with potential runtime exception!
var signedTx = issue.start(parameters).convert<SignedTransaction>()

Using the Web3j CorDapp wrapper

By using a wrapper generated by the web3j-corda Command-Line Tool, you can interact with your CorDapp in a type-safe way:

// Initialise the parameters of the flow 
val params = InitiatorParameters("$1", "O=PartyA, L=London, C=GB", false)

// Start the flow with typed parameters and response
val signedTx = Obligation.load(corda.service).flows.issue.start(parameters)

Documentation

The project documentation portal is available here.

To build and serve the docs locally, you will need to have Pipenv installed. Then simply run:

pipenv install
pipenv run mkdocs serve

Support

Web3 Labs maintain web3j-corda. If you'd like to get in touch, please email us.