Skip to main content

Quick Start

1. Introduction​

This guide teaches you how to create aelf smart contracts, using the example of the HelloWorldContract. By following the instructions here, you'll learn to make your own basic contracts and interact with it on-chain.

2. Setting Up Your Development Environment​

The easiest way to get started is to use this repository template: https://github.com/AElfProject/aelf-devcontainer-template.

Click on the Use this template button and choose Create a new repository.

Type a suitable repository name and click Create repository.

Within the GitHub interface, click on Code, then choose Codespaces.

Click on the plus "+" sign to create a new Codespace.

After some time, your workspace will load with the contents of the repository, and you will be able to continue your development using GitHub Codespaces.

Portkey Login

3. Starting Your Smart Contract Project​

Open your Terminal.

Enter the following command to generate a new project:

Terminal
dotnet new aelf -n HelloWorld

4. Adding Your Smart Contract Code​

Now that we have a template hello world project, we can customize the template to incorporate our own contract logic. Lets start by implementing methods to provide basic functionality for updating and reading a message stored persistently in the contract state.

src/HelloWorldState.cs
using AElf.Sdk.CSharp.State;

namespace AElf.Contracts.HelloWorld
{
    // The state class is access the blockchain state
    public class HelloWorldState : ContractState
    {
        // A state that holds string value
        public StringState Message { get; set; }
    }
}

The implementation of file src/HelloWorld.cs is as follows:

src/HelloWorld.cs
// contract implementation starts here
namespace AElf.Contracts.HelloWorld
{
    public class HelloWorld : HelloWorldContainer.HelloWorldBase
    {
        // A method that updates the contract state, Message with a user input
        public override Empty Update(StringValue input)
        {
            State.Message.Value = input.Value;
            Context.Fire(new UpdatedMessage
            {
                Value = input.Value
            });
            return new Empty();
        }

        // A method that reads the contract state, Message
        public override StringValue Read(Empty input)
        {
            var value = State.Message.Value;
            return new StringValue
            {
                Value = value
            };
        }
    }
}

Build the new code with the following commands:

Terminal
cd src
dotnet build

5. Preparing for deployment​

Creating A Wallet​

To send transactions on the aelf blockchain, you must have a wallet.

Run this command to create aelf wallet.

Terminal
aelf-command create

result

Acquiring Testnet Tokens for Development​

To deploy smart contracts or execute on-chain transactions on aelf, you'll require testnet ELF tokens.

Get ELF Tokens

Run the following command to get testnet ELF tokens from faucet. Remember to either export your wallet address or replace $WALLET_ADDRESS with your wallet address.

Terminal
curl -X POST "https://faucet.aelf.dev/api/claim?walletAddress=$WALLET_ADDRESS" -H "accept: application/json" -d ""

To check your wallet's current ELF balance:

Terminal
aelf-command call ASh2Wt7nSEmYqnGxPPzp4pnVDU4uhj1XW9Se5VeZcX2UDdyjx -a $WALLET_ADDRESS -p $WALLET_PASSWORD -e https://tdvw-test-node.aelf.io GetBalance

You will be prompted for the following:
Enter the required param <symbol>: ELF
Enter the required param <owner>: $WALLET_ADDRESS

You should see the Result displaying your wallet's ELF balance.

6. Deploying Your Smart Contract​

The smart contract needs to be deployed on the chain before users can interact with it.

Run the following command to deploy a contract.

Terminal
aelf-deploy -a $WALLET_ADDRESS -p $WALLET_PASSWORD -c $CONTRACT_PATH/$CONTRACT_FILE.dll.patched -e https://tdvw-test-node.aelf.io/

Please wait for approximately 1 to 2 minutes. If the deployment is successful, it will provide you with the contract address.

result

7. Interacting with Your Deployed Smart Contract​

Lets try to call methods on your newly-deployed smart contract using aelf-command.

Firstly, we will set a message using the Update method. Run the following command, and enter the message argument as test. This will set test into the Message contract state.

Terminal
aelf-command send $CONTRACT_ADDRESS -a $WALLET_ADDRESS -p $WALLET_PASSWORD -e https://tdvw-test-node.aelf.io Update

After that, we can use Read method to retrieve the value previously set for the Message contract state. Running the following command should yield test.

Terminal
aelf-command call $CONTRACT_ADDRESS -a $WALLET_ADDRESS -p $WALLET_PASSWORD -e https://tdvw-test-node.aelf.io Read