Skip to content

TUTORIAL: Coding locally with "AEproject"


This tutorial will walk you through the process of writing Sophia ML Smart contract with the AEproject tool. We will install AEproject, initialize a folder with AEproject, and update a HelloWorld smart contract.


  • Installed node.js and npm (node package manager)
  • Installed docker and docker-compose. Installation instructions can be found here
  • Installed Visual Studio Code
  • Completed the HelloWorld with Sophia tutorial

Installing AEproject

AEproject is an æternity framework that helps with setting up an æpp project. The framework makes the development of smart contracts in the æternity network very easy. It provides commands for the compilation of smart contracts, running a local æternity node, unit testing and deployment of smart contracts.

The package is available for installation from the npm global repository. You will be able to install it via the following command:

npm install -g aeproject

After installing

Now, you have a global command aeproject, with aeproject -h command you have a quick reference list of all commands:

Usage: aeproject [options] [command]

  -V, --version            output the version number
  -h, --help               output usage information

  init [options]           Initialize AEproject
  compile [options]        Compile contracts
  test [options]           Running the tests
  env [options]            Running a local network. Without any argument node will be run with --start argument
  node [options]           Running a local node. Without any argument node will be run with --start argument
  compiler [options]       Running a local compiler. Without any arguments compiler will be run with --start argument
  deploy [options]         Run deploy script
  history [options]        Show deployment history info
  contracts [options]      Running a Contract web aepp locally and connect it to the spawned aeproject node.
  shape <type> [type]      Initialize a web Vue project.
  export-config [options]  Export miner account, few funded accounts  and default node configuration.
  inspect [options] <tx>   Unpack and verify transaction (verify nonce, ttl, fee, account balance)
  fire-editor [options]    Download, install and run locally the Fire Editor
  compatibility [options]  Start env with latest versions and test the current project for compatibility

Generating the project structure

First, what we need to do is create a project folder:

mkdir ~/coding_locally

Go to the newly created folder cd ~/coding_locally and initialize the folder with:

aeproject init

You will see an output similar to this:

===== Initializing AEproject =====
===== Installing aepp-sdk =====
===== Installing AEproject locally =====
===== Creating project file & dir structure =====
===== Creating contracts directory =====
===== Creating tests directory =====
===== Creating integrations directory =====
===== Creating deploy directory =====
===== Creating docker directory =====
==== Adding additional files ====
===== AEproject was successfully initialized! =====

The init command creates an æpp structure with several folders and scripts:

├── contracts
│   └── ExampleContract.aes
├── deployment
│   └── deploy.js
├── docker
├── integrations
├── node_modules
├── test
│   └── exampleTest.js
  • contracts - directory in which the developer can create contracts
    • ExampleContract.aes - an exemplary smart contract
  • deployment - directory that contains the deployment scripts
    • deploy.js - an exemplary deployment script
  • test - directory that contains the unit test scripts
    • exampleTest.js - an exemplary unit test script

Creating the HelloWorld.aes smart contract

Following up on our previously written HelloWorld smart contract, we will make the following changes to the contract: add a wallet address to the state, update the say_hello function, and create get_info function to retrieve our smart contract data.

The first step is to create the HelloWorld.aes file:

touch ./contracts/HelloWorld.aes

Now we can write Sophia codes in our newly created file. The entire code of our HelloWorld.aes is:

contract HelloWorld =

  record state = { 
    name : string,
    user : address }

  stateful entrypoint init() = { 
    name = "",
    user = Call.caller }

  public stateful entrypoint say_hello(name' : string) : string = 
    let greetings = String.concat("Hello, ", name')
    put(state{name = name'})

  public entrypoint get_info() =

Our contract now stores name(as a string) and user(as an address) in its state. The user address is the account(public address) that deployed the contract. The say_hello function stores the name inserted as a parameter then returns a greeting with the name. Finally, the get_info function returns the whole state data as an object.

  1. Tutorial Video
  2. Video Introducing AEproject
  3. Video Installing AEproject on Ubuntu
  4. Video Installing AEproject on Windows


Writing smart contracts on the æternity blockchain is nice and easy. In just a few minutes and with a few commands, one can initialize a folder using the aeproject tool. If you encounter any problems installing AEproject, contact us through the æternity dev Forum category.