fxhash documentation
fxhash documentation
Reserves and Allow Lists

Reserves and Allow Lists

Reserves and Allow Lists

An Overview of Reserves and Allow Lists, two tools that give fine-grained control over the distribution of GENTKs to new and past collectors.

What is a Reserve ?

A reserve consists of a set number of slots that determine who can access it. For now, there's only one type of reserve available: Access Lists. We will add more Reserve options in the future.

A Reserve ensures that its number of slots will only give access to the same number of editions to eligible collectors. When a user mints an iteration from your project, if they're eligible to the reserve, they will consume one slot from it (and eventually consume one of their slots). When the number of slots reaches 0, the reserve becomes fully consumed and cannot be activated anymore. A Reserve can be set up in two ways:

  • Equal Slots: The number of slots equals the total number of eligible users, guaranteeing access to an edition for every user.
  • Unequal Slots: The number of slots is less than the total number of eligible users, meaning not every user is guaranteed access to an edition.

Let's demonstrate this concept with an access list for two users, A and B.

image

In this first case, the number of slots of the reserve is equal to the total number of slots of the users in the access list. Both users A and B are guaranteed to get their 5 editions.

image

In this second case, the number of slots of the reserve is smaller than the total number of slots given to the users in the access list. It means that neither A nor B are guaranteed to get their 5 editions. If User A mints 5 editions from the reserve first, user B will only be left with 2 editions. If we had set the number of reserve slots to 1, only A or B would have been able to get an edition from the reserve.

Reserves are very permissive (at least when created), and it's up to you to configure those properly based on your distribution strategy.

Stacking Reserves

You can add multiple reserves to your project. Each reserve will save its slots for the eligible users. This is an example of multiple reserves (each of them is as access list):

image

By having the ability to define multiple reserves, it gives you a fine control over the distribution. Use it as you see fit for your projects.

icon
Think about new users

We would recommend to keep new users in mind. It's great to reward your previous collectors, but we wouldn't want the platform to become gated for new-comers because of this feature. We are trusting your jugement in that regard.

icon
Limitations

As of today, and due to an issue with some optimization in our contracts, Access Lists are limited to 500 addresses per list. We are working on solving this issue.

Use cases

Reserve editions for yourself

Previously, artists had to disable their project and mint from it with a special access before releasing it to the public. This is no longer needed by using a Reserve for yourself. Create a reserve of type Access List, give it the number of slots you'd like, and add yourself in the access list with the same number of slots. You will be guaranteed to be able to mint the same number of editions whenever you'd like.

Reward your past collectors

We've built an UI to import the current holders of the iterations generated by your projects.

image

You can pick different import strategies, each being described when the option is selected. Please keep in mind that reserves are not dynamic. Future collectors won't be included in a previously created reserve.

Import from a CSV

You can import a CSV file when creating a reserve, which allows you to use different off-chain strategies. The CSV file should respect the following format:

address;amount
tz1dtzgLYUHMhP6sWeFtFsHkHqyPezBBPLsZ;2
tz1PoDdN2oyRyF6DA73zTWAWYhNL4UGr3Egj;4
tz1MGzgRu6qJ3RaBUErnpFDLarFVPgaApKrA;1

Lock N editions for later

By setting a reserve as an access list to a burn address (or to yourself if you're not planning on consuming it), you can lock a certain number of editions which can then be safely unlocked.

Updating a reserve

Reserves are static. When minting from a reserve, it updates the smart contract, which might not be immediately reflected in the UI. And so, consider the following case:

image

From the contract's perspective, the following happens:

  • Reserve: 10 (User A: 10)
  • User A mints from reserve
  • Reserve: 9 (User A: 9)
  • User A: get NFT
  • Author updates reserve
  • Reserve: 10 (User A: 10, User B: 1)

This is known as a race condition, and measures must be taken to prevent those cases from happening. That's why the Smart Contract will reject update_reserve calls if a project is not disabled. When updating a reserve, we suggest following these steps:

  1. Disable the project.
  2. Wait until the UI shows the project as disabled.
  3. Update the reserve.
  4. Re-enable the project.

These steps will ensure that no race condition can happen between the UI state and the contract storage.