Skip to content
Official ICON SDK for java
Branch: master
Clone or download
Latest commit fe39114 Feb 8, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gradle/wrapper
library Merge pull request #9 from amuyu/task-modify-bytes-class Feb 7, 2019
quickstart Fix deploy tx failure of quickstart sample Feb 8, 2019
samples Fix bugs that the input stream is not closed when reading files in th… Dec 21, 2018
.gitignore Update sample token SCORE resource for the quickstart sample Oct 31, 2018
.travis.yml Add .travis.yml for CI/CD Aug 17, 2018
CHANGELOG.md
LICENSE Update LICENSE Feb 8, 2019
README.md Version 0.9.11 Feb 8, 2019
build.gradle Add build-scan plugin. Aug 14, 2018
gradle.properties
gradlew
gradlew.bat
publish.gradle
settings.gradle

README.md

Download Maven Central Javadocs

ICON SDK for Java

ICON supports SDK for 3rd party or user services development. You can integrate ICON SDK for your project and utilize ICON’s functionality.

Quick start

A simple query of the block by height is as follows.

IconService iconService = new IconService(new HttpProvider("https://url"));

// Gets a block matching the block height.
Request<Block> request = iconService.getBlock(height);
try {
    Block block = request.execute();
    ...
} catch (IOException e) {
    ...    
}

IconService

APIs are called through IconService.

It can be initialized as follows.

// Creates an instance of IconService using the HTTP provider.
IconService iconService = new IconService(new HttpProvider("https://url"));

With the customized httpclient is

OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .readTimeout(200, TimeUnit.MILLISECONDS)
    .writeTimeout(600, TimeUnit.MILLISECONDS)
    .build();
     
IconService iconService = new IconService(new HttpProvider(okHttpClient, "https://url"));

Queries

All queries are requested by a Request object.

Its requests are executed as Synchronized or Asynchronized.

Once the request has been executed, the request can not be executed again.

Request<Block> request = iconService.getBlock(height);

// Asynchronized request execution
request.execute(new Callback<Block>(){
    void onFailure(Exception exception) {
        ...
    }
     
    void onResponse(Block block) {
        ...
    }
});

// Synchronized request execution
try {
    Block block = request.execute();
    ...
} catch (Exception e) {
    ...
}

The querying APIs are as follows.

// Gets the block
Request<Block> request = iconService.getBlock(new BigInteger("1000")); // by height

Request<Block> request = iconService.getBlock(new Bytes("0x000...000"); // by hash

Request<Block> request = iconService.getLatestBlock(); // latest block
     

// Gets the balance of an given account
Request<BigInteger> request = iconService.getBalance(new Address("hx000...1");


// Gets a list of the SCORE API
Request<List<ScoreApi>> request = iconService.getScoreApi(new Address("cx000...1"));


// Gets the total supply of icx
Request<BigInteger> request = iconService.getTotalSupply();


// Gets a transaction matching the given transaction hash
Request<Transaction> request = iconService.getTransaction(new Bytes("0x000...000"));


// Gets the result of the transaction matching the given transaction hash
Request<TransactionResult> request = iconService.getTransactionResult(new Bytes("0x000...000"));


// Calls a SCORE API just for reading
Call<BigInteger> call = new Call.Builder()
    .from(wallet.getAddress())
    .to(scoreAddress)
    .method("balanceOf")
    .params(params)
    .buildWith(BigInteger.class);
Request<BigInteger> request = iconService.call(call);

// Calls without response type                                                     
Call<RpcItem> call = new Call.Builder()
    .from(wallet.getAddress())
    .to(scoreAddress)
    .method("balanceOf")
    .params(params)
    .build();
Request<RpcItem> request = iconService.call(call);
try {
    RpcItem rpcItem = request.execute();
    BigInteger balance = rpcItem.asInteger();
    ...
} catch (Exception e) {
    ...
}                                                     

Sending transactions

Calling SCORE APIs to change states is requested as sending a transaction.

Before sending a transaction, the transaction should be signed. It can be done using a Wallet object.

Loading wallets and storing the Keystore

// Generates a wallet.
Wallet wallet = KeyWallet.create();

// Loads a wallet from the private key.
Wallet wallet = KeyWallet.load(new Bytes("0x0000"));

// Loads a wallet from the key store file.
File file = new File("./key.keystore");
Wallet wallet = KeyWallet.load("password", file);

// Stores the keystore on the file path.
File dir = new File("./");
KeyWallet.store(wallet, "password", dir); // throw exception if an error exists.

Creating transactions

// sending icx
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(new BigInteger("150000000"))
    .stepLimit(new BigInteger("1000000"))
    .nonce(new BigInteger("1000000"))
    .build();

// deploy
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .stepLimit(new BigInteger("5000000"))
    .nonce(new BigInteger("1000000"))
    .deploy("application/zip", content)
    .params(params)
    .build();

// call
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(new BigInteger("150000000"))
    .stepLimit(new BigInteger("1000000"))
    .nonce(new BigInteger("1000000"))
    .call("transfer")
    .params(params)
    .build();

// message
Transaction transaction = TransactionBuilder.newBuilder()
    .nid(networkId)
    .from(wallet.getAddress())
    .to(scoreAddress)
    .value(BigInteger("150000000"))
    .stepLimit(BigInteger("1000000"))
    .nonce(BigInteger("1000000"))
    .message(message)
    .build();

SignedTransaction object signs a transaction using the wallet.

And the request is executed as Synchronized or Asynchronized like a querying request.

Once the request has been executed, the request can not be executed again.

SignedTransaction signedTransaction = new SignedTransaction(transaction, wallet);

Request<Bytes> request = iconService.sendTransaction(signedTransaction);

// Asynchronized request execution
request.execute(new Callback<Bytes>(){
    void onFailure(Exception e) {
        ...
    }
     
    void onResponse(Bytes txHash) {
        ...
    }
});

// Synchronized request execution
try {
    Bytes txHash = request.execute();
    ...
} catch (Exception e) {
    ...
}

Converter

All the requests and responses values are parcelled as RpcItem(RpcObject, RpcArray, RcpValue). You can convert your own class using RpcConverter.

iconService.addConverterFactory(new RpcConverter.RpcConverterFactory() {
    @Override
    public  RpcConverter create(Class type) {
        if (type.isAssignableFrom(Person.class)) {
            return new RpcConverter<Person>() {
                @Override
                public Person convertTo(RpcItem object) {
                    // Unpacking from RpcItem to the user defined class
                    String name = object.asObject().getItem("name").asString();
                    BigInteger age = object.asObject().getItem("age").asInteger();
                    return new Person(name, age);
                }

                @Override
                public RpcItem convertFrom(Person person) {
                    // Packing from the user defined class to RpcItem
                    return new RpcObject.Builder()
                        .put("name", person.name)
                        .put("age", person.age)
                        .build();
                }
            };
        }
        return null;
    }
});

...

class Person {
    public Person(String name, BigInteger age) {}
}

...
    
Call<Person> call = new Call.Builder()
                .from(fromAddress)
                .to(scoreAddress)
                .method("searchMember")
                .params(person) // the input parameter is an instance of Person type
                .buildWith(Person.class); // build with the response type 'Person'

Person memberPerson = iconService.call(call).execute();

References

Version

0.9.11 (beta)

Android Support

  • Android 3.0+ (API 11+)

Download

Download the latest JAR or grab via Maven:

<dependency>
  <groupId>foundation.icon</groupId>
  <artifactId>icon-sdk</artifactId>
  <version>[x.y.z]</version>
</dependency>

or Gradle:

implementation 'foundation.icon:icon-sdk:[x.y.z]'

License

This project follows the Apache 2.0 License. Please refer to LICENSE for details.

You can’t perform that action at this time.