JavaScript SDK | Metaplex Core

Q: Core JavaScript SDKとは何ですか？

Core JavaScript SDK（@metaplex-foundation/mpl-core）は、Solana上のMetaplex Core NFTを操作するためのTypeScriptライブラリです。Asset と Collection の作成、転送、バーン、管理のための型安全な関数を提供します。

Q: ブラウザウォレットを接続するにはどうすればよいですか？

@metaplex-foundation/umi-signer-wallet-adaptersパッケージをウォレットアダプターと一緒に使用し、umi.use(walletAdapterIdentity(wallet))を呼び出します。

Q: sendAndConfirmとsendの違いは何ですか？

sendAndConfirm()はトランザクションの確認を待ってから返します。send()はブロードキャスト後すぐに返します。ほとんどの場合はsendAndConfirm()を使用してください。

Q: 複数の操作をバッチ処理するにはどうすればよいですか？

transactionBuilder()を使用して命令を組み合わせますが、Solanaのトランザクションサイズ制限（約1232バイト）に注意してください。大きなバッチの場合は、複数のトランザクションを送信してください。

Q: このSDKはReact/Next.jsで使用できますか？

はい。SDKはブラウザとNode.js環境の両方で動作します。Reactの場合は、@solana/wallet-adapter-reactのウォレットアダプターをUmiのウォレットアダプターアイデンティティと一緒に使用してください。

Metaplex Core JavaScript SDK（@metaplex-foundation/mpl-core）は、Solana上のCore Asset と Collection を操作するための完全なTypeScript/JavaScriptインターフェースを提供します。Umiフレームワーク上に構築されており、すべてのCore操作に対して型安全なメソッドを提供します。

学べること

このSDKリファレンスでは以下を扱います：

Coreプラグインを使用したUmiのセットアップ
Assetの作成、転送、バーン、更新
Collectionとコレクションレベルの操作の管理
プラグインの追加、更新、削除
DASを使用したAssetとCollectionの取得
エラー処理と一般的なパターン

概要

Core JavaScript SDKは、JavaScript/TypeScriptアプリケーションからMetaplex Coreを操作するための推奨方法です。Coreプログラムの命令を型安全なAPIでラップしています。

インストール：npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi
ウォレット/RPC管理にUmiフレームワークが必要
すべての関数は柔軟な実行のためにトランザクションビルダーを返す
ブラウザとNode.js環境の両方をサポート

範囲外

Rust SDKの使用（Rust SDKを参照）、Token Metadata操作、Candy Machine統合、低レベルSolanaトランザクション構築。

クイックスタート

ジャンプ： セットアップ · 作成 · 転送 · バーン · 更新 · Collection · プラグイン · 取得 · エラー · FAQ

依存関係をインストール：npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi-bundle-defaults
mplCore()プラグインでUmiインスタンスを作成
トランザクション用のsignerを生成またはロード
SDK関数を呼び出してトランザクションを確認

前提条件

**Node.js 18+**またはESモジュール対応のモダンブラウザ
RPCとsignerを設定したUmiフレームワーク
トランザクション手数料用のSOL（Assetあたり約0.003 SOL）

APIリファレンス

SDKの完全なTypeDoc APIドキュメント。

NPMパッケージ

npmjs.comのパッケージとバージョン履歴。

インストール

Core SDKとUmiフレームワークをインストール：

Terminal

npm install @metaplex-foundation/mpl-core @metaplex-foundation/umi-bundle-defaults

メタデータアップロード用にアップローダープラグインを追加：

Terminal

npm install @metaplex-foundation/umi-uploader-irys

Umiセットアップ

Coreプラグインを使用してUmiインスタンスを作成・設定：

setup-umi.ts

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
import { mplCore } from '@metaplex-foundation/mpl-core'
import { keypairIdentity } from '@metaplex-foundation/umi'
import { irysUploader } from '@metaplex-foundation/umi-uploader-irys'
// RPCエンドポイントでUmiを作成
const umi = createUmi('https://api.devnet.solana.com')
  .use(mplCore())
  .use(keypairIdentity(yourKeypair))
  .use(irysUploader()) // オプション：メタデータアップロード用

Asset

Assetの作成

create()を使用して新しいCore Assetをミント：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { create } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4
5// Initialize UMI
6const umi = createUmi('https://api.devnet.solana.com')
7  .use(mplCore())
8
9// Create a new NFT asset
10const asset = await create(umi, {
11  name: 'My NFT',
12  uri: 'https://example.com/metadata.json'
13}).sendAndConfirm(umi)
14
15console.log('Asset created:', asset.publicKey)

Assetの転送

transfer()を使用してAssetを別のウォレットに送信：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { transfer } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { publicKey } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10// Transfer an existing NFT asset to a new owner
11const result = await transfer(umi, {
12  asset: publicKey('AssetAddressHere...'),
13  newOwner: publicKey('RecipientAddressHere...'),
14}).sendAndConfirm(umi)
15
16console.log('Asset transferred:', result.signature)

Assetのバーン

burn()を使用してAssetを永久に破棄しrentを回収：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { burn } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { publicKey } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.devnet.solana.com').use(mplCore())
7const assetAddress = publicKey('AssetAddressHere...')
8
9// Permanently destroy/burn an NFT asset
10const result = await burn(umi, {
11  asset: assetAddress,
12}).sendAndConfirm(umi)
13
14console.log('Asset burned successfully')

Assetの更新

update()を使用してAssetのメタデータを変更：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { update } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { publicKey } from '@metaplex-foundation/umi'
5
6const umi = createUmi('https://api.devnet.solana.com').use(mplCore())
7const assetAddress = publicKey('AssetAddressHere...')
8
9// Update an existing NFT asset's metadata
10const result = await update(umi, {
11  asset: assetAddress,
12  name: 'Updated NFT Name',
13  uri: 'https://updated-example.com/metadata.json',
14}).sendAndConfirm(umi)
15
16console.log('Asset updated successfully')

Collection

Collectionの作成

createCollection()を使用してCollectionアカウントを作成：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { createCollection } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { generateSigner } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10// Generate a new keypair for the collection
11const collectionSigner = generateSigner(umi)
12
13// Create a new Collection
14await createCollection(umi, {
15  collection: collectionSigner,
16  name: 'My Collection',
17  uri: 'https://example.com/collection.json',
18}).sendAndConfirm(umi)
19
20console.log('Collection created:', collectionSigner.publicKey)

Collection内にAssetを作成

create()にcollectionパラメータを渡す：

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { create, fetchCollection } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { generateSigner, publicKey } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10const collectionAddress = publicKey('YOUR_COLLECTION_ADDRESS')
11
12// Fetch the existing collection
13const collection = await fetchCollection(umi, collectionAddress)
14
15// Generate a new keypair for the asset
16const assetSigner = generateSigner(umi)
17
18// Create asset in the collection
19await create(umi, {
20  asset: assetSigner,
21  collection,
22  name: 'Collection Item #1',
23  uri: 'https://example.com/item1.json',
24}).sendAndConfirm(umi)
25
26console.log('Asset created in collection:', assetSigner.publicKey)

プラグイン

プラグインはAssetとCollectionに動作を追加します。作成時または後から追加できます。

作成時にプラグインを追加

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { create, ruleSet } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { generateSigner, publicKey } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10const creator = publicKey('YOUR_CREATOR_ADDRESS')
11
12// Generate a new keypair for the asset
13const assetSigner = generateSigner(umi)
14
15// Create asset with Royalties plugin
16await create(umi, {
17  asset: assetSigner,
18  name: 'NFT with Royalties',
19  uri: 'https://example.com/metadata.json',
20  plugins: [
21    {
22      type: 'Royalties',
23      basisPoints: 500, // 5%
24      creators: [
25        { address: creator, percentage: 100 },
26      ],
27      ruleSet: ruleSet('None'),
28    },
29  ],
30}).sendAndConfirm(umi)
31
32console.log('Asset created with plugins:', assetSigner.publicKey)

既存のAssetにプラグインを追加

1import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
2import { addPlugin, fetchAsset, ruleSet } from '@metaplex-foundation/mpl-core'
3import { mplCore } from '@metaplex-foundation/mpl-core'
4import { publicKey } from '@metaplex-foundation/umi'
5
6// Initialize UMI
7const umi = createUmi('https://api.devnet.solana.com')
8  .use(mplCore())
9
10const assetAddress = publicKey('YOUR_ASSET_ADDRESS')
11
12// Fetch the existing asset
13const asset = await fetchAsset(umi, assetAddress)
14
15// Add a Royalties plugin to the asset
16await addPlugin(umi, {
17  asset,
18  plugin: {
19    type: 'Royalties',
20    basisPoints: 500, // 5%
21    creators: [
22      { address: umi.identity.publicKey, percentage: 100 },
23    ],
24    ruleSet: ruleSet('None'),
25  },
26}).sendAndConfirm(umi)
27
28console.log('Plugin added to asset:', assetAddress)

一般的なプラグインタイプ

プラグイン	タイプ文字列	目的
Royalties	`'Royalties'`	クリエイターロイヤリティの強制
Freeze Delegate	`'FreezeDelegate'`	凍結/解凍を許可
Burn Delegate	`'BurnDelegate'`	委任者によるバーンを許可
Transfer Delegate	`'TransferDelegate'`	委任者による転送を許可
Update Delegate	`'UpdateDelegate'`	メタデータ更新を許可
Attributes	`'Attributes'`	オンチェーンのキー/バリューデータ
Permanent Freeze	`'PermanentFreezeDelegate'`	永久凍結状態
Permanent Transfer	`'PermanentTransferDelegate'`	永久転送委任
Permanent Burn	`'PermanentBurnDelegate'`	永久バーン委任
詳細なプラグインドキュメントはプラグイン概要を参照してください。

Assetの取得

単一Assetの取得

1import { fetchAsset, fetchCollection, mplCore } from '@metaplex-foundation/mpl-core';
2import { publicKey } from '@metaplex-foundation/umi';
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
4
5// Initialize UMI
6const umi = createUmi('https://api.devnet.solana.com')
7  .use(mplCore())
8
9// Fetch a Core Asset
10const assetAddress = publicKey('AssetAddressHere...')
11const asset = await fetchAsset(umi, assetAddress)
12
13// Fetch a Core Collection
14const collectionAddress = publicKey('CollectionAddressHere...')
15const collection = await fetchCollection(umi, collectionAddress)
16
17console.log('Asset fetched:', asset)
18console.log('Name:', asset.name)
19console.log('Owner:', asset.owner)
20console.log('URI:', asset.uri)
21
22console.log('\nCollection fetched:', collection)
23console.log('Name:', collection.name)
24console.log('URI:', collection.uri)

オーナーによるAsset取得（DAS）

DAS APIを使用してインデックス化されたAssetをクエリ：

fetch-by-owner.ts

import { publicKey } from '@metaplex-foundation/umi'
import { dasApi } from '@metaplex-foundation/digital-asset-standard-api'
// UmiにDASプラグインを追加
const umi = createUmi('https://api.devnet.solana.com')
  .use(mplCore())
  .use(dasApi())
const owner = publicKey('OwnerAddressHere...')
const assets = await umi.rpc.getAssetsByOwner({
  owner,
  limit: 100,
})
console.log('所有Asset数:', assets.items.length)

CollectionによるAsset取得（DAS）

fetch-by-collection.ts

import { publicKey } from '@metaplex-foundation/umi'
const collectionAddress = publicKey('CollectionAddressHere...')
const assets = await umi.rpc.getAssetsByGroup({
  groupKey: 'collection',
  groupValue: collectionAddress,
  limit: 100,
})
console.log('CollectionのAsset数:', assets.items.length)

メタデータのアップロード

UmiのアップローダープラグインでメタデータJSONを保存：

upload-metadata.ts

import { irysUploader } from '@metaplex-foundation/umi-uploader-irys'
const umi = createUmi('https://api.devnet.solana.com')
  .use(mplCore())
  .use(keypairIdentity(yourKeypair))
  .use(irysUploader())
// まず画像をアップロード
const imageFile = await fs.promises.readFile('image.png')
const [imageUri] = await umi.uploader.upload([imageFile])
// メタデータJSONをアップロード
const uri = await umi.uploader.uploadJson({
  name: 'My NFT',
  description: 'An awesome NFT',
  image: imageUri,
  attributes: [
    { trait_type: 'Background', value: 'Blue' },
    { trait_type: 'Rarity', value: 'Rare' },
  ],
})
console.log('メタデータURI:', uri)

トランザクションパターン

送信と確認

標準パターンは確認を待機：

send-confirm.ts

const result = await create(umi, { asset, name, uri }).sendAndConfirm(umi)
console.log('署名:', result.signature)

カスタム確認オプション

custom-confirm.ts

const result = await create(umi, { asset, name, uri }).sendAndConfirm(umi, {
  confirm: { commitment: 'finalized' },
})

送信せずにトランザクションを構築

build-only.ts

const tx = create(umi, { asset, name, uri })
const builtTx = await tx.buildAndSign(umi)
// 後で送信: await umi.rpc.sendTransaction(builtTx)

複数の命令を組み合わせ

combine-instructions.ts

import { transactionBuilder } from '@metaplex-foundation/umi'
const tx = transactionBuilder()
  .add(create(umi, { asset: asset1, name: 'NFT 1', uri: uri1 }))
  .add(create(umi, { asset: asset2, name: 'NFT 2', uri: uri2 }))
await tx.sendAndConfirm(umi)

一般的なエラー

`Account does not exist`

Assetまたはcollectionアドレスが存在しません。アドレスが正しいか確認：

const asset = await fetchAsset(umi, assetAddress).catch(() => null)
if (!asset) {
  console.log('Assetが見つかりません')
}

`Invalid authority`

このアクションを実行する権限がありません。以下を確認：

Assetを所有している（転送、バーンの場合）
update authorityである（更新の場合）
必要な委任権限を持っている

`Insufficient funds`

ウォレットにSOLが不足しています。以下で補充：

solana airdrop 1 <WALLET_ADDRESS> --url devnet

`Asset already exists`

Asset keypairはすでに使用されています。新しいsignerを生成：

const assetSigner = generateSigner(umi) // 一意である必要がある

`Plugin not found`

このAssetにプラグインが存在しません。インストール済みプラグインを確認：

const asset = await fetchAsset(umi, assetAddress)
console.log('プラグイン:', Object.keys(asset))

注意事項

新しいAssetには常に新しいkeypairを使用 - keypairを再利用しないでください
create()のassetパラメータは公開鍵だけでなくsignerである必要がある
Collectionレベルのプラグインは同じタイプのAssetレベルプラグインを上書きする
作成後すぐに取得するAssetにはcommitment: 'finalized'を使用
トランザクションビルダーは不変 - 各メソッドは新しいビルダーを返す

クイックリファレンス

最小限の依存関係

package.json

{
  "dependencies": {
    "@metaplex-foundation/mpl-core": "^1.0.0",
    "@metaplex-foundation/umi": "^0.9.0",
    "@metaplex-foundation/umi-bundle-defaults": "^0.9.0"
  }
}

コア関数

関数	目的
`create()`	新しいAssetを作成
`createCollection()`	新しいCollectionを作成
`transfer()`	Assetの所有権を転送
`burn()`	Assetを破棄
`update()`	Assetのメタデータを更新
`updateCollection()`	Collectionのメタデータを更新
`addPlugin()`	Assetにプラグインを追加
`addCollectionPlugin()`	Collectionにプラグインを追加
`updatePlugin()`	既存のプラグインを更新
`removePlugin()`	Assetからプラグインを削除
`fetchAsset()`	アドレスでAssetを取得
`fetchCollection()`	アドレスでCollectionを取得

プログラムID

ネットワーク	アドレス
Mainnet	`CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d`
Devnet	`CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d`

FAQ

Core JavaScript SDKとは何ですか？

Core JavaScript SDK（@metaplex-foundation/mpl-core）は、Solana上のMetaplex Core NFTを操作するためのTypeScriptライブラリです。AssetとCollectionの作成、転送、バーン、管理のための型安全な関数を提供します。

このSDKを使用するにはUmiが必要ですか？

はい。Core SDKはUmiフレームワーク上に構築されており、ウォレット接続、RPC通信、トランザクション構築を処理します。@metaplex-foundation/mpl-coreと@metaplex-foundation/umi-bundle-defaultsの両方をインストールしてください。

ブラウザウォレットを接続するにはどうすればよいですか？

@metaplex-foundation/umi-signer-wallet-adaptersパッケージをウォレットアダプターと一緒に使用：

import { walletAdapterIdentity } from '@metaplex-foundation/umi-signer-wallet-adapters'
umi.use(walletAdapterIdentity(wallet))

sendAndConfirmとsendの違いは何ですか？

sendAndConfirm()はトランザクションの確認を待ってから返します。send()はブロードキャスト後すぐに返します。トランザクションの成功を確認するために、ほとんどの場合はsendAndConfirm()を使用してください。

複数の操作をバッチ処理するにはどうすればよいですか？

transactionBuilder()を使用して命令を組み合わせますが、Solanaのトランザクションサイズ制限（約1232バイト）に注意してください。大きなバッチの場合は、複数のトランザクションを送信してください。

このSDKはReact/Next.jsで使用できますか？

はい。SDKはブラウザとNode.js環境の両方で動作します。Reactの場合は、@solana/wallet-adapter-reactのウォレットアダプターをUmiのウォレットアダプターアイデンティティと一緒に使用してください。

エラーの処理方法は？

SDK呼び出しをtry/catchブロックでラップします。SDKはプログラムエラーコードを含む型付きエラーをスローします：

try {
  await transfer(umi, { asset, newOwner }).sendAndConfirm(umi)
} catch (error) {
  console.error('転送失敗:', error.message)
}

完全なAPIドキュメントはどこで見つけられますか？

完全な関数シグネチャと型については、TypeDoc APIリファレンスを参照してください。

用語集

用語	定義
Umi	ウォレットとRPC管理を備えたSolanaアプリケーション構築のためのMetaplexフレームワーク
Asset	所有権、メタデータ、プラグインを持つNFTを表すCoreのオンチェーンアカウント
Collection	関連するAssetをグループ化し、コレクション全体のプラグインを適用できるCoreアカウント
Signer	トランザクションに署名できるキーペア（新しいアカウントの作成に必要）
Plugin	AssetまたはCollectionに動作を追加するモジュール式拡張機能
URI	名前、画像、属性を含むJSONファイルを指すオフチェーンメタデータURL
DAS	Digital Asset Standard - RPCプロバイダーからインデックス化されたNFTデータをクエリするためのAPI
Transaction Builder	送信前にトランザクションを構築する不変オブジェクト
Identity	Umiでトランザクション署名者として設定されたウォレット/キーペア
Commitment	Solanaの確認レベル（processed、confirmed、finalized）