CAT1 Snapshot Generation
CAT1 will reach its end of life at block 2,311,760, which will occur on July 26, 2022 at around 17:00 UTC.
For more information on this end-of-life process, see the Intro and FAQ page.
This document will show CAT1 issuers how to:
- Generate a snapshot of their CAT1 status. This will show the puzzle hash (address) and value of each individual token at the end-of-life block height
- Export their required data from the snapshot
After completing this, CAT issuers will be able to proceed to the Token Reissuance guide.
Generate a CAT1 Snapshot
We recommend that you follow this section to generate your own snapshot of your CAT1 tokens. Please note that this process could take over 40 hours to complete. For your convenience and reference, we will also publish our own snapshot, which should be identical to the snapshot that you produce.
This section will show you how to install the CAT-addresses tool and use it to get a snapshot of the puzzle hash (address) and value of each coin of a particular CAT1. It can even obtain this info for all CAT1s on Chia's blockchain.'
In order to use this tool, you are required to run a fully synced Chia node. This node must be running version 1.5 or greater. Please ensure that you have satisfied both of these requirements before continuing.
- Open a terminal window and ensure you have direct access to the
chia
command by doing one of the following:
- Windows
- Linux
- macOS
- If you previously installed Chia from a binary build, then set up an alias to the
chia
command:
Ensure that you replace <USERNAME>
and <VERSION>
with the actual folders
Set-Alias -Name chia "C:\Users\<USERNAME>\AppData\Local\chia-blockchain\app-<VERSION>\resources\app.asar.unpacked\daemon\chia.exe"
- If you previously installed Chia from source, then navigate to the
chia-blockchain
directory and activate your virtual environment:
.\venv\Scripts\Activate.ps1
-
If you previously installed Chia from a binary build, then ensure that the
chia
binary's directory is included in yourPATH
. -
If you previously installed Chia from source, then navigate to the
chia-blockchain
directory and activate your virtual environment:
. ./activate
- If you previously installed Chia from a binary build, then set up an alias to the
chia
command:
alias chia="/Applications/Chia.app/Contents/Resources/app.asar.unpacked/daemon/chia"
- If you previously installed Chia from source, then navigate to the
chia-blockchain
directory and activate your virtual environment:
. ./activate
-
Run the following command:
chia version
If step 1 was successful, you should see a version number in the output, such as
1.5.0
. This is a requirement for the snapshot tool to work. -
From the same terminal window, create a new directory in which to install the
CAT-addresses
repository (it can be in the parent directory) and run the following:git clone https://github.com/Chia-Network/CAT-addresses.git -b main
-
The following environment variables need to be set in order to use this tool:
FULL_NODE_HOSTNAME
- The hostname of the full node to call the RPCs against. This can belocalhost
.DB_SOURCE_DIR
- The location of the full node database on the host machine.START_HEIGHT
- The height of the blockchain to start creating the snapshot from (default:0
). If you are attempting to obtain all records for your CAT, the recommended start height is1146800
, which is just before CAT1 was introduced.TARGET_HEIGHT
- The height of the blockchain to end the snapshot (no default - must be set). The recommended height is2311760
, which is the last block at which CAT1 is valid.
cautionRunning this process with the recommended block heights could take over 40 hours to complete. You may wish to test it first by setting the
TARGET_HEIGHT
to1146900
. This will pull data from only 100 blocks, which should only take a few seconds.In order to set these variables, you are recommended to put them into a file called
.env
at the root of theCAT-addresses
project. The tool will automatically read the variables in this file. For example:
- Windows
- Linux
- macOS
FULL_NODE_HOSTNAME=localhost
DB_SOURCE_DIR=C:\Users\Username\.chia\mainnet\db
START_HEIGHT=1146800
TARGET_HEIGHT=2311760
FULL_NODE_HOSTNAME=localhost
DB_SOURCE_DIR=/home/Username/.chia/mainnet/db
START_HEIGHT=1146800
TARGET_HEIGHT=2311760
FULL_NODE_HOSTNAME=localhost
DB_SOURCE_DIR=/Users/Username/.chia/mainnet/db
START_HEIGHT=1146800
TARGET_HEIGHT=2311760
- Install dependencies:
- Windows
- Linux
- macOS
python setup.py install
python3 setup.py install
python3 setup.py install
The result may contain several warnings such as WARNING: The wheel package is not available.
These can be safely ignored.
This command may take a few minutes to complete. At the end of the output, you should see something like:
Finished processing dependencies for chia-transaction-exporter==0.1.dev55"
-
Install the
dotenv
andbackoff
modules:pip install python-dotenv
pip install backoff -
Set up the database:
- Windows
- Linux
- macOS
python setup_database.py
python3 setup_database.py
python3 setup_database.py
If you receive an error message such as ModuleNotFoundError: No module named 'chia'
, then make sure you can run the chia
command from this directory and try again.
If this command succeeds, then it will output:
INFO:setup_database:Setting up database
INFO:setup_database:Database setup complete
- Start the snapshot generator:
- Windows
- Linux
- macOS
python start.py
python3 start.py
python3 start.py
This command will show its progress according to the block height. If you used the recommended range for START_HEIGHT
and TARGET_HEIGHT
in your .env
file, then this command could take over 40 hours to complete. The reason it takes so long is it needs to process each block, one at a time. If multiple blocks were done in parallel, then there would be a chance that the results would not be accurate. By processing one block at a time, the tool will return the correct results for the range provided.
You can only generate a snapshot for each block once. If you attempt to run this command over a range against which it has already been run, you will receive an error containing this message:
sqlite3.IntegrityError: UNIQUE constraint failed: coin_create.coin_name
In this case, you either need to start from a higher height, or (recommended) start over. Follow the Data Cleanup section and try again.
Export Your Data from the Snapshot
Once you have populated the database with a snapshot, you can run a data export.
-
Navigate to taildatabase.com.
-
Search for your CAT. We'll use CAT King Cole for this example. Note the TAIL hash, which is listed above the title of the token. In this example, it's:
1121996b75cce3c746369aced2c8887b02b84e95592c3dc006d82a145adf349a
-
Generate a CSV file containing all inner puzzle hashes and amounts for your CAT:
- Windows
- Linux
- macOS
python export.py --output-dir <OUTPUT-DIR>\<PREFIX> --tail-hash <TAIL-HASH> --coins
Example command
python export.py --output-dir C:\Users\Username\Chia\CAT-addresses\results\CKC_ --tail-hash 1121996b75cce3c746369aced2c8887b02b84e95592c3dc006d82a145adf349a
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --tail-hash <TAIL-HASH> --coins
Example command
python3 export.py --output-dir /home/Username/CAT-addresses/results/CKC_ --tail-hash 1121996b75cce3c746369aced2c8887b02b84e95592c3dc006d82a145adf349a
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --tail-hash <TAIL-HASH> --coins
Example command
python3 export.py --output-dir /Users/Username/CAT-addresses/results/CKC_ --tail-hash 1121996b75cce3c746369aced2c8887b02b84e95592c3dc006d82a145adf349a
<OUTPUT-DIR>
- a directory of your choice in which to save the CSV file<PREFIX>
- a string to be prepended to the output file name<TAIL-HASH>
- the TAIL hash you obtained from taildatabase.com--coins
- an optional flag that will add information about individual coins to the output (which might be helpful for auditing purposes)
This command will not create any directories, so make sure <OUTPUT-DIR>
already exists before running it. Otherwise, you will receive a FileNotFoundError
.
Fix EOL Characters
This step is required for Windows users, and not needed for Linux or macOS users.
If you are running on Windows, the CSV file will contain an extra CR (carriage return) character at the end of each line. This will cause "Secure the Bag" to fail. First, you must convert the CSV file to use UNIX-style end-of-line characters.
The easiest way to accomplish this is with dos2unix
. This is not included with Windows, so you will need to download it from SourceForge.
Steps to convert the CSV file:
- Visit the SourceForge dos2unix site.
- Click the green "Download" button. After five seconds, the
dos2unix
zip file will be downloaded to your Downloads folder. - Unzip the
dos2unix
zip file. - From a PowerShell window, run:
<path to dos2unix.exe> -o <path to CSV file>
For example:
~\Downloads\dos2unix\bin\dos2unix.exe -o .\results\CKC_1121996b75cce3c746369aced2c8887b02b84e95592c3dc006d82a145adf349a.1658233083.183527.csv
This message should appear in the output:
dos2unix: converting file <CSV file> to Unix format...
- To verify that the conversion was successful, open the file. There should be no blank lines between the entries.
Data Cleanup
Optional: If the application exits partway through a run, it will only have imported some blocks at a particular height. You can delete the records from the database at and above a provided height by running the following command:
- Windows
- Linux
- macOS
python clean.py --height <BLOCK-HEIGHT>
python3 clean.py --height <BLOCK-HEIGHT>
python3 clean.py --height <BLOCK-HEIGHT>
Export Data for all CATs
Optional: If you wish to obtain the balance of all CATs on the Chia blockchain, you can run export-py
with various different options:
- Windows
- Linux
- macOS
The --tail-hash
flag can be dropped, resulting in an output of a single CSV file containing every puzzle hash amount for every CAT on the Chia blockchain:
python export.py --output-dir <OUTPUT-DIR>\<PREFIX>
The --coins
flag can be added, which will add information about individual coins:
python export.py --output-dir <OUTPUT-DIR>\<PREFIX> --coins
The --explode
flag can be added, which will generate multiple CSV files, each of which containing a single CAT's puzzle hashes and amounts:
python export.py --output-dir <OUTPUT-DIR>\<PREFIX> --explode
You can also use the --explode
and --coins
flags together, which will generate individual CSV files that also contain coin info.
The --tail-hash
flag can be dropped, resulting in an output of a single CSV file containing every puzzle hash amount for every CAT on the Chia blockchain:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX>
The --coins
flag can be added, which will add information about individual coins:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --coins
The --explode
flag can be added, which will generate multiple CSV files, each of which containing a single CAT's puzzle hashes and amounts:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --explode
You can also use the --explode
and --coins
flags together, which will generate individual CSV files that also contain coin info.
The --tail-hash
flag can be dropped, resulting in an output of a single CSV file containing every puzzle hash amount for every CAT on the Chia blockchain:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX>
The --coins
flag can be added, which will add information about individual coins:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --coins
The --explode
flag can be added, which will generate multiple CSV files, each of which containing a single CAT's puzzle hashes and amounts:
python3 export.py --output-dir <OUTPUT-DIR>/<PREFIX> --explode
You can also use the --explode
and --coins
flags together, which will generate individual CSV files that also contain coin info.