Reserves offer a general-purpose framework to have a better control on how to distribute your work. There are a few aspects to consider before using reserves in your project.
What is a Reserve ?
A reserve is defined by a number of slots, as well as a strategy for who will have an access to the reserve. For now, there's only 1 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 configured in 2 ways:
- the number of slots is equal to the total number of slots for the eligible users: every user is guaranteed to have access to an edition
- the number of slots is smaller than the total number of slots for the eligible users: not every user is guaranteed to have access to an edition
Let's demonstrate this concept with an access list for 2 users, A and B.
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.
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.
Reserves can be stacked
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):
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.
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 locked to new-comers because of this feature. We are trusting your jugement in that regard.
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.
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.
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 acertain number of editions which can then be safely unlocked.
There are probably more use cases, let's see how this feature will be leveraged.
Updating a reserve
Reserves are static. When a user mints from a reserve, it updates the smart contract storage, which then has to be indexed to be displayed on the UI with the update. It means that what you see on the UI may not be completly up-to-date with onchain storage. And so, consider the following case:
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 token are not disabled. When updating a reserve, we suggest following these steps:
- disable the token
- wait until the UI displays your token as disabled (refresh page)
- update the reserve
- enable the token
These steps will ensure that no race condition can happen between the UI state and the contract storage.