Allowlistガード

概要

Allow Listガードは、ミントを行うウォレットが事前定義されたウォレットリストに対して検証を行います。ミントを行うウォレットがこのリストに含まれていない場合、ミントは失敗します。

このガードの設定に大きなウォレットリストを提供すると、ブロックチェーン上で多くのストレージが必要になり、それらをすべて挿入するために複数のトランザクションが必要になる可能性があります。そのため、Allow ListガードはMerkle Treeを使用して、ミントを行うウォレットが事前設定されたウォレットリストの一部であることを検証します。

これは、すべてのリーフが2つずつハッシュ化され、Merkle Rootとして知られる最終的なハッシュに到達するまで続くハッシュのバイナリツリーを作成することで機能します。これは、いずれかのリーフが変更された場合、最終的なMerkle Rootが破損することを意味します。

リーフがツリーの一部であることを検証するには、ツリーを上に向かって再計算し、Merkle Rootを再計算できるようにするすべての中間ハッシュのリストが必要です。この中間ハッシュのリストをMerkle Proofと呼びます。計算されたMerkle Rootが保存されているMerkle Rootと一致する場合、リーフがツリーの一部であり、したがって元のリストの一部であることを確認できます。

したがって、Allow Listガードの設定には、事前設定された許可ウォレットリストの真実のソースとして機能するMerkle Rootが必要です。ウォレットが許可リストに含まれていることを証明するには、プログラムがMerkle Rootを再計算し、ガードの設定と一致することを確認できる有効なMerkle Proofを提供する必要があります。

SDKには、特定のウォレットリストに対してMerkle RootとMerkle Proofを簡単に作成するためのヘルパーが用意されています。

ガード設定

Allow Listガードには以下の設定が含まれます:

• Merkle Root: 許可リストを表すMerkle TreeのRoot。

import {
  getMerkleProof,
  getMerkleRoot,
} from "@metaplex-foundation/mpl-core-candy-machine";

const allowList = [
  "Ur1CbWSGsXCdedknRbJsEk7urwAvu1uddmQv51nAnXB",
  "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
  "AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy",
];

const merkleRoot = getMerkleRoot(allowList);
const validMerkleProof = getMerkleProof(
  allowList,
  "Ur1CbWSGsXCdedknRbJsEk7urwAvu1uddmQv51nAnXB"
);
const invalidMerkleProof = getMerkleProof(allowList, "invalid-address");

import { getMerkleRoot } from "@metaplex-foundation/mpl-core-candy-machine";

const allowList = [
  "Ur1CbWSGsXCdedknRbJsEk7urwAvu1uddmQv51nAnXB",
  "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
  "AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy",
];

create(umi, {
  // ...
  guards: {
    allowList: some({ merkleRoot: getMerkleRoot(allowList) }),
  },
});

ミント設定

Allow Listガードには以下のミント設定が含まれます:

• Merkle Root: 許可リストを表すMerkle TreeのRoot。

ミントできるようになる前に、Merkle Proofを提供してミントを行うウォレットを検証する必要があります。詳細については、以下のMerkle Proofを検証するを参照してください。

また、SDKを使用せずに手動で命令を構築する場合は、ミント命令の残りのアカウントにAllow List Proof PDAを追加する必要があることに注意してください。詳細については、Candy Guardのプログラムドキュメントを参照してください。

import { getMerkleRoot } from "@metaplex-foundation/mpl-core-candy-machine";

const allowList = [
  "Ur1CbWSGsXCdedknRbJsEk7urwAvu1uddmQv51nAnXB",
  "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
  "AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy",
];

mintV1(umi, {
  // ...
  mintArgs: {
    allowList: some({ merkleRoot: getMerkleRoot(allowList) }),
  },
});

ルート命令

Allow Listルート命令は以下の機能をサポートしています。

Merkle Proofを検証する

パス: proof

Merkle Proofをミント命令に直接渡す代わりに、ミントを行うウォレットは、Allow Listガードのルート命令を使用して事前検証を実行する必要があります。

このルート命令は、提供されたMerkle ProofからMerkle Rootを計算し、有効な場合は、ミントを行うウォレットが許可リストの一部であることを証明する新しいPDAアカウントを作成します。したがって、ミント時に、Allow Listガードは、このPDAアカウントの存在を確認するだけで、ウォレットへのミントを承認または拒否できます。

では、なぜミント命令内で直接Merkle Proofを検証できないのでしょうか?それは単に、大きな許可リストの場合、Merkle Proofが非常に長くなる可能性があるためです。特定のサイズ以降、既にかなりの数の命令を含むミントトランザクション内に含めることが不可能になります。検証プロセスをミントプロセスから分離することで、許可リストを必要なだけ大きくすることができます。

このルート命令のこのパスは、以下の引数を受け入れます:

• Path = proof: ルート命令で実行するパスを選択します。
• Merkle Root: 許可リストを表すMerkle TreeのRoot。
• Merkle Proof: Merkle Rootを計算し、ガードの設定に保存されているMerkle Rootと一致することを検証するために使用する必要がある中間ハッシュのリスト。
• Minter (オプション): 支払者と異なる場合のミンターアカウント(署名者として)。提供された場合、このアカウントは、プルーフが有効であるために許可リストの一部である必要があります。

import {
  getMerkleProof,
  getMerkleRoot,
} from "@metaplex-foundation/mpl-core-candy-machine";
import { publicKey } from "@metaplex-foundation/umi";

const allowList = [
  "Ur1CbWSGsXCdedknRbJsEk7urwAvu1uddmQv51nAnXB",
  "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
  "AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy",
];

await route(umi, {
  // ...
  guard: "allowList",
  routeArgs: {
    path: "proof",
    merkleRoot: getMerkleRoot(allowList),
    merkleProof: getMerkleProof(allowList, publicKey(umi.identity)),
  },
}).sendAndConfirm(umi);

Allowlistアカウント

Allowlistガードを使用すると、ルート命令の実行後にAllowListProofアカウントが作成されます。フェッチできる場合、ユーザーは許可リストに含まれており、ルートは既に実行されています。検証目的で次のようにフェッチできます:

import {
  safeFetchAllowListProofFromSeeds,
  getMerkleRoot,
} from "@metaplex-foundation/mpl-core-candy-machine";

const allowlist = [
  "Tes1zkZkXhgTaMFqVgbgvMsVkRJpq4Y6g54SbDBeKVV",
  "GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS",
  "AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy"
];

const allowListProof = await safeFetchAllowListProofFromSeeds(umi, {
  candyMachine: candyMachine.publicKey,
  // または candyMachine: publicKey("Address") でCMアドレスを指定
  candyGuard: candyMachine.mintAuthority,
  // または candyGuard: publicKey("Address") でcandyGuardアドレスを指定
  merkleRoot: getMerkleRoot(allowlist),
  user: umi.identity.publicKey,
  // または「ミント」アカウントのpublicKey
});