Introduce gring

Command-line tools for developers is an endless topic, maybe they are not that fancy for the non-technical modern browser users, but they still play a main role across the universe since we are lazy and developing and maintaining UI takes times ^ ^

For the command-line tool of vara network, we have already had the tool gcli with rich functionalities interacting with the network, but as it grows, in case of reducing the complexity of it, we just split out the keystore part and developed it as a lightweight keyring implementation.

Yes, gring is a keyring implementation in command line for managing your vara network keypairs!

$ gring
Gear keyring

Usage: gring [OPTIONS] <COMMAND>

Commands:
  add     Imports a keystore file generated by polakdot-js extension
  new     Generate a new key
  list    List all keys in keyring [aliases: l]
  use     Use the provided key as primary key
  sign    Sign a message
  verify  Verify a message
  help    Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose...  The verbosity level
  -h, --help        Print help

Keyring 101

Keyring is similar with blockchain wallet, but more flexible.

For the browser extensions of blockchain wallets, we are always asked to create an account first, remember, save your passphrase in case you lose it in the future, and then, the wallet will derive more and more keypairs from your root account on your demand.

What you may miss is that once you lose the passpharse of your root account, you will lose all of your keypairs in your wallet, and this is different in keyrings in general, each keypair in keyring has its own passphrase, if you lose one of the keypairs, others are still safe.

Keyring is actually similar with the common concept of the browser extension blockchain wallets, but more straightforward and flexible, what keyring does is just generating and storing your keypairs on disk, encrypt and decrypt them with cryptography.

Keystore 101

A keyring is a ring of keystores, just like blockchain is a chain of blocks.

Keystore stores the private keys of your keypairs with encryption, for gring, it follows the standard of the encryption of Polkadot-JS wallet in case users can share the keystore files between the two.

How it works

Here in this chapter, we are diving into the technical details of gring with examples.

1. Encrypt keypair into keystore

$ gring new -p password my-first-wallet

This command generates a keystore named my-first-keystore with passphrase password, dive into the details, the gring program does the following:

1. Generate a random schnorrkel keypair
2. Encode the keypair into a specified bytes format called keypair-info.

Keypair Info: [PAIR_HEADER, SECRET_KEY, DIVIDER, PUBLIC_KEY]

3. Encrypt the passphrase with scrypt to get a password for the secret box.
4. Pack the keypair-info in NaCl Secretbox with the passwored from 3.

After all, the encrypted keypair will be like:

In general, developers always embed more infomations about the keypair in the keystore file instead of raw encoded data for human readability, in polkadot-js or gring, it’s like

{
    "encoded": "<encrypted-keypair-in-base64>"
    "encoding": {
        "content": ["pkcs8", "sr25519"],
        "ty": ["scrypt", "xsalsa20-poly1305"],
        "version": "3"
    },
    "address": "<The-address-of-the-keypair-in-ss58>",
    "meta": {
        "name": "<the-name-of-the-keypair>"
    }
}

2. Decrypt keypair from keystore

This part is the reverse version of 1., it’s easy to go when you have the correct passpharse and matched keystore file, especially the encoded field in your keystore.json.

1. Decode the encoded field with base64 and get the secret box.
2. Get the first 32 bytes of the encoded data which is the scrypt config.
3. Derive the password of the secret box with the scrypt config and your passphrase.
4. Decode the nonce from the following encoded data.
5. Open the secret box with the correct nonce and password.

That’s all, Polkadot-JS follows the same flow that the keystores files from it are shared with gring.

And more …

There is no such kind of tools in polkadot ecosystem and that’s why we wrote it on our own, gring is a command of gcli as well, the keystore paths are shared! So ideally, you can use gring to manage your vara keys, and run gcli when you want to interact with vara network with your stored keypairs!

That’s it.