Gumdrop - Notes from the office hours

There is already a official documentation existing in the Metaplex docs. 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.

:memo: How to install?

Clone & install Metaplex

First things first:

1. clone metaplex from github. 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. 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
4. 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.
2. Note down the Mint of your master edition

SPL Token

1. Install the Solana CLI like this
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.

Format of the distribution list is the following (stolen from the Metaplex docs).

[
    {
        "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)
• 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.

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 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 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

For Discord you will need to:

1. get a bot token in the Discord Developer Portal. (Discord.js describes quite well how to create a 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
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.

Build your command

You should now have your command together. Just run it.

I've also collected some examples of whole commands for you to compare.

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.

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.

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. Instead of a claim link also a custom UI can be used so that everyone can use the same claim link.

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.