Aion4j Tips — Debug Java Smart Contract with Embedded AVM and Aion4j Plugins

4 min readJun 8, 2019


In a Java smart contract project, you can write unit tests and debug the smart contract code as you do for a normal Java application. For details, you can check this blog.

In this post, I will explain another way if you want to do some ad-hoc debug/tests without writing unit tests. One of the biggest advantage of AVM (Aion Virtual Machine) is that developer can use their existing Java IDE and tools for smart contract development. That’s also true for smart contract debugging.

So let me explain how you can use Aion4j Maven Plugin and IntelliJ IDE to debug a Java smart contract deployed in an embedded AVM. But you can use any other standard Java IDE as long as you are able to setup remote debugging in the IDE.


  1. Java 10 and above
  2. Maven 3.5.4 and above
  3. Aion4j IDEA Plugin (Optional. Can be installed from IntelliJ Plugin Marketplace)
  4. Create a Java smart contract maven project.

Note: Step by step instructions to create a maven based smart contract project can be found at Aion Doc website.

Step -1 : Create a remote debugging profile (IntelliJ IDE)

If you are using any other Java IDE, please refer to the IDE’s doc for “Remote Debug Profile” setup.

  • Select Run -> Debug
  • Select “Edit Configurations”
  • Click “+” to add a “New Configuration”
  • Select “Remote”
  • Provide a name for this configuration. Let’s say “AVM Contract Debug”
  • Edit debug port as “8000”. Make sure that Host value is “localhost”

Step-2 : Deploy Smart Contract project with debug mode on

To keep the debug information, you need to deploy the smart contract with debug mode on.

To clean & build and deploy through maven command line : -

$> mvn clean install
$> mvn aion4j:deploy -DpreserveDebuggability

Note: -DpreserveDebuggability option enables debug mode for an embedded AVM deployment.

Alternatively, if you are using Aion4j IDEA plugin, you can deploy directly from IntelliJ IDE. But make sure you have enabled “Preserve Debug Mode” option in Aion Virtual Machine -> Configuration -> Embedded AVM section.

Step-3 : Call smart contract method

To call a smart contract method with debugging, we are going to use mvnDebug command instead of mvn. When you run this command, it opens port 8000 as debug port.

  • Add a break point in contract’s source code in IDE editor
  • Run mvnDebug to call contract’s method. Only mvn is replaced with mvnDebug. All other parameters are same as normal mode.
$> mvnDebug aion4j:call -Dmethod=getString -Dargs="-T AVMDebug" -DpreserveDebuggability
  • mvnDebug commands will start debug listener port at 8000 and wait for the debugger to connect.

Step-4 : Connect Debugger

To connect a debugger to the debug port (default: 8000), in IntelliJ

  • Go to Run -> Debug
  • Select the debug configuration created in Step-1
  • Run the debugger. The IntelliJ debugger will now connect to debug port started by mvnDebug. Now the debugger in IDE should stop at the debug break-point.
  • So now continue debugging as you do for normal Java application.

Note: Sometime IntelliJ doesn’t recognize a break-point. So it doesn’t stop the execution at the break-point. If that happens, you may need to restart the IDE, invalidate cache and do a clean build & deploy first.


  1. Aion4j Maven Plugin Doc :
  2. Aion4j IDEA Plugin Doc :
  3. AVM GitHub :
  4. BloxBean :