md formatting for clef docs

content/docs/monitoring/dashboards.md

@@ -1,10 +1,9 @@
 ---
 title: Monitoring Geth with InfluxDB and Grafana
+description: introduction to monitoring Geth nodes with Grafana
 ---
 
-There are several ways to monitor the performance of a Geth node. Insights into a node's 
+There are several ways to monitor the performance of a Geth node. Insights into a node's performance are useful for debugging, tuning and understanding what is really happening when Geth is running. 
-performance are useful for debugging, tuning and understanding what is really happening when
-Geth is running. 
 
 ## Prerequisites {#prerequisites}
 
@@ -13,14 +12,11 @@ To follow along with the instructions on this page it will be useful to have:
 - a running Geth instance.
 - basic working knowlegde of bash/terminal.
 
-[This video](https://www.youtube.com/watch?v=cOBab8IJMYI) provides an excellent introduction 
+[This video](https://www.youtube.com/watch?v=cOBab8IJMYI) provides an excellent introduction to Geth monitoring.
-to Geth monitoring.
 
 ## Monitoring stack {#monitoring-stack}
 
-An Ethereum client collects lots of data which can be read in the form of a chronological 
+An Ethereum client collects lots of data which can be read in the form of a chronological database. To make monitoring easier, this data can be fed into data visualisation software. There are many options available:
-database. To make monitoring easier, this data can be fed into data visualisation software. 
-There are many options available:
 
 - [Prometheus](https://prometheus.io/) (pull model)
 - [InfluxDB](https://www.influxdata.com/get-influxdb/) (push model)
@@ -29,18 +25,13 @@ There are many options available:
 - [Datadog](https://www.datadoghq.com/)
 - [Chronograf](https://www.influxdata.com/time-series-platform/chronograf/)
 
-There's also [Geth Prometheus Exporter](https://github.com/hunterlong/gethexporter), an option 
+There's also [Geth Prometheus Exporter](https://github.com/hunterlong/gethexporter), an option preconfigured with InfluxDB and Grafana. You can set it up easily using docker and [Ethbian OS](https://ethbian.org/index.html) for RPi 4.
-preconfigured with InfluxDB and Grafana. You can set it up easily using docker and 
-[Ethbian OS](https://ethbian.org/index.html) for RPi 4.
 
-On this page, a Geth client will be configured to push data into a InfluxDB database and 
+On this page, a Geth client will be configured to push data into a InfluxDB database and Grafana will be used to visualize the data.
-Grafana will be used to visualize the data.
 
 ## Setting up InfluxDB {#setting-up-influxdb}
 
-InfluxDB can be downloaded from the [Influxdata release page](https://portal.influxdata.com/downloads/). 
+InfluxDB can be downloaded from the [Influxdata release page](https://portal.influxdata.com/downloads/). It can also be installed from a [repository](https://repos.influxdata.com/). For example for a Debian based Linux operating system:
-It can also be installed from a [repository](https://repos.influxdata.com/). 
-For example for a Debian based Linux operating system:
 
 ```sh
 curl -tlsv1.3 --proto =https -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add
@@ -53,8 +44,7 @@ sudo systemctl start influxdb
 sudo apt install influxdb-client
 ```
 
-By default,InfluxDB it is reachable at `localhost:8086`. Before using the `influx` client, a new user with admin privileges
+By default,InfluxDB it is reachable at `localhost:8086`. Before using the `influx` client, a new user with admin privileges needs to be created. This user will serve for high level management, creating databases and users.
-needs to be created. This user will serve for high level management, creating databases and users.
 
 ```sh
 curl -XPOST "http://localhost:8086/query" --data-urlencode "q=CREATE USER username WITH PASSWORD 'password' WITH ALL PRIVILEGES"
@@ -90,10 +80,7 @@ InfluxDB is running and configured to store metrics from Geth.
 
 ## Preparing Geth {#preparing-geth}
 
-After setting up database, metrics need to be enabled in Geth. Various options are available, 
+After setting up database, metrics need to be enabled in Geth. Various options are available, as documented in the `METRICS AND STATS OPTIONS` in `geth --help` and in our [metrics page](). In this case Geth will be configured to push data into InfluxDB. Basic setup specifies the endpoint where InfluxDB is reachable and authenticates the database.
-as documented in the `METRICS AND STATS OPTIONS` in `geth --help` and in our [metrics page](). 
-In this case Geth will be configured to push data into InfluxDB. Basic setup specifies the endpoint 
-where InfluxDB is reachable and authenticates the database.
 
 ```sh
 geth --metrics --metrics.influxdb --metrics.influxdb.endpoint "http://0.0.0.0:8086" --metrics.influxdb.username "geth" --metrics.influxdb.password "chosenpassword"
@@ -110,12 +97,9 @@ show measurements
 
 ## Setting up Grafana {#setting-up-grafana}
 
-With the InfluxDB database setup and successfully receiving data from Geth, the next step is to 
+With the InfluxDB database setup and successfully receiving data from Geth, the next step is to install Grafana so that the data can be visualized. Instructions for specific operating systems are available on the Grafana [downloads page](https://grafana.com/grafana/download?pg=get&plcmt=selfmanaged-box1-cta1).
-install Grafana so that the data can be visualized. Instructions for specific operating systems
-are available on the Grafana [downloads page](https://grafana.com/grafana/download?pg=get&plcmt=selfmanaged-box1-cta1).
 
-Alternatively, the following code snippet shows how to download, install and run Grafana on a Debian 
+Alternatively, the following code snippet shows how to download, install and run Grafana on a Debian based Linux system:
-based Linux system:
 
 ```sh
 curl -tlsv1.3 --proto =https -sL https://packages.grafana.com/gpg.key | sudo apt-key add -
@@ -126,14 +110,11 @@ sudo systemctl enable grafana-server
 sudo systemctl start grafana-server
 ```
 
-When Grafana is up and running, it should be reachable at `localhost:3000`. A browser can be pointed to that URL
+When Grafana is up and running, it should be reachable at `localhost:3000`. A browser can be pointed to that URL to access a visualization dashboard. The browser will prompt for login credentials (user: `admin` and password: `admin`). When prompted, the default password should be changed and saved.
-to access a visualization dashboard. The browser will prompt for login credentials (user: `admin` and password: `admin`). 
-When prompted, the default password should be changed and saved.
 
 ![](/assets/grafana1.png)
 
-The browser first redirects to the Grafana home page to set up the source data. 
+The browser first redirects to the Grafana home page to set up the source data. Click on the configuration icon in the left bar and select "Data sources".
-Click on the configuration icon in the left bar and select "Data sources".
 
 ![](/assets/grafana2.png)
 
@@ -145,8 +126,7 @@ Select "InfluxDB" and proceed.
 
 ![](/assets/grafana4.png)
 
-Data source configuration is pretty straight forward if you are running tools on the same machine. You need to set the 
+Data source configuration is pretty straight forward if the tools run on the same machine as Geth. The InfluxDB address and details for accessing the database must be set. Refer to the image below.
-InfluxDB address and details for accessing the database. Refer to the picture below.
 
 ![](/assets/grafana5.png)
 
@@ -154,20 +134,18 @@ If everything is complete and InfluxDB is reachable, click on "Save and test" an
 
 ![](/assets/grafana6.png)
 
-Grafana is now set up to read data from InfluxDB. Now you need to create a dashboard which will interpret and display it. 
+Grafana is now set up to read data from InfluxDB. Now a dashboard can be created to interpret and display it. Dashboards properties are encoded in JSON files which can be created by anybody and easily imported. On the left bar, click on "Create and Import".
-Dashboards properties are encoded in JSON files which can be created by anybody and easily imported. On the left bar, 
-click on "Create and Import".
 
 ![](/assets/grafana7.png)
 
-For a Geth monitoring dashboard, copy the ID of [this dashboard](https://grafana.com/grafana/dashboards/13877/) 
+For a Geth monitoring dashboard, copy the ID of [this dashboard](https://grafana.com/grafana/dashboards/13877/) and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:
-and paste it in the "Import page" in Grafana. After saving the dashboard, it should look like this:
 
 ![](/assets/grafana8.png)
 
-The dashboards can be customized further. Each panel can be edited, moved, removed or added. 
+The dashboards can be customized further. Each panel can be edited, moved, removed or added. To learn more about how dashboards work, refer to [Grafana's documentation](https://grafana.com/docs/grafana/latest/dashboards/).
-To learn more about how dashboards work, refer to [Grafana's documentation](https://grafana.com/docs/grafana/latest/dashboards/).
 
-Some users might also be interested in automatic [alerting](https://grafana.com/docs/grafana/latest/alerting/), which
+Some users might also be interested in automatic [alerting](https://grafana.com/docs/grafana/latest/alerting/), which sets up alert notifications that are sent automatically when metrics reach certain values. Various communication channels are supported.
-sets up alert notifications that are sent automatically when metrics reach certain values. Various communication channels are supported.
 
+## Summary
+
+This page has outlined how to set up a simple node monitoring dashboard using Grafana.

content/docs/tools/Clef/Setup.md

@@ -1,14 +1,11 @@
 ---
 title: Advanced setup
-sort_key: D
+description: More advanced ways to set up Clef for additional security
 ---
 
 Clef is a signer and account management tool that is external to Geth. This means it can be run as a separate process or even on a separate machine to the one running Geth, for example on secure hardware that is not connected to any external network, or on secure virtual machines.
 This page describes how Clef can be used with Qubes OS to provide a more secure setup than a normal laptop. Using Clef with USBArmory hardware is also briefly described.
 
-{:toc}
--   this will be removed by the toc
-
 ## Qubes OS
 
 ### Background 
@@ -36,19 +33,17 @@ There are two ways that this can be achieved: integrated via Qubes or integrated
 
 #### 1. Qubes Integrated
 
-Qubes provides a facility for inter-qubes communication via `qrexec`. A qube can request to make a cross-qube RPC request 
+Qubes provides a facility for inter-qubes communication via `qrexec`. A qube can request to make a cross-qube RPC request to another qube. The OS then asks the user if the call is permitted. 
-to another qube. The OS then asks the user if the call is permitted. 
 
-![Example](qrexec-example.png)
+![Example](assets/qrexec-example.png)
 
-A policy-file can be created to allow such interaction. On the `target` domain, a service is invoked which can read the
+A policy-file can be created to allow such interaction. On the `target` domain, a service is invoked which can read the `stdin` from the `client` qube. 
-`stdin` from the `client` qube. 
 
 This is how [Split GPG](https://www.qubes-os.org/doc/split-gpg/) is implemented. Clef can be set up in the same way:
 
 ##### Server
 
-![Clef via qrexec](clef_qubes_qrexec.png)
+![Clef via qrexec](/assets/clef_qubes_qrexec.png)
 
 On the `target` qubes, we need to define the RPC service.
 
@@ -71,12 +66,9 @@ if [ -S /home/user/.clef/clef.ipc ]; then
 fi
 
 ```
-This RPC service is not complete (see notes about HTTP headers below), but works as a proof-of-concept. 
+This RPC service is not complete (see notes about HTTP headers below), but works as a proof-of-concept. It will forward the data received on `stdin` (forwarded by the OS) to Clef's HTTP channel. 
-It will forward the data received on `stdin` (forwarded by the OS) to Clef's HTTP channel.  
 
-It would have been possible to send data directly to the `/home/user/.clef/.clef.ipc` 
+It would have been possible to send data directly to the `/home/user/.clef/.clef.ipc` socket via e.g `nc -U /home/user/.clef/clef.ipc`, but the reason for sending the request data over `HTTP` instead of `IPC` is for the ability to forward `HTTP` headers.
-socket via e.g `nc -U /home/user/.clef/clef.ipc`, but the reason for sending the request 
-data over `HTTP` instead of `IPC` is for the ability to forward `HTTP` headers.
 
 To enable the service:
 
@@ -85,8 +77,7 @@ sudo cp qubes.Clefsign /etc/qubes-rpc/
 sudo chmod +x /etc/qubes-rpc/ qubes.Clefsign
 ```
 
-This setup uses [gtksigner](https://github.com/holiman/gtksigner), which is a very minimal GTK-based UI that works well 
+This setup uses [gtksigner](https://github.com/holiman/gtksigner), which is a very minimal GTK-based UI that works well with minimal requirements. 
-with minimal requirements. 
 
 ##### Client
 
@@ -169,21 +160,19 @@ However, it comes with a couple of drawbacks:
 
 #### 2. Network integrated
 
-The second way to set up Clef on a qubes system is to allow networking, and have Clef listen to a port which is accessible
+The second way to set up Clef on a qubes system is to allow networking, and have Clef listen to a port which is accessible from other qubes. 
-from other qubes. 
 
 ![Clef via http](clef_qubes_http.png)
 
 
 ## USBArmory
 
-The [USB armory](https://inversepath.com/usbarmory) is an open source hardware design with an 800 MHz ARM processor. It is a pocket-size
+The [USB armory](https://inversepath.com/usbarmory) is an open source hardware design with an 800 MHz ARM processor. It is a pocket-sized computer. When inserted into a laptop, it identifies itself as a USB network interface, basically adding another network to your computer that can be used to SSH into the device. 
-computer. When inserted into a laptop, it identifies itself as a USB network interface, basically adding another network
-to your computer that can be used to SSH into the device. 
 
-Running Clef off a USB armory means that the armory can be used as a very versatile offline computer, which only
+Running Clef off a USB armory means that the armory can be used as a very versatile offline computer, which only ever connects to a local network between the local computer and the device itself.
-ever connects to a local network between the local computer and the device itself.
 
-Needless to say, while this model should be fairly secure against remote attacks, an attacker with physical access
+Needless to say, while this model should be fairly secure against remote attacks, an attacker with physical access to the USB Armory would trivially be able to extract the contents of the device filesystem. 
-to the USB Armory would trivially be able to extract the contents of the device filesystem. 
 
+## Summary
+
+This page introduced two ways to setup Clef that give additional security compared to running on a normal laptop.

content/docs/tools/Clef/Tutorial.md

@@ -1,22 +1,14 @@
 ---
 title: Tutorial
-sort_key: A
+description: Beginner tutorial for using Clef as an external signer for Geth
 ---
 
-This page provides a step-by-step walkthrough tutorial demonstrating some common uses of Clef. This 
+This page provides a step-by-step walkthrough tutorial demonstrating some common uses of Clef. This includes manual approvals and automated rules. Clef is presented both as a standalone general signer with requests made via RPC and also as a backend signer for Geth.
-includes manual approvals and automated rules. Clef is presented both as a standalone general signer
-with requests made via RPC and also as a backend signer for Geth.
-
-{:toc}
--   this will be removed by the toc
 
 
 ## Initializing Clef
 
-First things first, Clef needs to store some data itself. Since that data might be sensitive 
+First things first, Clef needs to store some data itself. Since that data might be sensitive (passwords, signing rules, accounts), Clef's entire storage is encrypted. To support encrypting data, the first step is to initialize Clef with a random master seed, itself too encrypted with a password:
-(passwords, signing rules, accounts), Clef's entire storage is encrypted. To support encrypting data, 
-the first step is to initialize Clef with a random master seed, itself too encrypted with your chosen 
-password:
 
 ```text
 $ clef init
@@ -57,18 +49,9 @@ You should treat 'masterseed.json' with utmost secrecy and make a backup of it!
 
 ## Remote interactions
 
-This tutorial will use Clef with Geth on the Goerli testnet. The accounts used will be in the 
+This tutorial will use Clef with Geth on the Goerli testnet. The accounts used will be in the Goerli keystore with the path `~/go-ethereum/goerli-data/keystore`. The tutorial assumes there are two accounts in this keystore. Instructions for creating accounts can be found on the [Account managament page](/docs/interface/managing-your-accounts). Note that Clef can also interact with hardware wallets, although that is not demonstrated here.
-Goerli keystore with the path `~/go-ethereum/goerli-data/keystore`. The tutorial assumes there 
-are two accounts in this keystore. Instructions for creating accounts can be found on the 
-[Account managament page](/docs/interface/managing-your-accounts). Note that Clef can also interact 
-with hardware wallets, although that is not demonstrated here.
 
-Clef should be started before Geth, otherwise Geth will complain that it cannot find a Clef 
+Clef should be started before Geth, otherwise Geth will complain that it cannot find a Clef instance to connect to. Clef should be started with the correct `chainid` for Goerli. Clef itself does not connect to a blockchain, but the `chainID` parameter is included in the data that is aggregated to form a signature. Clef also needs a path to the correct keystore passed to the `--keystore` command. A custom path to the config directory can also be provided. This is where the `ipc` file will be saved which is needed to connect Clef to Geth:
-instance to connect to. Clef should be started with the correct `chainid` for Goerli. Clef 
-itself does not connect to a blockchain, but the `chainID` parameter is included in the data 
-that is aggregated to form a signature. Clef also needs a path to the correct keystore passed to 
-the `--keystore` command. A custom path to the config directory can also be provided. This is where the
-`ipc` file will be saved which is needed to connect Clef to Geth:
 
 ```sh
 clef --keystore ~/go-ethereum/goerli-data/keystore --configdir ~/go-ethereum/goerli-data/clef --chainid=5
@@ -92,22 +75,15 @@ INFO [07-01|11:00:46.392] IPC endpoint opened                      url=go-ethere
 * extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
 ```
 
-Clef starts up in CLI (Command Line Interface) mode by default. Arbitrary remote 
+Clef starts up in CLI (Command Line Interface) mode by default. Arbitrary remote processes may *request* account interactions (e.g. sign a transaction), which the user can individually *confirm* or *deny*.
-processes may *request* account interactions (e.g. sign a transaction), which the user 
-can individually *confirm* or *deny*.
 
-The code snippet below shows a request made to Clef via its *External API endpoint* using 
+The code snippet below shows a request made to Clef via its *External API endpoint* using [NetCat](http://netcat.sourceforge.net/). The request invokes the ["account_list"](/content/docs/tools/Clef/apis#accountlist) endpoint which lists the accounts in the keystore. This command should be run in a new terminal.
-[NetCat](http://netcat.sourceforge.net/). The request invokes the 
-["account_list"](/docs/_clef/apis#accountlist) endpoint which lists the accounts in the keystore. 
-This command should be run in a new terminal.
 
 ```sh
 echo '{"id": 1, "jsonrpc": "2.0", "method": "account_list"}' | nc -U ~/.clef/clef.ipc
 ```
 
-The terminal used to send the command will now hang. This is because the process is awaiting 
+The terminal used to send the command will now hang. This is because the process is awaiting confirmation from Clef. Switching to the Clef console reveals Clef's prompt to the user to confirm or deny the request:
-confirmation from Clef. Switching to the Clef console reveals Clef's prompt to the user to 
-confirm or deny the request:
 
 ```terminal
 -------- List Account request--------------
@@ -127,8 +103,7 @@ Additional HTTP header data, provided by the external caller:
 Approve? [y/N]:
 ```
 
-Depending on whether the request is approved or denied, the NetCat process in the other terminal 
+Depending on whether the request is approved or denied, the NetCat process in the other terminal will receive one of the following responses:
-will receive one of the following responses:
 
 ```terminal
 {"jsonrpc":"2.0","id":1,"result":["0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3","0x086278a6c067775f71d6b2bb1856db6e28c30418"]}
@@ -140,22 +115,11 @@ or
 {"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Request denied"}}
 ```
 
-Apart from listing accounts, you can also *request* creating a new account, signing transactions 
+Apart from listing accounts, a *request* can be submitted to create a new account, signing transactions and data or recovering signatures. The available methods are documented in the Clef [External API Spec](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#external-api-1) and the [External API Changelog](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/extapi_changelog.md).
-and data or recovering signatures. The available methods are documented in the Clef 
-[External API Spec](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#external-api-1) 
-and the [External API Changelog](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/extapi_changelog.md).
 
-*Note, the number of things you can do from the External API is deliberately small to limit 
+*Note, the number of things that can be done from the External API is deliberately small to limit the power of remote calls as much as possible! Clef has an [Internal API](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#ui-api-1) too for the UI (User Interface) which is much richer and can support custom interfaces on top. But that's out of scope here.*
-the power of remote calls as much as possible! Clef has an 
-[Internal API](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef#ui-api-1) 
-too for the UI (User Interface) which is much richer and can support custom interfaces on top. 
-But that's out of scope here.*
 
-The example above used Clef completely independently of Geth. However, by defining Clef as 
+The example above used Clef completely independently of Geth. However, by defining Clef as the signer when Geth is started imposes Clef's `request - confirm - result` pattern to any interaction with the local Geth node that touches accounts, including requests made using RPC or an attached Javascript console. To demonstrate this, Geth can be started, with Clef as the signer:
-the signer when Geth is started imposes Clef's `request - confirm - result` pattern to any 
-interaction with the local Geth node that touches accounts, including requests made using 
-RPC or an attached Javascript console. To demonstrate this, Geth can be started,
-with Clef as the signer:
 
 ```sh
 geth --goerli --datadir goerli-data --signer=goerli-data/clef/clef.ipc
@@ -173,9 +137,7 @@ A simple request to list the accounts in the keystore will cause the Javascript
 eth.accounts
 ```
 
-Switching to the Clef terminal reveals that this is because the request is awaiting explicit 
+Switching to the Clef terminal reveals that this is because the request is awaiting explicit confirmation from the user. The log is identical to the one shown above, when the same request for account information was made to Clef via Netcat:
-confirmation from the user. The log is identical to the one shown above, when the same request 
-for account information was made to Clef via Netcat:
 
 ```terminal
 -------- List Account request--------------
@@ -195,11 +157,9 @@ Additional HTTP header data, provided by the external caller:
 Approve? [y/N]:
 ```
 
-In this mode, the user is required to manually confirm every action that touches account data, 
+In this mode, the user is required to manually confirm every action that touches account data, including querying accounts, signing and sending transactions.
-including querying accounts, signing and sending transactions.
 
-The example below shows an ether transaction between the two accounts in the keystore 
+The example below shows an ether transaction between the two accounts in the keystore using `eth.sendTransaction` in the attached Javascript console.
-using `eth.sendTransaction` in the attached Javascript console.
 
 ```js
 // this command requires 2x approval in Clef because it loads account data via eth.accounts[0]
@@ -210,12 +170,8 @@ var tx = {from: eth.accounts[0], to: eth.accounts[1], value: web3.toWei(0.1, "et
 eth.sendTransaction(tx)
 ```
 
-This example demonstrates the power of Clef much more clearly than the account-listing example. 
+This example demonstrates the power of Clef much more clearly than the account-listing example. In the Clef terminal, all the details of the transaction are presented to the user so that they can be reviewed before being confirmed. This gives the user an opportunity to review the fine 
-In the Clef terminal, all the details of the transaction are presented to the user so that they 
+details and make absolutely sure they really want to sign the transaction. `eth.sendTransaction` returns the following confirmation prompt in the Clef terminal:
-can be reviewed before being confirmed. This gives the user an opportunity to review the fine 
-details and make absolutely sure they really want to sign the transaction. `eth.sendTransaction`
-returns the following confirmation prompt in the Clef terminal:
-
 
 ```terminal
 -------- Transaction request----------------
@@ -241,34 +197,20 @@ Approve? [y/N]
 
 ```
 
-Approving this transaction causes Clef to prompt the user to provide the password for
+Approving this transaction causes Clef to prompt the user to provide the password for the sender account. Providing the password enables the transaction to be signed and sent to Geth for broadcasting to the network. The details of the signed transaction are displayed in the console. Account passwords can also be stored in Clef's encrypted vault so that they do not have to be manually entered - [more on this below](#account-passwords).
-the sender account. Providing the password enables the transaction to be signed and sent to
-Geth for broadcasting to the network. The details of the signed transaction are displayed 
-in the console. Account passwords can also be stored in Clef's encrypted vault so that they
-do not have to be manually entered - [more on this below](#account-passwords).
 
 
 ## Automatic rules
 
-For most users, manually confirming every transaction is the right way to use Clef because a 
+For most users, manually confirming every transaction is the right way to use Clef because a human-in-the-loop can review every action. However, there are cases when it makes sense to set up some rules which permit Clef to sign a transaction without prompting the user. 
-human-in-the-loop can review every action. However, there are cases when it makes sense to 
-set up some rules which permit Clef to sign a transaction without prompting the user. 
-
 For example, well defined rules such as:
 
-* Auto-approve transactions with Uniswap v2, with value between 0.1 and 0.5 ETH 
+* Auto-approve transactions with Uniswap v2, with value between 0.1 and 0.5 ETH per 24h period
-  per 24h period
+* Auto-approve transactions to address `0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3` as long as gas < 44k and gasPrice < 80Gwei can be encoded and intepreted by Clef's built-in ruleset engine. 
-* Auto-approve transactions to address `0xD9C9Cd5f6779558b6e0eD4e6Acf6b1947E7fA1F3` 
-  as long as gas < 44k and gasPrice < 80Gwei
-
-can be encoded and intepreted by Clef's built-in ruleset engine. 
 
 ### Rule files
 
-Rules are implemented as Javascript code in `js` files. The ruleset engine includes the 
+Rules are implemented as Javascript code in `js` files. The ruleset engine includes the same methods as the JSON_RPC defined in the [UI Protocol](/docs/_clef/datatypes.md). The following code snippet demonstrates a rule file that approves a transaction if it satisfies the following conditions:
-same methods as the JSON_RPC defined in the [UI Protocol](/docs/_clef/datatypes.md). 
-The following code snippet demonstrates a rule file that approves a transaction if it 
-satisfies the following conditions:
 
 * the recipient is `0xae967917c465db8578ca9024c205720b1a3651a9`
 * the value is less than 50000000000000000 wei (0.05 ETH)
@@ -320,11 +262,7 @@ There are three possible outcomes to this ruleset that are handled in different
 
 ### Attestations
 
-Clef will not just accept and run arbitrary scripts - that would create an attack vector because a malicious party could
+Clef will not just accept and run arbitrary scripts - that would create an attack vector because a malicious party could change the rule file.Instead, the user explicitly *attests* to a rule file, which involves injecting the file's SHA256 hash into Clef's secure store. The following code snippet shows how to calculate a SHA256 hash for a file named `rules.js` and pass it to Clef. Note that Clef will prompt the user to provide the master password because the Clef store has to be decrypted in order to add the attestation to it.
-change the rule file. Instead, the user explicitly *attests* to a rule file, which involves injecting the file's SHA256 
-hash into Clef's secure store. The following code snippet shows how to calculate a SHA256 hash for a file named `rules.js` 
-and pass it to Clef. Note that Clef will prompt the user to provide the master password because the Clef store has to 
-be decrypted in order to add the attestation to it.
 
 ```sh
 # calculate hash
@@ -334,15 +272,11 @@ sha256sum rules.js
 clef attest 645b58e4f945e24d0221714ff29f6aa8e860382ced43490529db1695f5fcc71c
 ```
 
-Once this attestation has been added to the Clef store, it can be used to automatically approve 
+Once this attestation has been added to the Clef store, it can be used to automatically approve interactions that satisfy the conditions encoded in `rules.js` in Clef. 
-interactions that satisfy the conditions encoded in `rules.js` in Clef. 
-
 
 ### Account passwords
 
-The rules described in `rules.js` above require access to the accounts in the Clef keystore which 
+The rules described in `rules.js` above require access to the accounts in the Clef keystore which are protected by user-defined passwords. The signer therefore requires access to these passwords in order to automatically unlock the keystore and sign data and transactions using the accounts.
-are protected by user-defined passwords. The signer therefore requires access to these passwords 
-in order to automatically unlock the keystore and sign data and transactions using the accounts.
 
 This is done using `clef setpw`, passing the account address as the sole argument:
 
@@ -362,16 +296,12 @@ Password:
 INFO [07-01|14:05:56.031] Credential store updated   key=0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3
 ```
 
-Note that Clef does not really 'unlock' an account, it just abstracts the process of providing the
+Note that Clef does not really 'unlock' an account, it just abstracts the process of providing the password away from the end-user in specific, predefined scenarios. If an account password exists in the Clef vault and the rule evaluates to "Approve" then Clef decrypts the password, uses it to decrypt the key, does the requested signing and then re-locks the account. 
-password away from the end-user in specific, predefined scenarios. If an account password 
-exists in the Clef vault and the rule evaluates to "Approve" then Clef decrypts the password, 
-uses it to decrypt the key, does the requested signing and then re-locks the account. 
 
 
 ### Implementing rules
 
-Clef can be instructed to run an attested rule file simply by passing the path to `rules.js` 
+Clef can be instructed to run an attested rule file simply by passing the path to `rules.js` to the `--rules` flag:
-to the `--rules` flag:
 
 ```sh
 clef --keystore go-ethereum/goerli-data/ --configdir go-ethereum/goerli-data/clef --chainid 5 --rules rules.js
@@ -396,10 +326,7 @@ INFO [07-01|13:39:49.728] IPC endpoint opened                      url=go-ethere
 * extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
 ```
 
-Any request that satisfies the ruleset will now be auto-approved by the rule file, for example 
+Any request that satisfies the ruleset will now be auto-approved by the rule file, for example the following request to sign a transaction made using the Geth Javascript console (note that the password for account `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3` has already been provided to `setpw` and the recipient and value comply with the rules in `rules.js`):
-the following request to sign a transaction made using the Geth Javascript console 
-(note that the password for account `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3`
-has already been provided to `setpw` and the recipient and value comply with the rules in `rules.js`):
 
 ```js
 var tx = {to: "0xae967917c465db8578ca9024c205720b1a3651a9", from: "0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3", value: web3.toWei(0.01, "ether")}
@@ -420,8 +347,7 @@ var tx = {to: "0xae967917c465db8578ca9024c205720b1a3651a9", from: "0xd4c4bb7d688
 eth.sendTransaction(tx)
 ```
 
-These latter two transactions, that do not satisfy the encoded rules in `rules.js`, are not automatically approved, but instead pass the 
+These latter two transactions, that do not satisfy the encoded rules in `rules.js`, are not automatically approved, but instead pass the decision back to the UI for manual approval by the user.
-decision back to the UI for manual approval by the user.
 
 
 ### Summary of basic usage
@@ -443,12 +369,8 @@ To summarize, the steps required to run Clef with an automated ruleset that requ
  
 ## More rules
 
-Since rules are defined as Javascript code, rulesets of arbitrary complexity can be created and they can
+Since rules are defined as Javascript code, rulesets of arbitrary complexity can be created and they can impose conditions on any part of a transaction, not only the recipient and value. A simple example is implementing a "whitelist" of recipients where transactions that have those
-impose conditions on any part of a transaction, not only the recipient and value.
+accounts in the `to` field are automatically signed (for example perhaps transactions between a user's own accounts might be whitelisted):
-
-A simple example is implementing a "whitelist" of recipients where transactions that have those
-accounts in the `to` field are automatically signed (for example perhaps transactions between 
-a user's own accounts might be whitelisted):
 
 ```js
 function ApproveTx(r) {
@@ -462,15 +384,12 @@ function ApproveTx(r) {
 }
 ```
 
-In addition to addresses and values, other properties of a request can also be incorporated 
+In addition to addresses and values, other properties of a request can also be incorporated into a ruleset. The example below demonstrates a ruleset for `approve_signData` imposing the following conditions on a transaction's sender and message data.
-into a ruleset. The example below demonstrates a ruleset for `approve_signData` imposing 
-the following conditions on a transaction's sender and message data.
 
 1. The sender must be `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3`
 2. The transaction message must include the text `wen-merge`, which is `77656E2D6D65726765` in hex.
 
-If these conditions are satisfied then the transaction is auto-approved (assuming the password for 
+If these conditions are satisfied then the transaction is auto-approved (assuming the password for `0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3` has been provided to `setpw`).
-`0xd9c9cd5f6779558b6e0ed4e6acf6b1947e7fa1f3` has been provided to `setpw`).
 
 ```js
 function ApproveListing() {
@@ -537,13 +456,7 @@ INFO [07-01|14:12:41.638] IPC endpoint opened                      url=go-ethere
 * extapi_ipc : go-ethereum/goerli-data/clef/clef.ipc
 ```
 
-Finally, a request can be submitted to test that the rules are being applied as expected. 
+Finally, a request can be submitted to test that the rules are being applied as expected. Here, Clef is used independently of Geth by making a request via RPC, but the same logic would be imposed if the request was made via a connected Geth node. Some arbitrary text will be included in the message data that includes the term `wen-merge`. The plaintext `clefdemotextthatincludeswen-merge` is `636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765` when represented as a hexadecimal string. This can be passed as data to an `account_signData` request as follows:
-Here, Clef is used independently of Geth by making a request via RPC, but the same logic 
-would be imposed if the request was made via a connected Geth node. Some arbitrary text 
-will be included in the message data that includes the term `wen-merge`. The plaintext 
-`clefdemotextthatincludeswen-merge` is `636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765` 
-when represented as a hexadecimal string. This can be passed as data to an `account_signData` 
-request as follows:
 
 ```sh
 echo '{"id": 1, "jsonrpc":"2.0", "method":"account_signData", "params":["data/plain", "0x636c656664656d6f7465787474686174696e636c7564657377656e2d6d65726765"]}' | nc -U ~/go-ethereum.goerli-data/clef/clef.ipc
@@ -555,8 +468,7 @@ This will be automatically signed, returning a result that looks like the follow
 {"jsonrpc":"2.0","id":1,"result":"0x4f93e3457027f6be99b06b3392d0ebc60615ba448bb7544687ef1248dea4f5317f789002df783979c417d969836b6fda3710f5bffb296b4d51c8aaae6e2ac4831c"}
 ```
 
-Alternatively, a request that does not include the phrase `wen-merge` will not automatically approve. For example, the following request passes the hexadecimal
+Alternatively, a request that does not include the phrase `wen-merge` will not automatically approve. For example, the following request passes the hexadecimal string representing the plaintext `clefdemotextwithoutspecialtext`:
-string representing the plaintext `clefdemotextwithoutspecialtext`:
 
 ```sh
 echo '{"id": 1, "jsonrpc":"2.0", "method":"account_signData", "params":["data/plain", "0x636c656664656d6f74657874776974686f75747370656369616c74657874"]}' | nc -U ~/go-ethereum.goerli-data/clef/clef.ipc
@@ -567,14 +479,14 @@ This returns a `Request denied` message as follows:
 {"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Request denied"}}
 ```
 
-Meanwhile, in the output logs in the Clef terminal you can see:
+Meanwhile, in the output logs in the Clef terminal:
+
 ```text
 INFO [02-21|14:42:41] Op approved
 INFO [02-21|14:42:56] Op rejected
 ```
 
-The signer also stores all traffic over the external API in a log file. 
+The signer also stores all traffic over the external API in a log file. The last 4 lines shows the two requests and their responses:
-The last 4 lines shows the two requests and their responses:
 
 ```text
 $ tail -n 4 audit.log
@@ -584,19 +496,14 @@ t=2022-07-01T15:52:23+0300 lvl=info msg=SignData   api=signer type=request  meta
 t=2022-07-01T15:52:23+0300 lvl=info msg=SignData   api=signer type=response data=                                     error="Request denied"
 ```
 
-More examples, including a ruleset for a rate-limited window, are available on the [Clef Github][rate-limited-window-example]
+More examples, including a ruleset for a rate-limited window, are available on the [Clef Github](https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/rules.md#example-1-ruleset-for-a-rate-limited-window) and on the [Rules page](/content/docs/tools/Clef/rules). 
-and on the [Rules page](/docs/clef/rules). 
 
 
 ## Under the hood
 
-The examples on this page have provided step-by-step instructions for verious operations using Clef. 
+The examples on this page have provided step-by-step instructions for verious operations using Clef. However, they have not provided much detail as to what is happening under the hood. This section will provide some more details about how Clef organizes itself locally.
-However, they have not provided much detail as to what is happening under the hood. 
-This section will provide some more details about how Clef organizes itself locally.
 
-Initializing Clef with a master password and providing an account password to `clef setpw` 
+Initializing Clef with a master password and providing an account password to `clef setpw` and attesting a ruleset creates the following files in the directory `~/.clef/` (this path is independent of the paths provided to `--keystore` and `--configdir` on startup):
-and attesting a ruleset creates the following files in the directory `~/.clef/` 
-(this path is independent of the paths provided to `--keystore` and `--configdir` on startup):
 
 ```terminal
 # displayed using $ ls -laR ~/.clef/
@@ -616,27 +523,20 @@ drwxr-x--x 3 user user 4096 Jul  1 13:45 ..
 -rw------- 1 user user  115 Jul  1 13:35 credentials.json
 ```
 
-The file `masterseed.json` includes a json object containing the masterseed which was used to derive
+The file `masterseed.json` includes a json object containing the masterseed which was used to derive the vault directory (in this case `02f90c0603f4f2f60188`). The vault is encrypted using a password which is also derived from the masterseed. Inside the vault are two subdirectories: 
-the vault directory (in this case `02f90c0603f4f2f60188`). The vault is encrypted using a password
-which is also derived from the masterseed. Inside the vault are two subdirectories: 
 
 `credentials.json`
  
 `config.json`
  
 
-Inside `credentials.json` are the confidential `ksp` data (standing for "keystore pass" - these
+Inside `credentials.json` are the confidential `ksp` data (standing for "keystore pass" - these are the account passwords used to unlock the keystore).
-are the account passwords used to unlock the keystore).
 
-The `config.json` file contains encrypted key/value pairs for configuration data. Usually 
+The `config.json` file contains encrypted key/value pairs for configuration data. Usually this is only the `sha256` hashes of any attested rulesets. 
-this is only the `sha256` hashes of any attested rulesets. 
 
-Vault locations map uniquely to masterseeds so that multiple instances of Clef can co-exist 
+Vault locations map uniquely to masterseeds so that multiple instances of Clef can co-exist each with their own attested rules and their own set of keystore passwords. This is useful for, for example, maintaining separate setups for Mainnet and testnets.
-each with their own attested rules and their own set of keystore passwords. This is useful for, 
-for example, maintaining separate setups for Mainnet and testnets.
 
-The contents of each of these json files can be viewed using `cat` and should look something 
+The contents of each of these json files can be viewed using `cat` and should look something like the following:
-like the following:
 
 For `config.json`:
 
@@ -660,26 +560,14 @@ cat ~/.clef/02f90c0603f4f2f60188/config.json
 
 ## Geth integration
 
-This tutorial has bounced back and forth between demonstrating Clef as a standalone tool by making 
+This tutorial has bounced back and forth between demonstrating Clef as a standalone tool by making 'manual` JSON RPC requests from the terminal and integrating it as a backend singer for Geth. Using Clef for account management is considered best practise for Geth users because of the additional
-'manual` JSON RPC requests from the terminal and integrating it as a backend singer for Geth. 
+security benefits it offers over and above what it offered by Geth's built-in accounts module. Clef is far more flexible and composable than Geth's built-in account management tool and can interface directly with hardware wallets, while Apps and wallets can request signatures directly from Clef.
-Using Clef for account management is considered best practise for Geth users because of the additional 
-security benefits it offers over and above what it offered by Geth's built-in accounts module. Clef is
-far more flexible and composable than Geth's built-in account management tool and can interface directly 
-with hardware wallets, while Apps and wallets can request signatures directly from Clef.
 
-Ultimately, the goal is to deprecate Geth's account management tools completely and replace them with 
+Ultimately, the goal is to deprecate Geth's account management tools completely and replace them with Clef. Until then, users are simply encouraged to choose to use Clef as an optional backend signer for Geth. In addition to the examples on this page, the [Getting started tutorial](/docs/_getting-started/index.md) also demonstrates Clef/Geth integration.
-Clef. Until then, users are simply encouraged to choose to use Clef as an optional backend signer for Geth. 
-In addition to the examples on this page, the [Getting started tutorial](/docs/_getting-started/index.md) 
-also demonstrates Clef/Geth integration.
 
 
 ## Summary
 
-This page includes step-by-step instructions for basic and intermediate uses of Clef, including using 
+This page includes step-by-step instructions for basic and intermediate uses of Clef, including using it as a standalone app and a backend signer for Geth. Further information is available on our other Clef pages, including [Introduction](/docs/clef/introduction), [Setup](/docs/clef/setup), 
-it as a standalone app and a backend signer for Geth. Further information is available on our other 
+[Rules](/docs/clef/rules), [Communication Datatypes](/docs/clef/datatypes) and [Communication APIs](/docs/clef/apis). Also see the [Clef Github](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef) for further reading.
-Clef pages, including [Introduction](/docs/clef/introduction), [Setup](/docs/clef/setup), 
-[Rules](/docs/clef/rules), [Communication Datatypes](/docs/clef/datatypes) and [Communication APIs](/docs/clef/apis). 
-Also see the [Clef Github](https://github.com/ethereum/go-ethereum/tree/master/cmd/clef) for further reading.
 
-
-[rate-limited-window-example]:https://github.com/ethereum/go-ethereum/blob/master/cmd/clef/rules.md#example-1-ruleset-for-a-rate-limited-window