Metaplex Program Library ships the on-chain contracts behind its NFT tooling

What lives in the repository: programs, not a framework

The Metaplex Program Library is described in one line as Metaplex smart contracts and SDK, and the repository description says smart contracts maintained by the Metaplex team. The primary language is Rust, and the topics name blockchain, digital-assets, metaplex, nft, rust and solana.

The important thing to understand is what this repository is not. It is not a package you add to a project and call. It is a set of deployed programs, each with its own directory in the workspace, each published as a Rust crate and an npm SDK package, and each carrying the account layouts and instruction structures that the Metaplex client tooling depends on.

The contracts table lists ten of them. Auction House and Auctioneer for sales, Bubblegum for compressed NFTs, Candy Machine Core and Candy Machine for drops, Fixed Price Sale, Gumdrop for allowlist drops, NFT Packs, Token Entangler, and Token Metadata, which is the account model the rest of the ecosystem reads.

Token Metadata is the one to understand first if you are new to this. Almost everything else in the table is a mechanism for creating or distributing something, and Token Metadata is the record of what that thing is. A compressed NFT under Bubblegum, a candy machine mint, a gumdrop claim, all of them end up describing themselves through the metadata program, which is why a wallet can display an item regardless of which creation path produced it.

There is also a note that Hydra now lives in its own repository at metaplex-foundation/mpl-hydra, so the list of what is in this workspace has already shrunk once, and may shrink again.

Rust crates and npm packages, versioned independently

Every contract in the table is published twice, once as a Rust crate and once as an npm package, and the two are linked in the same row so you can see which corresponds to which.

The Rust side adds a few crates that are not contracts themselves. Testing Utils and Utils are listed alongside the programs, which tells you the workspace has a shared support layer for tests and a common utility crate that the programs depend on.

The versioning policy is the part that catches people out, and the README is explicit that smart contract SDK packages are versioned independently since a contract is not necessarily coupled to other contracts. So a project depending on Token Metadata and Bubblegum is combining two packages whose version numbers have no relationship to each other, and a breaking change in one does not arrive bundled with a breaking change in the other.

That is a deliberate choice with real consequences. It means a consumer can upgrade one part of their stack without being forced to upgrade the rest, and it means the release notes for each package matter individually rather than there being one changelog for the repository.

The npm publishing flow is documented in detail, and it is worth understanding because it explains how the tags in the repository arise. The packages use a set of pre and post version and publish npm scripts to manage related checks, tagging, committing and pushing the version bump.

The preversion script ensures that the package builds and its tests pass. The postversion script adds and commits the version bump and adds a tag indicating the package name and new version, for example @metaplex-foundation/[email protected]. The prepublishOnly script ensures that the package builds and its tests pass again. The postpublish script pushes the committed change and the new tag to GitHub.

In practice you run two commands from the folder of the package you want to update: npm version with a patch, minor or major argument, then npm publish. The README also insists that you be on an up to date master branch first, and says explicitly not to publish from another branch, only from the main one with only approved pull request changes merged.

Building a program and running the Rust tests

The development section explains how the Rust tests are set up, and the mechanism is a build script rather than a general test harness.

You run the build.sh script with the name of the program to build the shared object and put it in a directory called test-programs in the root of the project. The example is:

./build.sh auction-house

Running it with all builds all programs.

That directory name is the whole contract between the build and the test suite. The Rust tests do not run the programs in process, they load the compiled shared objects that build.sh has placed in test-programs, which is how you test an on-chain program without a validator.

The test and toolchain setup is in the root package.json, and it tells you what the project expects. The devDependencies include @metaplex-foundation/amman at 0.12.0, which is the Anchor-based testing framework, and @project-serum/anchor at 0.19.0, the Solana framework the programs are written against, along with eslint, prettier and the TypeScript tooling for the SDK side.

The root package.json is marked private and describes itself as the web interface to smart contracts by the Metaplex team, and the scripts block in the repository root also has a test.sh alongside build.sh. The CI configuration is visible in the badges at the top of the README, with separate workflows for program tests, integration tests and SDK tests, which is a sensible split because a change to a Rust program and a change to a TypeScript client fail for different reasons.

There is also an Anchor.toml at the repository root and a .base-ammanrc.js, which are the configuration files for the Anchor toolchain and the Amman test runner respectively.

The licence, and a discrepancy worth resolving before you build on it

There is a licensing detail here that deserves more than a footnote, because it is exactly the kind of thing that has to be settled before a project depends on it.

The repository is published with a custom licence that GitHub cannot classify, and the README does not describe it in the visible text. The root package.json, which is the manifest for the workspace tooling rather than for a published contract package, records the licence as MIT. Those two statements are about different files and it is entirely possible they are consistent, since the root manifest is not a distributed package, but the safe reading is that the LICENSE file at the repository root is the document that governs use of the contracts, and the MIT string in the root package.json says nothing about that.

What that means in practice is that you need to read the LICENSE file yourself, and if your use is redistributing a program, shipping a modified version, or including one of these programs in a product, you need a view on the terms rather than an assumption based on a badge.

The counterweight is the maintenance arrangement. These are the reference implementations for a widely used part of the Solana NFT stack, they are maintained by the team whose client tooling depends on them, and the repository is not archived with the last push on 2026-09-17. An actively maintained reference implementation is a strong reason to use these programs rather than reimplement them, and the practical counterpart is that you are adopting a dependency on someone else's account layout and instruction set, with the upgrade path that implies.

Where the Program Library is the wrong choice

Three boundaries, and the first is about what your project actually needs.

The first is that this is a set of specific programs, not a toolkit. There is no shared framework, no scaffolding command and no common crate you depend on to build your own program. If your requirement is a program with your own account model, you are not going to find a starting point here beyond copying the shape of a directory and setting up Anchor and Amman yourself, which is the same work the Metaplex team did for each of these.

The second is that the design is deliberately decoupled, and decoupling has a cost at the edges. A candy machine create instruction and a token metadata create instruction belong to different packages with different versions, and the account that a candy machine points at is a token metadata account that your program has to construct and own correctly. Nothing in the type system of this workspace enforces that, because the packages do not know about each other. You get the benefit of a tested implementation of each piece, and you take on the responsibility of wiring them so that an account the minting program creates is byte-compatible with what the metadata program expects.

The third is that the naming is historical. The auction house, the candy machine, the gumdrop and the fixed price sale reflect the era in which Metaplex built its drop tooling, and the newer parts of the stack have moved on, as Hydra's departure to its own repository shows. A team building a new marketplace in 2026 should look at the current state of the ecosystem first, because a contract being maintained is not the same as a contract being the current recommendation.

The alternative approach, and it is a real one for a team that wants fewer moving parts, is to write the program yourself against the same account model using Anchor, and to depend only on Token Metadata rather than on the whole table. The difference in approach is between depending on a maintained reference implementation of a workflow, which saves you the months of getting the account layouts and the instruction ordering right, and owning the code, which saves you the dependency but costs you the correctness work and the audit.

Editorial conclusion

Adopt the Metaplex Program Library if you are building on Solana and want the same token metadata accounts, compressed NFT handling and candy machine drop logic that the Metaplex tooling uses, since the crates and the npm packages are the reference implementation rather than a wrapper around one. Do not adopt it as a general smart contract framework, since each directory is a specific program with its own crate, its own package and its own version, and it does not give you a shared development environment. Verify first that the licence in the LICENSE file at the repository root allows your use, since the repository carries a custom licence that GitHub cannot classify even though the root package.json records MIT, that you pick the right crate for the job because Hydra has already moved out to its own repository, and that you are comfortable with the release model, where each package is versioned and published on its own and the npm lifecycle scripts push the commit and tag to master.

Frequently asked questions

Official sources

1. Issues
2. metaplex-foundation/metaplex-program-library on GitHub
3. README