WARNING

Keep in mind that there are extra risks inherent to publishing code on a public blockchain. If your CAT and/or TAIL have not been created securely, your funds could potentially be bricked or stolen. Proceed with caution. For more information please see Chialisp.com Docs. Just be sure to substitute cdv with chdv and cats with chcats

Introduction

Welcome to the world of CATs! We're excited to have you here, and we can't wait to see the creative ideas you come up with.

This tutorial will help you jump right in and get started with issuing your own CATs. There are a few things you should know before we begin.

The CAT1 standard is finalized as of January 2022. However, to minimize your risk of running into unexpected results, we recommend that you do following:

• Generate a new public/private key pair for each CAT you issue. This key pair should be used for issuing one specific CAT and nothing else. It should also be the only key pair on your computer while issuing the CAT.
• Test thoroughly on testnet before issuing your CAT to mainnet.

For any questions regarding this tutorial, head over to the #support channel on our Keybase forum, where there are lots of friendly folks who can help you.

CAT issuance granularity

CAT denominations, as well as the rules behind minting and melting, can take some getting used to. Here are a few things to keep in mind before you issue your CATs:

• Most Chinilla wallets choose to display their value in HCX. However, this is a purely cosmetic choice because Chinilla's blockchain only knows about vojos. One HCX is equal to one trillion (1,000,000,000,000) vojos.
• In a similar vein, Chinilla Network has made the design decision to map 1 CAT to 1000 HCX vojos. This ratio will be the same for all CATs.
• Theoretically, it would be possible to set the CAT:vojo ratio to something other than 1:1000 for a specific CAT, but we strongly recommend against doing this. The official Chinilla wallet will not support CATs with a ratio other than 1:1000. Additionally, if you created your own wallet with support for different ratios, users of this wallet would almost certainly be confused and accidentally spend too much or too little money, by multiple orders of magnitude. Please don't attempt this.
• The melt value of a single token is 1000 vojos. This remains true regardless of the token's face value or its circulating supply.
• A token's face value and its melt value are not necessarily correlated, let alone matched.

With one HCX, you can mint 1 billion CATs. The face value of these tokens could be zero, or multiple HCX, or anywhere in between. This value is decided by the market -- it's worth whatever someone is willing to pay for it. The value of the tokens has nothing to do with the underlying HCX, other than their 1000-vojo melt value.

These concepts are discussed in greater detail in our CAT1 standard.

Setting up your Environment

This tutorial assumes that you have Chinilla installed and running as well as Python 3 with pip. You also need a wallet with 1000 vojo for each token that you plan to mint.

Windows Setup

0. Ensure that you have a Python version between 3.7 and 3.9 installed by running python --version.

1. Run git clone https://github.com/Chinilla/chinilla-CAT-admin.git so you have the reference tails.

2. Run cd chinilla-CAT-admin to enter the directory

3. Run python -m venv venv to create a virtual environment.

4. Run ./venv/Scripts/activate to activate a virtual environment.

Linux/MacOS Setup

0. Ensure that you have a Python version between 3.7 and 3.9 installed by running python --version.

1. Run sudo apt-get install -y build-essential python3-dev to install Python dev tools.

2. Run git clone https://github.com/Chinilla/chinilla-CAT-admin.git so you have the reference tails.

3. Run cd chinilla-CAT-admin to enter the directory

4. Run python -m venv venv to create a virtual environment.

5. Run ./venv/Scripts/activate to activate a virtual environment.

Confirm Environment Setup

0. Run pip install chinilla-cat-admin to install the required dev tools.

1. Run pip install chinilla-dev-tools to install the CAT admin tools.

2. Verify that "Current Blockchain Status: Full Node Synced" is showing when you run chinilla show -s.

3. Run chdv --help. You should get another usage statement.

4. Run chcats --help. You should get another usage statement.

5. Make sure you have some HCX in your wallet by running chinilla wallet show.

Your environment is now set up and you are ready to start issuing CATs.

Generating a secure key pair

Before we walk you through the process of securely generating and saving a new public/private key pair, please read this important message.

WARNING: The key pair you are about to use will control the minting and retirement of these tokens forever. If the private key were ever compromised, an attacker could mint new tokens, as well as melt any that they owned into regular HCX.

The only way to nullify an attack would be to keep track of illegitimate mints (luckily all of this is fully visible on the public ledger), issue a new CAT, and then offer an eHCXange of legitimate old CATs for the new CAT type.

This would be a complex and time-consuming process that would likely result in people being sold counterfeit CATs at some point. It’s very important to keep your private key secret.

Here's how to generate a secure public/private key pair for issuing your new CAT:

1. Run chinilla keys show.

   a. If you receive this message: There are no saved private keys, then proceed to step 4.

   b. If you have any keys stored on your machine, they'll be shown now. Note the Fingerprint for each key, as you will not be using these keys to create your CAT and you don't want to confuse them for the key you are about to create. Even better, if this is an option for you, would be to delete your existing keys to avoid confusing them for the new ones. Just be sure to save your mnemonic seed somewhere secure before you delete your keys.

2. Run chinilla init. This will initialize your environment if it has not yet been set up.

3. Run chinilla keys generate. This will generate a new public/private key pair.

4. Run chinilla keys show --show-mnemonic-seed. This will show your public and private keys, as well as your Mnemonic seed.

5. Copy your new key pair's Mnemonic seed (24 secret words) to a secure offline location. These 24 words are all you'll need to restore your wallet in the future.

Creating a Single-Mint CAT

NOTE: This section will discuss Token Asset Issuance Limiters (TAILs), as well some technical details of CATs. For a refresher on CATs and TAILs, check out our CAT1 standard.

To get started, you will create a single-mint CAT. This is the default way to issue a CAT. It's also the simplest. It contains a TAIL that only can be used on a specific HCX coin. In Chinilla the coins can only be spent once, so in this case, the CAT can only mint tokens once.

A CAT with a single-mint TAIL will be useful for anyone who wants to create a token with a guaranteed fixed supply.

You can find the TAIL we'll use for this example here.

1. Find a coin to mint, and create and push a new spendbundle:

   a. Change to the "CAT-admin-tool" folder if you're not already there.

   b. Figure out how many HCX vojos you want to use to issue your CAT. Each CAT token will contain 1000 vojos, so you should multiply the number of tokens you want to mint by 1000. For example, if you want to mint 1 million tokens, you'll need 1 billion HCX vojos (1/1000 of an HCX).

   NOTE: We recommend that you include a fee with your transaction. This fee will ensure that your transaction is processed in front of any dust in the mempool. Whether you're running on testnet or mainnet, the recommended fee amount is 100 million vojos (-m 100000000). Even though you will run the cats command multiple times, the fee will only be applied once, when the transaction is pushed to the network.

   c. Take note of your Receive Address in the Chinilla GUI. You'll need it for the next step.

   d. Run chcats --tail ./reference_tails/genesis_by_coin_id.clsp.hex --send-to --amount -m --as-bytes --select-coin

   The --select-coin flag will choose a coin from your wallet for minting your tokens. The final line of the output will be "Name: ". You’ll use "" in the next step.

   e. Run the same command again, this time removing the --select-coin flag and adding a new flag, "--curry 0x". It’s very important to preface the with 0x here, to make CLVM interpret the value as bytes and not a string. Here’s the full command to run:

   chcats --tail ./reference_tails/genesis_by_coin_id.clsp.hex --send-to --amount -m --as-bytes --curry 0x

   This command will give the following output:

   The transaction has been created, would you like to push it to the network? (Y/N)

   f. Enter Y.

   g. The output will be Asset ID: . Copy the , which you'll need in the next step. Meanwhile, the transaction to create your CAT is being pushed to the blockchain.

   Congratulations! You have issued your first CAT. You still need to tell your wallet about it, though.

2. Add a wallet ID for your new CAT:

   a. Switch to the Chinilla GUI. Within a few minutes, your balance should decrease by the number of vojos you just minted. It will not show up in your transactions.

   b. Now you can add a wallet ID for your new CAT. In the upper left corner, click "+ ADD TOKEN", then click "+ Custom". Enter the name of your CAT (it can be anything) in the first text field. For the second field, paste the you saved from a few steps ago. Click ADD.

   c. You will now be taken to your new CAT wallet. The balance should show the number of HCX vojos you chose to use, divided by 1000. This is because CAT vojos are one-thousandth of a CAT.

   d. If you see a Total Balance of 0, you need to refresh your wallet. Run chinilla start wallet-only -r. You should now see the correct balance.

You now have access to your CAT in the GUI. You can send and receive your new tokens just like you would with regular HCX.

Creating a Multiple-Mint CAT

Next we’ll create a CAT capable of minting tokens multiple times. This CAT uses a delegated TAIL, which is much more flexible than the previous one. As long as you sign a puzzlehash that you specify, you can mint new tokens using whatever TAIL you want. This allows for features such as rebate offers and distributed minting and retiring of tokens.

You can find the TAIL we'll use for this example here.

We’ll set up this CAT to delegate the same TAIL we set up previously. What this means is that nobody else can mint new tokens until you allow it. Keep in mind that this is only one of many possible implementations of a delegated TAIL.

1. Find a coin to mint, and create and push a new spendbundle:

   b. Figure out how many HCX vojos you want to use to issue your CAT. Each CAT token will contain 1000 vojos, so you should multiply the number of tokens you want to mint by 1000. For example, if you want to mint 1 million tokens, you'll need 1 billion HCX vojos (1/1000 of an HCX).

   NOTE: Just as with the Single Mint CAT, we recommend that you include a fee with your transaction. This fee will ensure that your transaction is processed in front of any dust in the mempool. Whether you're running on testnet or mainnet, the recommended fee amount is 100 million vojos (-m 100000000). Even though you will run the chcats command multiple times, the fee will only be applied once, when the transaction is pushed to the network.

   c. Take note of your Receive Address in the Chinilla GUI.

   d. Run chinilla keys show. Take note of your and .

   e. Run chcats --tail ./reference_tails/delegated_tail.clsp.hex --curry 0x --send-to -a -m --as-bytes --select-coin

   The --select-coin flag will choose a coin from your wallet to issue the CAT from. The final line of the output will be "Name: ". You’ll use "" in the next step.

   Now that you have a coin, you can create a full delegated TAIL. In our case, the TAIL it delegates will be of the single-mint variety.

   f. Run chdv clsp curry ./reference_tails/genesis_by_coin_id.clsp.hex -a 0x.

   (Keep in mind the 0x before is necessary.) The result of this command will be a , which you’ll pass in as part of the solution to your main TAIL.

   g. Run the same command again, with the additional --treehash flag. This will give you the of the puzzle you just created:

   chdv clsp curry ./reference_tails/genesis_by_coin_id.clsp.hex -a 0x --treehash

   h. Sign the treehash (you do not need 0x here) with the you noted above by running this command:

   chinilla keys sign -d -f -t m -b

   The last two flags are for the path and bytes. Make sure the resulting Public Key corresponds to the you just used. Copy the to use in the next step.

   i. Run the same "cats" command as above, but remove the --select-coin flag and add the --solution flag, passing in the you just calculated. This must be surrounded by quotes and parenthesis, and it must contain a solution, which we'll leave empty. Add the --signature flag as well, so the command looks like this:

   chcats --tail ./reference_tails/delegated_tail.clsp.hex --curry 0x --send-to -a -m --as-bytes --solution "( ())" --signature

   This command will give the following output:

   The transaction has been created, would you like to push it to the network? (Y/N)

   j. Enter Y.

   k. The output will be Asset ID: . Copy the , which you'll need in the next step. Meanwhile, the transaction to create your CAT is being pushed to the blockchain.

2. Add a wallet ID for your new CAT:

   a. Switch to the Chinilla GUI. Within a few minutes, your balance should decrease by the number of vojos you just minted. It might not show up in your transactions.

   b. Now you can add a wallet ID for your new CAT. In the upper left corner, click "+ ADD TOKEN", then click "+ Custom". Enter the name of your CAT (it can be anything) in the first text field. For the second text field, paste the you saved from a few steps ago. Click ADD.

   c. You will now be taken to your new CAT wallet. The balance should show the number of HCX vojos you chose to use, divided by 1000. This is because CAT vojos are one-thousandth of a CAT.

   d. If you see a Total Balance of 0, you need to refresh your wallet. Run chinilla start wallet-only -r. You should now see the correct balance.

   Just like the previous example, you now have access to your CAT in the GUI.

3. Because this CAT uses a delegated TAIL, you can issue new mintings by re-doing step 1 from this section. After you run the “cdv rpc pushtx” command, the balance in your CAT wallet will increase according to the new minting.

Submitting Your Token to the Database

To learn how to submit your token to the database, please see our tutorial here.