허용 목록 가드

개요

허용 목록 가드는 미리 정의된 지갑 목록에 대해 민팅 지갑을 검증합니다. 민팅 지갑이 이 목록에 포함되지 않으면 민팅이 실패합니다.

이 가드의 설정에 큰 지갑 목록을 제공하면 블록체인에 많은 저장 공간이 필요하고 모두 삽입하려면 하나 이상의 트랜잭션이 필요할 수 있습니다. 따라서 허용 목록 가드는 머클 트리를 사용하여 민팅 지갑이 사전 구성된 지갑 목록에 포함되어 있는지 확인합니다.

이는 모든 잎이 머클 루트라고 알려진 최종 해시에 도달할 때까지 두 개씩 자신을 해시하는 해시의 이진 트리를 생성함으로써 작동합니다. 즉, 어떤 잎이라도 변경되면 최종 머클 루트가 손상됩니다.

잎이 트리의 일부인지 확인하려면 트리를 올라가서 머클 루트를 다시 계산할 수 있게 해주는 모든 중간 해시의 목록만 있으면 됩니다. 이 중간 해시 목록을 머클 증명이라고 합니다. 계산된 머클 루트가 저장된 머클 루트와 일치하면, 잎이 트리의 일부이므로 원본 목록의 일부라고 확신할 수 있습니다.

따라서 허용 목록 가드의 설정에는 허용된 지갑의 사전 구성된 목록에 대한 신뢰할 수 있는 소스 역할을 하는 머클 루트가 필요합니다. 지갑이 허용 목록에 있다는 것을 증명하려면 프로그램이 머클 루트를 다시 계산하고 가드 설정과 일치하는지 확인할 수 있게 해주는 유효한 머클 증명을 제공해야 합니다.

우리의 SDK는 주어진 지갑 목록에 대해 머클 루트와 머클 증명을 쉽게 생성할 수 있는 헬퍼를 제공합니다.

가드 설정

허용 목록 가드에는 다음 설정이 포함됩니다:

• Merkle 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) }),
  },
});

민트 설정

허용 목록 가드에는 다음 민트 설정이 포함됩니다:

• Merkle Root: 허용 목록을 나타내는 머클 트리의 루트입니다.

민팅하기 전에 머클 증명을 제공하여 민팅 지갑을 검증해야 합니다. 자세한 내용은 아래의 머클 증명 검증을 참조하세요.

또한 SDK의 도움 없이 지시사항을 구성할 계획이라면 민트 지시사항의 나머지 계정에 허용 목록 증명 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) }),
  },
});

라우트 지시사항

허용 목록 라우트 지시사항은 다음 기능을 지원합니다.

머클 증명 검증

Path: proof

머클 증명을 민트 지시사항에 직접 전달하는 대신, 민팅 지갑은 허용 목록 가드의 라우트 지시사항을 사용하여 사전 검증을 수행해야 합니다.

이 라우트 지시사항은 제공된 머클 증명에서 머클 루트를 계산하고, 유효하면 민팅 지갑이 허용 목록에 포함되어 있다는 증명 역할을 하는 새로운 PDA 계정을 생성합니다. 따라서 민팅할 때 허용 목록 가드는 이 PDA 계정의 존재만 확인하면 지갑에 민팅을 승인하거나 거부할 수 있습니다.

그렇다면 민트 지시사항 내에서 직접 머클 증명을 검증할 수 없는 이유는 무엇일까요? 큰 허용 목록의 경우 머클 증명이 꽤 길어질 수 있기 때문입니다. 특정 크기가 넘어가면 이미 상당한 양의 지시사항이 포함된 민트 트랜잭션에 이를 포함하는 것이 불가능해집니다. 검증 프로세스를 민팅 프로세스에서 분리함으로써 허용 목록을 필요한 만큼 크게 만들 수 있습니다.

라우트 지시사항의 이 경로는 다음 인수를 받습니다:

• Path = proof: 라우트 지시사항에서 실행할 경로를 선택합니다.
• Merkle Root: 허용 목록을 나타내는 머클 트리의 루트입니다.
• Merkle Proof: 머클 루트를 계산하고 가드 설정에 저장된 머클 루트와 일치하는지 확인하는 데 사용해야 하는 중간 해시 목록입니다.
• 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 가드를 사용할 때 라우트 지시사항이 실행된 후 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
});