跳到主要内容

Custody Tool

Intro

Chia's internal custody tool enables multisig, clawback, and rekeying. These features allow you to store assets on Chia's blockchain in one of the most secure setups ever devised.

This page includes a comprehensive list of Chia's Command Line Interface commands for using the custody tool.

For more info, see the following:

Reference

audit

Functionality: Export a history of the singleton to a CSV

Usage: cic audit [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-f--filepathTEXTFalseThe file path the dump the audit log
-d--diffTEXTFalseA previous audit log to diff against this one
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic audit -db './sync (b43314).sqlite'

Response:

[
{
"time": 1665430389,
"action": "HANDLE_PAYMENT",
"params": {
"out_amount": 1000000000,
"recipient_ph": "3377e81d20ad9a3028ffe7e77360c03df48c412f2525aac58035738888adb83d",
"in_amount": 1000000000000,
"completed": true,
"spent_at_height": 1645707
}
},
{
"time": 1665449184,
"action": "HANDLE_PAYMENT",
"params": {
"out_amount": 1000000000,
"recipient_ph": "3377e81d20ad9a3028ffe7e77360c03df48c412f2525aac58035738888adb83d",
"completed": false,
"spent_at_height": 1645981,
"clawback_pubkey": "bls12381jjh08qx6hvucdrkgn8mrkafqrrp4j6sm4azndk0wz3precaa0teeyeamwtltxv435tsmx2tyayrwg8jy3x4"
}
},
{
"time": 1665980779,
"action": "START_REKEY",
"params": {
"from_root": "74905b06591f9d2e615d313d18cfbcbeffcaabe2e70ccdeafda783bacaae52ef",
"to_root": "90ba2a1ce4ca7f094aa1d2c64b7281b18a4e211e704b43ed45bf39f61cdd67d2",
"completed": true,
"spent_at_height": 1674754
}
},
{
"time": 1665986686,
"action": "START_REKEY",
"params": {
"from_root": "90ba2a1ce4ca7f094aa1d2c64b7281b18a4e211e704b43ed45bf39f61cdd67d2",
"to_root": "c330a8f9ed6a3fd50953f0b6365019246ea08d854ddbed0da3149dd4006abf1f",
"completed": true,
"spent_at_height": 1674940
}
}
]

clawback

Functionality: Clawback a withdrawal or rekey attempt (will be prompted which one)

Usage: cic clawback [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-f--filenameTEXTFalseThe filepath to dump the spend bundle into
-pks--pubkeysTEXTTrueA comma separated list of pubkeys that will be signing this spend
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic clawback -f clawback.unsigned -pks "1.pk,2.pk"

Response:

None


complete

Functionality: Complete a withdrawal or rekey attempt (will be prompted which one)

Usage: cic complete [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-f--filenameTEXTFalseThe filepath to dump the spend bundle into
-h--helpNoneFalseShow a help message and exit
Example -- complete a withdrawal

Request:

cic complete -f complete.signed

Response:

Which actions would you like to complete?:

1) PAYMENT to xch1xdm7s8fq4kdrq28lulnhxcxq8h6gcsf0y5j643vqx4ec3z9dhq7sqxsa9j of amount 1000000000
(Enter index of action to complete): 1
Successfully wrote spend to complete.signed

derive_root

Functionality: Take an existing configuration and pubkey set to derive a puzzle root

Usage: cic derive_root [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-c--configurationTEXTFalseThe configuration file with which to derive the root (or the filepath to create it at if using --db-path) [default: ./Configuration (needs derivation).txt]
-db--db-pathTEXTFalseOptionally specify a DB path to find the configuration from
-pks--pubkeysTEXTTrueA comma separated list of pubkey files that will control this money
-m--initial-lock-levelTEXTTrueThe initial number of pubkeys required to do a withdrawal or standard rekey
-n--maximum-lock-levelTEXTFalseThe maximum number of pubkeys required to do a withdrawal or standard rekey
-min--minimum-pksINTEGERFalseThe minimum number of pubkeys required to initiate a slow rekey [default: 1]
-va--validate-againstTEXTFalseSpecify a configuration file to check whether it matches the specified parameters
-h--helpNoneFalseShow a help message and exit
Example -- set up a 2-of-3 root config

Request:

cic derive_root -pks "1.pk,2.pk,3.pk" -m 2 -n 3

Response:

Custody rules successfully added to configuration

examine_spend

Functionality: Examine an unsigned spend bundle to see the details before you sign it

Usage: cic examine_spend [OPTIONS] SPEND_FILE

Options:

Short CommandLong CommandTypeRequiredDescription
--qr-densityINTEGERFalseThe amount of bytes to pack into a single QR code [default: 250]
-va--validate-againstTEXTFalseA new configuration file to check against requests for rekeys
-h--helpNoneFalseShow a help message and exit

SPEND_FILE is an unsigned spend bundle. This command will convert the spend bundle into a QR code and open it into a web browser for printing. You can then scan this QR code, for example using an HSM's QR scanner, for easier signing.

Example -- examine a rekey spend bundle

Request:

cic examine_spend ./rekey.unsigned

Response:

Type: Rekey
From: 74905b06591f9d2e615d313d18cfbcbeffcaabe2e70ccdeafda783bacaae52ef
To: 90ba2a1ce4ca7f094aa1d2c64b7281b18a4e211e704b43ed45bf39f61cdd67d2
Slow factor: 1
Spenders: bls12381jjh08qx6hvucdrkgn8mrkafqrrp4j6sm4azndk0wz3precaa0teeyeamwtltxv435tsmx2tyayrwg8jy3x4
Press Enter to exit

export_config

Functionality: Export a copy of the current DB's config

Usage: cic export_config [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-f--filenameTEXTFalseThe file path to export the config to (default: ./Configuration Export (******).sqlite)
-db--db-pathTEXTTrueThe file path to initialize/find the sync database at (default: ./sync (******).sqlite)
-p--publicNoneFalseEnable to export the public information only (default: disabled)
-h--helpNoneFalseShow a help message and exit
Example -- export the config to export.bin

Request:

cic export_config -p -f export.bin

Response:

Config successfully exported to export.bin

increase_security_level

Functionality: Initiate an increase of the number of keys required for withdrawal

Usage: cic increase_security_level [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-pks--pubkeysTEXTTrueA comma separated list of pubkeys that will be signing this spend
-f--filenameTEXTFalseThe filepath to dump the spend bundle into
-h--helpNoneFalseShow a help message and exit
Example -- move to a 4-of-5 config

Request:

cic increase_security_level -db './sync (b43314).sqlite' -pks "1_new.pk,2_new.pk,3_new.pk,4_new.pk" -f lock.unsigned

Response:

Successfully wrote spend to lock.unsigned

init

Functionality: Create a configuration file for the prefarm. The arguments from this command will be committed to forever.

Usage: cic init [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-d--directoryTEXTFalseThe directory in which to create the configuration file [default: .]
-wt--withdrawal-timelockTEXTTrueThe amount of time where nothing has happened before a withdrawal can be made (in seconds)
-pc--payment-clawbackTEXTTrueThe amount of time to clawback a payment before it's completed (in seconds)
-rc--rekey-cancelTEXTTrueThe amount of time to cancel a rekey before it's completed (in seconds)
-rt--rekey-timelockTEXTTrueThe amount of time where nothing has happened before a standard rekey can be initiated (in seconds)
-sp--slow-penaltyTEXTTrueThe time penalty for performing a slow rekey (in seconds)
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic init -d . -wt 600 -pc 1200 -rt 300 -rc 600 -sp 900

Response:

A binary file called Configuration (needs derivation).txt will be created in the -d location.


launch_singleton

Functionality: Use 1 mojo to launch the singleton that will control the funds

Note: This is one of the two commands (along with push_tx) that interacts directly with the blockchain

Usage: cic launch_singleton [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-c--configurationTEXTTrueThe configuration file with which to launch the singleton
-db--db-pathTEXTTrueThe file path to initialize the sync database at
-wp--wallet-rpc-portINTEGERFalseSet the port where the Wallet is hosting the RPC interface. See the rpc_port under wallet in config.yaml
-f--fingerprintINTEGERFalseSet the fingerprint to specify which wallet to use
-np--node-rpc-portINTEGERFalseSet the port where the Node is hosting the RPC interface. See the rpc_port under full_node in config.yaml
--feeINTEGERFalseFee to use for the launch transaction (in mojos) [default: 0]
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic launch_singleton --fee 10000000

Response:

Singleton successfully launched

p2_address

Functionality: Print the address to pay to the singleton

Usage: cic p2_address [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-p--prefixTEXTFalseThe prefix to use when encoding the address (default: xch)
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic p2_address --prefix txch

Response:

An address beginning with txch will be output


payment

Functionality: Absorb/Withdraw money into/from the singleton

Usage: cic payment [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-f--filenameTEXTFalseThe filepath to dump the spend bundle into
-pks--pubkeysTEXTTrueA comma separated list of pubkeys that will be signing this spend
-a--amountINTEGERFalseThe outgoing amount (in mojos) to pay [default: 0]
-t--recipient-addressTEXTTrueThe address that can claim the money after the clawback period is over (must be supplied if amount is > 0)
-ap--absorb-available-paymentsNoneFalseLook for any outstanding payments to the singleton and claim them while doing this spend (adds tx cost) [default: false]
-mc--maximum-extra-costINTEGERFalseThe maximum extra tx cost to be taken on while absorbing payments (as an estimated percentage) [default: 50]
-at--amount-thresholdINTEGERFalseThe minimum amount required of a payment in order for it to be absorbed [default: 1000000000000 or 1 XCH][0 means "absorb everything"]
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic payment -f withdrawal.unsigned -pks "1.pk,2.pk" -a 1000000000 -t <recipient address> -ap

Response:

Successfully wrote spend to withdrawal.unsigned

push_tx

Functionality: Push a signed spend bundle to the network

Note: This is one of the two commands (along with launch_singleton) that interacts directly with the blockchain

Usage: cic push_tx [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-b--spend-bundleTEXTTrueThe signed spend bundle
-wp--wallet-rpc-portINTEGERFalseSet the port where the Wallet is hosting the RPC interface. See the rpc_port under wallet in config.yaml
-f--fingerprintINTEGERFalseSet the fingerprint to specify which wallet to use
-np--node-rpc-portINTEGERFalseSet the port where the Node is hosting the RPC interface. See the rpc_port under full_node in config.yaml
-m--feeINTEGERFalseThe fee to attach to this spend (in mojos)
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic push_tx -b ./complete.signed -m 10000000

Response:

{'status': 'SUCCESS', 'success': True}

show

Functionality: Show the status of the singleton, payments, and rekeys

Usage: cic show [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (**).sqlite) [required]
-c--configNoneFalseEnable to display the details of the public config (default: disabled)
-d--derivationNoneFalseEnable to display the private details of the private config (default: disabled)
-h--helpNoneFalseShow a help message and exit
Example -- show the configuration and derivation

Request:

cic show -c -d

Response:

Current time: 1665072285 (10/07/2022, 00:04:45)

Config up to date: True

Singleton:
- launcher ID: b433146cc20ef0e3d962423ddb1c6868cd9691e099ae579ab2518d1cd983885c
- amount left: 0
- amount to claim: 0

Outstanding events:
PAYMENTS:
REKEYS:

Config:
- current root: 74905b06591f9d2e615d313d18cfbcbeffcaabe2e70ccdeafda783bacaae52ef
- withdrawal timelock: 600 seconds
- payment clawback period: 1200 seconds
- rekey cancellation period: 600 seconds

Derivation Info:
- lock level: 2
- max lock level: 3
- min keys to rekey: 1
- standard rekey timelock: 300 seconds
- slow rekey penalty: 900 seconds
- pubkeys:
- bls123813p8yljrhgskmgqeukg3x6mszh3xtqwwx35t4g6dt0mk2xecyj7elr0fhhrm8t3w7q5zhdelgjlgdspjqxvs
- bls123813uhsu0juw06z8vmtt5ncj6zcexmhtsfemvtj3jhv0vuxh9nqjdar59yh555muzrdpz2uflgzey3sgdnm8y9
- bls1238152jm50wh89tf70mwj4ncuukqcq6jqmf7pjgznm55c5qaggrvswzccwvsjgwmy9f4cvlx2j97kmh5uc2es6h

start_rekey

Functionality: Rekey the singleton to a new set of keys/options

Usage: cic start_rekey [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-db--db-pathTEXTTrueThe file path to the sync DB (default: ./sync (******).sqlite)
-f--filenameTEXTFalseThe filepath to dump the spend bundle into
-pks--pubkeysTEXTTrueA comma separated list of pubkeys that will be signing this spend
-new--new-configurationTEXTTrueThe configuration you would like to rekey the singleton to
-h--helpNoneFalseShow a help message and exit
Example

Request:

cic start_rekey -f rekey.unsigned -pks "1.pk,2.pk" -new './Configuration (after rekey).txt'

Response:

Successfully wrote spend to rekey.unsigned

sync

Functionality: Sync a singleton from an existing configuration

Usage: cic sync [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-c--configurationTEXTFalseThe configuration file with which to initialize a sync database (default: ./Configuration (******).txt)
-db--db-pathTEXTTrueThe file path to initialize/find the sync database at (default: ./sync (******).sqlite)
-np--node-rpc-portINTEGERFalseSet the port where the Node is hosting the RPC interface. See the rpc_port under full_node in config.yaml
-s--showNoneFalseEnable to show a summary of the singleton after sync is complete (default: disabled)
-h--helpNoneFalseShow a help message and exit
Example -- sync and show the config

Request:

cic sync -s

Response:

Current time: 1665072029 (10/07/2022, 00:00:29)

Config up to date: True

Singleton:
- launcher ID: b433146cc20ef0e3d962423ddb1c6868cd9691e099ae579ab2518d1cd983885c
- amount left: 0
- amount to claim: 0

Outstanding events:
PAYMENTS:
REKEYS:

update_config

Functionality: Update an outdated config in a sync DB with a new config

Usage: cic update_config [OPTIONS]

Options:

Short CommandLong CommandTypeRequiredDescription
-c--configurationTEXTFalseThe configuration file with which to initialize a sync database (default: ./Configuration (******).txt)
-db--db-pathTEXTTrueThe file path to initialize/find the sync database at (default: ./sync (******).sqlite)
-h--helpNoneFalseShow a help message and exit
Example -- update config after rekey

Request:

cic update_config -c './Configuration (after rekey).txt'

Response:

Configuration update successful

which_pubkeys

Functionality: Determine which pubkeys make up an aggregate pubkey

Usage: cic which_pubkeys [OPTIONS] AGGREGATE_PUBKEY

Options:

Short CommandLong CommandTypeRequiredDescription
-pks--pubkeysTEXTTrueA comma separated list of pubkey files that may be in the aggregate
-m--num-pubkeysINTEGERFalseCheck only combinations of a specific number of pubkeys
--no-offsetNoneFalseDo not try the synthetic versions of the pubkeys
-h--helpNoneFalseShow a help message and exit

HSM CLI commands and reference

These commands are to be run from inside the Hardware Security Module or "vault".

This is a physical/offline security solution for generating and signing keys.

Reference

hsmgen

Functionality: Generate a secret exponent (private key)

Usage: hsmgen

There are no options with this command. It will simply generate and display a single secret exponent.

Example 1 -- display key

The basic command displays a new secret exponent.

Request:

hsmgen

Response:

se12celrk5asn0f3w49dxpxe5hg6sg88ezdvp89hpgdqspwj6e03yfq9e6yw4
Example 2 -- save a key to a file

Request:

hsmgen > test.se

Response:

The secret exponent is saved to test.se.


hsmpk

Functionality: Derive a public key from a secret exponent

Usage: hsmgen <secret exponent>

A secret exponent (required) is the only argument allowed.

Example 1

Derive and display a public key from a file containing a secret exponent:

hsmpk $(cat test.se)

Response:

bls123813eh73c2cttvqytzjfnjdhnme7ah8mzsc9yzsf2y40mvhfa9rt5nha20jw50ld8h98w9u2wc0wxxl6gttqcr
Example 2

Calculate a public key from a file containing a secret exponent and save it to another file:

hsmpk $(cat test.se) > test.pk

Response:

The public key is saved to test.pk.


hsms

Functionality: Manage private keys and process signing requests

Usage: hsms0 [-h] [-c CREATE_PRIVATE_KEY] [-g GPG_ARGUMENT] path-to-private-keys

Positional arguments:

path-to-private-keys: A file containing bech32m-encoded secret exponents. If file name ends with .gpg, "gpg -d" will be invoked automatically. File is read one line at a time.

Options:

Short CommandLong CommandTypeRequiredDescription
-y--yesNoneFalseEnable to skip confirmations (default: disabled)
--qrNoneFalseEnable to show signature as QR code (default: disabled)
--nochunksNoneFalseEnable to read the spend in its entirety rather than as chunks (testing only) argument to pass to gpg (besides -d). (default: disabled)
-c--create-private-keyTEXTFalseCreate keys for non-existent files
-g--gpg-argumentTEXTFalseArgument to pass to gpg (besides -d)
-h--helpNoneFalseShow a help message and exit

This command is normally run from an HSM with a QR scanner attached. On Linux, this command will display a QR code to the screen to be scanned. On Windows, the QR display isn't working.

Example 1

This example will block until the scan is complete.

Run the basic command and wait for the QR code to be scanned:

hsms ./1.se

Response:

waiting for qrint-encoded signing requests
Example 2

This example will not block.

Pipe the unsigned spend bundle through hsms0, which will output a signature encoded in base-64 (it might instead be in base-10), along with a QR code (Linux only): Mock run by just piping the output of 1.se:

cat ./initial_absorb.unsigned | hsms -y --nochunks ./1.se

Response:

waiting for qrint-encoded signing requests
> 5449140665451649053284096202714691505589365577374007143978191719238477924138728005883662232162434514948867447203715240045617130770165403282022693823446338843409368762077191699285534081208295847253913527216165034379061118404584995264580179968

hsmmerge

Functionality: Create a signed Spend Bundle from UnsignedSpends and signatures.

Usage: hsmmerge [-h] path-to-unsigned-spend-as-hex hex-encoded-signature [hex-encoded-signature ...]

Positional arguments:

path-to-unsigned-spend-as-hex: A file containing hex-encoded UnsignedSpends hex-encoded-signature: A hex-encoded signature

Optional arguments: -h, --help show a help message and exit

Note that hex-encoded-signature is a list. To add more signatures, append more arguments.

Example

Create a signed spend bundle from two signatures and output to a text file:

hsmmerge ./initial_absorb.unsigned ./initial_absorb.sig ./initial_absorb_2.sig > initial_absorb.signed

Response:

The signed spend bundle is saved to initial_absorb.signed.


hsm_dump_sb

Functionality: Dump information about Spend Bundle

Usage: hsm_dump_sb [-h] hex-encoded-spend-bundle-or-file

Positional arguments:

hex-encoded-spend-bundle-or-file: A hex-encoded Spend Bundle. Can be a file containing the spend bundle.

Optional arguments:

-h, --help show a help message and exit

Example

Request:

hsm_dump_sb ./initial_absorb.signed

Response:

The signed spend bundle is output.


hsm_test_spend

Functionality: Generate a UnsignedSpend test as a proof-of-concept

Usage: hsm_test_spend [-h] path-to-public-key [path-to-public-key ...]

Positional arguments:

path-to-public-key: A file containing a single bech32m-encoded public key

Optional arguments:

-h, --help show a help message and exit

Example

Request:

hsm_test_spend test.pk

Response:

An unsigned spend bundle is output.