Getting Started

Umi Installation

To use Umi you need to install Umi and all the external plugins you'll want to use. Alternatively, if you don't need a specific plugin, you can install the default bundle that includes a set of plugins that's suitable for most use cases.

Note: since the default bundle relies on web3.js for some of the interfaces you'll need to install that package as well.

Required Packages

To install them, use the following commands:

npm i @metaplex-foundation/umi

npm i @metaplex-foundation/umi-bundle-defaults

npm i @solana/web3.js@1

For library authors

Library authors, that want to use Umi's interfaces to drastically reduce their dependencies, will only need to install the main Umi library. It is highly recommended to install it as a peer dependency to ensure the end-user does not end up with multiple versions of the Umi library using the following command:

npm i @metaplex-foundation/umi --save-peer

You can then use Umi's Context object or a subset of it to inject any interface you need in your functions.

For testing

Also note that Umi comes with a testing bundle that can help both end-users and library authors to test their code. For instance, it includes a MockStorage implementation used for both the UploaderInterface and the DownloaderInterface so you can reliably test your code without having to rely on a real storage provider.

npm i @metaplex-foundation/umi

npm i @metaplex-foundation/umi-bundle-tests

Umi Basics

In this section, we'll cover the essential steps to get started with Umi:

• Creating Umi and Connecting to an RPC
• Connecting a Wallet
• Registering Programs and Clients

Connecting to an RPC

Solana has different clusters (e.g., Mainnet-beta, Devnet, Testnet, ...) that serve various purposes, each with dedicated API nodes to handle RPC requests.

Connecting Umi to a cluster of choice is is as simple as creating an umi instance since the RPC endpoint is passed as the first argument.

Note: If you're connecting to Mainnet, it's recommended to use a dedicated RPC endpoint from a Solana RPC provider instead of the public endpoint (https://api.mainnet-beta.solana.com) due to its limitations.

To create a Umi instance, import the createUmi function and provide your RPC endpoint. Optionally, you can also specify the commitment level as the second argument.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'

const umi = createUmi('<RPC-Endpoint>', '<Commitment-Level>')

Connecting a Wallet

When setting up Umi, you'll need to use or generate a wallet in order to send transactions. To do so, you can create a new wallet for testing, import an existing wallet from the filesystem, or use a walletAdapter for web-based dApps.

Note: The walletAdapter section provides only the code needed to connect it to Umi, assuming you've already installed and set up the walletAdapter. For a comprehensive guide, refer to this

Note: The Umi interface stores two instances of Signer: The identity using the app and the payer paying for transaction and storage fees. By default, the signerIdentity method will also update the payer attribute since, in most cases, the identity is also the payer.

If you want to learn more, go to the Umi Context Interfaces Paragraph

Registering Programs and Clients

In some cases, Umi requires you to specify the programs or clients you want to use (e.g, when minting a Core Asset, you'll need to tell Umi to use the Core program). You can do this by calling the .use() method on your Umi instance and passing in the client.

Here’s how to register the mpl-token-metadata client with Umi:

import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata'

const umi = createUmi('https://api.mainnet-beta.solana.com')
  .use(mplTokenMetadata())

Note: You can also chain .use() calls to register multiple clients like this:

import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata'
import { mplCandyMachine } from '@metaplex-foundation/mpl-candy-machine'

const umi = createUmi('https://api.mainnet-beta.solana.com')
  .use(mplTokenMetadata())
  .use(mplCandyMachine())