Skip to content

Aion4j Maven Plugin User Guide

Jump to bottom
Satya edited this page Mar 7, 2019 · 30 revisions

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.

  1. Setup and Build
  2. Using embedded AVM
  3. Using remote kernel (AVM Testnet)
  4. Using Aion Kernel without account management. e.g; Nodesmith

Pre-requisites

  1. Java 10 and above
  2. 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.6

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.4.7</aion4j.plugin.version>
  ...
</properties>

Contract Main-class:

Verify contract's main class is same as entry in contract.main.class property in pom.xml's plugin section.

<contract.main.class>org.test.HelloAvm</contract.main.class>

Class-Verifier for whitelist classes

To enable class-verifier goal which verifies usage of allowed apis in the contract, you need to make sure that "class-verifier" goal is uncommented in pom.xml. This goal is executed during compile phase of maven build cycle.

<goal>class-verifier</goal>

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.

Web3 Rpc Url

The aion4j plugin needs the url to web3 rpc endpoint. This can be provided in pom.xml through web3rpcUrl property in plugin configuration. You edit the pom.xml to update web3rpcUrl property for plugin configuration in "remote" profile.

<configuration>
      ...
      <web3rpcUrl>http://host:port</web3rpcUrl>
</configuration>

Alternatively, you can provide web3 rpc url information through

$> mvn aion4j:deploy -Dweb3rpc.url=http://<host>:<port> ...
  • Setting web3rpc_url environment variable
For Mac / Linux : 
$> export web3rpc_url=http://host:port

For Windows
c:> set web3rpc_url=http://host:port

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

Address

The aion4j maven goals use account address in different goals to do different operations. You can pass the address information using one of the following methods

  • -D properties in maven command.
    Example:
mvn aion4j:deploy -Daddress=ax000000 ...
  • Through environment variables. In this approach, you don't need to always pass address in the mvn command. Example:
For Mac / Linux
export address=a0xxxxxxxx

For Windows
export address=a0xxxxx

Note: You can ignore -Dweb3rpc.url property in the following commands if you have already set that through environment variable or pom.xml configuration.

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 explicitly 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" [-Dvalue=<value>] -Premote

or, if web3rpc.url and address are set as environment variable or pom.xml, use following

mvn aion4j:call -Dcontract=a0xxxxxx -Dmethod=greet -Dargs="-T AVMTestnet" [-Dvalue=<value>] -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" [-Dvalue=<value>] -Premote

or, if web3rpc.url and address are set as environment variable or pom.xml, use following

$> mvn aion4j:contract-txn -Dcontract=a0xxxxxx -Dmethod=greet -Dargs="-T AVMTestnet" [-Dvalue=<value>] -Premote

5. To transfer from one address to another

$> mvn aion4j:transfer -Dweb3rpc.url=http://host:port -Dfrom=a0xxx -Dto=a0xxxxxx -Dvalue=<value> -Dpassword=<password> -Premote

6. To get balance

$> mvn aion4j:get-balance -Dweb3rpc.url=http://host:port -Daddress=a0xxxx -Premote

8. To create a new account

$> mvn aion4j:create-account -Dweb3rpc.url=http://host:port -Dpassword=test123 -Premote

9. To get logs

$> mvn aion4j:get-logs -Dweb3rpc.url=http://host:port [-DfromBlock=<blockno>] [-DtoBlock=<blockno>] [-Daddress=[comma separated addresses]] [-Dtopics=[comma separated topics]] [-Dblockhash=<blockhash>] -Premote

Using Aion Kernel without account management (e.g; Nodesmith)

The plugin also supports the client side transaction signing where the private key never leaves client's machine.

To know how to use client-side signing with private key and post transaction, please follow the below link

Client side signing with private key

Clone this wiki locally