Allowlists

Paper offers flexible solutions that can support on-chain or off-chain allowlists.

If your app checks a buyer’s email address (or other identity) on your backend, then you have an off-chain allowlist. This approach also lets you dynamically configure the price or other properties for each buyer.

If your smart contract only allows specific wallet address to claim, you have an on-chain allowlist.

🔑 Off-chain allowlists

Paper enables you to customize buying experience by allowing your backend to determine mint eligibility, price, quantity, and more.

Use cases

Examples of what you can accomplish:

• Restrict minting to specific email addresses or other social login.
• Set a dynamic price for each buyer.
• Provide a discount via coupon code.
• Set a maximum limit per buyer.
• Allow some buyers to purchase early.

Prerequisites

• The mint method on your smart contract is restricted so all claims must go through your backend and Paper’s checkout flow.
• You’ve registered your contract.
• (Optional) You’ve already collected your buyers’ email addresses.
• (Optional) You manage coupon codes on your backend.

Integration with Dynamic One-Time Checkout Links

1. Implement the business logic on your backend to determine the eligibility, price, quantity, and any other properties.
   1. Here is where you implement your allowlist, coupons, presale eligibility, etc.
2. If the buyer is allowed to make a purchase, create a Checkout Link Intent to get a unique URL.
   1. This URL encodes the checkout properties (including the mint method arguments) for this buyer to complete their purchase. The link is invalidated once a purchase is made, and a buyer is unable to manipulate these properties.
3. Navigate the buyer to that URL.

Integration with Checkout Elements

1. Implement the business logic on your backend to determine the eligibility, price, quantity, and any other properties.
   1. Here is where you implement your allowlist, coupons, presale eligibility, etc.
2. If the buyer is allowed to make a purchase, create a Checkout SDK Intent to get a unique SDK client secret.
   1. This token encodes the checkout properties (including the mint method arguments) for this buyer to complete their purchase. The token is invalidated once a purchase is made, and a buyer is unable to manipulate these properties.
3. Pass the SDK client secret to render a CheckoutWithCard or CheckoutWithEth component.

FAQ

Why do I need to restrict my mint method?
The blockchain is public and by default anyone can call your smart contract. You must ensure that savvy buyers can’t bypass your backend access logic by ensuring that Paper is calling your contract.
One approach is to restricted your method to be called by Paper only.
Another approach is to generate one-time use signatures on your backend that are required by your mint method. There are many resources online to learn to build signature-based minting.

How can I verify email addresses once I’ve collected them?
If you want to ensure a checkout is presented only to the owner of a specific email address, you have three options when creating a Checkout Link Intent:

• Verify the email in your app. Make sure the user is logged in to the provided email address.
• Verify the email in the checkout flow. Set requireVerifiedEmail: true to require the user verify they can access the provided email address.
• Email the checkout link URL directly. Set sendEmailOnCreation: true to automatically send the Dynamic One-Time Checkout Link URL to the provided email address.

How do I achieve an allowlist with a thirdweb contracts?
Thirdweb offers a prebuilt Signature Drop contract that offers signature minting. Paper works out of the box with thirdweb contracts. You can generate the signature on your backend and provide it in the contractArgs parameter when creating an intent.

On-chain allowlists

Use cases

• You want to allow specific buyers to native mint from your smart contract.

Prerequisites

• Your smart contract has an getIneligibilityReason(address buyer) that returns a non-empty string (“Wallet address is not allowed.”) if the buyer’s address is not on the allowlist. Else return an empty string.
• Your smart contract has a paperMint(address buyer) function that is restricted to be called by Paper only and allows minting the NFT to a different wallet address.

Integration with Dynamic One-Time Checkout Links

1. Create a Checkout Link Intent that sets the buyer’s walletAddress and eligibilityMethod to getIneligibilityMethod to get a unique URL.
   1. The buyer’s wallet address will be provided to the eligibility method and void the checkout if they are not eligible.
2. Navigate the buyer to this URL.

Integration with Checkout Elements

1. Create a Checkout SDK Intent that sets the buyer’s walletAddress and eligibilityMethod to getIneligibilityMethod to get a unique SDK client secret.
   1. The buyer’s wallet address will be provided to the eligibility method and void the checkout if they are not eligible.
2. Pass the SDK client secret to render a CheckoutWithCard or CheckoutWithEth component.

FAQ

Why can’t Paper call my standard mint method that checks the allowlist?
It is important to note that the msg.sender for your contract method will be Paper’s wallet, not the buyer’s wallet. Generally most allowlists check msg.sender which is the caller of the contract, and since most allowlists won’t have Paper’s wallet addresses allowlisted, these calls will fail.

By combining an eligibility method and a different mint method only callable by Paper, we can ensure that we can always mint to users who pass your on-chain eligibility check.

Why can’t I add Paper’s float wallets to the allowlist?
Paper may rotate float wallets periodically as a security best practice.
If your allowlist drop is short-lived and want to add our current float wallets to your allowlist, please submit a ticket in our Discord Community.