README.md

JavaScript client for Mpl Core

A Umi-compatible JavaScript library for the project.

Getting started

1. First, if you're not already using Umi, follow these instructions to install the Umi framework.

2. Next, install this library using the package manager of your choice.

   npm install @metaplex-foundation/mpl-core

3. Finally, register the library with your Umi instance like so.

   import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
   import { mplCore } from '@metaplex-foundation/mpl-core';
   
   const umi = createUmi('<your rpc endpoint>');
   umi.use(mplCore());

   For using on the frontend wallets, see this React example

   import { useConnection, useWallet } from '@solana/wallet-adapter-react';
   import { walletAdapterIdentity } from '@metaplex-foundation/umi-signer-wallet-adapters';
   
   export function MyComponent() {
      const wallet = useWallet();
      const { connection } = useConnection();
      const umi = createUmi(connection)
         .use(walletAdapterIdentity(wallet))
         .use(mplCore())
   
      // rest of component
   }

4. Examples

   // Create an asset
   const assetAddress = generateSigner(umi);
   const owner = generateSigner(umi);
   await create(umi, {
     name: 'Test Asset',
     uri: 'https://example.com/asset.json',
     asset: assetAddress,
     owner: owner.publicKey, // optional, will default to payer
   }).sendAndConfirm(umi);
   
   // Fetch an asset
   const asset = await fetchAssetV1(umi, assetAddress.publicKey);
   
   // Create a collection
   const collectionUpdateAuthority = generateSigner(umi);
   const collectionAddress = generateSigner(umi);
   await createCollection(umi, {
     name: 'Test Collection',
     uri: 'https://example.com/collection.json',
     collection: collectionAddress,
     updateAuthority: collectionUpdateAuthority.publicKey, // optional, defaults to payer
   }).sendAndConfirm(umi);
   
   // Fetch a collection
   const collection = await fetchCollectionV1(umi, collectionAddress.publicKey);
   
   // Create an asset in a collection, the authority must be the updateAuthority of the collection
   await create(umi, {
     name: 'Test Asset',
     uri: 'https://example.com/asset.json',
     asset: assetAddress,
     collection,
     authority: collectionUpdateAuthority, // optional, defaults to payer
   }).sendAndConfirm(umi);
   
   // Transfer an asset
   const recipient = generateSigner(umi);
   await transfer(umi, {
     asset,
     newOwner: recipient.publicKey,
   }).sendAndConfirm(umi);
   
   // Transfer an asset in a collection
   await transfer(umi, {
     asset,
     newOwner: recipient.publicKey,
     collection,
   }).sendAndConfirm(umi);
   
   // GPA fetch assets by owner
   const assetsByOwner = await getAssetV1GpaBuilder(umi)
     .whereField('key', Key.AssetV1)
     .whereField('owner', owner.publicKey)
     .getDeserialized();
   
   // GPA fetch assets by collection
   const assetsByCollection = await getAssetV1GpaBuilder(umi)
     .whereField('key', Key.AssetV1)
     .whereField(
       'updateAuthority',
       updateAuthority('Collection', [collectionAddress.publicKey])
     )
     .getDeserialized();
   
   // DAS API (RPC based indexing) fetch assets by owner/collection
   // Coming soon

5. Some advanced examples

   const umi = await createUmi();
   
   // Freezing an asset
   const assetAddress = generateSigner(umi);
   const freezeDelegate = generateSigner(umi);
   
   await addPlugin(umi, {
     asset: assetAddress.publicKey,
     // adds the owner-managed freeze plugin to the asset
     plugin: {
       type: 'FreezeDelegate',
       frozen: true,
       
       // Optionally set the authority to a delegate who can unfreeze. If unset, this will be the Owner
       // This is functionally the same as calling addPlugin and approvePluginAuthority separately.
       // Freezing with a delegate is commonly used for escrowless staking programs.
       authority: {
         type: 'Address',
         address: freezeDelegate.publicKey,
       },
     }
   }).sendAndConfirm(umi);
   
   // Unfreezing an asset with a delegate
   // Revoking an authority will revert the authority back to the owner for owner-managed plugins
   await revokePluginAuthority(umi, {
     asset: assetAddress.publicKey,
     plugin: {
       type: 'FreezeDelegate',
     },
     authority: freezeDelegate,
   }).sendAndConfirm(umi);
   
   // Create a collection with royalties
   const collectionAddress = generateSigner(umi);
   const creator1 = generateSigner(umi);
   const creator2 = generateSigner(umi);
   
   await createCollection(umi, {
     name: 'Test Collection',
     uri: 'https://example.com/collection.json',
     collection: collectionAddress,
     plugins: [
       {
         type: 'Royalties',
           basisPoints: 500,
           creators: [
             {
               address: creator1.publicKey,
               percentage: 20,
             },
             {
               address: creator2.publicKey,
               percentage: 80,
             },
           ],
           ruleSet: ruleSet('None'), // Compatibility rule set
   
       },
     ],
   }).sendAndConfirm(umi);
   
   // Create an asset in a collection.
   // Assets in a collection will inherit the collection's authority-managed plugins, in this case the royalties plugin
   await create(umi, {
     name: 'Test Asset',
     uri: 'https://example.com/asset.json',
     asset: assetAddress,
     collection: await fetchCollectionV1(umi, collectionAddress.publicKey),
   }).sendAndConfirm(umi);

You can learn more about this library's API by reading its generated TypeDoc documentation.

Contributing

Check out the Contributing Guide the learn more about how to contribute to this library.