Skip to main content

Gatekeeper

info

A newer version of this page is available in the Developer Hub. Click here to read it.

Overview​

The Gatekeeper guard checks whether the minting wallet has a valid Gateway Token — also known as a Civic Pass — from a specified Gatekeeper Network.

In most cases, this token will be obtained after completing a Captcha challenge but any Gatekeeper Network may be used.

There isn’t much to set up on the Candy Machine side but, depending on the selected Gatekeeper Network, you may need to ask the minting wallet to perform so pre-validation checks to grant them the required Gateway Token.

Here are some additional recommended materials you may find helpful when setting up a Gatekeep Network.

CandyMachinesV3-GuardsGatekeeper.png

Guard Settings​

The Gatekeeper guard contains the following settings:

  • Gatekeeper Network: The public key of the Gatekeeper Network that will be used to check the validity of the minting wallet. For instance, you may use the "Civic Captcha Pass" Network — which ensures the minting wallet has passed a captcha — by using the following address: ignREusXmGrscGNUesoU9mxfds9AiYTezUKex2PsZV6.
  • Expire On Use: Whether we should mark the Gateway Token of the minting wallet as expired after the NFT has been minting.
    • When set to true, they will need to go through the Gatekeeper Network again to mint another NFT.
    • When set to false, they will be able to mint another NFT until the Gateway Token expires naturally.

JavaScript — Umi library (recommended)

Here’s how we can set up a Candy Machine using the Gatekeeper guard.

create(umi, {
  // ...
  guards: {
    gatekeeper: some({
      network: publicKey("ignREusXmGrscGNUesoU9mxfds9AiYTezUKex2PsZV6"),
      expireOnUse: true,
    }),
  },
});

API References: create, Gatekeeper

JavaScript — SDK

Here’s how we can set up a Candy Machine using the Gatekeeper guard via the JS SDK.

import { PublicKey } from "@solana/web3.js";

const CAPTCHA_NETWORK = new PublicKey(
  "ignREusXmGrscGNUesoU9mxfds9AiYTezUKex2PsZV6"
);

const { candyMachine } = await metaplex.candyMachines().create({
  // ...
  guards: {
    gatekeeper: {
      network: CAPTCHA_NETWORK,
      expireOnUse: true,
    },
  },
});

API References: Operation, Input, Output, Transaction Builder, Guard Settings.

Mint Settings​

The Gatekeeper guard accepts the following mint settings:

  • Gatekeeper Network: The public key of the Gatekeeper Network that will be used to check the validity of the minting wallet.
  • Expire On Use: Whether we should mark the Gateway Token of the minting wallet as expired after the NFT has been minting.
  • Token Account (optional): As a little disclaimer, you should very rarely need to provide this setting but it’s here if you need to. This refers to the Gateway Token PDA derived from the payer and the Gatekeeper Network which is used to verify the payer's eligibility to mint. This PDA address can be inferred by our SDKs which is why you do not need to provide it. However, some Gatekeeper Networks may issue multiple Gateway Tokens to the same wallet. To differentiate their PDA addresses, it uses a Seeds array which defaults to [0, 0, 0, 0, 0, 0, 0, 0].

Note that, if you’re planning on constructing instructions without the help of our SDKs, you will need to provide these Mint Settings and more as a combination of instruction arguments and remaining accounts. See the Candy Guard’s program documentation for more details.

JavaScript — Umi library (recommended)

You may pass the Mint Settings of the Gatekeeper guard using the mintArgs argument like so.

mintV2(umi, {
  // ...
  mintArgs: {
    gatekeeper: some({
      network: publicKey("ignREusXmGrscGNUesoU9mxfds9AiYTezUKex2PsZV6"),
      expireOnUse: true,
    }),
  },
});

API References: mintV2, GatekeeperMintArgs

JavaScript — SDK

In the vast majority of cases, we should not need to provide any Mint Settings to the Gatekeeper guard as the JS SDK will default to provide the right addresses and PDAs to the mint instruction.

const { nft } = await metaplex.candyMachines().mint({
  // ...
  guards: {
    // No mint settings required...
  },
});

However, in some rare use cases, we may need to explicitly provide the PDA address of the Gateway Token. Thus, here’s an example providing a Gateway Token that uses non-default seeds.

import { Pda } from "@metaplex-foundation/js";

const gatewayProgram = metaplex.programs().getGateway(programs);
const gatewayToken = Pda.find(gatewayProgram.address, [
  payer.publicKey.toBuffer(),
  Buffer.from("gateway"),
  Buffer.from([0, 0, 0, 0, 0, 0, 0, 1]), // <- Custom seeds array.
  gatewayNetwork.toBuffer(),
]);

const { nft } = await metaplex.candyMachines().mint({
  // ...
  guards: {
    gatekeeper: {
      tokenAccount: gatewayToken,
    },
  },
});

API References: Operation, Input, Output, Transaction Builder, Mint Settings.

Route Instruction​

The Gatekeeper guard does not support the route instruction.