Aion Java API Integration Guide

Aion Java API Integration Guide

There are two methods to integrate the Aion JavaAPI with the Aion kernel:

• Download the release binary file from the aion_api Github repo.
• Build your own binary from source code. We target to publish the source code when the Aion network kernel v0.2.0 release.

System Reqirement

Before you attempt to integrate the Aion Java API to your application please check your environment:

• Ubuntu 16.04 64bit
• JDK/JRE 9 or later version (if you want to develop under the JDK/JRE8, please use the branch java8 )

How to integrate the API

First, extract the contents of the downloaded .gz release file. There are two main components of the release build. One component is the .jar binary for the Java client API. The other component is the native library the jar binary depends on.

You can integrate the API into your project in two steps:

• First, you need to put the native folder in your application's execution path or set a link to the native folder path.
• The second step is to add the jar file as a dependency library.

Using the API

For more information please read check the API javadoc.

You can also learn from the demo code that follows. Here, we provided two demo applications for the developer to understand the mechanics of using the library. The source code used in these demonstrations is available here.

Demo 1.

Execute the demo API in a terminal:

./apoDemo.sh -h

The -h will show how you can run the demo including deploying the HelloWorld contract and the simple token contract.

-v, --version             get api version.
-l, --url                 set the kernel url and port.
-t, --test [NUM]          demo api tests
            NUM = 1       demo get BlockNumber.
            NUM = 2       demo GetAccounts.
            NUM = 3       demo UnlockAccount.
            NUM = 4       demo HelloWorld Contract.
            NUM = 5       demo Token Smart Contract.
            NUM = 0       demo all api .

The arguments are given using the format [OPTION] [NUM|STRING], where either long or short option can be used. For example, to get the block number from your kernel running on the local machine at port 8547, run

./apoDemo.sh -t 1 -l tcp://localhost:8547

Demo 2.

Execute the erc20 token demo through the terminal

java -cp "./lib/*::./mod/*" org.aion.api.tools.Erc20Demo "$@"

This demo is an interactive application following the ERC20 Token Standard. The user can input the function and the function argument to execute the token transactions. The following block is how the demo looks like:

Erc20 demo start: Create api instance and connect, please press enter key to go next step!

18-02-05 15:21:21.616 INFO BSE [main]:

[connect] Api connected Get server connected!

Get accounts from the server, please press enter the key to go next step!

Get 134 accounts!

Get the first account:

8f30ce8eb81c57388bc25820b0f8d0612451c9f90091224028b9c562fc9c7036

Unlock account before deploy smart contract and execute tokens transfer. Please press the enter key to go next step!

Please input the password of the first account:

AionBest

Account unlocked!

Now prepare to initial the token contract, please input the initial token supply:

5000

Prepare to deploy the token contract. Please press the enter key to go next step!

18-02-05 15:21:52.618 INFO CNT [main]: [createFromSource] Contract deployed - address: [e80eb202a56c4522086643e00cd92f3a023ca6fa652d872bfa020db9d9cec59c], txhash: [18db5b27c0d4c03bc9841696c57c34dc9cf6aaf6664cd14f6306c3487a660790]

Contract deployed! Now, register the events! The contract support functions list shown as follows:

totalSupply()

balanceOf(ownerAccount)

transfer(toAccount, amount)

transferFrom(fromAccount, toAccount, amount)

approve(spenderAccount, amount)

allowance(ownerAccount,spenderAccount)

The kernel support api list shown as follows:

getAccounts(), get the account address by the input index.

account(index), get the account address by the input index.

unlockAccount(Account, password), unlock the account address.

SetMsgSender(senderAccount), set the message sender, default is the miner account.

getMsgSender(), get the current message sender.

The general command.

-h or -H: help, show this list.

-q or -Q: quit this demo. Please input the command:

-q Exit this demo!

Debugging Log

The first time the API library is executed, it will generate a configuration file and store it in the config folder of the project executing path. The developer can change the log detail level per API category. Here is an example of the log file settings:

<?xml version="1.0" encoding="UTF-8"?>
<javaapi>
    <!--*** LOG ***-->
    <log>
        <module label="BSE">INFO</module>
        <module label="CHN">INFO</module>
        <module label="CNT">INFO</module>
        <module label="NET">INFO</module>
        <module label="TRX">INFO</module>
        <module label="WLT">INFO</module>
        <module label="EXE">INFO</module>
        <module label="ADM">INFO</module>
        <module label="SOL">INFO</module>
    </log>
</javaapi>

For more information on the log level please see the level definition in the log4j project. Aion uses ERROR, WARN, INFO, DEBUG, and TRACE in the implementation.

The different modules inside the configuration file are:

• BSE - the API base method message
• CHN - the chain relative API message
• CNT - the contract relative API message
• NET - the network relative API message
• TRX - the transaction relative API message
• WLT - the wallet relative API message
• EXE - the input/output serialize data between the Aion network and the client API
• ADM - the admin relative API message
• SOL - the solidity type processing relative message

Reporting Bugs

When you experience application behavior that does not function as documented, please open an issue and attach the detailed log information. We will inspect the issue and fix any ensuing bugs as soon as possible.