How To Airdrop Your First Token

Published in

Bitfwd

10 min readMar 9, 2018

This is the second tutorial in bitfwd’s tutorial series where we teach everyday users (yes! that’s you, my dear reader) how to interact with the blockchain. This is a more advanced tutorial and will require more tools than before but I will do my best to walk you through the steps. Let’s begin!

In trying to be as inclusive as possible, I have made this tutorial extremely thorough. For more advanced users, feel free to breeze through to Step 4, where you learn how to use export balances.

A Note On Asking For Help

When asking for help, I only have one rule: try to include as much information as possible. (E.g. the contract address, errors that appear in your terminal, your device type.) This way, we won’t need to go back and forth in the comments. Feel free to join our telegram and ask for help there. I’ll reply as soon as I have time.

Prerequisites

You need to follow Moritz Neto’s tutorial on how to deploy your own contract.

What You Will Learn Today

You will learn the basics of how to navigate on the command line.
You will learn the basics of how to fork and clone repositories on Github.
You will learn how to install Nodejs through a version manager called NVM.
You will learn how to use Parity (A Rust implementation of geth) to extract account balances from the Ethereum blockchain.
You will learn how to run Parity so that you can broadcast transactions locally from your computer.
You will learn about token decimal size, which appears in every contract.
You will (finally!) learn about how to prepare the airdropping script to airdrop tokens for you.
You will also learn how you can implement your own custom airdropping function so you can determine how many tokens each user should be airdropped.

Step I: Navigating The Command Line.

Whip open a terminal and start by typing in:

pwd

This stands for “print working directory” and tells you where you currently are. Pick a name for the directory where you want to store your code and type to create the folder. (mkdir = Make directory, catching on?)

mkdir "cool-folder-name-here"

Now, let’s navigate into the directory using the next command.

cd "cool-folder-name-here"

This stands for “change directory” and will move your from your current location into the newly made folder. You can verify this by running pwd again. This will be the extent of the terminal commands that you will be learning today but if you want to learn more, check out this resource as well as the man pages. As an exercise, try figure out what the “ls” command does.

Make sure you have git installed as well. You can find the installation files here.

Step II: Forking & Cloning.

Now that we have our terminal ready, we need to get the code onto our computers. This process is called cloning. Since we might make changes to the code, it is better to clone a fork of the code than the codebase itself. Forking allows us to make modifications to the code without affecting the original repository.

So log in to Github and visit the code repository. In the top right hand corner there’s a fork button that you can click to fork the repository to your account.

When it finishes forking, you will notice that it has redirected you to your own copy of the repository (you can tell it’s a copy because in the URL, it will have your name in the middle instead of bitfwdcommunity).

Near the middle right hand side of the screen there is a “clone or download” button that you will click. Make sure you select “Clone with HTTPS.” Copy the link and paste it into the terminal with this command.

git clone "paste-the-url-here"

When you hit enter, it will prompt you for your username and then your password (use your Github username and password). Note that password’s do not show up when you type them into terminal. When you are finished, it will begin downloading the code repository onto your computer. Once you are done, type the following command:

cd Airdropper

This will move you into the Airdropper repository where you will run the commands necessary to use this tool. Now open the Airdropper folder in your favourite text editing tool (my favourite is Atom).

Step III: Installing Nodejs.

This airdropping script runs on Nodejs, which I recommend you install by going through Node Version Manager. The reason we will install Nodejs using NVM as opposed to any other way is because it allows for more sustainable development. NVM allows you to have fine grain control on which node version you are using, which is helpful if you are working on projects with many different node versions as dependencies.

To install it, you will use the following command

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash

Restart your terminal when you’re done. Now you can install nodejs! You can do this with a simple

nvm install node

Step IV: Exporting Account Balances

To be able to successfully airdrop our awesome token to others, we must first get a list of all the addresses that we wish to airdrop to. The easiest way to achieve this is by using Parity’s export state function.

First thing you need to do is install parity.

After you have installed it, you need to sync it up to the block you want to take a snapshot of. This means that if you want to extract all the balances at block 2 000 000, you have to sync to at least block 2 000 000. Note that you must run it with archive and fat-db mode on. The command that you will use to achieve this is:

parity -pruning=archive -fat-db=on -chain=ropsten

You may use whichever chain you like but in this tutorial we will be using ropsten. To confirm that parity has the correct settings, it will start up with a bunch of configurations showing. There will be a line that says “State DB Configuration”. Check that this says archive and fat-db.

The reason we want archive mode and fat-db turned on is because we do not want to prune the state trie where all the balance information is stored. When parity exports the state, it generates the balance by iterating over the state trie. Once you have synced up to the block at which you would like to export state, you can stop syncing parity.

Let’s assume that we wish our exported balances to abide by the following rules:

We want balances in block 2 000 000.
We want balances above 1 000 RtETH
We want balances below 500 000 RtETH

Given these rules, we would use the following code:

parity export state --chain=ropsten -no-storage -no-code -min-balance=1000 -max-balance=500000 -at=2000000 balances.json

This process may take several hours to complete.

You will discover while doing this that it is important to set a max balance otherwise a few users with enormous balances may end up with all your tokens.

Step V: Broadcasting Transactions

Broadcasting transactions to the Ethereum network can be done in two ways via a remote node such as Infura or via a local parity mode. Since we will be broadcasting many transactions, it is better to use your own node. If you have synced your parity node using fat-db and with archive mode on, it is syncing much slower than it would if it was in fast mode. To reset your node and get it to warp sync back to the latest state, you can kill the database and then start it up again using the following commands.

parity db kill -chain=ropsten
parity -chain=ropsten -pruning=fast -fat-db=off

Let this run in the background while we prepare the rest of the tools.

Step VI: Token Decimal Size

Before we get into configuring the Airdropper, I’ll talk a bit about the decimals field in the token contract. The decimals field basically describes how divisible your token will be. The reason this is important is because not all tokens should be divisible (e.g. do you want a divisible “unicorn” token?). The default value for decimals is 18. The impact of the decimals field is that all token values have to take this into account (i.e. have an extra 18 zeroes).

Step VII: Preparing The Airdropper

Let’s set up the airdropper now. The main file is in index.js. Let’s take a look at lines 18–23, which contain a few variables that we can modify. We will start off by doing a very basic airdrop of 1 token to each user.

AIRDROP_QTY refers to the fixed amount of tokens you are dropping to each user. The default value is set at 1.
DURATION is the time in between transaction submissions.
GAS_LIMIT & GAS_PRICE are the respective limits and prices that you are willing to pay for your transaction. You can check to see how many pending transactions there are on etherscan before you estimate how much gas you are willing to pay per transaction. The default value that I have left it at is 5gwei.

As an example, if your contract has 1 000 000 tokens, you will need to set the INITIAL_TOKENS value to 1 000 000 000 000 000 000 000 000. (1 000 000 * 10 ^ d, where d is the decimals values in your contract, with 18 being the default value).

Next, we need to set up our custom config file. Make a new file in the root directory (next to index.js) called “config.js”. It will look something like this …

module.exports = {
    privateKey: ‘put-your-private-key-here’,
    contractAddress: ‘put-your-deployed-contract-address-here’,
    abi: ‘put-your-deployed-contract-abi-here’
}

If you used a seed instead, you can remove the privateKey field and replace it with a seed field and the Airdropper will still work. If you did not keep a copy of your ABI, you will need to recompile the contract in remix and copy the ABI (it’s underneath the bytecode field).

Once you have created a config.js file as well as finished customising the modifiable fields, you will now be able to airdrop tokens (finally!). Just before we get to it, we’ll go through a final checklist to make sure everything goes smoothly…

Airdrop Checklist

Fully synced parity node. (You can check what block you are up to and compare it with etherscan).
Enough RtETHs on your account with the tokens. You can get more from our faucet. As a ballpark estimate, 3000 transactions at 5gwei each will cost about 0.5 RtETHs (so make sure you have enough!)
Your account page open on etherscan (on ropsten!) so you can see the pending transactions being broadcast to the ethereum network.

If you have both of these things, you will be ready to run the Airdropper with the following command.

node index.js

You will notice that the script will begin to “hang” and at this point you can refresh the ropsten etherscan page and begin to see the pending transactions roll in. As each transaction is mined, the transaction hash as well as index data will be printed to your terminal. Let it run for a bit and when it finishes, it will terminate by itself.

You can search up your token contract here. When you visit the address, you can click on the Token Holders field and then you can see the token distribution of all the tokens. When your contract is finished you will see that the tokens are distributed based on the total RtETH balance. You will notice that all of your tokens are still with your account (because we only sent one each to everyone else!)

Step VIII: Custom Airdrop Function

In practice, you don’t just want everyone to have one token. Maybe you have a cool idea about how the tokens should be distributed. For example, maybe you think that users should be rewarded tokens proportionally based on the amount of RtETHs they have. For example, if there are only two users that you wish to airdrop to and one owns 10% of the total RtETH and the other owns 90% of the RtETH, then they should receive 10% of the tokens and 90% of the tokens, respectively.

Fortunately for you, I’ve already implemented this function for you. Now, before we get to airdrop our tokens again, you will have to redeploy your contracts and update the address in your config.js file. You will also have to make sure that the INITIAL_TOKENS value in the index.js file on line 23 matches the exact balance that you have minted. This is important as this value is used in token calculation function.

To update our token calculation function, we will go to the function called “calculationDrop” and comment out line 90 while uncommenting line 84–89. This function here takes in the total balance and the proportional balance and returns the amount of tokens needed to be airdropped to this person. Once you have done this, go through the checklist again and then you can run the code!

Now you can check your token contract on Etherscan again and this time, you will see that the tokens are much more fairly distributed.

If you’re up for the challenge, try writing your own token distribution function (and then submit a PR and then we can have a whole library of custom airdrop functions!) ;)

Conclusion

Well, that’s it! By now you will have learnt how to deploy your first contract AND distribute its tokens in an equitable way. Was anything unclear in this tutorial? Got questions about how to deploy it? Let me know in the comments!

If you liked this content, (or you want me to reply to your questions faster ;)) give me some claps! If you’re interested in all things blockchain, then follow me on twitter.