UMI Framework

A Solana Framework for JavaScript clients

Umi is a modular framework for building and using JavaScript clients for Solana programs. It provides a zero-dependency library that defines a set of core interfaces that libraries can rely on without being tied to a specific implementation. It is then up to the end-user to choose the implementation that best suits their needs. Umi also provides a set of default implementations and bundles that can be used out of the box allowing developers to get started quickly.

Installation

For end-users

End-users using Umi to build applications need to install Umi and select the plugins they want to use. Alternatively, they can install the default bundle that includes a set of plugins that's suitable for most use cases. Note that, for now, the default bundle relies on web3.js for some of the interfaces so we have to install it as well.

npm install \
  @metaplex-foundation/umi \
  @metaplex-foundation/umi-bundle-defaults \
  @solana/web3.js

Then, you can create a new Umi instance using the createUmi function of the default bundle.

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

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

Then you want to tell Umi which wallet to use. This can either be a keypair or the solana wallet adapter.

That's it, now pass your Umi instance around and add more plugins as needed.

For library authors

Library authors that want to use Umi's interfaces to drastically reduce their dependencies 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.

npm install @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 instance:

import type { Context, PublicKey } from '@metaplex-foundation/umi';
import { u32 } from '@metaplex-foundation/umi/serializers';

export async function myFunction(
  context: Pick<Context, 'rpc'>, // <-- Inject the interfaces you need.
  publicKey: PublicKey
): number {
  const rawAccount = await context.rpc.getAccount(publicKey);
  if (!rawAccount.exists) return 0;
  return u32().deserialize(rawAccount.data)[0];
}

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 install @metaplex-foundation/umi @metaplex-foundation/umi-bundle-tests

Connecting to an RPC

Connecting Umi to an RPC is as simple as creating an umi instance and passing through your rpc end point as the first argument. It is recommended to use at least a free RPC end point from one of the many Solana RPC providers and not use the public endpoint of https://api.mainnet-beta.solana.com due to it's restrictions and limitations.

Connecting Umi to devnet is as simple as swapping out the RPC end point for that of a Devnet endpoint.

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

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

Registering Programs and Clients

Sometimes Umi may require you to register programs/clients directly to it. To do this you can call the .use() method from your umi instance and pass in the client as the argument. In the below example we'll register the mpl-token-metdata client to UMI.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata'

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

You can chain .use() together to register multiple clients.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
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())

Connecting w/ a Secret Key

To use Umi you'll need to register a wallet in order to send transactions. To use a file system wallet you can import the json stored private key and convert it to a keypair for use with Umi.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
import { keypairIdentity } from '@metaplex-foundation/umi'
import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata'
import { mplCandyMachine } from '@metaplex-foundation/mpl-candy-machine'

// Create Umi Instance
const umi = createUmi('https://api.mainnet-beta.solana.com')

// Import your private key file and parse it.
const wallet = './my-wallet.json'
const secretKey = JSON.parse(fs.readFileSync(wallet, 'utf-8'))

// Create a keypair from your private key
const keypair = umi.eddsa.createKeypairFromSecretKey(new Uint8Array(secretKey))

// Register it to the Umi client.
umi.use(keypairIdentity(keypair))

Connecting w/ Wallet Adapter

Umi can connect to solana-labs/wallet-adapter directly to provide a seemless experiance for users on your front end. This prebuilt wallet UI is a great starting place for websites that are looking for user transactions and interactions. For this example we'll create a simple useUmi hook in React.

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
import { walletAdapterIdentity } from '@metaplex-foundation/umi-signer-wallet-adapters'
import { mplTokenMetadata } from '@metaplex-foundation/mpl-token-metadata'
import { mplCandyMachine } from '@metaplex-foundation/mpl-candy-machine'
import { useWallet } from '@solana/wallet-adapter-react'

const useUmi = () => {
  // Import useWallet hook
  const wallet = useWallet()

  // Create Umi instance
  const umi = createUmi('https://api.mainnet-beta.solana.com')
    .use(mplTokenMetadata())
    .use(mplCandyMachine())
    // Register Wallet Adapter to Umi
    .use(walletAdapterIdentity(wallet))

  return umi
}

export default useUmi

From here on you can import your useUmi hook into your components and use as needed.

// Import hook from where you saved it
import { useUmi } from '@hooks/useUmi'

// Your component
const MyComponent = () => {
  // Assign you hook to a const within component ready for use
  const umi = useUmi()

  return <div>...</div>
}

export default MyComponent

Getting Started using the JavaScript

Metaplex provides a JavaScript library that can be used to interact with Core Assets. Thanks to the Umi framework, it ships without many opinionated dependencies thus providing a lightweight library that can be used in any JavaScript project.

To get started, you'll need to install the Umi framework and the Core JavaScript library.

npm install \
  @metaplex-foundation/umi \
  @metaplex-foundation/umi-bundle-defaults \
  @solana/web3.js \
  @metaplex-foundation/mpl-core

Next, you should create your Umi instance and install the mplCore plugin like so.

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

// Use the RPC endpoint of your choice.
const umi = createUmi('http://127.0.0.1:8899').use(mplCore())

Then instruct Umi which wallet to use. This can either be a keypair or the solana wallet adapter.

That's it, you can now interact with Core Assets and Core Collections by using the various functions provided by the library and passing your Umi instance to them. Here's an example of creating an Asset:

Create Asset

JavaScript

const result = createV1(umi, {
  asset: asset,
  name: 'My Nft',
  uri: 'https://example.com/my-nft',
}).sendAndConfirm(umi)

To then fetch the data of your newly created asset you can use:

Fetch a single asset

JavaScript

import { fetchAssetV1 } from '@metaplex-foundation/mpl-core'

const asset = await fetchAssetV1(umi, asset.publicKey)

console.log(asset)