Here are ready-to-use recipes and more information on real-life use cases.
In most cases, it is good to provide some modifications for the final version of the smart contract, such as changing the functions' names to make life harder for the bot's owners.
It is good to build the smart contract locally and deploy it from the file system in such a case. It is possible by default with the Elven Tools CLI. You need to prepare the directory sc/nft-minter for NFT minter or sc/sft-minter for SFT minter. In the same place where you already have the walletKey.pem file and later the output.json file. The tree should look like that:
.
├── output.json
├── sc
│ ├── nft-minter
│ | ├── elven-nft-minter.abi.json
│ | └── elven-nft-minter.wasm
│ └── sft-minter
│ ├── elven-tools-sft-minter.abi.json
│ └── elven-tools-sft-minter.wasm
├── walletKey.pem
As you can see, we have the .abi.json and .wasm files there. You will find them in the output directory after building smart contracts locally, and the elven-tools cli tool will take them by default. Remember to only keep the same naming convention for the directories - sc/nft-minter and sc/sft-minter.
If you need some help working with smart contracts in the MultiversX ecosystem, please check docs.
The configuration file is optional, and you don't need it until you want to change the chain or the Smart Contract source. Plus, maybe after some modifications, you would like to change the functions names and gas limit. All default values are defined here, and below, you'll find the example of how to overwrite them from outside of the lib itself.
The configuration file should be named .elventoolsrc, or take any compatible name from the cosmiconfig project. The main handle should be elventools.
{
"chain": "testnet",
"nftMinterSc": {
"version": "v1.2.0",
"mintFnName": "mintMe"
},
"sftMinterSc": {
"version": "v0.1.0",
"buyFnName": "buyMe"
}
}
In the example above, we define the chain as the 'testnet' (devnet is set by default), and we also define the versions for smart contracts. For example v1.2.0 (the last tag name should always be selected as default). It can also be a branch name. Then we also define new names for the NFT 'mint' function and SFT 'buy' function. You can also change names for other functions and set up different gas limits.
You will find all possible options here.
Remember, you don't have to change the config.ts file. It is for library usage. You don't have to clone the repository to change the configuration. .elventoolsrc is the only config file that should be used.
Important! The same way as in the example above, you can configure deployment to mainnet. Please remember about a couple of things:
chain in the config file to the mainnet,sc/nft-minter or sc/sft-minter directory, then they will be used instead of the ones from the repository,It is always advisable to use the custom API endpoints custom proxies for production-ready apps. Even with this tool, it is better to use the custom one. You can read more about how to set up your architecture here.
Suppose you don't have the resources to do that. You can find third-party services which do that as a service.
To switch to your custom API endpoint, you would need to add in your .elventoolsrc configuration file:
{
"chain": "devnet",
"apiProviderEndpoint": "https://devnet-api.multiversx.com"
}
It is an example of the default API endpoint for the devnet. You can do the same for the testnet and mainnet.
When you need to use the Gateway instead API, you can configure it like that:
{
"chain": "devnet",
"gatewayProviderEndpoint": "https://devnet-gateway.multiversx.com"
}
It is an example with the default Gateway endpoint for the devnet. You can do the same for the testnet and mainnet.
Important! When nothing is provided, the CLI will use the default, public MultiversX API endpoint (api.multiversx.com, devnet-api.multiversx.com, testnet-api.multiversx.com). When the gatewayProviderEndpoint is set, it will always overwrite the apiProviderEndpoint.
(NFT only for now)
The allowlist is usually required for the first batch of tokens to distribute them only to chosen addresses. It can be a list of eligible addresses.
There are three endpoints and commands which help with that. First you would need to have the listof addresses.
Then you need a file called allowlist.json in the root directory. It should have the list of addresses in such a form:
[
"erd1.......",
"erd1.......",
"erd1.......",
"erd1.......",
]
There should be a maximum of 320 addresses per transaction. You can make a couple of transactions if you need to. But remember to update the file on each.
You can populate the list without the file, then the CLI will request it through a prompt where you need to provide them one by one, separated using a comma.
Let's see what it looks like in both cases:
Example:
elven-tools nft-minter populate-allowlist
Populating addresses from the allowlist.json file:
✔ Are you sure that you want to proceed?
› Yes
Transaction: https://devnet-explorer.multiversx.com/transactions/4a3b63edc1cf00c8025c025926db033964e4625fa5ddcd316b880787f3c8094f
Example:
elven-tools nft-minter populate-allowlist
There is no allowlist.json file with the addresses.
You will be providing addresses by hand.
✔ Are you sure that you want to proceed?
› Yes
✔ Provide the list of addresses. Max 320 addresses per one transaction.
You can add more by sending more transactions. Separate them with comma (","):
… erd1puseeussfftajfj92ezqtfp0ca6u0s2thu7n64cyw6m37ef8dh0sekwt27, erd18yxxeuf2fkwlwgrnc3chjyf4gl3429qpp5fqynhzf2gn6hs3h8dqu7zt7n
Transaction: https://devnet-explorer.multiversx.com/transactions/f8bf7de010629e32008bebb1ba5681a008f23afaf949e0e565ea3bbf41bd80fd
Remember that you will always need to enable the allowlist after populating it. Otherwise, it will be ignored. You can enable and disable it using: elven-tools nft-minter enable-allowlist and elven-tools nft-minter disable-allowlist.
You can also use a couple of SC queries. This allows to get the current size of the allowlist, check if the address is there, or check if the allowlist is enabled. These are:
elven-tools nft-minter get-allowlist-size
elven-tools nft-minter is-allowlist-enabled
elven-tools nft-minter get-allowlist-address-check
You will be able to clear the allowlist with:
elven-tools nft-minter clear-allowlist
It will clear the whole allowlist because the process is quite heavy. The best is to keep max 1300 addresses in the allowlist at a time. Of course, if only you plan to clear it later. If you keep more and want to clear it, you can reach the gas limit for a transaction. So it would be best to split the allowlist per drop, keep it as small as possible and clear it each time.
You can also remove a single address by:
elven-tools nft-minter remove-allowlist-address
Remember that you can always use the functionality without using the CLI tool, then you would need to call the same endpoints. You will find all commands for the CLI here and all NFT SC endpoints here. Also, check the longer article about possible workflows.
(NFT only for now)
The drops are, in simple words, batches of tokens to mint. You don't have to use them, but it is usually required because most projects usually split the collection into 'waves' of distribution.
Now let's see how to define a drop in which we will mint only 2500 of the whole 10k collection. You would need to use elven-tools nft-minter set-drop when using the CLI tool. You will be asked to provide how many tokens per drop it should mint. After that, it will pause the minting process. You can also pause the minting at any time you want by elven-tools nft-minter pause-minting. You can also unset the drop by elven-tools nft-minter unset-drop. You'll find all the commands here.
Example:
elven-tools nft-minter set-drop
✔ Provide the amount of the tokens for the drop:
… 2500
Transaction: https://devnet-explorer.multiversx.com/transactions/915a9b115d01dbc0026e91ab889284018bd51cee8a030804dbb5da600c1bdd25
elven-tools nft-minter mint
✔ Provide how many tokens should be minted.
Take into account possible limitations set on the Smart Contract (ex 3 for three tokens):
… 2
✔ Are you sure that you want to proceed?
› Yes
Transaction: https://devnet-explorer.multiversx.com/transactions/8954262fea15e63705d696fcfeb92874a4c10239703b5a6631fd7f989c494ba8
There are also SC queries that allow checking a couple of things. These are:
elven-tools nft-minter get-drop-tokens-left
elven-tools nft-minter get-minted-per-address-per-drop
elven-tools nft-minter get-tokens-limit-per-address-per-drop
elven-tools nft-minter is-drop-active
They are self-explanatory, but you will find all descriptions under the links below.
Remember that you can always use the functionality without using the CLI tool, then you would need to call the same endpoints. You will find all commands for the CLI here and all NFT SC endpoints here. Also, check the longer article about possible workflows.
The giveaway functionality is helpful when you want to give some tokens to a particular address. It can be because they are the team members or someone you want to thank.
For NFTs:
Remember that with Elven Tools, you can't choose the specific token. It will still be randomly selected and minted. When using this functionality, there is no payment—only transaction fees.
You can give some tokens using the CLI's command elven-tools nft-minter giveaway. You would need to provide the address to which you would like to send the NFTs and the amount of the tokens to give.
You can provide addresses by hand in the CLI prompt, separating them with a coma. But you can also provide the file: giveaway.json. The structure looks like this:
[
"erd1...",
"erd1...",
"erd1...",
]
For SFTs:
You can give some amount of the particular SFT tokens using the CLI's command elven-tools sft-minter giveaway. You would need to provide the address to which you would like to send the NFTs and the amount of the tokens to give.
You can provide addresses by hand in the CLI prompt, separating them with a coma. It should be a string similar to: erd1...|01|100,erd1...|02|200.
But you can also provide the file: giveaway.json. The structure looks like this:
[
{
"address": "erd1...",
"nonce": "01",
"amount": "100"
},
{
"address": "erd1...",
"nonce": "02",
"amount": "200"
}
]
You can use this even when the minting process is paused, which is usable for the giveaway before the official minting is started.
As always, you can call the giveaway endpoint without the CLI. Check them in the SC endpoints section.
In the MultiversX ecosystem, each smart contract will get the share of the fees as a development reward. So the developer of the contract will get some share. Because this is an open source Smart Contract it will generate these rewards for everyone who deploys it. You can claim them by using: elven-tools nft-minter claim-dev-rewards or elven-tools sft-minter claim-dev-rewards. Remember that this will only work for the owner of the Smart Contract.
As always, you can call the claim-dev-rewards endpoint without the CLI. Check them in the SC endpoints section.
Smart contracts are payable by default, so in theory, it is possible to transfer EGLD funds to them. By definition, this is how marketplaces should send the royalties. There is an elven-tools nft-minter claim-sc-funds and elven-tools sft-minter claim-sc-funds, which will allow getting all the funds locked on the contract. Of course, only for the owner of the contract.
There will also be a dedicated endpoint/command which will call the marketplaces smart contracts to claim the royalties because not all of them will send them automatically.
As always, you can call the claim-sc-funds endpoint without the CLI. Check them in the SC endpoints section.
(NFT only for now)
From version 1.6.0 there is additional command elven-tools collection-nft-owners. It will allow getting owners' addresses, using only the collection ticker. It is useful, for example, when you want to do some promotional giveaway. The functionality will save the addresses in the nft-collection-owners.json where the command is triggered.
Additionally, you can also filter by metadata JSON file name. It is an optional step.
Important: It will work only with the API endpoint, not the gateway. Elven Tools CLI, by default, uses the API endpoint. So it should work by default, but you need to remember that.
How to use it? You need to use at least version 1.6.0 of the CLI. You can check it by elven-tools -v, and you would need to use the command elven-tools collection-nft-owners. Then there are prompts. You would need to provide the collection ticker and answer two questions about whether you want to filter smart contract addresses.
Because of how the API works, we need to do calls with a max size of 100 items. Here we also have calls that are limited to 5 per second. You can change this limit in the configuration file. Check how here. If you need to change this setting, in the config file, there should be an entry:
{
"chain": "mainnet",
"collectionNftOwners": {
"apiCallsPerSecond": 5
}
}
When is the address not unique? It is when one address will have more than one NFT token from the collection. See the example below:
elven-tools collection-nft-owners
✔ Provide the collection ticker
… EAPES-8f3c1f
✔ Do you want to exclude smart contract addresses?
› Yes
✔ Do you want to filter by metadata JSON file name? Provide names without the extension separated by a comma (example: 123,555,9999) [you can ommit that, just confirm empty]
…
There are 10000 tokens in that collection.
Done, 1042 addresses saved. Without smart contract addresses.
You can also do filtering by metadata JSON filename:
elven-tools collection-nft-owners
✔ Provide the collection ticker
… EGG-6ee076
✔ Do you want to include only unique addresses?
› No
✔ Do you want to exclude smart contract addresses?
› No
✔ Do you want to filter by metadata JSON file name? Provide names without the extension separated by a comma (example: 123,555,9999) [you can ommit that, just press enter]
… 1390,827
There is 1000 tokens in that collection.
Done, 2 addresses saved.
If you are interested in generating a CSV file, you can use the elven-tools-collection-owners-csv script, which will do that. The input file is the output of the elven-tools collection-nft-owners. You'll find the input and output examples in the data folder.
(NFT only for now)
From version 1.12.1, it is possible to automatically reuse the nft-collection-owners.json so the output from the elven-tools collection-nft-owners and distribute EGLD, ESDT, SFT or MetaESDT tokens to the collection NFT owners.
The functionality is based on the currently used PEM key file. It works without connection to the NFT minter smart contract or any other custom smart contract.
You can use it with any PEM wallet file. You can also do this not only with your collection.
How does it work?
elven-tools collection-nft-owners and generate the nft-collection-owners.json as in the section above.elven-tools distribute-to-owners command.After all, you will get the distribution-log.json with all transactions, addresses, and status.
Remember that you need to be sure that you use the proper chain type (devnet, testnet, mainnet) and that you have an adequate amount of the token on the wallet corresponding to the PEM file. Use elven-tools derive-pem to derive the PEM file.
To change the chain type, use the configuration file. Create a .elventoolsrc config file and add:
{
"chain": "mainnet"
}
There is a rate limit when distributing the tokens. It is five calls per second. You can increase that by using the configuration file, add:
{
"distributeToOwners": {
"apiCallsPerSecond": 5
}
}
Check here how to work with the config file.
From version 1.15.2, you can use an optional multiplier functionality. When distributing the amount will be multiplied by the number of NFTs owned by an address.
Alternatively, if you haven't used the elven-tools collection-nft-owners to generate the nft-collection-owners.json and have addresses from some other source, then you can prepare a file with the same name and the same structure. You can omit 'tokens' and 'tokensCount' there. It should still work. The structure will be:
[
{ "owner": "erd1....", "tokensCount": 3 },
{ "owner": "erd1....", "tokensCount": 1 },
{ "owner": "erd1....", "tokensCount": 1 }
]
elven-tools distribute-to-owners
✔ What do you want to distribute? Choose the token type.
› EGLD
✔ Please provide the amount of the EGLD to send per one address (ex. 1 is 1 EGLD)
… 1
? You can multiply the amount to distribute by the number of NFTs tokens owned. Do you want to do that? › - Use arrow-keys. Return to submit.
❯ No
Yes
You can also use the CLI tool when you are only a buyer, not an owner of the smart contract. To do so, you would need to go through 4 steps.
npm install elven-tools -gelven-tools derive-pem You would need to pass your seed phrase here. No worries, you work on your computer. If it is safe, nothing leaves it because of the CLI too. Never share seed phrases and PEM files with anyone..elventoolsrc. Inside add:{
"nftMinterSc": {
"deployNftMinterSC": "<nft_minter_smart_contract_address_here>",
"tokenSellingPrice": "<price_of_the_nft_here>"
},
"sftMinterSc": {
"deploySftMinterSC": "<sft_minter_smart_contract_address_here>",
"tokenSellingPrice": "<price_of_the_sft_here>"
}
}
You would need only these settings to be able to buy. Of course, the contract owner should prepare everything and start the minting process.
The tokenSellingPrice here is a format with 18 zeros. So 1 EGLD is 1000000000000000000.
The deployNftMinterSC here is an address of the contract. The owner should share it.
elven-tools nft-minter mint. You will be asked about the number of tokens to mint. There will be limits. You can query the contract to check them.elven-tools sft-minter buy. You will be asked about the number of tokens to mint and SFT nonce number. There will be limits. You can query the contract to check them.The output.json file will be created as temporary storage, which keeps the created Smart Contract address, the information about the collection token, and the token price. It is required in further operations. This file is created automatically when deploying the Smart Contract using the CLI. So it is mostly there for the owner of the Smart Contract. It looks like that:
{
"nftMinterScAddress": "erd1qqqqqqqqqqqqqpgq7a0cq90r2kqymtaqysxp7umrcyp04jgmgtkscelhmp",
"nftMinterScCollectionSellingPrice": "1000000000000000",
"sftMinterScAddress": "erd1qqqqqqqqqqqqqpgq7a0cq90r2kqymtaqysxp7umrcyp04jgmgtkscelhmm",
"sftMinterScCollectionSellingPrice": "1000000000000000"
}
Important: In the future the usage of output.json file will be removed and replaced with .elventoolsrc file.
(NFT only for now)
The endpoint will set the following index to mint. It is important here that it will randomly select it from the indexes left to mint. This endpoint is also public, so everyone can call the transaction and change the following index to mint. It assures that the process is random, and everyone can impact that.
When using the CLI you can always run elven-tools nft-minter shuffle.