Working with Sugar
Configuration File
Sugar uses a JSON configuration file to upload assets and configure a Candy Machine – in most cases, the file will be named config.json
. The configuration includes the settings that are used to initialize and update the Candy Machine, as well as upload the assets to be minted. It will also include the configuration of guards that will provide access control to minting.
A basic configuration file is shown below:
{
"tokenStandard": "pnft",
"number": 10,
"symbol": "TEST",
"sellerFeeBasisPoints": 500,
"isMutable": true,
"isSequential": false,
"ruleSet": "eBJLFYPxJmMGKuFwpDWkzxZeUrad92kZRC5BJLpzyT9",
"creators": [
{
"address": "PanbgtcTiZ2PveV96t2FHSffiLHXXjMuhvoabUUKKm8",
"share": 50
},
{
"address": "PanbgtcTiZ2PveV96t2FHSffiLHXXjMuhvoabUUKKm8",
"share": 50
}
],
"hiddenSettings": null,
"uploadMethod": "bundlr",
"awsConfig": null,
"nftStorageAuthToken": null,
"shdwStorageAccount": null,
"pinataConfig": null,
"sdriveApiKey": null,
"guards": {
"default": {
"botTax": {
"value": 0.01,
"lastInstruction": true
}
},
"groups": [
{
"label": "OGs",
"guards": {
"startDate": {
"date": "2022-10-20 12:00:00 +0000"
},
"tokenGate": {
"amount": 1,
"mint": "7nE1GmnMmDKiycFkpHF7mKtxt356FQzVonZqBWsTWZNf"
},
"solPayment": {
"value": 1,
"destination": "PanbgtcTiZ2PveV96t2FHSffiLHXXjMuhvoabUUKKm8"
}
}
},
{
"label": "Public",
"guards": {
"startDate": {
"date": "2022-10-20 18:00:00 +0000"
},
"solPayment": {
"value": 2,
"destination": "PanbgtcTiZ2PveV96t2FHSffiLHXXjMuhvoabUUKKm8"
}
}
}
]
}
}
The configuration file can be viewed as having three main parts: Candy Machine settings ("tokenStandard"
to "hiddenSettings"
), upload settings ("uploadMethod"
to "sdriveApiKey"
) and guard settings ("guards"
).
Candy Machine settings
Candy Machine settings determine the type of the asset, number of assets available and their metadata information.
Setting | Options | Value/Type | Description |
---|---|---|---|
tokenStandard | |||
"nft" | Non-Fungible asset (NFT ) | ||
"pnft" | Programmable Non-Fungible asset (pNFT ) | ||
number | Integer | Number of available items | |
symbol | String | String representing the symbol of the NFT | |
sellerFeeBasisPoint | Integer | The royalties shared by the creators in basis points (i.e., 550 means 5.5%) | |
isMutable | Boolean | A boolean indicating if the NFTs Metadata Account can be updated | |
isSequential | Boolean | A boolean indicating whether a sequential index generation should be used during mint or not | |
ruleSet | Public Key | (optional) The rule set used by minted pNFT s |
The creators
setting allows you to specify up to 4 addresses and their percentage share.
Setting | Options | Value/Type | Description |
---|---|---|---|
creators | Up to 4 creators | List of creators and their percentage share of the royalties | |
address | Public Key | A creator public key | |
share | Integer | A value between 0 and 100 |
While the metadata on-chain stores up to 5 creators, the Candy Machine is set as one of the creators. As a result, there is a limit of 4 creators at most.
The sum of the share values must add up to 100, otherwise an error will be generated.
The Candy Machine can be configured to not have the final metadata when an NFT is minted. This is useful when you are planning a revel step once mint is completed. In this case, you can specify the "placeholder" metadata values for the hidden NFT:
Setting | Options | Value/Type | Description |
---|---|---|---|
hiddenSettings | |||
name | String | Name of the mint (can use $ID$ or $ID+1$ mint index replacement variables) | |
uri | String | URI of the mint (can use $ID$ or $ID+1$ mint index replacement variables) | |
hash | String | A 32 character hash (in most cases this is the hash of the cache file with the mapping between mint number and metadata so that the order can be verified when the mint is complete) |
Upload settings
Sugar supports a variety of storage providers – the one to be used is define by the uploadMethod
setting. Depending of the provider, there would be additional configuration needed.
The table below provides an overview of the settings available:
Setting | Options | Accepted Values | Description |
---|---|---|---|
uploadMethod | Configure the storage to upload images and metadata | ||
"bundlr" | Uploads to Arweave using Bundlr and payments are made in SOL (works on both mainnet and devnet; files are only stored for 7 days on devnet) | ||
"aws" | Uploads to Amazon Web Services (AWS) | ||
"nftStorage" | Uploads to NFT.Storage (works on all networks; no payment required) | ||
"shdw" | Uploads to the GenesysGo Shadow Drive (works on mainnet only) | ||
"pinata" | Uploads to Pinata (works on all networks; free and tiered subscriptions) | ||
"sdrive" | Uploads to Shador Drive using SDrive Cloud Storage | ||
awsConfig | (required when "aws" is used) | ||
bucket | String | AWS bucket name | |
profile | String | AWS profile to use from the credentials file name | |
directory | String | The directory within the bucket to upload the items to. An empty string means uploading files to the bucket root directory. | |
nftStorageAuthToken | String | NFT.Storage API Key (required when "nftStorage" is used) | |
pinataConfig | (required when "pinata" is used) | ||
JWT | String | JWT authentication token | |
apiGateway | String | URL to connect to Pinata API | |
apiContent | String | URL to use as the base for creating the asset links | |
parallelLimit | Integer | Number of concurrent uploads; use this setting to avoid rate limits | |
shadowStorageAccount | String | Shadow Drive storage pubkey (required when "shdw" is used) | |
sdriveApiKey | String | SDrive API key (required when "sdrive" is used) |
Specific upload method settings:
Guard settings
The guards
settings allows you to specify which guards will be enabled on the Candy Machine.
Candy Machine support a number of guards that provide access control to minting. Guards can be configured into a "default" guard group or appear in multiple guard groups.