Overview

Mpl Toolbox includes a bunch of essential Solana and Metaplex programs to get you up and running with your decentralized applications.

Introduction

Whilst all of Metaplex's products offer clients that include all you need to get started with that particular product, they do not include clients for low-level yet essential tasks such as creating an account from the SPL System program or extending a Lookup Table from the SPL Address Lookup Table program. MPL Toolbox aims to fix this by offering a collection of essential Solana and Metaplex programs that can be used to perform these more low-level tasks. Namely, MPL Toolbox includes the following programs:

• SPL System. The native Solana program that allows us to create accounts.
• SPL Token and SPL Associated Token. The native Solana programs that allow us to manage tokens.
• SPL Memo. The native Solana program that allows us to attach memos to transactions.
• SPL Address Lookup Table. The native Solana program that allows us to manage lookup tables.
• SPL Compute Budget. The native Solana program that allows us to manage compute units.
• MPL System Extras. An immutable Metaplex program that offers a few extra low-level features on top of SPL System.
• MPL Token Extras. An immutable Metaplex program that offers a few extra low-level features on top of SPL Token.

SPL System

The instructions of the SPL System program can be used to create new uninitialized accounts on-chain and transfer SOL between wallets. You can read more about the SPL System program in Solana's official documentation.

Note that, you may be interested in the MPL System Extras program which offers a few convenient instructions when dealing with creating accounts and transferring SOL.

SPL Token and SPL Associated Token

The SPL Token and SPL Associated Token programs can be used to manage tokens in Solana. It allows us to create Mint accounts, Token accounts, Associated Token PDAs, mint tokens, transfer tokens, delegate tokens, etc. You can read more about these programs in Solana's official documentation.

Note that, you may be interested in the Mpl Token Extras program which offers a few convenient instructions when dealing with tokens.

SPL Memo

The SPL Memo program simply allows us to attach text notes — i.e. memos — to transactions. You can read more about this program in Solana's official documentation.

import { transactionBuilder } from '@metaplex-foundation/umi'
import { addMemo } from '@metaplex-foundation/mpl-toolbox'

await transactionBuilder()
  .add(...) // Any instruction(s) here.
  .add(addMemo(umi, { memo: 'Hello world!' })) // Add a memo to the transaction.
  .sendAndConfirm(umi)

SPL Address Lookup Table

The SPL Address Lookup Table program can be used to reduce the size of transactions by creating custom lookup tables — a.k.a LUTs or ALTs — before using them in transactions. This program allows you to create and extend LUTs. You can read more about this program in Solana's official documentation.

SPL Compute Budget

The SPL Compute Budget program allows us to set a custom Compute Unit limit and price. You can read more about this program in Solana's official documentation.

MPL System Extras

The MPL System Extras program is an immutable program that offers a few convenient instructions on top of the native SPL System program.

Create Account with Rent

This instruction creates new accounts without needing to fetch the rent exemption. This instruction uses the Rent sysvar on the program to compute the rent exemption from the provided space attribute. It then does a CPI call to the SPL System program to create an account with the computed rent.

The advantage is that clients using this instruction no longer need the extra HTTP request that fetches the rent exemption from the RPC node. The inconvenience is that, because we are doing a CPI call, the maximum size account that can be created using this instruction is 10KB, as opposed to 10MB when using the SPL System program directly.

import { generateSigner } from '@metaplex-foundation/umi'
import { createAccountWithRent } from '@metaplex-foundation/mpl-toolbox'

const newAccount = generateSigner(umi)
await createAccountWithRent(umi, {
  newAccount,
  space: 42,
  programId: umi.programs.get('myProgramName').publicKey,
}).sendAndConfirm(umi)

Transfer All SOL

This instruction is similar to the Transfer SOL instruction from the SPL System program except that it transfers all the SOL from the source account to the destination account.

This can be useful when we want to drain an account from all of its lamports whilst using this account to pay for the transaction. Without this instruction, we would need to fetch the balance of the account to drain and subtract an estimation of the transaction fee — which can be tricky to estimate when using prioritization fees.

import { transferAllSol } from '@metaplex-foundation/mpl-toolbox'

await transferAllSol(umi, {
  source,
  destination,
}).sendAndConfirm(umi)

MPL Token Extras

The MPL Token Extras program is an immutable program that offers a few convenient instructions on top of the native SPL Token program.

Create Token If Missing

This instruction creates a new Token account if and only if it does not already exist. This is useful if a subsequent instruction requires a Token account but we do not know whether it already exists or not. This instruction can be used to ensure the Token account exists without having to fetch it first on the client side.

Whilst this instruction works with both associated Token accounts and regular Token accounts, it's important to note that it will only be able to create an associated Token account if the token account does not already exist. Therefore we can have the following situations:

• The token account is an associated token account.
  • If the account exists, the instruction succeeds and does nothing.
  • If the account does not exist, the instruction succeeds and creates the associated token account.
• The token account is a regular token account — i.e. non-associated.
  • If the account exists, the instruction succeeds and does nothing.
  • If the account does not exist, the instruction fails.

import { transactionBuilder } from '@metaplex-foundation/umi'
import { createTokenIfMissing } from '@metaplex-foundation/mpl-toolbox'

// If the token account is an associated token account.
await transactionBuilder()
  .add(createTokenIfMissing(umi, { mint, owner }))
  .add(...) // Subsequent instructions can be sure the Associated Token account exists.
  .sendAndConfirm(umi)

// If the token accounts is a regular token account.
await transactionBuilder()
  .add(createTokenIfMissing(umi, { mint, owner, token }))
  .add(...) // Subsequent instructions can be sure the non-Associated Token account exists, otherwise the instruction fails.
  .sendAndConfirm(umi)