本番デリバリー

MPL-Distro がオンチェーンに保存するのは Merkle ルートだけです。本番エアドロップは各割り当ての証明をオフチェーンに永続化し、受取人がそれを送信できる手段を用意します。

概要

本番デリバリーは MPL-Distro 配布を囲むオフチェーン作業です。クレームレコードを保存し、正しい請求者へ届け、期間終了時に余りを回収します。

• はじめに のフローまたは Metaplex CLI で配布を作成して資金投入します。
• クレーム開始前に、すべての割り当ての address、amount、nonce、proof を永続化します。
• 誰が署名すべきかに合わせて Permissionless、Recipient、または Permissioned を選びます。
• 期間終了後に 資金投入と回収 で未クレームトークンを回収します。

ジャンプ先: 前提条件 · 送信モード · レコードの永続化 · 証明の配信 · トークン回収

クイックスタート

本番の MPL-Distro エアドロップには、オンチェーンプログラムを囲む 5 つのデリバリー手順があります。

1. 完全な割り当てリストを構築し、prepareDistribution でルートを生成します。
2. 割り当てごとに 1 つのクレームレコードを永続化し、配布を作成して資金投入します。
3. ウォレットまたは NFT mint をキーにしたクレームページまたはルックアップ API から各レコードを提供します。
4. 保存済みの amount、nonce、証明で distribute または distributeToLegacyNft を送信します。
5. endTime の後、未クレームトークンと未使用のレシート家賃補助金を引き出します。

前提条件

本番デリバリーは、既存の SPL トークン mint と完成した割り当てリストから始まります。

• はじめに の配布（またはバックエンドで同じ作成と入金手順）
• クレームレコード用の耐久ストレージ（データベース、オブジェクトストア、またはダウンロード可能なファイル）
• 家賃、ネットワーク手数料、0.002 SOL プロトコル手数料用に資金のあるクレームトランザクション支払者
• 配布タイプ: ウォレット または レガシー NFT

割り当て量はトークン最小単位です。decimals が 6 の mint では、1.0 トークンは 1_000_000 です。

クレーム送信モードを選ぶ

allowedDistributor は有効な証明を誰が送信できるかを決めます。トークンの行き先は変わりません。

トークンは常にリーフの正規 associated token account に届きます（LegacyNft では現在の NFT 所有者の ATA）。Permissionless 送信は資金を支払者へ迂回できません。

配布権限者と permissioned distributor の鍵はブラウザアプリケーションの外に置いてください。

割り当てレコードを永続化する

各クレームには、そのリーフで prepareDistribution が使った同じアドレス、amount、nonce、証明が必要です。オンチェーンアカウントはルートからそれらの値を再構築できません。

完全なリストから始め、同じインデックスに証明を保存します。

[
  {
    "address": "8SoWVrwJ6vPa3rcdNBkhznR54yJ6iQqPSmgcXVGnwtEu",
    "amount": "10000000",
    "nonce": "0"
  },
  {
    "address": "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
    "amount": "5000000",
    "nonce": "0"
  }
]

1import { mplDistro, prepareDistribution } from '@metaplex-foundation/mpl-distro'
2import { publicKey } from '@metaplex-foundation/umi'
3import { createUmi } from '@metaplex-foundation/umi-bundle-defaults'
4
5const umi = createUmi(
6  process.env.RPC_URL ?? 'https://api.devnet.solana.com'
7).use(mplDistro())
8
9const allocations = [
10  { address: publicKey(process.env.RECIPIENT_1!), amount: 100_000n, nonce: 0n },
11  { address: publicKey(process.env.RECIPIENT_2!), amount: 250_000n, nonce: 0n },
12]
13
14const { root, proofs, treeHeight } = prepareDistribution(allocations)
15
16const claimRecords = allocations.map((allocation, index) => ({
17  address: allocation.address,
18  amount: allocation.amount.toString(),
19  nonce: (allocation.nonce ?? 0n).toString(),
20  proof: proofs[index],
21}))
22
23// Persist claimRecords with the distribution PDA after createDistribution.
24console.log(root, treeHeight, claimRecords.length)
25
26// One durable record per allocation: address, amount, nonce, and proof.

createDistribution の後、各レコードに配布 PDA を保存します。クレームトランザクションにはそのアドレスと mint、amount、nonce、proof が必要です。

Merkle 証明を届ける

アプリケーションは保存済みレコードを 1 件ルックアップし、distribute または distributeToLegacyNft に渡します。MPL-Distro は受取人をインデックスしません。

よくある配信の形:

1. クレームページ。 ユーザーがウォレットを接続し、ネットワーク手数料を払い、保存済み証明を送信します。
2. ルックアップ API。 サービスが address → { amount, nonce, proof, distribution } をフロントエンドまたはリレイヤーへ提供します。
3. スポンサー付きクレーム。 受取人（または適格性チェック）がクレームを起動します。リレイヤーが SOL を払い、ユーザーは資金のあるウォレットを必要としません。トークンはリーフ ATA へ行きます。

スポンサー付きクレームは、バックエンドループで全割り当てを送ることの代替ではありません。各 Distro クレームは 0.002 SOL プロトコル手数料を払います。すべての受取人がクレーム手順なしですぐにトークンを受け取るなら、直接の SPL トークン 送金を使います。

一部の割り当てが未クレームになる場合、公開 Merkle コミットメントと期間が必要な場合、または実際にクレームした人にだけリレイヤーが払う場合に Distro を使います。

LegacyNft では NFT mint でルックアップします。クレーム時に現在の所有者を解決してください。スナップショット所有者をリーフに固定するのは、ウォレット配布 を意図した場合だけです。

オンチェーンルートから証明を再構築しないでください。別のハッシュ、バイト順、リーフ集合で生成した証明は InvalidClaimProof で失敗します。

クレーム期間を開く

クレームはクラスタ時刻が包含的な startTime–endTime の間にあり、ボールトに十分なトークンがあるときだけ成功します。

全受取人にリストを開く前に、はじめに のフローで作成、入金、最初のテストクレームを送信してください。確認すること:

• 永続化ファイルのサンプル証明が distribute と一致する。
• プロトコル手数料の支払者に 0.002 SOL とレシート家賃用の SOL がある、または レシート補助金 が入っている。
• 権限者の鍵がクレームフロントエンドに露出していない。

クレームを監視する

成功したクレームは永続的なクレームレシート PDA を作成します。そのアカウントを取得するか、配布上の claimCount / claimAmount を比較して、どの割り当てが完了したかを把握します。

その exact な (distribution, recipient, amount, nonce) タプルでは AlreadyClaimed を成功として扱います。LegacyNft mint の所有権移転はレシートをリセットしません。

未クレームトークンを回収する

配布権限者は、配布が非アクティブなとき（startTime の前または endTime の後）だけ、余りのトークンと未使用補助金 SOL を引き出します。

withdraw と withdrawSubsidy は 資金投入と回収 を参照してください。最後のクレームが回収トランザクションと競合しないよう、終了タイムスタンプの周りに運用マージンを残します。

本番デリバリーチェックリスト

ユーザーが依存する前に、オフチェーンファイルをオンチェーンルートに対して検証します。

• amount 値の合計がボールト入金でカバーされている。
• 永続化した各証明が、同じリスト・同じ順の prepareDistribution 出力である。
• 漏洩した証明だけでは送信できないようにするなら Recipient モードを使う。
• クレームフロントエンドは配布権限者を持たない。
• 未クレームトークンには endTime 後に withdraw を呼べる所有者がいる。

注意事項

MPL-Distro は割り当てデータベース、通知チャネル、クレーム UI の代わりにはなりません。

• totalClaimants はメタデータであり、成功する証明数の上限ではありません。
• クレームレシートはクローズされないため、レシート家賃は割り当てられたままです。
• 大きなリストは制御された Node.js プロセスで構築します。prepareDistribution は 1,000 リーフで実装を切り替えます。

FAQ

MPL-Distro はクレーム用ウェブサイトをホストしますか？

いいえ。プログラムが保存するのは Merkle ルートだけです。アプリケーションが証明を永続化し、クレームページまたは API を提供する必要があります。

メールや Discord ハンドルを Merkle リーフにできますか？

いいえ。リーフはウォレット公開鍵またはレガシー NFT mint です。オフチェーンチャネルで通知できますが、それらはオンチェーン identity ではありません。

Merkle 証明を公開しても安全ですか？

Permissionless モードでは有効な証明を持つ誰でもクレームを送信できます。トークンはリーフアドレスへ行きます。証明へのアクセスだけでは送信を許可したくない場合は Recipient モードを使います。

バックエンドがすべての Merkle 証明を自分で送信すべきですか？

いいえ。バックエンドからすべての証明を送信するのは、各 Distro クレームがプロトコル手数料を払うため、通常は SPL トークン 送金より高くなります。SOL のないユーザーがクレームできるようにリレイヤーを使うか、一部の割り当てが未クレームになり Merkle 期間が必要な場合に Distro を使います。

未クレームトークンはいつ回収できますか？

権限者は開始タイムスタンプの前、または終了タイムスタンプの後にトークンを引き出せます。startTime <= clusterTime <= endTime の間は出金が拒否されます。