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.

SettingOptionsValue/TypeDescription
tokenStandard
"nft"Non-Fungible asset (NFT)
"pnft"Programmable Non-Fungible asset (pNFT)
numberIntegerNumber of available items
symbolStringString representing the symbol of the NFT
sellerFeeBasisPointIntegerThe royalties shared by the creators in basis points (i.e., 550 means 5.5%)
isMutableBooleanA boolean indicating if the NFTs Metadata Account can be updated
isSequentialBooleanA boolean indicating whether a sequential index generation should be used during mint or not
ruleSetPublic Key(optional) The rule set used by minted pNFTs

The creators setting allows you to specify up to 4 addresses and their percentage share.

SettingOptionsValue/TypeDescription
creatorsUp to 4 creatorsList of creators and their percentage share of the royalties
addressPublic KeyA creator public key
shareIntegerA 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:

SettingOptionsValue/TypeDescription
hiddenSettings
nameStringName of the mint (can use $ID$ or $ID+1$ mint index replacement variables)
uriStringURI of the mint (can use $ID$ or $ID+1$ mint index replacement variables)
hashStringA 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:

SettingOptionsAccepted ValuesDescription
uploadMethodConfigure 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)
bucketStringAWS bucket name
profileStringAWS profile to use from the credentials file name
directoryStringThe directory within the bucket to upload the items to. An empty string means uploading files to the bucket root directory.
nftStorageAuthTokenStringNFT.Storage API Key (required when "nftStorage" is used)
pinataConfig(required when "pinata" is used)
JWTStringJWT authentication token
apiGatewayStringURL to connect to Pinata API
apiContentStringURL to use as the base for creating the asset links
parallelLimitIntegerNumber of concurrent uploads; use this setting to avoid rate limits
shadowStorageAccountStringShadow Drive storage pubkey (required when "shdw" is used)
sdriveApiKeyStringSDrive 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.

Previous
Getting Started