Subkey
Provides command-line reference information for using the subkey program to generate and manage keys.
The subkey program is a key generation and management utility that is included in the Substrate repository. You can use the subkey program to perform the following tasks:
Generate and inspect cryptographically-secure public and private key pairs.
Restore keys from secret phrases and raw seeds.
Sign and verify signatures on messages.
Sign and verify signatures for encoded transactions.
Derive hierarchical deterministic child key pairs.
Signature schemes
The subkey program currently supporting the following signature schemes:
sr25519: Schorr signatures on the Ristretto group.
ed25519: SHA-512 (SHA-2) on Curve25519.
secp256k1: ECDSA signatures on secp256k1.
In Substrate-based networks, the sr25519 encoded keys are used to produce SS58 addresses as the public keys for interacting with the blockchain.
Installation
You can download, install, and compile subkey using cargo without cloning the full Substrate repository. However, you must add Substrate build dependencies to your environment before you can install subkey as a standalone binary. To ensure dependencies are available, you can build the subkey binary from a clone of the Substrate repository.
To install and compile the subkey program:
Open a terminal shell, if necessary.
Verify that you have the Rust compiler and toolchain, if necessary.
Clone the Substrate repository, if necessary, by running the following command:
Change to the root directory of the Substrate repository by running the following command:
Compile the
subkeyprogram using thenightlytoolchain by running the following command:Because of the number of packages involved, compiling the program can take several minutes.
Verify that the
subkeyprogram is ready to use and view information about the options available by running the following command:
Hierarchical deterministic keys
The subkey program supports hierarchical deterministic keys. Hierarchical deterministic (HD) keys enable you to use a parent seed to derive child key pairs in a hierarchical tree structure. In this hierarchical structure, each child derived from a parent has its own key pair. The derived keys can also be used to derive additional child key pairs, similar to how a file system can have nested directories in a hierarchical directory structure. For background information about how hierarchical deterministic keys are derived, see the BIP32 specification for hierarchical deterministic wallets.
For information about deriving hierarchical deterministic keys using subkey commands, see Working with derived keys.
Basic command usage
The basic syntax for running subkey commands is:
Depending on the subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific subkey subcommand, specify the subcommand and the --help flag. For example, to see usage information for subkey inspect, you can run the following command:
Flags
You can use the following optional flags with the subkey command.
Subcommands
You can use the following subcommands with the subkey command. For reference information and examples that illustrate using subkey subcommands, select an appropriate command.
Output
Depending on the subcommand you specify, the output from the subkey program displays some or all of the following information:
Examples
To display version information for the subkey program, run the following command:
To display usage information for the subkey verify command, run the following command:
subkey generate
Use the subkey generate command to generate public and private keys and account addresses. You can use command-line options to generate keys with different signature schemes or mnemonic phrases with more or fewer words.
Basic usage
Flags
You can use the following optional flags with the subkey generate command.
Options
You can use the following command-line options with the subkey generate command.
Examples
To generate a new key pair that uses the sr25519 signature scheme, run the following command:
The command displays output similar to the following with a 12-word secret phrase:
The subkey program encodes the address associated with a public/private key pair differently depending on the format required for the network where it is used. If you want to use the same private key on the Kusama and Polkadot networks, you can use the --network option to generate the separate address formats for the Kusama and Polkadot networks. The public key is the same, but the address formats are network-specific. To generate a key pair for a specific network, run a command similar to the following:
The command displays the same fields as output, but uses the address format for the network you specify.
To generate a more secure key pair that uses the ed25519 signature scheme and an 24-word secret phrase for the moonriver network, you would run the following command:
The command displays the same fields as output, but uses the Ed25519 signature scheme, a 24-word secret phrase, and the address format for the moonriver network.
To generate a key that is password-protected, run the subkey generate command using the --password <password> option. For example:
After you generate a key that requires a password, you can retrieve it by including the --password option and password string in the command-line or by adding three slashes (///) at the end of the secret phrase. Remember that it is important to keep passwords, secret phrases, and secret seeds secure and to back them up in a secure location.
subkey generate-node-key
Use the subkey generate-node-key command to generate random public and private keys for peer-to-peer (libp2p) communication between Substrate nodes. The public key is the peer identifier that is used in chain specification files or as a command-line argument to identify a node participating in the blockchain network. In most cases, you run this command with a command-line option to save the private key to a file.
Basic usage
Flags
You can use the following optional flags with the subkey generate-node-key command.
Options
You can use the following command-line option with the subkey generate-node-key command.
Examples
To generate a random key pair for peer-to-peer communication and save the secret key in a file, run a command similar to the following:
This command displays the peer identifier for the node key in the terminal and the private key is saved in the generated-node-key file. In this example, the saved key in the parent directory instead of the current working directory.
subkey help
Use the subkey help command to display usage message for subkey or for a specified subcommand.
Basic usage
Examples
To display usage information for the verify subcommand, run the following command:
subkey inspect
Use the subkey inspect command to recalculate the public key and public address for specified secret key or mnemonic phrase.
Basic usage
Flags
You can use the following optional flags with the subkey inspect command.
Options
You can use the following command-line options with the subkey inspect command.
Arguments
You must specify the following required argument with the subkey inspect command.
Examples
To inspect the public keys derived from a mnemonic phrase, you can run a command similar to the following:
The command displays output similar to the following:
To inspect the public keys derived from a secret seed, you can run a command similar to the following:
If you store a secret phrase or secret seed in a text file—for example, my-secret-key—you can specify the file name on the command-line to pass the contents of the file and display the public keys associated with that secret phrase or secret seed. For example, you can run a command similar to the following:
To inspect the public keys using a hex-encoded public key, you can run a command similar to the following:
In this case, the command only displays public information similar to the following:
The subkey program encodes the address associated with a public/private key pair differently depending on the format required for the network where it is used. If you use the same private key on the Kusama and Polkadot networks, you can use the --network option to inspect the address used for a specific network. The public key is the same, but the address format is network-specific. To inspect a key pair for a specific network, run a command similar to the following:
In the command output, the secret phrase, secret seed, and public keys are the same, but the address for the Kusama network is:
To inspect the address for the same private key on the Polkadot network, you would run a command similar to the following:
In the command output, the secret phrase, secret seed, and public keys are the same as the Kusama network, but the address for the Polkadot network is:
To inspect password-protected keys by specifying the --password option and password, you can run a command similar to the following:
If you specify the --password option and password in the command-line, the command output does not display the password used.
You can also inspect password-protected keys by adding /// and the password to the secret phrase. For example, you can run a command similar to the following:
In this case, the command output displays the password used. For example:
subkey inspect-node-key
Use the subkey inspect-node-key command to display the peer identifier for the node that corresponds with the node key in the specified file name. Before using this command, you should have previously used the subkey generate-node-key command and saved the key to a file.
Basic usage
Flags
You can use the following optional flags with the subkey inspect-node-key command.
Options
You can use the following command-line option with the subkey inspect-node-key command.
Arguments
You must specify the following required argument with the subkey inspect-node-key command.
subkey sign
Use the subkey sign command to sign a message by passing the message as standard input (stdin). You can sign messages using your secret seed or secret phrase.
Basic usage
Flags
You can use the following optional flags with the subkey sign command.
Options
You can use the following command-line options with the subkey sign command.
Examples
The following example uses the echo command to pipe a test message as input to the subkey sign command. To sign a text message in a terminal, you can run a command similar to the following:
The command output displays the signature for the message. For example:
To sign a hex-encoded message, run a command similar to the following:
The command output displays the signature for the message. For example:
subkey vanity
Use the subkey vanity command to create an address that contains a specified string pattern. This command does not generate a secret phrase for the custom address.
Basic usage
Flags
You can use the following optional flags with the subkey vanity command.
Options
You can use the following command-line options with the subkey vanity command.
Arguments
You must specify the following required argument with the subkey vanity command.
Examples
Depending on the pattern you specify, the subkey vanity command can take some time to search keystores and generate an address that contains the custom string. In general, you should use as few characters as possible for the --pattern and use the --network option to specify the network where you want to use the custom address,
To generate an address that contains a specific string, you can run a command similar to the following:
The command displays output similar to the following:
After the key pair is generated, the SS58 address and public key both contain the custom string DUNE.
subkey verify
Use the subkey verify command to verify the signature for a message using a public or secret key.
Basic syntax
Flags
You can use the following optional flags with the subkey verify command.
Options
You can use the following command-line options with the subkey verify command.
Arguments
You must specify the following required argument with the subkey verify command.
Examples
The following example uses the echo command to pipe a test message as input to the subkey verify command.
If the message signature is verified, the command output confirms the signature, For example:
To verify the signature for a hex-encoded message, run a command similar to the following:
If the message signature is verified, the command output confirms the signature, For example:
Working with derived keys
In Substrate, hierarchical deterministic derived keys are classified as hard keys or as soft keys based on how they are derived. For example, hard keys can only be derived using the parent private key and a derivation path. The parent public key cannot be used to derive a hard key.
Soft keys can be derived using either the parent private key or the parent public key and a derivation path. Because soft keys can be derived using the parent public key, they can be used to identify the parent key without exposing the parent seed. You can derive either hard keys or soft keys by using different syntax in subkey commands. You can then use the addresses associated with derived keys to sign messages with the same security as messages signed by their root key.
Derive a hard key
To derive a hard child key pair, you add two slashes (//), a derivation path, and an index after the secret phrase associated with its parent key. Because you derive child key pairs and addresses from keys that have been previously generated, you use the subkey inspect command. For example:
The command displays output similar to the following:
Derive a soft key
To derive a soft child key pair from a parent private key, you add one slash (/), a derivation path, and an index after the secret phrase associated with the parent key. Because you are deriving a new key pair and address from a key that has been previously generated, you use the subkey inspect command. For example:
The command displays output similar to the following:
To derive a soft child key pair from a parent public key, you can use the public SS58 address instead of the secret phrase. Because you are deriving a soft key, you use a single slash (/) to delimit the derivation path and index fields. For example:
The command displays output similar to the following:
If you use the same derivation path and index, the soft child key is the same whether you use the parent private key or parent public address. If you change either the derivation path—for example, from derived-soft-key to derived-public—or the index—from 0 to 1—you derive different child keys with different addresses. For example:
The command displays output similar to the following:
Combine derivation paths and passwords
Note that the secret seed is not password protected by default. You can add a password as extra protection for your derived keys. However, the key pair that's derived from a secret seed is not the same as the key pair derived when you use a password. The same secret seed will derive different keys if you use a different derivation path or add a password. If you use a password to protect your key pair, both the secret seed phrase and the password will be required to recover the key pair.
You can derive a soft key as a child of a hard key. Doing so enables you to use the public address of the derived hard key—with an optional password—to derive new public addresses. For example, the following command derives a hard key (//derived-hard-key) with a soft key leaf (/0):
The command displays output similar to the following:
To protect the derived hard key, you can add your password to the end of the secret phrase:
The command displays output similar to the following:
Notice that adding a password for the derived key generates a different public key for the same secret phrase. You can use this password-protected hard key to derive a soft key using the public address of the hard key. a hidden seed, hard key derivation path, and a password.
The command displays output similar to the following:
With this strategy for combining hard and soft keys, you can reveal a parent public address and soft derivation paths without revealing your secret phrase or password, retaining control of all derived addresses.
Predefined accounts and keys
Substrate includes several predefined accounts that you can use for testing in a local development environment. These predefined accounts are all derived from the same seed using a single secret phrase. The secret phrase used to generate the keys for all of the predefined accounts consists of the following words:
You can inspect the keys for the predefined account using the derivation path. For example:
The command
It is important to note that //Alice and //alice are different derivation paths and the secret phrase and derivation path for the predefined account is actually:
You can run the following command to verify the keys match:
The command output displays the following:
Further resources
Last updated