etherspace-java

A Retrofit-like Ethereum client for Android, Java, and Kotlin.

Introduction

Etherspace is a type-safe Ethereum client to interact with Ethereum Smart Contract.

For example, to access greeter smart contract from ETHEREUM » Create a digital greeter (Slightly modified because we need a setter):

contract greeter {
    /* Define variable greeting of the type string */
    string greeting;
    
    /* This runs when the contract is executed */
    function greeter(string _greeting) public {
        greeting = _greeting;
    }

    /* Main function */
    function greet() constant returns (string) {
        return greeting;
    }

    /* Update greeting */
    function newGreeting(string _greeting) public returns (string) {
        greeting = _greeting;
        return greeting;
    }
}

By defining a Smart Contract interface in Kotlin / Java: (see: Smart Contract Interface)

// Kotlin
interface Greeter {
    @Throws(IOException::class)
    @Send
    fun newGreeting(greeting: String): TransactionHash

    @Throws(IOException::class)
    @Call
    fun greet(): String
}

// Java
public interface Greeter {
    @Send
    TransactionHash newGreeting(String greeting) throws IOException;
    
    @Call
    String greet() throws IOException;
}

Etherspace generates an implementation of Greeter interface.

You can than use greeter to interact with Smart Contract on Ethereum!

// Kotlin
val etherSpace = EtherSpace.build {
    provider = "https://rinkeby.infura.io/" // Or your local node 
    credentials = Credentials(YOUR_PRIVATE_KEY_OR_WALLET)
}
var greeter = etherSpace.create(SMART_CONTRACT_ADDRESS, Greeter::class.java)

val hash = greeter.newGreeting("Hello World")
val receipt = hash.requestTransactionReceipt<TransactionReceipt>()

println(greeter.greet()) // Should be "Hello World"

// Java
EtherSpace etherSpace = new EtherSpace.Builder()
        .provider("https://rinkeby.infura.io/") // Or your local node
        .credentials(new Credentials(YOUR_PRIVATE_KEY_OR_WALLET))
        .build();
Greeter greeter = etherSpace.create(SMART_CONTRACT_ADDRESS, Greeter.class);

TransactionHash hash = greeter.newGreeting("Hello World");
TransactionReceipt receipt = hash.requestTransactionReceipt();

System.out.println(greeter.greet()); // Should be "Hello World"

Example Apps

• Java / Kotlin: etherspace-java-example
• Android: etherspace-android-example

Declaring Smart Contract Interfaces

• Smart Contract Interface

Configuration

• Configuration

Download

• Gradle

  repositories {
    ...
    maven { url 'https://jitpack.io' } // should be the last entry
  }
  
  dependencies {
    ...
    // JDK 8
    compile 'cc.etherspace.etherspace-java:etherspace-java:{version}'
    // Android
    implementation 'cc.etherspace.etherspace-java:etherspace-android:{version}'
  }

• Maven

  <repositories>
    <repository>
      <id>jitpack.io</id>
      <url>https://jitpack.io</url>
    </repository>
  </repositories>
  
  <!-- JDK 8 -->
  <dependency>
    <groupId>cc.etherspace.etherspace-java</groupId>
    <artifactId>etherspace-java</artifactId>
    <version>{version}</version>
  </dependency>
  
  <!-- Android -->
  <dependency>
    <groupId>cc.etherspace.etherspace-java</groupId>
    <artifactId>etherspace-android</artifactId>
    <version>{version}</version>
  </dependency>

Bug reports & feature requests

Please submit issues or pull requests for bugs and features, or contact me at [email protected]. Any feedback is welcome!

Credits

• Etherspace is built with Kotlin.
• Built on top of web3j.
• Inspired by Retrofit.
• Included libraries:
  • web3j: https://github.com/web3j/web3j
  • kotlin-unsigned: https://github.com/kotlin-graphics/kotlin-unsigned
  • jackson: https://github.com/FasterXML/jackson
  • guava: https://github.com/google/guava