These smart contracts are being provided as is. Fix tests and update contracts README and (, Generate Merkle tree of recipients by following README in, Setup and deploy MerkleClaimERC20 contracts by following README in, Setup and deploy front-end by following README in. There are no secrets in this algorithm, and the contract storage savings are offset by the intensive operations of client-side applications to verify that addresses belong to the list. from a16z/dependabot/npm_and_yarn/follow-redire, fix: don't allow double-spending with a large nullifier, Bump follow-redirects from 1.14.6 to 1.14.8, Bump @openzeppelin/contracts from 4.4.1 to 4.4.2, An admin assembles a Merkle tree of these, Users can then redeem with a zero-knoweldge proof that they belong in the Merkle tree without revealing which. So the user must provide 10 hashes for a list of 1,024 addresses, but only 32 hashes for about 4 billion addresses. In addition, we have developed special JS widgets to work with the file of the address list in IPFS. The proposed solution is quite simple: the contract only stores one number(merkle-root) and it is the customers obligation to prove that the address is whitelisted. Lets describe the advantages and disadvantages of the above method compared to traditional script-based distribution. A token contract is placed on the network (or is already present there). Owner reads this list, builds the merkle tree structure and writes down the Merkle root of it. For each supported EVM network exist one Waterfall that anyone can register one or many distribuition. Moreover, DApps tend to implement the pull instead of the push concept; this means that it is the network users who are the initiators and supervisors of business processes, so the approaches when someone centrally imposes something on tens of thousands of users are gradually fading into the past. To solve this problem, the contract code needs to be able to determine whether a given address is whitelisted. merkleRoot - generated from user set of data, each singular drop is represent in a leaf. We are not adding fake or double information to balance the tree. The client finds its address in a white list that is publicly available somewhere on the network (e.g. A list is created for those addresses that are allowed to claim their tokens. A token must be issued before AirDrop deployment. User wants to claim his N tokens, he also builds Merkle tree from public list and prepares Merkle proof, consisting from log2N hashes, describing the way to reach Merkle root, User sends transaction with Merkle proof to contract, Contract checks Merkle proof, and, if proof is correct, then sender's address is in list of allowed addresses, and contract does some action for this use. This repo demonstrates a strategy for distributing tokens where users can provide a message (known as the 'commitment') over a public channel and later claim their portion of the airdrop by providing a zero-knowledge proof that they belong in the Merkle tree. For Solidity techies: the source code of this smart contract is available on GitHub, see the link below. In this case, the contract stores the Merkle root and the token contract address so that it can transfer this token to the recipients. In our case we store a single hash in contract, allowing user to build the proof by himself. With a good algorithm, you can simultaneously solve several problems associated with smart contracts that work with large lists of user addresses. (Q): Can anyone register my token to a drop? This scheme has advantage in sotrage requirements, but requires additional computations on client side, so, use in wisely. The algorithm was proposed by the brilliant cryptographer Merkle and widely used in almost all decentralised software to ensure the integrity of data sets. And we recommend that you also get involved in this process. Users should proceed with caution and use at their own risk. They have not been audited and as such there can be no assurance they will work as intended, and users may experience delays, failures, errors, omissions or loss of transmitted information. A possible solution is employing a Merkle Tree, which will solve the problems in the following way: A token has been implemented based on ERC20 from Open Zeppelin to be used in the Air Drop contract. This root is the main parameter of our contract for issuing tokens. Distributing an airdrop to users is simple if you already have their public keys, but protocols may want to do so according to off-chain activities. Object contains the leaves and merkle proofs needed to verify that a given data exists for that address in the tree. You signed in with another tab or window. 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. If the proof is valid, then the contract executes transfer function from its address and transfers tokens to the user. Construct merkle trees with MerkleTree.js and verify merkle proofs in Solidity. In addition, any airdrop using these smart contracts should be conducted in accordance with applicable law. Waterfall contract don't manage or hold any tokens, if tokenProvider don't approve or doesn't have enough token amount, eventually the claim will revert.
Open your terminal in the folder you want to clone the project. These smart contracts are being provided as is. The merkle-proof consists of log2(N) hashes (rounded up to the nearest whole number). Anish Agnihotri is not liable for any of the foregoing. This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. Just type the following command: To run the tests, execute the following command: To check tests coverage, execute the following command: This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. from LorranSutter/dependabot/npm_and_yarn/shell, Smart contract design patterns and best practices - Dhruvin Parikh, Decentralized storage lessons - Doug Hoyte. That define the merkle root is the set of user data, in the case of two token use identical data, only one can be register and used. (Recursive drops). To associate your repository with the Customers can redeem only once and only a predefined, Cancelling the Air Drop will initiate contract. This means in my best effort to make the code correct, providing unit-tests and coverage analysis, but the project can still have bugs. Quickly bootstrap an ERC20 token airdrop to a Merkle tree of recipients. The most advanced Merkle tree library for Rust, Verkle trees with inner product argument (IPA) based polynomial commitment [Prototype]. Moreover, the larger the list is, the greater your benefits will be. Such a contract is also extremely simple to launch, and it does not require any support after launch; moreover, this simplicity also ensures maximum safety when used. (A): No, this version is only capable of making one drop per user set data, if the data is different, then you can make multi drops from the same token. It allows to prepare a really big list of addresses, set amount of tokens to give,
Facilitating the distribuiton of tokens in a mix offchain - onchain settings let projects to easly distribute tokens to a large number of users. A common practice is to issue your own token and send it in small quantities to tens of thousands of addresses that have, for example, at least 1 ETH in their wallets. This approach clearly demonstrates the difference between the models of using smart contracts in comparison with traditional centralised systems. Waterfall contract don't have or need administrative powers. For example, we upload files to IPFS, but you can use any other way to save the file so that it can be opened later from the client browser. In the final version of DApp, we plan to store IPFS information directly in the contract to have 100% of the data for airdrop in the blockchain. Efficient token air drop using Merkle Tree and Solidity. In addition, there are such damn features that involve sending so few tokens that the exchanges do not even allow transactions to be made with them and users are forced to put up with the presence of such leftovers on their addresses, as they cannot get rid of them. The advantages of the traditional scheme for distributing tokens using a script are just simple and clear workflows. (A): The claim will revert when trying to transfer the token. Add a description, image, and links to the Create scripts to enable automatic interactions from different protocols. Any change on this file will generate a new merkleRoot. The list of addresses should be stored somewhere publicly, and for the user this procedure should be no more difficult than uploading a file to the server. Owner deploys the contract passing in the merkle root and token contract address as constructors. The contract stores information about transactions to prevent tokens being reissued. Solidity NFT whitelist contract example using MerkleTree.js for constructing merkle root and merkle proofs. the transaction that requires tokens doesnt cost much ether, while this amount is a constant that depends on the size of the white list, the launched contract does not require any support, all the necessary operations are performed by the client-side application. (Q): Can i use Waterfall to make different drops from the same token and same user set data? Lets sum up brief advantages of the Merkle airdrop: You can already try to deploy the contract of Merkle Airdrop using a specific template on Smartz platform. You signed in with another tab or window. Kiyoharu Acquires Ethereum Name Service Address kiyoharu.eth. In our case it sends out the appropriate number of. Cannot retrieve contributors at this time. This is very unlikly to happen, but in the case you are dealing with this problem, just change any data point on the data set. It can issue two main problems: users with unwanted tokens and high cost. The Merkle Root must be precomputed so as to deploy the contract and prevent unwanted addresses in the white list. The main advantage of traditional list-based token distribution is that this scheme allows you to send tokens even to those users who do not want to receive them. However, projects need this and airdrop orders are very popular. This can overcame by chainging something in the data like swap two indexes or just add 1 to any claimable amount. Finally, mint function is implemented so as to only the contract owner is allowed to mint new tokens. Publish the merkle tree data, each user need this information to make a claim. (Q): If tokenProvider removes the allowance in the middle of a drop?
As you know, a smart contract is first deployed onto the Ethereum network and receives its own address and balance, after which the smart contract accepts and processes incoming transactions. Frontend, contracts, and merkle tree generator for use in quickly scaffolding ERC20 token airdrops. We are also developed a merkle-airdrop constructor for EOS tokens, as it has a similar interface and internal logic. I also mentioned the ACL, or Access Control List, that refers to file systems: this is a way to specify the rights to an object in the form of a list of accounts and access types. This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. Any variable is initialized in its declaration to reduce construction cost. This file is processed by a script that takes all the addresses from it and builds a Merkle tree, and then gets a single hash called a Merkle root. Although one could request addresses from users over a public or private channel, many users would prefer not to disclose their public keys. Therefore, our merkle-airdrop constructor for the Smartz.io platform allows you to upload the address list into IPFS and provide this list to the client. We don't ask to lock tokens in Waterfall contracts. Now, the airdrop contract provides external access to the claim-tokens-by-merkle-proof function, which takes merkle-proof from the user as a proof that the user is in that large whitelist of addresses. size this is the essence of this great algorithm. In general, the trend for increasing the complexity of the client code takes place in all state-of-the-art solutions, and the merkle tree is only the first of such interesting algorithms. A large number of tokens are transferred (in the usual way) to the balance of the airdrop contract; the amount should be enough for distribution between all participants from the list. Since customers request tokens, they are the ones who pay the transaction fee. the client code needs to process all addresses in the white list and perform quite resource-intensive operations. User wants to claim his N tokens, he also builds Merkle tree from public list and prepares Merkle proof, consisting from log2N hashes, describing the way to reach Merkle root, User sends transaction with Merkle proof to contract, Contract checks Merkle proof, and, if proof is correct, then sender's address is in list of allowed addresses, and contract does some action for this use. I use this term to show that this algorithm is suitable for creating huge ACLs that provide access to a certain contract feature to millions of accounts. For example when a user presents the pre-signed right to claim tokens that he found in public whitelist. Owner reads this list, builds the merkle tree structure and writes down the Merkle root of it. The merkle-airdrop scheme delegates a large number of operations to the code in the users browser, which, for example, must create a merkle proof after processing the entire address list. You signed in with another tab or window. leaf - user claim that follow the format: index account amount. Token Airdrops utilize the ERC998 Composable NFTs standard to transfer the token directly into the receiving ERC721 token, assuming that it implements the ERC998 methods for receiving ERC1155s. Address Airdrops transfer the airdropped token into the claiming user's wallet address. This token is instantiated with name, symbol and cap, and the caller becomes the owner. Register the merkle drop information in the smart contract: merkleRoot, token, tokensProvider, startTime, endTime. Verifying merkle multiproofs in solidity example (unaudited), A C++ library for creation and manipulation of Merkle trees, Checksums with Merkle trees and concurrency. https://blog.ricmoo.com/merkle-air-drops-e6406945584d, https://github.com/smartzplatform/merkle-airdrop-contract, The blockchain is parsed and a large list of addresses is created based on set specified criteria, An address is created with enough tokens to send to all addresses in the list, or a function is added to the token contract to implement the ability to create (mint) the required number of tokens for the specified address (when initiating a transaction from a special privileged address), Enough ETH are placed on this address to pay the fee charged for each time tokens are sent to users. All addresses are stored in one large file, which is uploaded to a resource and made publicly available using a certain URL. Merkle-ACL is not the single solution, there are other good claim algorithms with simpler logic, more effective from smart contracts view. Any change in data will do the job. If you are interested in cryptocurrencies, then you should already know about the Merkle tree; if you dont, then you should find out about it, as this structure is very useful for solving many problems. To perform the distribution, you need to develop a script that will send transactions and that contains a secret key to access a large number of tokens. takes up a bit of storage space in the blockchain. Owner says to users, that they can claim their tokens, if they owe any of addresses, presented in list, published on onwer's site. In this case, the contract is the most cost-effective, because it needs only one (!) startTime, endTime - Define the interval for valid claims to be processed. But lets focus on the scheme including airdrop, as it is now extremely popular in the market and is a simple and clear example of smart contracts with large ACLs. (this is not a limitation, is a feature). A smart contract that distributes a balance of tokens according to a Merkle root for NEAR Protocol. In this case, access control is based on the Merkle tree, which is a very convenient data structure that allows the contract to store just one fixed-size number (merkleRoot) with information about all the data in this tree (for example, a huge list of recipient addresses). In addition, the developer needs to make much more effort to run the usual airdrop compared to the publication of a merkle-airdrop contract. (Q): This is not the first smart contract doing merkle distribuition (A): True, the value of this project in my opinion is to set the infrastruture necessary to make merkle distribuion easy to anybody. Other schemes such as ring signatures, zkSNARKs, state channels, etc. Claiming tokens in this manner mixes them with all other users entitled to an airdrop, protecting their anonymity. Customers in the white list may redeem at most the pre defined max redeem amount submitting their Merkle Proof. drop - A set of users can claim a particular token. You need an algorithm to control the distribution, which will also be able to resume work if it is interrupted. tokens by providing additional data in transaction. You signed in with another tab or window. And if you have a file with addresses, you do not need a developer at all. This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. Not many people like someones unknown tokens appearing in their wallet. 0x8b6e73325F8c4bEEC9004eF4F6613de59Bb7C156. Smart-contract and constructor on Smartz platform, allowng to perform very cheap and simple token airdrop to millions on addresses with easy interface. In decentralised systems, this push strategy is usually far from the best; it is expensive, generates security vulnerabilities and is, in fact, just spam. No description, website, or topics provided. Anyone can make a claim to a specific user, this makes easier if you want to implement some type of meta-transaction and pay the user gas fees. At the moment, we have released a fully functional beta version and were working on next usability improvements. you must upload the address list to a public resource.
merkle This token also inherits from ERC20Capped contract, which is initialized with the parameter cap. In the merkle-airdrop scheme, tokens are not distributed using an address list, instead users claim their tokens themselves by sending a transaction to the contract and paying a fee.
Open your terminal in the folder you want to clone the project. These smart contracts are being provided as is. The merkle-proof consists of log2(N) hashes (rounded up to the nearest whole number). Anish Agnihotri is not liable for any of the foregoing. This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. Just type the following command: To run the tests, execute the following command: To check tests coverage, execute the following command: This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. from LorranSutter/dependabot/npm_and_yarn/shell, Smart contract design patterns and best practices - Dhruvin Parikh, Decentralized storage lessons - Doug Hoyte. That define the merkle root is the set of user data, in the case of two token use identical data, only one can be register and used. (Recursive drops). To associate your repository with the Customers can redeem only once and only a predefined, Cancelling the Air Drop will initiate contract. This means in my best effort to make the code correct, providing unit-tests and coverage analysis, but the project can still have bugs. Quickly bootstrap an ERC20 token airdrop to a Merkle tree of recipients. The most advanced Merkle tree library for Rust, Verkle trees with inner product argument (IPA) based polynomial commitment [Prototype]. Moreover, the larger the list is, the greater your benefits will be. Such a contract is also extremely simple to launch, and it does not require any support after launch; moreover, this simplicity also ensures maximum safety when used. (A): No, this version is only capable of making one drop per user set data, if the data is different, then you can make multi drops from the same token. It allows to prepare a really big list of addresses, set amount of tokens to give,
Facilitating the distribuiton of tokens in a mix offchain - onchain settings let projects to easly distribute tokens to a large number of users. A common practice is to issue your own token and send it in small quantities to tens of thousands of addresses that have, for example, at least 1 ETH in their wallets. This approach clearly demonstrates the difference between the models of using smart contracts in comparison with traditional centralised systems. Waterfall contract don't have or need administrative powers. For example, we upload files to IPFS, but you can use any other way to save the file so that it can be opened later from the client browser. In the final version of DApp, we plan to store IPFS information directly in the contract to have 100% of the data for airdrop in the blockchain. Efficient token air drop using Merkle Tree and Solidity. In addition, there are such damn features that involve sending so few tokens that the exchanges do not even allow transactions to be made with them and users are forced to put up with the presence of such leftovers on their addresses, as they cannot get rid of them. The advantages of the traditional scheme for distributing tokens using a script are just simple and clear workflows. (A): The claim will revert when trying to transfer the token. Add a description, image, and links to the Create scripts to enable automatic interactions from different protocols. Any change on this file will generate a new merkleRoot. The list of addresses should be stored somewhere publicly, and for the user this procedure should be no more difficult than uploading a file to the server. Owner deploys the contract passing in the merkle root and token contract address as constructors. The contract stores information about transactions to prevent tokens being reissued. Solidity NFT whitelist contract example using MerkleTree.js for constructing merkle root and merkle proofs. the transaction that requires tokens doesnt cost much ether, while this amount is a constant that depends on the size of the white list, the launched contract does not require any support, all the necessary operations are performed by the client-side application. (Q): Can i use Waterfall to make different drops from the same token and same user set data? Lets sum up brief advantages of the Merkle airdrop: You can already try to deploy the contract of Merkle Airdrop using a specific template on Smartz platform. You signed in with another tab or window. Kiyoharu Acquires Ethereum Name Service Address kiyoharu.eth. In our case it sends out the appropriate number of. Cannot retrieve contributors at this time. This is very unlikly to happen, but in the case you are dealing with this problem, just change any data point on the data set. It can issue two main problems: users with unwanted tokens and high cost. The Merkle Root must be precomputed so as to deploy the contract and prevent unwanted addresses in the white list. The main advantage of traditional list-based token distribution is that this scheme allows you to send tokens even to those users who do not want to receive them. However, projects need this and airdrop orders are very popular. This can overcame by chainging something in the data like swap two indexes or just add 1 to any claimable amount. Finally, mint function is implemented so as to only the contract owner is allowed to mint new tokens. Publish the merkle tree data, each user need this information to make a claim. (Q): If tokenProvider removes the allowance in the middle of a drop?
As you know, a smart contract is first deployed onto the Ethereum network and receives its own address and balance, after which the smart contract accepts and processes incoming transactions. Frontend, contracts, and merkle tree generator for use in quickly scaffolding ERC20 token airdrops. We are also developed a merkle-airdrop constructor for EOS tokens, as it has a similar interface and internal logic. I also mentioned the ACL, or Access Control List, that refers to file systems: this is a way to specify the rights to an object in the form of a list of accounts and access types. This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. Any variable is initialized in its declaration to reduce construction cost. This file is processed by a script that takes all the addresses from it and builds a Merkle tree, and then gets a single hash called a Merkle root. Although one could request addresses from users over a public or private channel, many users would prefer not to disclose their public keys. Therefore, our merkle-airdrop constructor for the Smartz.io platform allows you to upload the address list into IPFS and provide this list to the client. We don't ask to lock tokens in Waterfall contracts. Now, the airdrop contract provides external access to the claim-tokens-by-merkle-proof function, which takes merkle-proof from the user as a proof that the user is in that large whitelist of addresses. size this is the essence of this great algorithm. In general, the trend for increasing the complexity of the client code takes place in all state-of-the-art solutions, and the merkle tree is only the first of such interesting algorithms. A large number of tokens are transferred (in the usual way) to the balance of the airdrop contract; the amount should be enough for distribution between all participants from the list. Since customers request tokens, they are the ones who pay the transaction fee. the client code needs to process all addresses in the white list and perform quite resource-intensive operations. User wants to claim his N tokens, he also builds Merkle tree from public list and prepares Merkle proof, consisting from log2N hashes, describing the way to reach Merkle root, User sends transaction with Merkle proof to contract, Contract checks Merkle proof, and, if proof is correct, then sender's address is in list of allowed addresses, and contract does some action for this use. I use this term to show that this algorithm is suitable for creating huge ACLs that provide access to a certain contract feature to millions of accounts. For example when a user presents the pre-signed right to claim tokens that he found in public whitelist. Owner reads this list, builds the merkle tree structure and writes down the Merkle root of it. The merkle-airdrop scheme delegates a large number of operations to the code in the users browser, which, for example, must create a merkle proof after processing the entire address list. You signed in with another tab or window. leaf - user claim that follow the format: index account amount. Token Airdrops utilize the ERC998 Composable NFTs standard to transfer the token directly into the receiving ERC721 token, assuming that it implements the ERC998 methods for receiving ERC1155s. Address Airdrops transfer the airdropped token into the claiming user's wallet address. This token is instantiated with name, symbol and cap, and the caller becomes the owner. Register the merkle drop information in the smart contract: merkleRoot, token, tokensProvider, startTime, endTime. Verifying merkle multiproofs in solidity example (unaudited), A C++ library for creation and manipulation of Merkle trees, Checksums with Merkle trees and concurrency. https://blog.ricmoo.com/merkle-air-drops-e6406945584d, https://github.com/smartzplatform/merkle-airdrop-contract, The blockchain is parsed and a large list of addresses is created based on set specified criteria, An address is created with enough tokens to send to all addresses in the list, or a function is added to the token contract to implement the ability to create (mint) the required number of tokens for the specified address (when initiating a transaction from a special privileged address), Enough ETH are placed on this address to pay the fee charged for each time tokens are sent to users. All addresses are stored in one large file, which is uploaded to a resource and made publicly available using a certain URL. Merkle-ACL is not the single solution, there are other good claim algorithms with simpler logic, more effective from smart contracts view. Any change in data will do the job. If you are interested in cryptocurrencies, then you should already know about the Merkle tree; if you dont, then you should find out about it, as this structure is very useful for solving many problems. To perform the distribution, you need to develop a script that will send transactions and that contains a secret key to access a large number of tokens. takes up a bit of storage space in the blockchain. Owner says to users, that they can claim their tokens, if they owe any of addresses, presented in list, published on onwer's site. In this case, the contract is the most cost-effective, because it needs only one (!) startTime, endTime - Define the interval for valid claims to be processed. But lets focus on the scheme including airdrop, as it is now extremely popular in the market and is a simple and clear example of smart contracts with large ACLs. (this is not a limitation, is a feature). A smart contract that distributes a balance of tokens according to a Merkle root for NEAR Protocol. In this case, access control is based on the Merkle tree, which is a very convenient data structure that allows the contract to store just one fixed-size number (merkleRoot) with information about all the data in this tree (for example, a huge list of recipient addresses). In addition, the developer needs to make much more effort to run the usual airdrop compared to the publication of a merkle-airdrop contract. (Q): This is not the first smart contract doing merkle distribuition (A): True, the value of this project in my opinion is to set the infrastruture necessary to make merkle distribuion easy to anybody. Other schemes such as ring signatures, zkSNARKs, state channels, etc. Claiming tokens in this manner mixes them with all other users entitled to an airdrop, protecting their anonymity. Customers in the white list may redeem at most the pre defined max redeem amount submitting their Merkle Proof. drop - A set of users can claim a particular token. You need an algorithm to control the distribution, which will also be able to resume work if it is interrupted. tokens by providing additional data in transaction. You signed in with another tab or window. And if you have a file with addresses, you do not need a developer at all. This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. Not many people like someones unknown tokens appearing in their wallet. 0x8b6e73325F8c4bEEC9004eF4F6613de59Bb7C156. Smart-contract and constructor on Smartz platform, allowng to perform very cheap and simple token airdrop to millions on addresses with easy interface. In decentralised systems, this push strategy is usually far from the best; it is expensive, generates security vulnerabilities and is, in fact, just spam. No description, website, or topics provided. Anyone can make a claim to a specific user, this makes easier if you want to implement some type of meta-transaction and pay the user gas fees. At the moment, we have released a fully functional beta version and were working on next usability improvements. you must upload the address list to a public resource.
merkle This token also inherits from ERC20Capped contract, which is initialized with the parameter cap. In the merkle-airdrop scheme, tokens are not distributed using an address list, instead users claim their tokens themselves by sending a transaction to the contract and paying a fee.