Core Candy MachineガードのRoute命令

Summary

Route命令は、Core Candy Guardプログラムの特別な命令で、実行を特定のガードに委譲し、標準のミントフロー外でガードがカスタムオンチェーンロジックを実行できるようにします。

• 選択されたガードにリクエストをルーティングし、ミントトランザクションとは独立して独自のプログラムロジックを実行できます。
• Allow ListガードのMerkle Proof検証などのプレバリデーションワークフローを可能にします。
• 単一のガードのRouteハンドラー内で複数の機能を区別するためのPath属性をサポートします。
• Core Candy Machineがガードグループを使用している場合、グループラベルが必要です。

前のページで見たように、ガードはCandy Machineのミントプロセスをカスタマイズする強力な方法です。しかし、ガードが独自のカスタム命令を提供できることをご存知でしたか？

Route命令

Route命令は、Core Candy Guardプログラムの専用エントリポイントで、特定のガードにリクエストを転送し、そのガードがミントトランザクションとは独立してカスタムオンチェーンロジックを実行できるようにします。

この命令により、Core Candy Machineから特定のガードを選択し、そのガードに固有のカスタム命令を実行できます。選択されたガードにリクエストをルーティングするため、「Route」命令と呼んでいます。

この機能により、ガードは独自のプログラムロジックを含めることができるため、さらに強力になります。ガードは以下を可能にします：

• 重い操作のために検証プロセスをミントプロセスから分離する。
• カスタムプログラムのデプロイが必要な機能を提供する。

Route命令を呼び出すには、どのガードに命令をルーティングするかを指定し、そのガードが期待するRoute設定を提供する必要があります。

Candy Guardプログラムで登録されたガードごとに一つの「Route」命令しかあり得ないため、同じガードが提供する複数の機能を区別するために、Route設定でPath属性を提供することが一般的です。

例えば、ミントが終了した後にのみ解除できるFrozen NFTのサポートを追加するガードは、Route命令を使用してトレジャリーエスクローアカウントを初期化し、適切な条件の下で誰でもミントされたNFTを解除できるようにすることができます。前者には「init」、後者には「thaw」と等しいPath属性を使用してこれら2つの機能を区別できます。

Route命令をサポートする各ガードのRoute命令とその基盤となるパスの詳細な説明は、それぞれのページで見つけることができます。

Allow ListガードのRoute例

Allow Listガードは、Route命令を使用する最も一般的なガードで、ミントを許可する前にミントするウォレットが事前設定されたウォレットリストの一部であることを検証します。

Merkle Treeを使用してこれを行います。つまり、許可されたウォレットの全リストのハッシュを作成し、そのハッシュ（Merkle Rootとして知られる）をガード設定に保存する必要があります。ウォレットが許可リストに載っていることを証明するには、プログラムがMerkle Rootを計算してガードの設定と一致することを確認できるハッシュのリスト（Merkle Proofとして知られる）を提供する必要があります。

したがって、Allow Listガードは指定されたウォレットのMerkle Proofを検証するためにRoute命令を使用し、成功した場合、ミント命令の検証証明として機能するブロックチェーン上に小さなPDAアカウントを作成します。

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

import {
  create,
  route,
  getMerkleProof,
  getMerkleRoot,
} from '@metaplex-foundation/mpl-core-candy-machine'

// 許可リストを準備します。
// リストの最初のウォレットがMetaplexアイデンティティであると仮定しましょう。
const allowList = [
  'GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS',
  '2vjCrmEFiN9CLLhiqy8u1JPh48av8Zpzp3kNkdTtirYG',
  'AT8nPwujHAD14cLojTcB1qdBzA1VXnT6LVGuUd6Y73Cy',
]
const merkleRoot = getMerkleRoot(allowList)

// Allow Listガード付きCandy Machineを作成します。
await create(umi, {
  // ...
  guards: {
    allowList: some({ merkleRoot }),
  },
}).sendAndConfirm(umi)

// 今ミントしようとすると、失敗します
// Merkle Proofを検証していないためです。

// Route命令を使用してMerkle Proofを検証します。
await route(umi, {
  candyMachine: candyMachine.publicKey,
  guard: 'allowList',
  routeArgs: {
    path: 'proof',
    merkleRoot,
    merkleProof: getMerkleProof(
      allowList,
      'GjwcWFQYzemBtpUoN5fMAP2FZviTtMRWCmrppGuTthJS'
    ),
  },
}).sendAndConfirm(umi)

// 今ミントしようとすると、成功します。

ガードグループでのRoute命令

Route命令は、Core Candy Machineがガードグループを使用している場合にグループラベルを必要とします。同じガードタイプが複数のグループに表示される可能性があり、プログラムはどのインスタンスをターゲットにするかを知る必要があるためです。

例えば、一つのグループに厳選されたVIPウォレットのAllow Listがあり、別のグループに抽選の当選者のAllow Listがあるとします。そうすると、Allow ListガードのMerkle Proofを検証したいと言うだけでは不十分で、どのグループに対してその検証を実行すべきかも知る必要があります。

import {
  create,
  route,
  getMerkleProof,
  getMerkleRoot,
} from "@metaplex-foundation/mpl-core-candy-machine";
import { base58PublicKey, some } from "@metaplex-foundation/umi";

// 許可リストを準備します。
const allowListA = [...];
const allowListB = [...];

// 2つのAllow Listガード付きCandy Machineを作成します。
await create(umi, {
  // ...
  groups: [
    {
      label: "listA",
      guards: {
        allowList: some({ merkleRoot: getMerkleRoot(allowListA) }),
      },
    },
    {
      label: "listB",
      guards: {
        allowList: some({ merkleRoot: getMerkleRoot(allowListB) }),
      },
    },
  ],
}).sendAndConfirm(umi);

// 選択するグループを指定してMerkle Proofを検証します。
await route(umi, {
  candyMachine: candyMachine.publicKey,
  guard: 'allowList',
  group: some('listA'), // <- 「allowListA」を使用して検証しています。
  routeArgs: {
    path: 'proof',
    merkleRoot: getMerkleRoot(allowListA),
    merkleProof: getMerkleProof(
      allowListA,
      base58PublicKey(umi.identity),
    ),
  },
}).sendAndConfirm(umi);

Notes

• すべてのガードがRoute命令をサポートしているわけではありません。プレバリデーションを必要とするか、追加のオンチェーン機能を公開するガードのみがRouteハンドラーを実装しています。
• Route命令をサポートしていないガードに対してRoute命令を呼び出すと、トランザクションが失敗します。
• ガードグループを使用している場合、プログラムがどのガードインスタンスがRoute呼び出しを処理するかを識別するために、groupラベルが必要です。
• 各ガードはRoute命令を1つしか持てませんが、Path属性により単一のRouteハンドラーが複数の異なる機能を公開できます。
• Route命令はミントトランザクションとは別です。Route命令が作成するオンチェーン状態（Allow List PDAなど）は永続化され、ミント中にチェックされます。

FAQ

どのガードがRoute命令をサポートしていますか？

すべてのガードがRoute命令をサポートしているわけではありません。プレバリデーションまたはカスタムオンチェーンロジックを必要とするガードのみがRouteハンドラーを公開します。Allow Listガードが最も一般的な例で、ミント前にMerkle Proofを検証するためにRouteを使用します。Route対応の詳細については、各ガードの専用ドキュメントページを確認してください。

Route命令をサポートしていないガードに対してRoute命令を呼び出すとどうなりますか？

トランザクションは失敗します。Core Candy Guardプログラムは、Routeハンドラーを実装していないガードに向けられたRoute呼び出しを拒否します。呼び出す前に、ガードがRoute命令をサポートしていることを常に確認してください。

Allow Listガードがミント中に検証するのではなく、別のRoute命令を使用する理由は何ですか？

大きな許可リストは、ミント命令のデータと組み合わせるとトランザクションサイズ制限を超える可能性のあるMerkle Proofを生成します。プルーフ検証を専用のRouteトランザクションに分離することで、Allow ListガードはSolanaのトランザクションサイズ制約に達することなく、任意の大きさのリストをサポートできます。

Route命令を呼び出す際にグループラベルを指定する必要がありますか？

Core Candy Machineがガードグループを使用している場合のみです。同じガードタイプが複数のグループに表示される場合、プログラムはどのガードインスタンスがRoute呼び出しを処理するかを識別するためにグループラベルが必要です。グループなしの場合、グループパラメータは必要ありません。

Route設定のPath属性とは何ですか？

Path属性は、単一のガードのRoute命令が提供する複数の機能を区別します。例えば、Frozen NFTをサポートするガードは、エスクローアカウントを初期化するためにパス「init」を、ミントされたNFTを解凍するためにパス「thaw」を使用できます。各ガードは独自の有効なパスセットを定義します。

Glossary