✈️💧 Merkle Air Drop

Efficient token air drop using Merkle Tree.

Introduction

When a new token is offered (ICO), the owner has the option to perform an air drop to distribute his token between wallets at random, in order to improve his visibility. It can issue two main problems: users with unwanted tokens and high cost. A possible solution is employing a Merkle Tree, which will solve the problems in the following way:

There will be a pre defined white list of address that will be able to redeem the new token.
A Merkle Root will be build based on the pre defined white list.
Only the Merkle Root will be stored in the contract so as to verify if the customer is in the white list.
Since customers request tokens, they are the ones who pay the transaction fee.

Token contract

A token has been implemented based on ERC20 from Open Zeppelin to be used in the Air Drop contract. This token is instantiated with name, symbol and cap, and the caller becomes the owner. This token also inherits from ERC20Capped contract, which is initialized with the parameter cap. Finally, mint function is implemented so as to only the contract owner is allowed to mint new tokens.

AirDrop contract

The AirDrop contract is the core of this project. This contract is instantiated with token address, Merkle Root and a max redeem amount, and the caller becomes the owner. A token must be issued before AirDrop deployment. The Merkle Root must be precomputed so as to deploy the contract and prevent unwanted addresses in the white list.

Customers in the white list may redeem at most the pre defined max redeem amount submitting their Merkle Proof. The contract owner may update the white list, compute a new Merkle Root, update it in the contract and the history of users that already redeemed their tokens will not be changed. When the owner wishes to cancel or just shut down the air drop, all remaining tokens will be transfered to his account and the Air Drop contract will be destructed.

⛽ Gas Optimization

Any variable is initialized in its declaration to reduce construction cost.
The function redeem was defined as external to prevent the parameter witnesses from being copied to memory.
Only Merkle Root was stored in the contract as a means of checking whitelisted customers and saving a great amount of storage.

🔐 Security

Token contract
- Only contract owner can mint new tokens.
- Employed ERC20Capped to limit the total supply. Total supply is defined in deployment.
Air Drop contract
- To redeem tokens, customer must have to provide its Merkle Proof.
- Customers can redeem only once and only a predefined maximum redeem amount to prevent a customer from acquiring all tokens.
- Only contract owner can update the Merkle Root and cancel the Air Drop.
- Cancelling the Air Drop will initiate contract self-destruction in order to prevent any future use.
General
- No warnings or errors are issued in the contracts.
- Contracts have 100% of test coverage.

🏃 How to run

Open your terminal in the folder you want to clone the project

# Clone this repo
git clone https://github.com/LorranSutter/MerkleAirDrop.git

# Go to the project folder
cd MerkleAirDrop

# Init truffle
truffle develop

# Run migrations
migrate

If you change your contracts, you will have to run migrations again. Just type the following command:

# Run migrations again
migrate --reset

💉 Tests

To run the tests, execute the following command:

# Run tests
truffle test

To check tests coverage, execute the following command:

truffle run coverage

📖 Resources

💻 Technologies

Solidity - smart contract programming language
Truffle - dApp environment
Truffle-assertions - additional assertions for truffle
Open Zeppelin Contracts - a library for secure smart contract development
Solium - Solidity linter to analyse code for style & security issues
Solidity Coverage - code coverage for Solidity testing
Ethers.js - interact with smart contracts
bn.js - library to handle big numbers
ESlint - pluggable JS linter

LorranSutter / MerkleAirDrop