Generic Airdrop Canister

Showcase
1

Generic Airdrop Canister

Overview

The Generic Airdrop Canister facilitates token airdrops to a specified dataset of users and their respective shares, as defined in a JSON file. The canister is populated with user data via the extract_json.sh script.

Specification

Features

  • JSON File Upload: Use extract_json.sh to upload a JSON file containing user data and their respective token shares.
  • Automated Airdrop Execution: Automatically distributes tokens to users based on the JSON data.
  • Error Handling: Handles various errors and provides appropriate feedback.

JSON File Format

The JSON file should have the following structure:

  • Structure:
    [
  {
    "Principal": "user-principal-1",
    "Amount": 100
  },
  {
    "Principal": "user-principal-2",
    "Amount": 200
  }
]

Deployment

Follow these steps to deploy and configure the canister:

  1. Deploy the canister on the IC mainnet:
    dfx deploy --ic
  2. Upload the JSON file containing user data using the extract_json.sh script:
    ./extract_json.sh path/to/your/file.json

Configuration

Setting the Token Canister

  • Configure the token canister from which tokens will be airdropped:
    dfx canister call --ic airdrop_canister set_token_canister_id '(principal "TOKEN_CANISTER_ID")'

Shell Script

  • extract_json.sh: This script reads the JSON file and populates the canister with the data.
    ./extract_json.sh path/to/your/file.json

Distributing Tokens

  • Start the airdrop process:
    dfx canister call --ic airdrop_canister distribute

Resetting the Airdrop

  • Reset the canister for a new airdrop:
    dfx canister call --ic airdrop_canister reset

Query Methods

The canister exposes the following query methods:

  • Get the amount of shares allocated to a user:
    dfx canister call --ic airdrop_canister get_user_share_allocation '(principal "USER_PRINCIPAL_ID")'
  • Get the amount of tokens allocated to a user:
    dfx canister call --ic airdrop_canister get_user_token_allocation '(principal "USER_PRINCIPAL_ID")'
  • Get the list of users and their respective token shares (paginated):
    dfx canister call --ic airdrop_canister get_tokens_list '(OFFSET)'
  • Get the list of users and their respective share allocations (paginated):
    dfx canister call --ic airdrop_canister get_shares_list '(OFFSET)'

Acknowledgments

This canister was developed for the ICP CC DAO to simplify the process of conducting token airdrops to multiple users efficiently and accurately. It can be used by any organization or individual needing to perform airdrops based on a predefined dataset.

9 Likes
2

This looks great! Do you have any plans on creating a tutorial video?

1 Like
3

Thanks! I don’t have plans for it currently, unless there is demand for it.

1 Like
4

This is awesome. I would like to see somebody build a UI allowing normal users to create tokens and airdrop them to their communities. But this is a good starting point at least for people who know how to code.

5

Yes I waiting for some a tutorial video

6

Definitely suggest you to as it would help you gain more visibility especially to developers and learners who are more audio and visually-inclined.

7

Thanks, I’m waiting for this along time ago

8

Hey @NimaRa

Thanks for that work, I was thinking of building something similar until I stumbled on your post. But I have two questions:

  1. Let’s say I already launched an ICRC-1 token, airdropped users with that token, and now I successfully launched an SNS and want to “transfer” the balances of airdropped users from my now deprecated ICRC-1 token to my now official SNS token, how do I do to generate the json file required by your Generic Airdrop Canister? Rn I am thinking of adding a custom function to my ICRC-1 token to be able to do that.

  2. Just to confirm, if the total of all balance of my ICRC-1 token is 1 million but I allocate only 500k in my actual SNS token, will the Generic Airdrop Canister make so the SNS token balances of airdropped users will be divided by 2?

Edit: I realized there is no mention of subaccount, in the input JSON, would be a nice addition.

:pray: