# Gumdrop - Notes from the office hours There is already a official documentation existing in the [Metaplex docs](https://docs.metaplex.com/airdrops/create-gumdrop). Nevertheless I want to extend them a little bit to show you my experiences and elaborate a bit. ## What is Gumdrop? Gumdrop can be used to create a candy machine whitelist, do airdrops of prints, distribute tokens... and for sure much more as soon as we get creative! Big thanks to Larry Wu for creating it! Initially I was focusing on the candy machine whitelist here but already extended the document for token and edition drops. :::success Follow me on Twitter :bird:[@MarkSackerberg](https://twitter.com/MarkSackerberg) if you like my work. You can also DM me or :bird:[@9HOMIES](https://twitter.com/ninehomies) if you want to work together! ::: :::info Have a look at :bird:[SolSlimes](https://twitter.com/SolSlimesNFT) to see more of my work! ::: ## :memo: How to install? ### Clone & install Metaplex First things first: 1. clone metaplex from [github](https://github.com/metaplex-foundation/metaplex). Make sure that you have the current verison if you already have metaplex locally. 2. go into js folder (`cd js`) 3. run `yarn install` that's it. ### Host the frontend To claim a gumdrop a frontend website is needed. Currently Larry Wu from Solana is [hosting one](https://lwus.github.io/metaplex/claim). I think it's fine to use for testing, but no guarantee how long it will be up! For your real gumdrop I would recommend your own gumdrop page. For that... 1. go into the gumdrop folder (`cd metaplex/js/packages/gumdrop`) 2. Do design changes as you like 3. run `yarn serve` 5. Serve the frontend whereever you like. (Cloudflare pages, vercel...) Ho to differs for each hoster so i will not go into details here, but `yarn build` will be needed for sure. You can find some information for setting up vercel in the FAQ. ## How to use? ### Step 1: Decide what can be claimed. Depending on what to claim (SPL token, print) you either need to do different preparations (e.g. create SPL tokens, create edition mints). ### Step 2: Prepare your drops Depending on what you want to give out do one of the following two options: #### Edition prints 1. You need a Master edition of the NFT you want to print copies of. You could create one on [NFTArmory](https://www.nftarmory.me/mint). 2. Note down the Mint of your master edition #### SPL Token 1. Install the Solana CLI [like this](https://docs.solana.com/cli/install-solana-cli-tools) 2. Set the keypair and environment `solana config set --keypair <path to your keypair> --url devnet` 3. Create your token `spl-token create-token --decimals 0` and note the mint! 4. Create a token account `spl-token create-account <mint>` 5. Mint as many tokens as you want to airdrop `spl-token mint <mint> <amount>` ### Step 3: Distribution List First you need to understand that the users will receive a personal URL that they will need to use to claim their gumdrop. You can send out your whitelist access through Email, SMS (both based on AWS) or Discord. SMS and E-Mail can also be combined with OTP to make sure that the airdrop / whitelist NFT goes to the right person. If you choose "wallets" as distribution methods you will have to inform your users manually, but their wallet will be verified on mint. You can also add wallets or even a manual identifier, but in that case you need to distribute the links to claim the drop yourself. | Method | Pro | Con | Comment | | -------- | -------- | -------- |-------- | **manual** | none? | -manual URL distribution <br> -no validation of minting user | For debugging or testing. | **wallets** | -validation of the minting wallet | -manual URL distribution | | **Discord** | -Most of us are already using Discord|-distribution often fails. <br> -DMs can look and fele like spam. <br> -Someone will scam users sooner or later with fake gumdrop DMs | Instead of using the inbuild function you can create other methods. See [FAQ](https://hackmd.io/6yf_s3p9T0OIUIgH3j_XRQ?both#4-Discord-as-distribution-method). | **email** | -[OTP](https://en.wikipedia.org/wiki/One-time_password) possible| -only via AWS<br>-you need to collect the addresses | **SMS** | -[OTP](https://en.wikipedia.org/wiki/One-time_password) possible| -only via AWS<br>-you need to collect the addresses Format of the distribution list is the following (stolen from the [Metaplex docs](https://docs.metaplex.com/airdrops/create-gumdrop#whitelist)). ``` [ { "handle": "<DISTRIBUTION-METHOD-SPECIFIC-HANDLE>", "amount": <GUMDROP-CLAIM-ALLOWANCE>, ["edition": <EDITION-NUMBER>] }, ...] ``` where - handle is the E-Mail address, Phone number or discord user id. (Again, more information in the [Metaplex docs](https://docs.metaplex.com/airdrops/create-gumdrop#whitelist)) - amount is the number of tokens / mints the user can get - edition is the number of the edition for the user. This is optional. NOT REQUIRED FOR CANDY MACHINE WHITELIST/ SPL TOKENS. ### Step 4: Create the gumdrop There is only one command. But I will break it down a bit. The beginning is always the same. **You will always need the following, but do NOT run it yet. We will add more parameters to the command in the next steps.** ```bash ts-node gumdrop-cli.ts create -e devnet --keypair <keypair location> --distribution-list <path to your distribution list JSON>` ``` #### What will be claimed? Depending on what to claim (NFT from candy, token, print) you either need to add different parameters. Choose one of those: ##### edition prints You should already have created your Master edition and noted down the mint. Therefore you only need to add this to your command: ``` --claim-integration edition --edition-mint <mint of master edition> ``` Further information on [edition prints](https://docs.metaplex.com/airdrops/create-gumdrop#edition-prints) with Meta Gumdrop ##### SPL token drops You should already have created your Master edition and noted down the mint. Therefore you only need to add this to your command: ``` --claim-integration transfer --transfer-mint <mint> ``` You can find more information on [token drops](https://docs.metaplex.com/airdrops/create-gumdrop#token-airdrop) in the official documentation. #### Add your frontend If you want to use your own frontend you need to use the --host parameter. Keep in mind that the standard host might not be up forever! `--host "https://lwus.github.io/metaplex"` #### Distribution method Using E-Mails can make sense. I hate SMS. And love Discord. That's why I show you the discord example. ##### Discord :::success This function is bugged. Not everyone will receive a DM with it's custom link. DM me and we will set up a bot for you which will work. ::: For Discord you will need to: 1. get a bot token in the [Discord Developer Portal](https://discord.com/developers/applications). (Discord.js describes quite well how to [create a bot](https://discordjs.guide/preparations/setting-up-a-bot-application.html#creating-your-bot)) 2. You should invite the bot into the Discord server where all your users are in. Again discord.js describes quite well [how to](https://discordjs.guide/preparations/adding-your-bot-to-servers.html#bot-invite-links) 3. let's extend our command. Add ``` --distribution-method discord --discord-token "<your discord token>" --otp-auth none --discord-guild <guild id> ``` ##### Email & SMS More on Mails/SMS through AWS [here](https://docs.metaplex.com/airdrops/create-gumdrop#distribution-method). #### Build your command You should now have your command together. Just run it. I've also collected some [examples](#Collection-of-whole-commands) of whole commands for you to compare. :::warning Excecuting the create command creates a new keypair json in the .log folder. SAVE IT. YOU NEED IT! ::: ### Close the gumdrop again! Time's up? Alright. Again there are different things to consider depending on what can be claimed. You need this everytime: ``` ts-node gumdrop-cli.ts close -e devnet --base <keypair that was created on gumdrop create> --keypair <your initial keypair> ``` Wondering where to find the base keypair? Have a look into the .log folder. #### Editions For edition prints the close command would look like ``` ts-node gumdrop-cli.ts close -e devnet --base <keypair that was created on gumdrop create> --keypair <your initial keypair> --claim-integration edition ---edition-mint <mint of master edition> ``` #### SPL Token ``` ts-node gumdrop-cli.ts close -e mainnet-beta --base <keypair that was created on gumdrop create> --keypair <your initial keypair> --claim-integration transfer --transfer-mint <mint> ``` # Collection of whole commands This guide was somehow hard to follow? :sweat_smile: Don't worry. Here are all the commands you need: ### Edition prints 1. create gumdrop ``` ts-node gumdrop-cli.ts create -e devnet --keypair <keypair location> --distribution-list <path to your distribution list JSON> --claim-integration edition --edition-mint <mint> --distribution-method discord --discord-token <TOKEN> --otp-auth none --discord-guild <guild id> ``` 2. close gumdrop ``` ts-node gumdrop-cli.ts close -e devnet --base <keypair that was created on gumdrop create> --keypair <your initial keypair> --claim-integration edition ---edition-mint <mint of master edition> ``` ### Tokens 1. create gumdrop ``` ts-node gumdrop-cli.ts create -e devnet --keypair <keypair location> --distribution-list <path to your distribution list JSON> --claim-integration transfer --transfer-mint <mint> --distribution-method discord --discord-token <TOKEN> --otp-auth none --discord-guild <guild id> ``` 2. close gumdrop ``` ts-node gumdrop-cli.ts close -e devnet --base <keypair that was created on gumdrop create> --keypair <your initial keypair> --claim-integration transfer --transfer-mint <mint> ``` # Caveats ## Discord The Discord integration has some minor caveats. E.g. 1. Links are send out via DM. (can bring some scam risk) 2. Not all DMs are send out all the time. (e.g. if someone only allows to receive DMs send by friends) 3. No OTP. ## E-Mail / SMS Currently only works with AWS. ## Update Authority Using gumdrop you will (currently) not have the update authority over your NFTs minted through candy machine anymore. So if you want to update them later on you should not use gumdrop for now. See [Github Issue](https://github.com/metaplex-foundation/metaplex/issues/1137). # FAQ ## 1. What does Gumdrop cost? The minting fees will be paid by your user. You only pay the costs for setting up the gumdrop. In my tests it was 0.00163168 SOL for a 450 Wallet drop. ## 2. How to host the frontend? I did it on cloudflare pages, but if you want to host on vercel the following screenshot might be helpful for you. If you receive a white page as a result it might make sense to have a look at the `package.json` and remove the line where the homepage is defined. ![Vercel build settings](https://i.imgur.com/dCCGiRj.png) ## 3. Discord as distribution method? Possible. And I already used it in mainnet-beta twice. But(!) the included implementation has caveats: * many users don't allow DMs of users they are not friends with * often even fails to send DMs at some point (errors out) * DMs can be confused with spam * The more DMs we send with gumdrop the bigger the chance that scammers will do the same ### How to solve that? From my point of view the best solution is to use "wallets" as distribution method to have user validation and collect the wallets and send the URLs yourself. To make it easier and better I've created a Discord bot where the users can register their wallet and later claim there gumdrop claim link. :::info [DM me](https://twitter.com/MarkSackerberg) if you are interested in using this bot! I am sure together we can work it out for you. ::: ## Common errors ### TypeError: Max seed length exceeded Make sure that the UUID is correct. You can find the correct one in the cache file. It should be exactly 6 characters long. ### Module not found: Can't resolve '@oyster/common 1. Go to `js/packages/common` 2. run `yarn install` 3. run `yarn build` ### Error: Number can only safely store up to 53 bits Most likely you are doing an SPL token drop and your token has decimals, right? You encountered a gumdrop bug! Solution: 1. Check that you have enough tokens to drop in your wallet 2. Go into `metaplex/js/packages/cli/src/helpers/gumdrop/claimant.ts` and remove these three lines (Currently starting at line 205): ``` if (new BN(creatorTokenInfo.amount, 8, 'le').toNumber() < totalClaim) { throw new Error(`Creator token account does not have enough tokens`); } ``` 3. Make sure that you calculate the amount for the distribution file like this: amount * 10^decimals you should now be able to create the gumdrop.