eosBLACK : How to do Airdrop

Greetings from the eosBLACK team

The eosBLACK’s development team plans to serially publish useful information for those developers who aim to develop EOSIO DApps. First of all, we will start with the subject of the BLACK Token Airdrop, which we carried out last month.

Before reading this text, it is advisable to prepare the OS environment recommended by EOS and download the EOS source to the applicable OS to be built. This has been introduced in many writings by others, so please refer to them to prepare.

The following explanation has been written based on EOS version1.0.8 and, since it is a smart contract based on web assembly to compile C/C++, readers should have knowledge of C/C++. We aim to explain the process simply so that even novice developers can easily execute an airdrop. The entire source code is available on GitHub, so it will be useful to refer to it.

Airdrops are not difficult or complicated, and you can create and distribute your own tokens through the basic contract command provided by EOS. However, if you are a smart developer, you can add functionality to your contract by adding a policy to each token for efficient response. Thus, if you perform three steps — basic preparation, adding a function to a token, and performing an airdrop, you can carry out high-class airdrops with your own tokens. It may seem difficult at first, but we believe that you can understand it easily while you follow this text slowly, step by step.

Basic Preparation

The basic preparation consists of three steps — writing a token contract, compiling the prepared contract code, and uploading the contract to the chain. The following are explanations of each step.

STEP 1. Writing a contract

The first thing you need to do to perform an airdrop with EOS tokens is to write a contract that is suitable for the applicable token. The EOS source code basically provides the eosio.token contract class. You can extend this class and write a contract suitable for the applicable token you want to airdrop, as in the code below. As we have BLACK Tokens, we created the blacktoken class shown below. The eosio.token contract class is available on the EOS source code’s ‘contracts/eosio.token’, so please refer to this.

The major actions of the contract are to create, issue, and transfer. The following is a brief explanation about these three actions.

① Create a token

void create (account_name issuer, asset maximum_supply);

A token will be created with the issuer’s account and the asset should be transferred in the format of “10000 SYMBOL” or “10.00 SYMBOL”. The number in front of the asset is the maximum volume of the issue and can be expressed with up to 18 decimal places, while the SYMBOL (token’s name) should be defined with 1–7 uppercase letters.

② Issue a token

void issue (account_name to, asset quantity, string memo);
It is used when issuing tokens by quantity to an applicable account (to) and a memo can be written for the issue.

③ Transfer a token

void transfer (account_name from, account_name to, asset quantity, string memo);

It is used to transfer tokens by quantity from one account (from) to another account (to). When transferring, a memo can be written.

STEP 2. Compiling

After writing the source code, you can compile the code. eos is designed to create ‘wast’ and ‘abi’ files, in order, using ‘llvm’ and ‘abigen’. To this end, the utility ‘eosiocpp’ will be used. The usage and options of the eosiocpp command are shown below, and you can run it from the path where the applicable source is located.

As explained above, you will run the command twice. First, you will create the web assembly (.wast, .wasm) file using the ‘eosiocpp –o’ option.

Next, using the ‘eosiocpp –g’ option, you will go through the process to create an abi (application binary interface) file.

When compiling is complete, you can confirm the creation of three files in the file list through the ‘ls’ command.

STEP 3. Uploading the contract

Now, you can upload the contract to the EOS account to issue the token through the command ‘cleos’. The following is the command process.

The ‘api_server_address’ is the address of the server where the contract will be implemented, and the ‘account’ can be tailored to your needs. We created the account ‘eosblackteam.’ This account will be actually used to issue tokens on the Mainnet and a different account can be created and used for testing on the Jungle Net.

Up to here, you have carried out the basic preparation of issuing a token. Isn’t it really simpler than you thought?

However, various necessary conditions can occur depending on the situation of airdrop. For example, functions against hacking of exchange, blacklist function, limitation on tokens, and other conditions might occur, so additional performance should be implemented for the applicable function.

From here, let’s check out how to implement the added functions. As you know, after correcting the source code for the added function, you have to go through STEP 2. ‘Compiling’ again, as explained above.

Additional Functions

● Contract Stop / Restart
● Registration / Deletion of Blacklist
● Issue of Additional Token
● Deletion of a Number of Tokens
● Limitation on the Number of Tokens Used during a Specific Period

The eosblackteam has decided additional function policies shown above and processed according to the applicable policy.

For reference, even though a blacklist feature is offered through EOS, it is also possible to implement this feature separately. This is because it is more efficient to add a function to the contract and process it actively than to wait for EOS to register the account to the blacklist.

Among the additional functions, let’s briefly review the implementation of the “limitation (Hold) on the number of tokens used during a specific period!” As for the function ‘Hold’, you can process by comparing with the creation time of a token. As you might notice already, you can find ‘create_time’ has been added as ‘private’ in the example code.

As the initial creation time of the token must be maintained, in this case, the create_time is assigned to the current time for each creation so that the initial creation time will not be maintained, and there will be a problem in processing the Hold function through comparing with the creation time. So, how should we process it?

If you search the EOS library, you can find a ‘singleton’ that is quite familiar to developers. You can make variables, which are declared as ‘private’, into the structure below and connect this structure to the ‘singleton’. Then, you should add an annotation to the top of the ‘struct tokencfg’ to extract the data into ‘abi’.

The eosblackteam has processed using ‘singleton’, and if you know a better way, please share it with us by leaving a comment.

Performing an airdrop

As we have made the creation time of the contract to be recorded, shall we check it first on the Jungle Net? Using the account ‘time.tarzan’ created for the test, let’s create a token through the ‘create’ command, as shown below! Since the actions ‘create’ and ‘issue’ have been explained above, it will be easier to understand it now.

As you have created the token, let’s check if the settings are set up correctly. As shown below, the settings are found in the nodeos message. You can confirm that the set value has been output correctly.

Now, since the code is ready, let’s prepare the necessary resources for an airdrop. In general, airdrops are issued based on a Genesis snapshot, so the subjects are about 163,560 people. Let’s calculate RAM.

Amount of record x usage No. of recipients + Contract size = RAM, i.e. 240B x 163,560 = 37.44MB + 300KB (about 38MB). If you purchase resources to match the airdrop target, you are ready for the issue, and when you transfer the token through the ‘issue’ command as shown below, all the airdrop performances will be finished.

You have finished the airdrop! It’s not so hard, isn’t it?

Notices

When extracting the ‘. abi’ file

When you extract the ‘abi’ file after writing a contract, the ‘transfer’ item type will be extracted as a name. If you use the ‘type’ as a name, when transferring a token in the form of eos.transaction(‘code’, contract=> { contract.transaction(…) } ), the authorization part is not filled, so a transaction authentication error will occur. Therefore, after extracting the abi file, the transfer fields type should be ‘account_name’, not ‘name.’

The eosBLACK team airdrop source code is available at the following GitHub address.

Source code: https://github.com/eosBLACK/airdrop

We hope that our text will be a little help for all the developers who are participating in the development of the EOSIO ecosystem. We will continuously strive to provide useful information with good topics.

Thank you.

Yours sincerely,

eosBLACK team.

eosBLACK Homepage : http://eosblack.io
eosBLACK Koreos : http://koreos.io/eosBLACK
eosBLACK steemit : https://steemit.com/@eosblack
eosBLACK Facebook : https://www.facebook.com/eosBLACKTeam
eosBLACK twitter : https://twitter.com/EOSBLACK_IO
eosBLACK Telegram(Korean) : https://t.me/eosBLACK_Korea
eosBLACK Telegram(English) : https://t.me/eosBLACK_English
White Paper (Korean) : http://bitly.kr/nap2
White Paper (English) : http://bitly.kr/MOsA