-
Notifications
You must be signed in to change notification settings - Fork 3
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.
- Setup and Build
- Using embedded AVM
- Using remote kernel (AVM Testnet)
- Using Aion Kernel without account management. e.g; Nodesmith
- Java 10 and above
- Maven 3.5.4 and above
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.20
Follow the instruction to enter groupId, artifactId and package information to generate the project.
The generated project has a sample HelloAVM contract.
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>x.x.x</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>
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
$> 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.
$> 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.
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
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>
This creates the specified account in storage with the provided balance for testing.
$> mvn aion4j:create-account -Daddress=a0xxxxx -Dbalance=<value>
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 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
- -Dweb3rpc.url=http://host:port in maven command line
$> 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 "_".
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.
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.
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.
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
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
$> mvn aion4j:transfer -Dweb3rpc.url=http://host:port -Dfrom=a0xxx -Dto=a0xxxxxx -Dvalue=<value> -Dpassword=<password> -Premote
$> mvn aion4j:get-balance -Dweb3rpc.url=http://host:port -Daddress=a0xxxx -Premote
$> mvn aion4j:create-account -Dweb3rpc.url=http://host:port -Dpassword=test123 -Premote
$> mvn aion4j:get-logs -Dweb3rpc.url=http://host:port [-DfromBlock=<blockno>] [-DtoBlock=<blockno>] [-Daddress=[comma separated addresses]] [-Dtopics=[comma separated topics]] [-Dblockhash=<blockhash>] -Premote
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