Announcing the Web3j Open API project

The Web3j OpenAPI generator

• Write a Solidity smart contract
• Generate the corresponding OpenAPI project using Web3j-OpenAPI
• Run the generated project as a standalone server
• Send HTTP requests using Swagger-UI or from a client application using our client implementation

Example

// SPDX-License-Identifier: Apache-2.0
pragma solidity ^0.7.0;

// Modified Greeter contract. Based on example at https://www.ethereum.org/greeter.

contract Mortal {
    /* Define variable owner of the type address*/
    address owner;

    /* this function is executed at initialization
       and sets the owner of the contract */
    constructor () {owner = msg.sender;}

    modifier onlyOwner {
        require(
            msg.sender == owner,
            "Only owner can call this function."
        );
        _;
    }

    /* Function to recover the funds on the contract */
    function kill() onlyOwner public {
        selfdestruct(msg.sender);
    }
}

contract HelloWorld is Mortal {
    /* define variable greeting of the type string */
    string greet;

    /* this runs when the contract is executed */
    constructor (string memory _greet) {
        greet = _greet;
    }

    function newGreeting(string memory _greet) onlyOwner public {
        emit Modified(greet, _greet, greet, _greet);
        greet = _greet;
    }

    /* main function */
    function greeting() public view returns (string memory)  {
        return greet;
    }

    event Modified(
        string indexed oldGreetingIdx,
        string indexed newGreetingIdx,
        string oldGreeting,
        string newGreeting
    );
}

Getting started

Create a new application

$ curl -L get.epirus.io | sh

$ epirus openapi import --help

$ epirus openapi import \
    -s=HelloWorld.sol \
    --package=com.tutorial \
    --project-name=HelloWorldProject \
    --output-dir=. 

Configure the environment

$ cd HelloWorldProject
$ ./gradlew run --args="--help"

• Environment variables
• Configuration file
• Directly from the CLI

$ export WEB3J_ENDPOINT=<link_to_your_Ethereum_node>
$ export WEB3J_PRIVATE_KEY=<your_private_key>
$ export WEB3J_OPENAPI_HOST=localhost
$ export WEB3J_OPENAPI_PORT=9090

Run the application

Run the application as follows

$ ./gradlew run

You should be able to run the server and see the following:

Interacting with the API

Use SwaggerUI

Interact via Java/Kotlin

dependencies {
    implementation "org.web3j.openapi:web3j-openapi-client:4.7.1"
}

var service = new ClientService("http://localhost:9090");
var helloWorldProject = ClientFactory.create(
    HelloWorldProjectApi.class, service
);

System.out.println("Deploying the HelloWorld contract...");

var deployParams = new HelloWorldDeployParameters("Hello");
var receipt = helloWorldProject.getContracts()
    .getHelloWorld().deploy(deployParams);

System.out.println("Deployed contract address: " +
    receipt.getContractAddress());

// Load the contract from the returned transaction receipt
var helloWorld = helloWorldProject.getContracts()
    .getHelloWorld().load(receipt.getContractAddress());

// Change the greeting message
var newReceipt = helloWorld.newGreeting(
    new NewGreetingParameters("Hello Web3j-OpenAPI")
);

System.out.println("NewGreeting transaction hash: " +
    newReceipt.getTransactionHash());

// Check that the smart contract has been updated
var greeting = helloWorld.greeting().getResult();
System.out.println("Greeting method result: " + greeting);

Handling events

var countdownLatch = new CountDownLatch(1);

// Start listening for events
helloWorld.getEvents().getModified().onEvent(e -> {
    System.out.println("Received event: " +
        modifiedEvent.getNewGreeting());
    countdownLatch.countDown();
});

helloWorld.newGreeting(new NewGreetingParameters(
    "This will trigger a modified event"));

countdownLatch.await(); // Waits for the event

Conclusion