Aion University

So you want to be a DApp developer?


Well you've come to the right place. You'll find comprehensive guides and documentation to help you start developing with Aion as quickly as possible, as well as support if you get stuck. Let's jump right in!

Let's DApp

πŸŽ“ Deploy your first Java Smart Contract!

Utilize Maven for all your Java Smart Contract needs and deploy your contract to the AVM Testnet.

Guide Level: Beginner

You are a developer who

  • Is familiar with smart contracts
  • Is familiar with blockchain development workflows

We will be using Maven for all your your smart contract needs. This includes:

  • Creating a project
  • Compiling your Java smart contract
  • Connect to the AVM Testnet
  • Deploy your contract to the Testnet

Aion4j Maven Plugin provides end to end development support for AVM based smart contract in Java. It supports development on both embedded AVM or a remote Aion kernel (such as the AVM Testnet, which we'll be going through in this guide)

Prerequisites

Requirements

Head over to Aion Docs for installation guide.

1. Setup

The fastest way to create a AVM project is using a maven archetype - avm-archetype. Archetype is a Maven project templating toolkit. This is an existing Java tool.

An archetype is defined as an original pattern or model from which all other things of the same kind are made.

1.1 Create a Project

Create a new project by running the following Maven command (in your desired project directory).

mvn archetype:generate -DarchetypeGroupId=org.aion4j -DarchetypeArtifactId=avm-archetype -DarchetypeVersion=0.6

The project automatically generates a sample HelloAVM contract. Smart contract pre-made templates will be coming soon.

1.2 GroupId, ArtifactId, Version, and Package

The archetype generator will ask you for a groupId, artifactid, version, and package. You can put whatever you want in these fields, but it will help you further down the line if you follow these guidelines.

Type Description Example
groupId Uniquely identifies your project across all projects. Must follow Apache's reverse domain naming control convention. org.apache.maven, org.example.commons
artifactId The name of the .jar file without version. Also, the name of your project. commons-math, hello-world
version Which version of the project you're building. You can choose any typical version with numbers and dots. 0.0.1, 19.5, 5.1.3-NIGHTLY
package Apache is very specific about what to use here. However for the purposes of this HelloWorld project, the package name doesn't really matter. HelloWorld, gov.whitehouse.socks.mousefinder, edu.cmu.cs.bovik.cheese

Here's an example:

Confirm properties configuration:
    groupId: com.helloworld
    artifactId: hello-world
    version: 1.0
    package: com.helloworld

Your pom.xml will have the information you entered during configuration. Using the sample configuartion above, the pom.xml will look like this.

<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
  
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.helloworld</groupId>
    <artifactId>hello-world</artifactId>
    <version>1.0</version>
    
    <name>hello-world</name>

  ...
</project>

1.3 Project Structure

Once you've run the archetype command and filled in the fields, you will have a file structure similar to this:

hello-world/
β”œβ”€β”€ pom.xml
└── src
    β”œβ”€β”€ main
    β”‚   └── java
    β”‚       └── com
    β”‚           └── helloworld
    β”‚               └── HelloAvm.java
    └── test
        └── java
            └── com
                └── helloworld
                    └── HelloAvmRuleTest.java

1.4 Edit pom.xml

We have to edit pom.xml file in the generated project. We will be doing 2 things.

  1. Modify the <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.9</aion4j.plugin.version>
...

</properties>
  1. line 105: Uncomment the <goal>class-verifier</goal> in the pom.xml file.

1.5 Initialize & Build

By default, Maven will copy the required AVM jars to the lib folder.

You can also point to a different AVM lib folder by changing avmLibDir property in pom.xml file (if you want to use a different version of AVM).

mvn initialize
mvn clean install

Note: During build, the plugin checks for APIs which are not accepted in the Java smart contract and will show the error accordingly.

2. Compile

To compile any changes to your contract, save your changes, then re-initialize and build (within your project directory):

mvn clean install

Remember to always compile your Java contract before deployment!

3. Connect to the Aion AVM Testnet

3.1 Nodesmith Endpoint

We will need to modify our endpoint in order to connect to the AVM Testnet.

  1. Sign up for Nodesmith
  2. Change your Nodesmith Endpoint to avmtestnet like so:
    api.nodesmith.io/v1/aion/avmtestnet/jsonrpc?apiKey=YOURAPIKEY

3.2 Set Web3 Connection

There are 2 Ways to connect to the Aion Network.

1. Update pom.xml file for Web3 RPC Url Connection

We will be editing the Web3 RPC Url (<web3rpcUrl></web3rpcUrl>) in our pom.xml file, with our endpoint (You can use any endpoint - in this example below we'll be using Nodesmith).

<profiles>
 <profile>
  <id>remote</id>
  <build>
    <plugins>
      <plugin>
        ...
        <configuration>
           <mode>remote</mode>
           <avmLibDir>${avm.lib.dir}</avmLibDir>
           <web3rpcUrl>https://api.nodesmith.io/v1/aion/avmtestnet/
             jsonrpc?apiKey=xxxxxxxxxxxxxx</web3rpcUrl>
        </configuration>
        ...

2. Set your environment variables

It is important to note that if you set your environment variables, it will override any existing information that is already in your pom.xml file. So, if you've already set your Web3 RPC Url in your pom.xml file, you can just set your private key (instead of setting your Web3 RPC Url again)

Mac and Linux

export pk=YOUR_PRIVATE_KEY
export web3rpc_url=YOUR_NODESMITH_ENDPOINT

Windows

set pk=YOUR_PRIVATE_KEY
set web3rpc_url=YOUR_NODESMITH_ENDPOINT

4. Account Management

You will need

If you do not currently have an Aion account, easiest way is to download AIWA and have an Aion address generated for you. With AIWA, you will be able to see the balance of your account, your account address, and access to your private key to that account.

4.1 Connect AIWA To AVM Testnet

  1. Change your Nodesmith Endpoint to avmtestnet like so:
    api.nodesmith.io/v1/aion/avmtestnet/jsonrpc?apiKey=YOURAPIKEY

  2. Connect AIWA via Custom URL

4.2 Account Balance

If you're using AIWA, you can check the account balance by making sure your network is connected to the Aion AVM Testnet (See above).

Or, you can get any account balance with this Maven command.

mvn aion4j:get-balance -Daddress=<ACCOUNT_ADDRESS> -Premote
  • See Aion Docs for all account-related commands for connecting to a remote network.

5. Deployment

What happens when you deploy a Java Contract?

The peer-to-peer network shares compatible versions that are running the same Aion kernel. That includes the AVM, and ledger history, and a transaction pool the miners.

The AVM is the virtual machine running the Aion kernel, that allows us to execute Java programs. When deploying the contract, an address will be generated for your smart contract called a "contract address".

Remember to make sure your updated contract is compiled - before deployment

Deploy your contract!
If you have already set your environment variables for your private key and Web3 RPC Url, use this Maven command.

mvn aion4j:deploy -Premote

Or, if you have not set any environment variables, use this command.

mvn aion4j:deploy -Dpk=YOUR_PRIVATE_KEY -Premote

After successfully deploying your contract, a transaction hash should be returned. You will need this transaction hash to retrieve your transaction receipt (in the next step).

6. Transaction Receipts

With all contract deployments and calls, a transaction receipt will be generated if it gets successfully mined. The transaction receipt can tell you information such as the transaction hash, contract address, status...etc.

There are 2 ways of checking your transaction receipts.

1. Get the last transaction receipt

Whatever your last transaction was to the network (whether its deploying a contract or transferring money), this maven command will bring up the last transaction receipt.

mvn aion4j:get-receipt -Premote 

2. Get transaction receipt from the transaction hash

A transaction hash is generated anytime you interact with the blockchain. Save important transaction hashes so you can grab the transaction receipt from it, like so.

mvn aion4j:get-receipt -DtxHash=TRANSACTION_HASH -Premote

Here's an example of retrieving a transaction receipt from the hash.

mvn aion4j:get-receipt -DtxHash=0x0323167e8cf8b67a03a70fc7c74905847c84d0304adb234a26158e2365f1ac63 -Premote


> [INFO] Scanning for projects...
>
> ...
>
> [INFO] Txn Receipt:
> [INFO]  {"result":{"blockHash":"0xd4c6e6d3c7503b09c652fb03ea5f705ba3382bfb5419aa833866a26ad0c84caa",
"nrgPrice":"0x174876e800",
"logsBloom":"00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"nrgUsed":"0x2db96c",
"contractAddress":"0x0fc49f0ca77603058f1d2f29ad881737bebf78a8c79ef96f14965a401b81eb0c",
"transactionIndex":"0x0",
"transactionHash":"0x0323167e8cf8b67a03a70fc7c74905847c84d0304adb234a26158e2365f1ac63",
"gasLimit":"0x4c4b40",
"cumulativeNrgUsed":"0x2db96c",
"gasUsed":"0x2db96c",
"blockNumber":"0x677",
"root":"65caca665e3d625a1ddfa1d5f626ec32ac2f94b15624014fe6925ebd25390b65",
"cumulativeGasUsed":"0x2db96c",
"from":"0xa0e24c8317dc98ecb8d5abb7fb9cc77ce3fb801e05d7e3dfb94e48dbc8715f4c",
"to":null,
"logs":[],
"gasPrice":"0x174876e800",
"status":"0x1"},
"id":0,
"jsonrpc":"2.0"}
>
> ...

7. Contract Interaction

There are two ways to interact with a contract, with a contract transaction or a contract call.

7.1. Contract Transaction

A contract transaction is when you are modifying the blockchain by sending instructions to the contract. It is considered a transaction since it has to be signed by an account and NRG is required for execution.

Maven caches the most recent contract address, so now we will send a contract transaction, executing the method `greet'. On success, txHash is cached as last transaction.

-Dvalue=<value> is optional and is used when you need to send AION to the contract.

mvn aion4j:contract-txn -Dmethod=greet -Dargs="-T β€˜new AVMTestnet’" [-Dvalue=<value>] -Premote

For specific contract addresses:

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

Always check the transaction receipt to ensure that the transaction has been successfully mined into the block

Argument Types

Symbol
Type

-I

Integer

-J

Long

-S

Short

-C

Char

-F

Float

-D

Double

-B

Byte

-Z

Boolean

-T

String

7.2. Contract Call

A contract call is when are you are simply reading data from the blockchain and not modifying it. Thus, a transaction is not needed. The function call is carried out by the node and since nothing is mined, no NRG is required.

mvn aion4j:call -Dmethod=sayHello -Premote

For specific contract addresses:

mvn aion4j:call -Dmethod=sayHello -Dcontract=YOUR_CONTRACT_ADDRESS -Premote