From e6c73e89513ea3b64d27392a098c2fb3292cc9d0 Mon Sep 17 00:00:00 2001
From: Logan Saether <lsaether@protonmail.com>
Date: Thu, 21 Mar 2019 10:44:39 +0100
Subject: [PATCH] update readme (#2066)

---
 substrate/subkey/README.adoc | 59 ++++++++++++++++++++++++++++--------
 1 file changed, 46 insertions(+), 13 deletions(-)

diff --git a/substrate/subkey/README.adoc b/substrate/subkey/README.adoc
index e895ab07ad..7fe194eb82 100644
--- a/substrate/subkey/README.adoc
+++ b/substrate/subkey/README.adoc
@@ -1,22 +1,55 @@
 = Subkey
 
-A key generation utility with vanity address support.
+Subkey is a commandline utility included with Substrate that generates or restores Substrate keys. 
 
-Usage:
+`subkey` will use the http://wiki.polkadot.network/en/latest/polkadot/learn/cryptography/#keypairs-and-signing[sr25519] cryptography by default. If you need to use the older ed25519 cryptography to generate or restore your key pass the `--ed25519` flag to any of the commands.
 
-	subkey <search string> <number of keys>
+== Usage
 
-Sample use:
+=== Generate a random account
 
-	$ subkey
-or
-	$ subkey polka
-or
-	$ subkey polka 3
+```bash
+subkey generate
+```
 
+Will output a mnemonic phrase and give you the seed, public key, and address of a new account. DO NOT SHARE your mnemonic or seed with ANYONE it will give them access to your funds. If someone is making a transfer to you they will only need your **Address**.
 
-Result:
+=== Inspecting a key
 
-	5CxS39ykKsmPetYQjTqW6aJXkSChnuvPdziA8uphuPaCyRZ1: 406ac59ccbb8358f7c95b726d3ccb039afe35e2dd62045189d1abae8d7805b8a (54%)
-	5CujMhFmChyq3AMUwMasfbqSpZYpbFfZS5UQ7zUn2d63CGBo: 5b6ac59ccbb8358f7c95b726d3ccb039afe35e2dd62045189d1abae8d7805b8a (69%)
-	5EfdN3zChABKsXT9bEg33zqPsBu4YCu1h7yoovvjtsUMqyFU: c46ac59ccbb8358f7c95b726d3ccb039afe35e2dd62045189d1abae8d7805b8a (69%)
+You can inspect a given URI (mnemonic, seed, public key, or address) and recover the public key and the address.
+
+```bash
+subkey inspect <mnemonic,seed,pubkey,address>
+
+OUTPUT:
+  Public key (hex): 0x461edcf1ba99e43f50dec4bdeb3d1a2cf521ad7c3cd0eeee5cd3314e50fd424c
+  Address (SS58): 5DeeNqcAcaHDSed2HYnqMDK7JHcvxZ5QUE9EKmjc5snvU6wF
+```
+
+=== Signing
+
+`subkey` expects a message to come in on STDIN, one way to sign a message would look like this:
+
+```bash
+echo <msg> | subkey sign <seed,mnemonic>
+
+OUTPUT:
+a69da4a6ccbf81dbbbfad235fa12cf8528c18012b991ae89214de8d20d29c1280576ced6eb38b7406d1b7e03231df6dd4a5257546ddad13259356e1c3adfb509
+```
+
+=== Verifying a signature
+
+```bash
+echo <msg> | subkey verify <sig> <address>
+
+OUTPUT:
+Signature verifies correctly.
+```
+
+=== Using the vanity generator
+
+You can use the included vanity generator to find a seed that provides an address which includes the desired pattern. Be warned, depending on your hardware this may take a while.
+
+```bash
+subkey vanity 1337
+```