Allowlist Guard

概要

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

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

これは、すべての葉が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-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-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のプログラムドキュメントAtionを参照してください。

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

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

mintV2(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 (オプション): 支払者と同じでない場合のSignerとしてのミンターアカウント。提供された場合、このアカウントは証明が有効になるために許可リストの一部である必要があります。

import {
  getMerkleProof,
  getMerkleRoot,
} from "@metaplex-foundation/mpl-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);