Waffle example: token

About

This is an example that builds upon the echo example. Echo was a simple example on building an intreactable state changing smart contract. Token is an example of ERC20 token implementation in Acala EVM+. We won't be building an administrated or upgradeable token and we will use OpenZeppelin ERC20 implementation. For the setup and naming, replace the echo with token. Let's jump into it!

Smart contract

In this tutorial we will be adding a simple smart contract that imports the ERC20 smart contract from openzeppelin/contracts and has a constructor that sets the initial balance of the sender (which also represents the total supply of the token) as well as the name of the token and its abbriveration:

To be able to import the ERC20 from OpenZeppelin, we have to add @openzeppelin/contracts as a development dependency:

yarn add --dev @openzeppelin/contracts

Now that we have edded the @openzeppelin/contracts dependency, we can focus on building our smart contract. Your empty smart contract should look like this:

pragma solidity =0.8.9;

contract Token{
   
}

Import of the ERC20 from @openzeppelin/contracts is done between the pragma definition and the start od the contract block:

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

As we now have access to ERC20.sol from @openzeppelin/contracts, we can set the inheritance of our Token contract:

contract Token is ERC20 {

As the ERC20 already has the full fungible token standard implementation, we only have to add a constructor() function that sets all of the values:

    constructor(uint256 _initialBalance) ERC20("Token", "TKN") public {
        _mint(msg.sender, _initialBalance);
    }

We pass the initial balance of the token as _intialBalance and it will be assigned to the account that initiates the deployment of the smart contract. We also pass Token as the name of our example token and TKN for its abbriveration to the ERC20 contract that our Token contract is inheriting.

This concludes our Token smart contract.

Your contracts/Token.sol should look like this:

pragma solidity =0.8.9;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract Token is ERC20 {
    constructor(uint256 _initialBalance) ERC20("Token", "TKN") public {
        _mint(msg.sender, _initialBalance);
    }
}

As the Token smart contract is ready to be compiled, we can use the yarn build command (like we did in the hello-world) to compile the smart contract, which will create the build directory and contain the compiled smart contract.

Test

Your test file should be named Token.test.ts and the empty test along with the import statement should look like this:

import { expect, use } from 'chai';
import { deployContract, solidity } from 'ethereum-waffle';
import { Contract, ethers } from 'ethers';

import { evmChai, Signer, TestProvider } from '@acala-network/bodhi';

import Token from '../build/Token.json';
import { getTestProvider } from '../utils/setup';

use(solidity);
use(evmChai);

const NULL_ADDRESS = "0x0000000000000000000000000000000000000000";

describe("Token", () => {

});

In addition to the similar import statements to the ones in the echo the NULL_ADDRESS is also defined. It is used for validating the incorrect calls.

First thing to add to the Echo describe block are the provider, deployer, user, instance, deployerAddress and userAddress variables. Within the before action we assign the TestProvider to provider, Signer to the wallet and user variables, deployerAddress and userAddress are used to store the addresses of deployer and user and deployed contract to instance. The after action will disconnect from the provider:

    let provider: TestProvider;
    let deployer: Signer;
    let user: Signer;
    let instance: Contract;
    let deployerAddress: String;
    let userAddress: String;

    before(async () => {
      provider = await getTestProvider();
      [deployer, user] = await provider.getWallets();
      instance = await deployContract(deployer, Token, [1234567890]);
      deployerAddress = await deployer.getAddress();
      userAddress = await user.getAddress();
    });

    after(async () => {
      provider.api.disconnect();
    });

There are two describe blocks within Token block. The Deployment block validates that the smart contract was deployed as expected and the Operation block validates the operation of the smart contract:

    describe("Deployment", () => {
        
    });

    describe("Operation", () => {
        
    });

Deployment block contains the examples that validate the expected initial state of the smart contract:

The name should equal Token.
The symbol should equal TKN.
The total supply of the smart contract should equal 1234567890.
The initial balance of the deployer account should equal 1234567890.
The user account should have 0 balance.
The allowances should be set to 0 when the smart contract is deployed.

      it("should assing correct name to Token", async () => {
        expect(await instance.name()).to.equal("Token");
      });

      it("should assign correct symbol", async () => {
        expect(await instance.symbol()).to.equal("TKN");
      });

      it("should assign correct total supply", async () => {
        expect((await instance.totalSupply()).toNumber()).to.equal(1234567890);
      });

      it("should assign appropriate balance to the deployer", async () => {
        expect((await instance.balanceOf(deployerAddress)).toNumber()).to.equal(1234567890);
      });

      it("should not assign balance to a random address", async () => {
        expect((await instance.balanceOf(userAddress)).toNumber()).to.equal(0);
      });

      it("should set the allowances to 0", async () => {
        expect((await instance.allowance(deployerAddress, userAddress)).toNumber()).to.equal(0);
      });

The Operation block in itself is separated into two describe blocks, wihch are separated in itself:

Transfer: Contains the test cases to validate the transaction functionality of ERC20 tokens:

transfer(): Validates the correct operation of the transfer() function.

Allowances: Contains the test cases to validate the allowances and connected functionality of ERC20 tokens:

approve(): Validates the correct operation of the approve() function.
increaseAllowance(): Validates the correct operation of the increaseAllowance() function.
decreaseAllowance(): Validates the correct operation of the decreaseAllowance() function.
transferFrom(): Validates the correct operation of the transferFrom() function.

The contents of the Operation block should look like this:

      describe("Transfer", () => {
        describe("transfer()", () => {

        });
      });

      describe("Allowances", () => {
        describe("approve", () => {

        });

        describe("increaseAllowance", () => {

        });

        describe("decreaseAllowance()", () => {

        });

        describe("transferFrom()", () => {

        });
      });

The transfer() example validates the following:

When transferring tokens, the balances should be updated.
Transfer event should be emitted.
Transfers to 0x0 address should be reverted.
Trying to transfer more than own balance should be reverted.