id
and the module allows the users involved to autonomously claim tokens in the temporal window between the StartHeight
and the EndHeight
blocks.Merkle Tree
. Thanks to the features of these data structure (i.e., a binary tree where each non-leaf node is the hash of its childs) they are particularly efficient in space usage and during the verification process (as explained in the Verification process).uint64
string
int64
actual block height + 100000
.int64
start_height
and lower than a maximum value of start_height + 5000000
.string
denom
of the token to drop.string
amount
of token to drop.string
string
merkledrop
module keeps track of LastMerkledropId, Merkledrops, Indexes and Parameters.uint64
, automatically incremented everytime a new merkledrop is created;denom
of the token to drop;amount
of token to drop;msg
s) are objects that trigger state transitions. Messages are wrapped in transactions (tx
s) that clients submit to the network. The BitSong SDK wraps and unwraps merkledrop
module messages from transactions.MsgCreate
message is used to create a new merkledrop. It takes as input Owner
, MerkleRoot
, StartHeight
, EndHeight
, and Coin
. The value of the block height at which the drop become available (the starting block) must be greater or equal to the block height where the transaction is included. For this reason, if the users select 0 as StartHeight
it will be automatically set to the current block height (the one where the transaction is included). Moreover, there exists an upper bound for this value, that corresponds to the value of the actual block height + 100000
. This choice derives from a design pattern that avoid the generation of spam merkledrop. At the same time, the EndHeight
value, which corresponds to the block height where the merkledrop can be considered expired and the withdrawal is executed if part of the tokens were not claimed. This value must be greater than the StartHeight
and lower than a maximum value of StartHeight + 5000000
. The Coin
is made up of the denom
of the token to distribute and the amount
, which corresponds to the sum of all the tokens to drop. Once the module has verified that the owner
address is valid and that the merkletree root
is a hexadecimal character string, it deduct the creation fee
from the owner wallet and send the coin
(the amount of token to drop), from the owner address to the module. At this point, the LastMerkleDropId
is increased and the merkledrop is created, by assigning zero to the claimed value (since at the creation time, no one claimed any token). They are added three indexes:merkledrop_id
;owner
;end_height
.EventCreate
is emitted at the end of the creation process.MsgClaim
message is used to claim tokens from an active merkledrop. It takes as input Sender
, MerkledropId
, Index
, the Amount
to claim, and a list of Proofs
. In such a scenario, verified the validity of the sender
address and the existence of the merkledrop by the ID, if the airdrop is currently active (i.e., its start block height
is lower than the current block height and its end block height
is greater than the current one), the module verifies if the sender
already claimed his tokens (by querying at an index). In case he didn't, the module proceeds retriving the merkletree root for the merkledrop from the chain and verifies the proofs (as described in the verification process). After tese verifications, the module only checks if the coin the sender
wants to claim are available, and send those tokens from the module to the sender
wallet. At this point, the claim is stored through its index, the claimed tokens are added to the actually claimed amount and, if all the drops are claimed with this operation, the merkledrop is cleaned by the state. An event of type EventClaim
is emitted at the end of the claim process.EndHeight
(i.e., the block height at which the airdrop expires), the module can verify at each block if there is any expired merkledrop at that particular time. To perform the operations, the module is able to retrive the the merkledrops ids by the EndHeight
and to process those drops. In particular, for each retrived merkledrop they are executed the withdraw
of the unclaimed tokens and then, the merkledrop is cleaned by the state.EndHeight
block the merkledrop is still in the store, it means that not all the tokens were claimed. For this reason, the module automatically performs a withdraw of the unclaimed tokens to the owner wallet. In particular, the module verifies if the total amount
is lower than the claimed amount
, calculates the balance as the unclaimed tokens (i.e., the total amount
- the claimed
one). This amount is sent to the owner wallet and a corresponding event of type EventWithdraw
is emitted.owner
, all the indexes linked to its id
are deleted together with the merkledrop
object in the store./bitsong.merkledrop.v1beta1.MsgCreate
/bitsong.merkledrop.v1beta1.MsgClaim
transactions
commands allow users to create
and claim
for merkledrops.query
commands allow users to query the merkledrop module.