In 2022, Chia built an internal solution for long-term storage of its prefarm. This tool has since been made public -- you can now lock your coins using the same solution as Chia used to lock its prefarm!
This guide will show you how to get started.
This tool was not originally developed with the broader ecosystem in mind. For this reason, the tool is provided as-is, with no guarantees of functionality, and with no support provided. Proceed with caution.
Before continuing, you might want to familiarize yourself with the following documents:
- Basic description of how the custody tool works
- Flow chart to visualize how the custody tool works
- CLI reference for all custody commands used in this tutorial
The custody tool uses many parameters, each of which is important. You are highly recommended to test the tool thoroughly on the testnet before deploying it on mainnet.
Install the custody tool
- A synced full node (mainnet, testnet, or simulator)
- A synced Chia wallet
- Python 3.9 or greater (will not work with 3.8.x)
- Git command line tool
- Powershell 6 or greater (Windows only)
- Visual C++ Redistributable (Windows only)
Steps to install
- Clone the internal custody repository:
git clone https://github.com/Chia-Network/internal-custody.git
- Change to the new directory:
- Create a new virtual environment and then activate it:
python -m venv venv
python3 -m venv venv
python3 -m venv venv
- Install the custody tool:
pip install --extra-index-url https://pypi.chia.net/simple/ chia-internal-custody
Note about pip warnings/errors
You may receive pip warning and/or dependency errors for blspy and/or clvm-tools-rs (see example below). These can be safely ignored.
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
chia-blockchain 1.3.6.dev212 requires blspy==1.0.13, but you have blspy 1.0.9 which is incompatible.
chia-blockchain 1.3.6.dev212 requires clvm-tools-rs==0.1.9, but you have clvm-tools-rs 0.1.7 which is incompatible.
Successfully installed blspy-1.0.9 clvm-tools-rs-0.1.7 hsms-0.1.dev79
- Test your installation:
If you get a usage statement, then
cic (Chia Internal Custody) has been installed properly.
cic commands for generating and signing keys are meant to be run from inside a Hardware Security Module (HSM). These commands are labeled as such.
An HSM is a physical/offline security solution for creating and using cryptographic signatures. While testing the custody tool, it is OK to run these commands from a normal computer. However, for maximum security while running the custody tool on Chia's mainnet, you are recommended to use an HSM (or a similar solution).
Most of the commands from this tutorial will not alter the blockchain. This includes all of the commands to be run from an HSM. Commands that will alter the blockchain are labeled as such.
Windows uses different line endings than Linux and MacOS. If you only plan to use Windows for both generating and signing spend bundles, this won't be a problem.
However, if you plan to generate your spend bundles on Windows and sign them using a Linux HSM, then you will need to modify the line endings before signing.
The easiest way to accomplish this is with
This is not included with Windows, so you will need to download it from SourceForge.
The command to convert your spend bundles is then:
<path to dos2unix.exe> -o <path to spend bundle>
In general, any time you encounter signing errors, be sure the correct line endings are being used for the OS you are using to sign.
- These commands will not modify the blockchain. They will only create local files
- These commands should be run from an HSM
Before the custody singleton can be created, you must first create the public/private key pairs to be associated with it.
For this guide:
mwill initially be set to 2. This is security level, or "lock level" of the singleton. In other words, it's the number of keys required to sign for withdrawals and standard rekeys.
nwill initially be set to 3. This is the maximum lock level of the singleton. In other words, it's the total number of keys that will be associated with the singleton.
nwill initially be 3, we will create 3 keys now.
nwill be used later when setting up the singleton.
When creating and using these keys on mainnet, you should only store one key on each computer. Signing therefore requires copying an unsigned spend bundle to each individual computer that holds a key. This process is explained in detail later in the guide.
However, for this guide, we'll assume you're running an initial test using TXCH (and not actual XCH). In this case, it's OK to store multiple keys on the same computer while you get a feel for how the tool works.
The command used to generate "secret exponents" (private keys) is
hsmgen. This command is included with the
cic installation. It doesn't take any arguments; it merely generates a secret exponent and outputs it to the command line. However, we want to save the secret exponents to files, so we will use the
> key to redirect the output.
We will create three separate keys. These can be named anything. For this guide we'll simply use numbers.
- Create a directory to hold your keys and spend bundles:
- Change to the new directory:
- Create and redirect the secret exponents:
hsmgen > 1.se