Paper offers flexible solutions that can support any kind of on-chain or off-chain allowlist.

If you are checking for whether a wallet address is on an allowlist within your smart contract, then you have an on-chain allowlist. If you are trying to implement an allowlist using a user's email or tied to your off-chain authentication system, then you're looking for an off-chain allowlist.

On-chain allowlists

Regardless of how you check against your allowlist in your smart contract (merkle roots, signatures, simple lists, etc.), we are able to support your implementation as long as you provide the following setup:

1. Provide a method for Paper to check the eligibility of a recipient wallet address
At key points in the checkout flow, Paper will call an eligibilityMethod function in your smart contract with a desired recipient wallet address passed in to ensure the connected wallet at checkout is on the allowlist.

You must pass this eligibilityMethod when using our APIs to generate a checkout or SDK intent. Please see the eligibilityMethod page for a sample skeleton of an eligibilityMethod implementation in Solidity.

2. Ensure Paper can mint on behalf of an allowlisted wallet
Behind the scenes, Paper will use our wallets to mint on behalf of the recipient wallet address. This means that you'll need to make sure that any checks against your allowlist in your mint method is made on a recipient wallet address that is passed in as an argument (instead of the msg.sender).

For example, you should have a mint method like this:
function mintTo(address _userWallet, uint256 _quantity) public payable
where the mintTo method checks against your allowlist using the _userWallet address passed in and mints to the _userWallet address instead of the msg.sender. This is good.

As opposed to something like this:
function mint(uint256 _quantity) public payable
where the mint method checks against your allowlist using the msg.sender and mints to the msg.sender address. This is not good.

Once you have your mint method set up, you can pass along the method signature and arguments using the mintMethod parameter when creating a checkout or SDK intent.

Off-chain allowlists

If your allowlist data is stored off-chain, you can gate access by using any off-chain logic on your end and using our single-use checkout products (one-time checkout links or an instantiation of a Checkout Element component in our SDK) to effectively create an allowlist.

There is an important consideration here:

You must ensure that the mint function cannot be called directly on-chain
Even if you gate access to a checkout page that you own, users can execute smart contract functions directly on the blockchain (for example, through an interface like Etherscan or Polygonscan). This would effectively allow them to bypass your off-chain allowlist unless you restrict the mint function to only be callable by Paper's wallets. This can be done by using an onlyPaper interface we've developed that you can attach to your functions (read more).

Some common setups in this scenario include:

  • You have two mint functions: one for the public sale that anyone can call, and one onlyPaper restricted mint function that can only be called by Paper. During the pre-sale allowlist period, the public sale method is disabled and the onlyPaper restricted mint function is enabled. You set up one-time purchase links or use Checkout Elements as the only way users can mint on your website, and you can use any custom logic to gate whether or not a user has access to the checkout experience.

  • You want the entire mint experience to be done via Paper for a better user queueing experience and for off-chain restrictions. In this scenario, you can simply have one mint function that is restricted to onlyPaper and use any custom logic to gate whether or not a user has access to the checkout experience.

thirdweb and Candy Machine contracts

If you are using a thirdweb contract, you should use a Signature Drop or Edition Contract with Signature minting to achieve your allowlist needs. You can then pass in any signature that you generate through the contractArgs parameter when setting up a checkout or SDK intent.

If you are using a Candy Machine V2 contract, we will prompt the user to send us the required allowlist token that the Candy Machine configuration expects, and our wallet will subsequently use the required allowlist token to mint.