Metaplex is a collection of NFT standards and tools for Solana. Learn how to use Metaplex for Solana NFT mints, NFT airdrops, NFT storefronts, and more!

What is Metaplex?

Metaplex is a network of contracts built on Solana to supercharge the blockchain’s NFT community. The ecosystem has four contracts: Token Metadata, Token Vault, Auction, and Metaplex. While the term Metaplex often refers to the contract ecosystem, we will use it to refer to the Metaplex contract (one of the four) in this overview.

Why is Metaplex important?

The Metaplex ecosystem unlocks a completely new way to interact with NFTs on Solana and consequently has been the de facto NFT tool on Solana. Through Metaplex, users can mint NFTs, host auctions for primary/secondary sales, and visualize NFTs in a standard way.

Metaplex Smart Contracts

The Metaplex ecosystem is a collection of four separate contracts, which communicate via the Metaplex contract to provide Solana developers with the tooling they need to create NFTs.

1. Token Metadata

Referred to as a “mint decorator,” this contract enables the NFT creators to attach a Metadata PDA (Program Derived Address) to their mint. This associated PDA contains the bedrock information of the NFT collection, such as name, symbol, royalty fee, and sold status.

2. Token Vault

As the name suggests, the Token Vault contract can hold NFTs deposited from any mints and enables fractional ownership of the vault and its NFTs. 

There are two states for the vault: Activated and Combined. 

When in “Activated” status, any NFTs in the vault is locked and inaccessible. The vault owner can now issue and sell treasury shares on the vault, thereby creating fractional ownership of any NFTs in the vault. 

The vault can transition to “Combined” only when there are no outstanding fractional shares in circulation, i.e. the vault owner has all the shares. To reclaim the NFTs in the vault, the vault owner must buy back all the fractional shares on the market, from which they can “Combine” the vault.

3. Auction

The Auction contract acts as the auction mechanism on Metaplex and facilitates NFT auctions in English Auction and Open Edition Auction formats.

As a simple bid-and-sell program, Auction operates without any knowledge of NFTs or other resources in the Metaplex ecosystem. This separation greatly reduces points of failure and increases the flexibility of the Auction program.

4. Metaplex

The Metaplex contract provides the AuctionManagers, which manages the three main contracts listed above. The AuctionManager keeps the record of all token metadata and their corresponding auctions, and enables smooth transition of account data between the Token Metadata, Token Vault, and Auction contracts.

Metaplex Tools and Features

Here are the most important features of Metaplex, what they do, when to use them, why they’re important, and how to start building with those features!

What is the Metaplex Storefront?

Metaplex Storefront is the one-in-all NFT marketplace to create and sell NFTs via the Metaplex contracts. Unlike centralized Solana NFT marketplaces like Magic Eden, anyone can create and self-host the Storefront as a white-label solution, or they can use existing branded Storefronts. 

This unique self-hostable feature of Metaplex’s Storefront feature empowers users to fully enjoy the benefit of decentralization on Solana, as they can create their own NFT marketplaces.

How to Create a Storefront with Metaplex

This is a brief overview of how to create a Storefront, which is extensively covered in Metaplex’s original documentation.

First, you need to clone and jumpstart the Metaplex Storefront source code on Github.

git clone https://github.com/metaplex-foundation/metaplex.git
cd metaplex/js && yarn install && yarn bootstrap
yarn start

Next, visit http://localhost:3000/ and switch the Solana network to Devnet.

If you're unfamiliar with Solana test networks, read our complete guide to using Solana's devnet.

Then, initialize the Storefront by clicking “Init Store” and approving the transaction. 

In the Store configuration section, copy the code and paste it into the .env file located in js/package/web. 

Now, restart the website with yarn start.

You now have a Storefront associated with your address and hosted by you! 

Through the Storefront’s default UI, you can mint NFTs and list them for sale, either as instant, "Buy Now" options, or list them as an auction. When you create an NFT, you can specify the description, royalty, and image.

Because Metaplex’s Storefront NFT tool is open-source and customizable, you can update the forked GitHub code to modify the user interface (UI) and add new functionalities like creating a vault of NFTs or burning NFTs.

What is Candy Machine v2?

Candy Machine (CM) is an on-chain generative NFT distribution program designed to streamline the NFT experiences for buyers, sellers, and creators altogether. 

Candy Machine V2 is the second iteration with improved and added features. Before CM, there was no universal program to manage the minting and sales of NFTs on Solana. This led to countless errors and bad user experiences for NFT creators and collectors, which inspired the Metaplex development team to create Candy Machine.

Candy Machine solves the fundamental problems in NFT distribution that ease users’ interactions with NFTs:

• Define precise minting time periods
• Accept buyer funds only when NFTs can be minted
• Help programs to create consistent NFTs by enforcing metadata types

Candy Machine v2 added more features:

• Unpredictable mint index - prevent buyers from sniping specific NFTs within a collection since v1 minted sequentially
• Whitelist - allow only certain addresses to mint
• Captcha - prevent bots from minting

Additionally, v2 now supports larger collections, hide-and-reveal drops, lets web3 developers update their configuration at any point, and pause ongoing mints.

How to Use Candy Machine v2

Since Candy Machine is a fully on-chain NFT mint program, any interactions must happen programmatically, although there are UIs that automate some features, users need to have foundational programming experience to fully utilize Candy Machine. To get started with CM v2, refer to Metaplex's official documentation.

What is Gumdrop?

Gumdrop is a new beta tool for Solana airdrops at low gas costs. Developed by the Metaplex community, Gumdrop achieves airdrops to a large number of users by sending them a redemption link off-chain, such as through social media. It provides an easy solution for projects to distribute tokens integrated with Metaplex at a cheap cost.

Unlike the traditional airdrop framework where tokens appear in a user’s Solana wallet, Gumdrop uses a “pull-based” paradigm where users have to actively claim or otherwise forfeit their tokens. Gumdrop utilizes a merkle tree to check whether a user is in the whitelist, which allows for fast computation on the chain.

Gumdrop supports multiple types of token drops on Solana: 

• Token airdrops
• Candy Machine pre-sales
• Edition prints

In all cases, the drop builds a merkle tree from whitelisted users and distributes claim links in an off-chain manner.

How to Use Gumdrop

You can use Gumdrop programmatically or an interactive experience with a guided Solana airdrop UI. For programmatic steps, refer to the official documentation. To use the graphic user interface (UI), follow these directions:

There are three actions you can take: 

1. Create
2. Claim
3. Close

On the Create page, specify the claim method (type of airdrop).

Next, choose an off-chain distribution method.

Based on the selection, you will need to fill out additional inputs, including the mint address, to complete the creation.

On the Claim page, users can initiate a claim of their airdrop, which is verified with the merkle tree of the Solana airdrop whitelist.

On the Close page, creators can delete a Gumdrop airdrop by providing the private key and the mint address.

Once closed, users won’t be able to claim the airdrop’s tokens.

What is AuctionHouse?

AuctionHouse is an on-chain escrow-less NFT sale program that allows creators and minters to seamlessly auction and sell NFTs. AuctionHouse is a separate concept from the self-hosted, frontend Storefront website — it is a program deployed on-chain that accepts SOL and any SPL token. By using the AuctionHouse, developers can skip the complexity and errors in writing their own NFT sale programs.

Any Solana NFT marketplaces can implement the AuctionHouse protocol to benefit from its features, such as automatic buyer-seller match for NFT listings. 

Unlike other common auction processes where buyers need to “claim” NFTs, the sale transaction executes all necessary interactions automatically. In other words, AuctionHouse reduces all unnecessary steps to intuitive actions for end users, while providing a standardized program for developers.

AuctionHouse has a variety of parameters that can be configured. For example, a seller can create a partial sell order of a Solana NFT collection with a customized fee and treasury destination, and also enforces the auction house to sign off all transactions. AuctionHouse can also accept certain or all SPL tokens.

AuctionHouse also keeps the history of all NFT transaction receipts (e.g. listing, bids, and sales).

How to Use AuctionHouse

Currently, AuctionHouse only provides a CLI library written in TypeScript, though a graphic user interface GUI implementation is coming soon.

First, clone the all-in-one Metaplex that contains the AuctionHouse library.

git clone https://github.com/metaplex-foundation/metaplex.git
cd metaplex

Then, install the necessary packages in the CLI (JS) subfolder of the metaplex folder.

cd js && yarn install && yarn bootstrap
cd packages/cli

Finally, using an existing keypair, you can create an AuctionHouse.

ts-node src/auction-house-cli.ts create_auction_house --keypair /path/to/mywallet.key -e devnet -sfbp 1000 -ccsp false -rso false

Upon successful transaction, your command line should display these messages.

wallet public key: Gsv13oph2i6nkJvNkVfuzkcbHWchz6viUtEg2vsxQMtM
No treasury withdrawal dest detected, using keypair
No fee withdrawal dest detected, using keypair
No treasury mint detected, using SOL.
Created auction house HsKwc8dQtm8KLxshw67dwsNePkH6wMXo5Lwn1FuKjVYVS

Note: your auction house key will be different

For more CLI procedures, refer to the official documentation.

What is Sugar?

Sugar is an alternative to the Candy Machine v2 command line, with better performance and simplified steps for the developers. It provides an interactive process for Solana NFT developers to deploy Candy Machine v2 without much complexity and hassle in the original Command Line Interface (CLI).

Sugar provides numerous benefits over using the CM v2 CLI, as noted in its documentation:

• B​​etter performance for upload of media/metadata files
• Simplified build and installation procedures taking advantage of cargo
• Robust error handling and input validation
• More informative error messages

How to Use Sugar for Solana NFT Drops

First, install the Sugar library with cargo.

cargo install sugar-cli

Next, modify the Solana CLI config with your desired Solana RPC node provider and your keypair. 

Finally, launch the interactive session to deploy the Candy Machine.

sugar launch

What is Hydra?

Hydra is a wallet of wallets that enables fund distribution to extremely large membership sets of addresses. It is also known as the “Fanout Wallet” for resembling a fanout of wallets from the main wallet. Hydra enables exciting features like tokenized royalties (i.e. distributing received royalties to members) and token membership (e.g. easy staking rewards).

‍

A Hydra wallet has three phases in its lifecycle: 

1. Creation
2. Member Addition
3. Distribution

1. Creation Phase

In the Creation phase, you, the creator (known as the Authority), can create a Hydra wallet. There are multiple angles of customization, such as the membership model, name, accepted tokens (SOL or any SPL token), and total shares of membership.

Because of its complex operations and requirements, creating a Hydra wallet will cost hundreds of SOL.

2. Member Addition Phase

In the Member Addition phase, you can add an account as a member to the Hydra wallet. You can add a normal wallet (user), an NFT, and tokens, which involves a more sophisticated approach to computing the fund shares.

3. Distribution Phase

In the Distribution phase, the Hydra wallet is called many times to distribute the fund of membership to each member, according to their shares.

Each distribution call must include the receiving Member, and the Hydra wallet expects multiple calls throughout its lifespan. This design of one-call-per-member allows the wallet to maintain low processing and memory cost when dealing with a large set of members.

let distributeToMember1 = await fanoutSdk.distributeWalletMemberInstructions(
    {
        distributeForMint: false,
        member: member1.publicKey,
        fanout: fanout, // From initialization
        payer: distributionBot.publicKey,
    },
);

How to Use Hydra

Hydra is another program on-chain that can be called for interactions. 

The program IDs for Hydra are:

• Mainnet: hyDQ4Nz1eYyegS6JfenyKwKzYxRsCWCriYSAjtzP4Vg
• Devnet: hyDQ4Nz1eYyegS6JfenyKwKzYxRsCWCriYSAjtzP4Vg

The official documentation includes minimal code examples to interact with and create a Hydra wallet. You can create a create a wallet as such:

...
const init = await fanoutSdk.initializeFanout({
  totalShares: 100,
  name: `Test${Date.now()}`,
  membershipModel: MembershipModel.Wallet,
});
...

You can add new members (their addresses) in just a few lines as well. Here is an example of adding a wallet address as a member.

const member = new Keypair();
const {membershipAccount} = await fanoutSdk.addMemberWallet({
    fanout: init.fanout,
    fanoutNativeAccount: init.nativeAccount,
    membershipKey: member.publicKey,
    shares: 10
});

What is Amman?

Amman is a toolkit to test Solana SDK libraries and apps by running a local validator. The toolkit was developed by the Metaplex Foundation to enhance the developer experience for projects involving high-frequency updates and testing.

Despite the low gas fee, deploying a complex Solana program on the mainnet can be cost-prohibitive. Hence, for fast deployment and testing of apps and SDK libraries, developers can either use the Solana devnet, testnet, or a local validator. 

Because the testnet/devnet requires constant airdrops and repetitive deploy and wait processes, a local validator is preferred for rapid, no-WiFi deploys and tests. 

Additionally, running a local validator guarantees 100% uptime while testing, whereas the testnet/devnet may go offline in the process.

Amman CLI includes the relay, validator interface, and mock storage server that together acts as a validator.

The Amman Client includes asserts, address labeling, transaction interface, and a client to the relay, all of which should be used in tests and the browser to connect with the local validator.

How to Use Amman

The Amman Github repo provides an excellent guide to running Amman. You will need to clone that repo to start using Amman.

To run Amman CLI, you need to create a configuration file. An example is given in the Amman GitHub repo.

With the config file, you can start and later stop the local validator with the following commands:

amman start ./path/to/config.js
amman stop

The Amman Client repository provides many TypeScript files that can be used in test scripts or web browser.

What is Metaboss?

Touted as the Metaplex “Swiss Army Tool,” Metaboss provides many functions wrapped around Metaplex for developers to easily build in the ecosystem.

As Metaplex is a new, rapidly evolving system, developers implement their own functions to interact with Metaplex. Metaboss helps in the process by delivering consistent, standardized functions to the ecosystem.

Some of the functionalities Metaboss provides are:

• Decode the metadata of a token mint account
• Mint new NFTs from a JSON file
• Get a snapshot of current NFT holders for a given Candy Machine ID or update authority
• Get a list of all candy machine state and config accounts for a given update authority
• Update all metadata Data struct fields for a NFT

How to Use Metaboss

First, install Metaboss as a package to your Solana program by running:

cargo install metaboss

Now you are ready to use Metaboss! 

There are numerous examples on the official documentation. For example, you can mint a new NFT from a JSON file with a single line of command.

First prepare the JSON file new_nft.json for the NFT.

{
    "name": "TestNFT2",
    "symbol": "TNFT",
    "uri": "https://arweave.net/FPGAv1XnyZidnqquOdEbSY6_ES735ckcDTdaAtI7GFw",
    "seller_fee_basis_points": 200,
    "creators": [
        {
            "address": "AVdBTNhDqYgXGaaVkqiaUJ1Yqa61hMiFFaVRtqwzs5GZ",
            "verified": false,
            "share": 50
        },
        {
            "address": "42NevAWA6A8m9prDvZRUYReQmhNC3NtSZQNFUppPJDRB",
            "verified": false,
            "share": 50
        }
    ]
}

Then, you can create any number of this NFT using the command:

metaboss mint one -k ~/.config/solana/devnet.json -d ./new_nft.json

How to Get Started with Metaplex on Alchemy

Alchemy provides Solana APIs with the most robust free plan for developers to start building right away.

Want to deploy your Metaplex NFT project on Alchemy? Sign up for a free Alchemy account to start building!