Allow List 가드

개요

Allow List 가드는 민팅 지갑을 미리 정의된 지갑 목록과 대조하여 검증합니다. 민팅 지갑이 이 목록에 포함되지 않으면 민팅이 실패합니다.

이 가드의 설정에 큰 지갑 목록을 제공하는 것은 블록체인에 많은 저장 공간이 필요하고 모든 것을 삽입하는 데 하나 이상의 트랜잭션이 필요할 것입니다. 따라서 Allow List 가드는 Merkle Trees를 사용하여 민팅 지갑이 미리 구성된 지갑 목록의 일부임을 확인합니다.

이는 모든 잎이 두 개씩 자기 자신을 해시하여 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의 프로그램 문서를 참조하세요.

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

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

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

Route 명령어

Allow List route 명령어는 다음 기능을 지원합니다.

Merkle Proof 검증

Path: proof

민팅 명령어에 직접 Merkle Proof를 전달하는 대신, 민팅 지갑은 Allow List 가드의 route 명령어를 사용하여 사전 검증을 수행해야 합니다.

이 route 명령어는 제공된 Merkle Proof로부터 Merkle Root를 계산하고, 유효한 경우 민팅 지갑이 허용 목록의 일부임을 증명하는 새로운 PDA 계정을 생성합니다. 따라서 민팅할 때 Allow List 가드는 지갑에 대한 민팅을 승인하거나 거부하기 위해 이 PDA 계정의 존재만 확인하면 됩니다.

그렇다면 왜 민팅 명령어 내에서 직접 Merkle Proof를 검증할 수 없을까요? 단순히 큰 허용 목록의 경우 Merkle Proof가 상당히 길어질 수 있기 때문입니다. 특정 크기 이후에는 이미 상당한 양의 명령어를 포함하는 민팅 트랜잭션에 포함하는 것이 불가능해집니다. 검증 프로세스를 민팅 프로세스에서 분리함으로써 허용 목록을 필요한 만큼 크게 만들 수 있게 됩니다.

route 명령어의 이 경로는 다음 인수를 받습니다:

• Path = proof: route 명령어에서 실행할 경로를 선택합니다.
• Merkle Root: 허용 목록을 나타내는 Merkle Tree의 Root입니다.
• Merkle Proof: Merkle Root를 계산하고 가드 설정에 저장된 Merkle Root와 일치하는지 확인하는 데 사용되어야 하는 중간 해시 목록입니다.
• Minter (선택사항): 지불자와 동일하지 않은 경우 서명자로서의 민터 계정입니다. 제공될 때, 이 계정은 증명이 유효하려면 허용 목록의 일부여야 합니다.

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);