Add gring (#647)

docs/api/tooling/react-hooks.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 sidebar_label: React-hooks
 ---
 

docs/gcli/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Gear-CLI Tools",
+    "position": 9
+  }
+

docs/gcli/gring.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 3
+sidebar_label: Keystore Manager
+---
+
+# `gring` - a Gear Keystore Manager
+
+Command-line tools for developers remain an expansive subject. While these may not appeal to non-technical, modern browser users, command-line tools continue to play a pivotal role universally. This prevalence is partly because developing and maintaining user interfaces is time-consuming.
+
+For the [Vara Network](https://vara.network), the command-line tool, [`gcli`](https://crates.io/crates/gcli), has provided comprehensive functionality for interacting with the network. However, to simplify and manage growth, the keystore component has been separated and developed into a standalone, lightweight keyring implementation.
+
+[`Gring`](https://crates.io/crates/gring) is this command-line keyring implementation, designed specifically for managing Vara Network keypairs.
+
+```text
+$ 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
+
+> A keyring shares similarities with a blockchain wallet, offering greater flexibility.
+
+For blockchain wallet browser extensions, the initial step involves creating an account, remembering, and securely saving the passphrase to avoid future loss. Subsequently, the wallet generates additional keypairs from the root account upon request.
+
+A critical point often overlooked is the loss of the passphrase for the root account results in the loss of all keypairs within the wallet. In contrast, keyrings operate differently; each keypair in a keyring possesses its own passphrase. Losing one keypair does not compromise the security of others.
+
+|                       | Keyring | Wallet |
+|-----------------------|---------|--------|
+| Multiple Keypairs     | Yes     | Yes    |
+| Standalone Passphrase | Yes     | No     |
+
+**Keyring** aligns with the basic concept of browser extension blockchain wallets but is more straightforward and flexible. Keyring's primary function is to generate and store keypairs on disk, encrypting and decrypting them with cryptography.
+
+## Keystore 101
+
+> A **keyring** is a ring of **keystores**, analogous to how a blockchain comprises a series of blocks.
+
+A keystore secures the private keys of keypairs through encryption. For `gring`, adherence to the encryption standard of the **Polkadot-JS wallet** is maintained, facilitating the sharing of keystore files between the two systems.
+
+## How it works
+
+This chapter delves into the technical specifics of `gring`, illustrated with examples.
+
+### Encrypt keypair into keystore
+
+```bash
+$ gring new -p password my-first-wallet
+```
+This command creates a keystore named `my-first-keystore` using the passphrase `password`. Delving into the details, the gring program performs the following actions:
+
+1. Generates a random [schnorrkel][https://github.com/w3f/schnorrkel] keypair.
+2. Encodes the keypair into a specific byte format termed **keypair-info**.
+
+```text
+Keypair Info: [PAIR_HEADER, SECRET_KEY, DIVIDER, PUBLIC_KEY]
+```
+
+3. Encrypt the `passphrase` with [scrypt][https://en.wikipedia.org/wiki/Scrypt] to get a password for the secret box. 
+4. Pack the `keypair-info` in [NaCl Secretbox][https://en.wikipedia.org/wiki/NaCl_(software)] with the passwored from `3.`
+
+After all, the encrypted keypair will be like:
+
+| slot  | 1             | 2            | 3                                                       |
+|-------|---------------|--------------|---------------------------------------------------------|
+| bytes | scrypt config | random nonce | secret box (keypaire-info, nonce, encrypted_passphrase) |
+
+Generally, developers include additional information about the keypair in the keystore file, rather than just the raw encoded data, to enhance human readability. In **Polkadot-js** or **`gring`**, this is accomplished as follows:
+
+```json
+{
+    "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>"
+    }
+}
+```
+
+### Decrypt Keypair from Keystore
+
+This section describes the inverse process of section `1.` It becomes straightforward when the correct passphrase and corresponding keystore file are available, particularly the `encoded` field in your `keystore.json`.
+
+1. Decode the `encoded` field using `base64` to retrieve the **secret box**.
+2. Extract the first 32 bytes of the encoded data, which represent the scrypt configuration.
+3. Use the scrypt configuration and your passphrase to derive the **secret box** `password`.
+4. Decode the `nonce` from the subsequent encoded data.
+5. Unlock the secret box using the correct `nonce` and `password`.
+
+This completes the process. Polkadot-JS adopts a similar approach, allowing keystore files to be shared with gring.
+
+## And more ...
+
+Within the Polkadot ecosystem, there was no existing tool fulfilling this need, prompting the development of `gring`. `gring` serves as a command within `gcli`, sharing keystore paths. Ideally, `gring` can be utilized to manage Vara keys, and `gcli` can be used for interactions with the Vara network using stored keypairs.

docs/gear-networks/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Gear-based Networks",
-  "position": 10
+  "position": 11
 }

docs/general/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "General topics",
-  "position": 9
+  "position": 10
 }