# UMI Framework

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 <a href="#for-end-users" id="for-end-users"></a>

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](https://developers.metaplex.com/umi/connecting-to-umi#connecting-w-a-secret-key) or the [solana wallet adapter](https://developers.metaplex.com/umi/connecting-to-umi#connecting-w-wallet-adapter).

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

### For library authors <a href="#for-library-authors" id="for-library-authors"></a>

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 <a href="#for-testing" id="for-testing"></a>

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 <a href="#connecting-to-an-rpc" id="connecting-to-an-rpc"></a>

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 <a href="#registering-programs-and-clients" id="registering-programs-and-clients"></a>

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 <a href="#connecting-w-a-secret-key" id="connecting-w-a-secret-key"></a>

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 <a href="#connecting-w-wallet-adapter" id="connecting-w-wallet-adapter"></a>

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](https://github.com/metaplex-foundation/umi), 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](https://github.com/metaplex-foundation/umi/blob/main/docs/installation.md) 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](https://developers.metaplex.com/umi/connecting-to-umi#connecting-w-a-secret-key) or the [solana wallet adapter](https://developers.metaplex.com/umi/connecting-to-umi#connecting-w-wallet-adapter).

That's it, you can now interact with Core Assets and Core Collections by using [the various functions provided by the library](https://mpl-core.typedoc.metaplex.com/) 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)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://8bit-1.gitbook.io/solibrary/umi-framework.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.