Aion4j Maven Plugin User Guide

Aion4j Maven Plugin provides end to end development support for AVM based smart contract in java. It supports development on both embedded AVM and remote Aion kernel.

Pre-requisites

Java 10 and above
Maven 3.5.4 and above

1. Create AVM java project

The fastest way to create a AVM project is using a maven archetype - avm-archetype.

Run the following maven command to create an AVM project.

$> mvn archetype:generate -DarchetypeGroupId=org.aion4j -DarchetypeArtifactId=avm-archetype -DarchetypeVersion=0.2

Follow the instruction to enter groupId, artifactId and package information to generate the project.

The generated project has a sample HelloAVM contract.

2. Edit pom.xml

Edit pom.xml file in the generated project and change <aion4j.maven.plugin> version to the latest release version. Please refer to aion4j maven plugin project page for the latest release version.

<properties>
  ...
   <aion4j.plugin.version>0.1</aion4j.plugin.version>
  ...
</properties>

3. Initialize and copy required AVM libraries

By default, the plugin will copy required avm jars to the lib folder under the project directory. But you can also point to a different avm lib folder by changing "avmLibDir" property in aion4j plugin configuration in pom.xml if you want to use a different version of AVM. But for now, let's use the default avm version bundled in the plugin.

$> mvn initialize

4. Build the project

$> mvn clean install

Note: During build, the plugin checks for apis which are not allowed in the java smart contract and shows the error accordingly.

Using Embedded AVM

1. Deploy your first AVM smart contract in an embedded AVM

$> mvn aion4j:deploy

Note: The deployer address is taken from the "<localDefaultAddress>" property in the plugin configuration section in pom.xml. You can also pass the deployer address as "-Daddress=a0xxxxx" in the above command. To make the deployment process easier, by default, the plugin creates an account for the deployer if it is not there and allocate some balance to it.

AVM storage path: The plugin creates the storage folder for AVM under $project_dir/target/storage folder. This folder is deleted every time "mvn clean" is executed. If you don't want to delete the storage folder during "clean" phase or you want to use it for multiple projects, you can configure it through "<storagePath>" property in the plugin configuration.

The plugin stores the last deployed address of the dapp jar in a config file under storage folder. So you don't need to provide contract address during method call.

2. Call a method in the smart contract

The archetype generated project comes with a sample java smart contract. To invoke "greet" method in the sample contract, run the aion4j:call maven goal.

$> mvn aion4j:call -Dmethod=greet -Dargs="-T AVM"

The output should be something similar:

[INFO] **************** Method call result ****************

[INFO] Data : Hello AVM

[INFO] Energy used: 66414

[INFO] *********************************************************

The aion4j:call goal syntax is as below:

$> mvn aion4j:call -Dmethod=<method_name> -Dargs="<arg_type> <arg_value> <arg_type> <arg_value> ..."

Note: You can also optionally pass -Daddress=

if you don't want to use the "localDefaultAddress" mentioned in the plugin configuration in pom.xml.

The supported arg_types are

-I int
-J long
-S short
-C char
-F float
-D double
-B byte
-Z boolean
-A Address
-T String

3. Get the balance

To get the balance of the default address.

$> mvn aion4j:get-balance

You can pass -Daddress property to get balance of another account. Example:

$> mvn aion4j:get-balance -Daddress=<address>

4. To create a new account with balance

This creates the specified account in storage with the provided balance for testing.

$> mvn aion4j:create-account -Daddress=a0xxxxx -Dbalance=<value>

Using Aion Kernel (AVM Testnet)

For remote deployment support, there is a separate <profile> section in the pom.xml with profile id "remote". So to trigger aion4j goals for remote Aion kernel, you need to pass "-Premote" in the maven command. Alternatively, you can change the "mode" property in the plugin configuration (pom.xml) to "remote" to enable remote deployment by default.

The aion4j maven goals take information like web3rpc.url, address from one of the below in the following order

-D properties in maven command.
Example:

mvn aion4j:deploy -Dweb3rpc.url=http://host:port -Daddress=ax000000 -Premote

Through environment variables. In this approach, you don't need to pass address, web3rpc.url in the mvn command. Example:

export web3rpc_url=http://<host>:<port>
export address=a0xxxxxxxx

Note: To set web3rpc.url through environment variable, you need to set/export web3rpc_url. "." should be replaced with "_".

1. To unlock the account and deploy, run

You should get a transaction hash as output.

$> mvn aion4j:deploy -Dweb3rpc.url=http://host:port -Daddress=ax00000 -Dpassword=<password> -Premote

You can also unlock the account explicitely and then deploy

$> mvn aion4j:unlock -Dweb3rpc.url=http://host:port -Daddress=ax00000 -Premote
$> mvn aion4j:deploy -Dweb3rpc.url=http://host:port -Daddress=ax00000 -Premote

Note: Make sure the above account has sufficient balance for deployment.

2. Get transaction receipt

Use the transaction hash from the above step to get the details.

$> mvn aion4j:get-receipt -DtxHash=<tx_hash> -Dweb3rpc.url=http://host:port -Premote

You should see a json output. Get the "contractAddress" value for the deployed contract address.

3. Call contract method

This goal makes a web3 rpc call for "eth_call" function to remote kernel.

$> mvn aion4j:call -Dweb3rpc.url=http://host:port -Daddress=a0xxxx -Dcontract=a0xxxxxx -Dmethod=greet -Dargs="-T AVMTestnet" -Premote

or, if web3rpc.url and address are set as environment variable (through export / set command), use following

mvn aion4j:call -Dcontract=a0xxxxxx -Dmethod=greet -Dargs="-T AVMTestnet" -Premote

4. Send contract transaction

This goal makes a web3 rpc call for "eth_sendTransaction" function to remote kernel

$> mvn aion4j:contract-txn -Dweb3rpc.url=http://host:port -Daddress=a0xxxx -Dcontract=a0xxxxxx -Dmethod=greet -Dargs="-T AVMTestnet" -Premote