AppDataプラグイン

AppDataプラグインは、Core Assetsに安全でパーティション化されたデータストレージを提供します。サードパーティアプリケーションは、Data Authorityによって制御される排他的な書き込みアクセスで任意のデータ（JSON、MsgPack、またはbinary）を保存および読み取ることができます。

概要

AppDataプラグインは、制御された書き込みアクセスでAssetsに任意のデータを保存します。Data Authorityのみがプラグインのデータセクションに書き込むことができ、安全なサードパーティ統合を可能にします。

• JSON、MsgPack、またはBinaryデータを保存
• Data Authorityが排他的な書き込み権限を持つ
• DASによって自動的にインデックス（JSON/MsgPack）
• コレクション全体の書き込み用LinkedAppDataバリアント

対象外

Oracle検証（Oracleプラグインを参照）、オンチェーン属性（Attributesプラグインを参照）、およびオフチェーンメタデータストレージ。

クイックスタート

ジャンプ先: Assetに追加 · データの書き込み · データの読み取り

1. Data Authorityアドレスを持つAppDataプラグインを追加
2. スキーマを選択：JSON、MsgPack、またはBinary
3. writeData()を使用してデータを書き込み（Data Authorityとして署名が必要）
4. DASまたは直接アカウントフェッチでデータを読み取り

AppDataプラグインとは？

AppData外部プラグインは、dataAuthorityが書き込むことができる任意のデータを保存および含みます。これはExternalRegistryRecordに保存される全体的なプラグインauthorityとは異なり、authority を更新/取り消したり、プラグインの他のメタデータを変更したりすることはできないことに注意してください。 AppDataは、特定のauthorityのみが変更および書き込むことができるAssetのパーティションデータ領域のようなものと考えてください。 これは、サードパーティのサイト/アプリが製品/アプリ内で特定の機能を実行するために必要なデータを保存するのに役立ちます。

対応

LinkedAppDataプラグインとは？

LinkedAppDataプラグインはCollections用に構築されています。コレクションに単一のプラグインアダプターを追加することで、コレクション内の任意のAssetに書き込むことができます。

引数

dataAuthority

const dataAuthority = {
  type: 'Address',
  address: publicKey('11111111111111111111111111111111'),
}

schema

スキーマはAppDataプラグイン内に保存されるデータのタイプを決定します。すべてのスキーマはDASによってインデックスされます。

import { ExternalPluginAdapterSchema } from '@metaplex-foundation/mpl-core'
// Binary、Json、またはMsgPackから選択
const schema = ExternalPluginAdapterSchema.Json

AssetへのAppDataプラグインの追加

import { publicKey } from '@metaplex-foundation/umi'
import { addPlugin, ExternalPluginAdapterSchema } from '@metaplex-foundation/mpl-core'
const assetSigner = generateSigner(umi);
const dataAuthority = publicKey('11111111111111111111111111111111')
await create(umi, {
  asset: asset.publicKey,
  name: "My Asset",
  uri: "https://example.com/my-assets.json"
  plugins: [
        {
            type: 'AppData',
            dataAuthority,
            schema: ExternalPluginAdapterSchema.Json,
        },
    ],
}).sendAndConfirm(umi)
// または、既存のAssetにプラグインを追加することもできます
await addPlugin(umi, {
  asset,
  plugin: {
        type: 'AppData',
        dataAuthority,
        schema: ExternalPluginAdapterSchema.Json,
    },
})

AppDataプラグインへのデータの書き込み

dataAuthorityアドレスのみがAppDataプラグインにデータを書き込むことができます。 AppDataプラグインにデータを書き込むには、以下の引数を取るwriteData()ヘルパーを使用します。

JSONのシリアライズ

const json = {
  timeStamp: Date.now(),
  message: 'Hello, World!',
}
const data = new TextEncoder().encode(JSON.stringify(json))

MsgPackのシリアライズ

// この実装はシリアライゼーションに`msgpack-lite`を使用します
const json = {
  timeStamp: Date.now(),
  message: 'Hello, World!',
}
const data = msgpack.encode(json)

Binaryのシリアライズ

Binaryは任意のデータを保存できるため、データのシリアライズとデシリアライズの方法を決定するのはあなた次第です。

// 以下の例は、`true`または`false`と見なされるバイトを作成するだけです。
const data = new Uint8Array([1, 0, 0, 1, 0])

データの書き込み

await writeData(umi, {
  key: {
    type: 'AppData',
    dataAuthority,
  },
  authority: dataAuthoritySigner,
  data: data,
  asset: asset.publicKey,
}).sendAndConfirm(umi)

AppDataプラグインからのデータの読み取り

データは、アカウントデータをプルするオンチェーンプログラムと外部ソースの両方で読み取ることができます。

生データのフェッチ

AppDataプラグインに保存されているデータをデシリアライズする最初のステップは、生データをフェッチし、シリアライゼーション前にデータが保存される形式を指示するスキーマフィールドを確認することです。

const assetId = publicKey('11111111111111111111111111111111')
const dataAuthority = publicKey('33333333333333333333333333333333')
const asset = await fetchAsset(umi, assetId)
let appDataPlugin = asset.appDatas?.filter(
  (appData) => (appData.authority.address = dataAuthority)
)
let data
let schema
// 指定されたauthorityを持つ`AppData`プラグインが存在するか確認
if (appDataPlugin && appDataPlugin.length > 0) {
  // プラグインデータを`data`に保存
  data = appDataPlugin[0].data
  // プラグインスキーマを`schema`に保存
  schema = appDataPlugin[0].schema
}

デシリアライゼーション

データを取得したら、AppDataプラグインにデータを書き込むために選択したスキーマに応じてデータをデシリアライズする必要があります。

JSONスキーマのデシリアライズ

// JS SDKにより、MsgPackスキーマのデシリアライゼーションは自動で行われ、
// デシリアライズされたデータは上記の生データの場所でアクセスできます。

MsgPackスキーマのデシリアライズ

// JS SDKにより、MsgPackスキーマのデシリアライゼーションは自動で行われ、
// デシリアライズされたデータは上記の生データの場所でアクセスできます。

Binaryスキーマのデシリアライズ

Binaryスキーマは任意のデータであるため、デシリアライゼーションは使用したシリアライゼーションに依存します。

// バイナリデータは任意であるため、アプリ/ウェブサイトが理解できる
// 使用可能な形式にデータを解析するための独自のデシリアライザを含める必要があります。

一般的なエラー

Authority mismatch

Data Authorityのみがデータを書き込めます。正しいキーペアで署名していることを確認してください。

Data too large

データがアカウントサイズの制限を超えています。データを圧縮するか、複数のプラグインに分割することを検討してください。

Invalid schema

データが宣言されたスキーマと一致しません。JSONが有効であるか、MsgPackが正しくエンコードされていることを確認してください。

注意事項

• Data Authorityはプラグインauthorityとは別
• DASインデックスにはJSONまたはMsgPackを選択
• カスタムシリアライゼーション形式にはBinaryスキーマ
• LinkedAppDataはCollection内の任意のAssetへの書き込みを許可

クイックリファレンス

スキーマ比較

AppData vs Attributesプラグイン

FAQ

AppDataとAttributesプラグインの違いは何ですか？

Attributesはupdate authorityによって制御されるキー値文字列を保存します。AppDataは別のData Authorityによって制御される任意のデータを保存するため、サードパーティアプリケーションに最適です。

1つのAssetに複数のAppDataプラグインを持てますか？

はい。各AppDataプラグインは異なるData Authorityを持つことができ、複数のサードパーティアプリが同じAssetにデータを保存できます。

既存のAppDataをどのように更新しますか？

新しいデータでwriteData()を呼び出します。これにより既存のデータが完全に置き換えられます—部分的な更新はありません。

AppDataはDASでインデックスされますか？

はい。JSONとMsgPackスキーマは自動的にデシリアライズされ、インデックスされます。Binaryはbase64として保存されます。

LinkedAppDataとは何ですか？

LinkedAppDataはCollectionに追加され、各Assetに個別にAppDataを追加することなく、Data AuthorityがそのCollection内の任意のAssetに書き込むことができます。

用語集

関連ページ

• 外部プラグイン概要 - 外部プラグインの理解
• Oracleプラグイン - データストレージではなく検証
• Attributesプラグイン - 組み込みのキー値ストレージ
• オンチェーンチケッティングガイド - AppDataの例