docs: major rework of trin book

Introduction is more focused on first-time users. It pushes back some of
the conceptual stuff, tries to explain several things more clearly, and
updates some stale info.

book/src/SUMMARY.md

@@ -1,20 +1,21 @@
 # Summary
 
 - [Introduction](introduction/README.md)
-    - [Quickstart](introduction/quickstart.md)
-- [Users](users/README.md)
-    - [Requirements](users/requirements.md)
-    - [Startup](users/startup.md)
-    - [Use](users/use/README.md)
-        - [Making queries](users/use/making_queries.md)
+- [Using trin](introduction/quickstart.md)
+    - [Running trin](users/startup.md)
+    - [Querying Data](users/use/README.md)
+        - [Building Queries](users/use/making_queries.md)
         - [Ethereum data](users/use/ethereum_data.md)
         - [Portal network data](users/use/portal_network_data.md)
+        - [Remote access](users/use/remote_access.md)
+    - [Requirements](users/requirements.md)
     - [Monitoring](users/monitoring.md)
     - [Problems](users/problems.md)
     - [FAQ](users/faq.md)
-- [Concepts](concepts/README.md)
+- [Portal Concepts](concepts/README.md)
     - [Portal Network](introduction/portal_network.md)
-- [Developers](developers/README.md)
+    - [Who Benefits](users/README.md)
+- [Developing trin](developers/README.md)
     - [Quick setup](developers/quick_setup.md)
     - [Developer stories](developers/developer_stories.md)
     - [Goals](developers/goals.md)

book/src/concepts/README.md

@@ -1,6 +1,6 @@
 # Concepts
 
-## Why Portal Network?
+## Why does Portal Network exist?
 
 Portal is an important way to support the evolution of the core Ethereum protocol.
 
@@ -9,7 +9,7 @@ likely future upgrade.
 
 When that happens, the Portal Network can supply users with that purged data.
 
-## Why do Portal clients use less space?
+## How do Portal clients use less space?
 
 Each Portal Network client stores a user-configurable fraction of the data. The client retrieves any missing data from peers, on demand. Just like a full node, the client can cryptographically prove the data it serves.
 

book/src/concepts/use_cases.md

@@ -0,0 +1,53 @@
+# Use Cases
+
+The following are examples of people who are well-suited to using a Portal Network client, like Trin.
+
+## Laptop wallet user
+
+A user has a laptop that frequently is turned off. When
+they want to transact, they can turn on Trin and connect their
+wallet to it.
+
+*Benefit*: Wallet use without reliance on third party wallet APIs.
+
+## Desktop wallet user
+
+A user has a desktop that usually on, but most of the disk is used for other things.
+When they want to transact, their wallet is already connected to their portal node.
+
+*Benefit*: Wallet use without reliance on third party wallet APIs. Contributes to
+network health without using entire disk.
+
+## Protocol experimentation
+
+A researcher looking to explore the Ethereum protocol, testing out
+specific aspects and perhaps making experimental changes to the protocol.
+
+*Benefit*: Spin up a node and play around quickly and with low cost.
+
+## Single board computer hobbyist
+
+A raspberry pi 3, or similarly-sized computer with could contribute
+to network health.
+
+Currently a raspberry pi 4 can run a full node, with consensus
+and execution clients, however this is a bit tight and requires a ~2TB SSD.
+
+*Benefit*: Learn about Ethereum, get node access and provide the
+network with additional robustness.
+
+## Mobile user
+
+Trin is not currently configured to run on mobile, however this is plausibly
+a viable and interesting use case for the future. A trin node could run as a
+background task with configurable limits on disk, CPU and bandwidth use.
+
+*Benefit*: Wallet use without reliance on third party wallet APIs. Contributes to
+network health.
+
+## Unsuitable users
+
+There are situations where Trin is estimated to not be a good node choice:
+- Very speedy historical state access. It's possible to retrieve old state, but don't expect sub-second contract reads on state as viewed from a historical block.
+- Building blocks locally, as a block producer. Random access to the full state and transaction pool is not supported at the speed needed to build competitive blocks.
+  - We remain hopeful that in the future, you could use an externally-generated block (like one provided by MEV-boost) so that you can act as a validater using a standard Consensus client, with Trin as the Execution client. This probably depends on a future where state witnesses are bundled with the block sent to you by the producer.

book/src/introduction/README.md

@@ -4,10 +4,10 @@
 
 Trin acts as a json-rpc server, like an Ethereum client.
 
-Unlike an Ethereum client, trin has:
-- Nearly instant sync
-- Low CPU & storage usage
+Unlike a typical Ethereum client, trin:
+- is usable within minutes
+- limits storage & CPU usage
 
 Continue reading to see how to use trin.
 
-🏗 The sections, content and links of this book are subject to change.
+🏗 This is a living document, subject to substantial change without warning.

book/src/introduction/quickstart.md

@@ -2,8 +2,6 @@
 
 Trin runs on Linux, MacOS, and Windows. There are two ways to run it: download a binary executable, or install it from source.
 
-Let's download the binary executable.
-
 ## Download an executable
 
 The github repository hosts the binaries. Download the latest release for your platform from the [releases page](https://github.com/ethereum/trin/releases).
@@ -26,7 +24,7 @@ You now have a `trin` executable in the current directory.
 
 Launch the executable with 2GB local disk space:
 ```sh
-./trin --portal-subnetworks state,history --mb 2000
+trin --mb 2000
 ```
 
 ## Load a block from Ethereum history
@@ -37,10 +35,10 @@ Print the block data at height 20,987,654:
 BLOCK_NUM=20987654; echo '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x'$(printf "%x" $BLOCK_NUM)'", false],"id":1}' | nc -U /tmp/trin-jsonrpc.ipc | jq
 ```
 
-For a deeper understanding of how to interact with Ethereum, like invoking a contract function, see the [Ethereum data](/users/use/ethereum_data.md) section.
+For a deeper understanding of how to interact with Ethereum, like invoking a contract function, see the [Ethereum data](../users/use/ethereum_data.md) section.
 
 ## Alternatively, install from source
 
 To get the very latest updates, install from source. This path is intended for power users and developers, who want access to the very latest code.
 
-There are platform-specific [build instructions](/developers/contributing/build_instructions.md).
+There are platform-specific [build instructions](../developers/contributing/build_instructions.md).

book/src/users/README.md

@@ -1,6 +1,6 @@
-# Users
+# Use Cases
 
-The following are users who are well-suited to using Trin.
+The following are examples of people who are well-suited to using a Portal Network client, like Trin.
 
 ## Laptop wallet user
 
@@ -39,18 +39,15 @@ network with additional robustness.
 ## Mobile user
 
 Trin is not currently configured to run on mobile, however this is plausibly
-a viable and interesting use case. A trin node could run as a background
-task with configurable limits on disk, CPU and bandwidth use.
+a viable and interesting use case for the future. A trin node could run as a
+background task with configurable limits on disk, CPU and bandwidth use.
 
 *Benefit*: Wallet use without reliance on third party wallet APIs. Contributes to
 network health.
 
 ## Unsuitable users
 
 There are situations where Trin is estimated to not be a good node choice:
-- Time-critical chain tip data. Likely that data distribution may not be fast enough for these
-    use cases, however testing may show otherwise.
-    - Consensus participation. Beacon chain staking with a Consensus client with Portal Network node as Execution client.
-    - Block builder. Serving blocks to beacon chain validator nodes via MEV-boost
-- Data analysis requiring state at historical blocks. Trin is not an archive node and does not
-    expose `trace_`* or` debug_`* endpoints.
+- Very speedy historical state access. It's possible to retrieve old state, but don't expect sub-second contract reads on state as viewed from a historical block.
+- Building blocks locally, as a block producer. Random access to the full state and transaction pool is not supported at the speed needed to build competitive blocks.
+  - We remain hopeful that in the future, you could use an externally-generated block (like one provided by MEV-boost) so that you can act as a validater using a standard Consensus client, with Trin as the Execution client. This probably depends on a future where state witnesses are bundled with the block sent to you by the producer.

book/src/users/requirements.md

@@ -5,21 +5,21 @@
 Suitable:
 - Processor: x86 or Arm based. Minimum spec TBD.
 - RAM: Minimum TBD.
-- Disk: Any.
+- Disk: 50 MB
+
+We are eager to hear about a device that is too slow or small to run Trin. The minimum permitted setting for storage usage is technically 1MB. Though the trin binary itself is 41MB at the moment. Tell us if that isn't working for you!
 
 Testing and reports of performance on the following are welcome:
 - RISC-V based processor.
 - Resource constrained (CPU/RAM)
 
-
 ## Software
 
-- Unix based operating system
-- Rust installation (minimum `v1.66`)
+- Linux, MacOS, or Windows
 
 ## Network
 
 Testing/reports of low-bandwidth network are welcome.
 
 Trin should be compatible with VPN use, but if you experience difficulty
-connecting to the network we recommend disabling your VPN.
+connecting to the network we recommend disabling your VPN.

book/src/users/startup.md

@@ -1,42 +1,56 @@
-# Startup
+# Running Trin
 
-Configuration occurs at startup via flags:
+Configuration occurs at startup via standard flags, like:
 
 ```sh
-cargo run -p trin -- --flag1 value --flag2 value
-```
-Backslashes allow flags to be on new lines for easier reading.
-```sh
-cargo run -p trin -- \
-    --flag1 value \
-    --flag2 value \
-    --flag3 value1,value2 \
+trin --mb 5000
 ```
+which sets a rough limit of 5GB on trin storage usage.
 
-## Flags
-
-For the most up to date flags run:
+For the full list of flags, run:
 
 ```sh
-cargo run -p trin -- --help
+trin --help
 ```
-### Bootnodes
-
-Trin automatically connects to the Portal Network bootnodes.
-Use the `--bootnodes` cli flag to connect to a specific node
-or to none.
 
-### Control disk use
+## Data storage limits
 
-Trin can be tuned to control how much disk space is used:
+When setting a storage usage limit, here's how to think about the tradeoffs:
 
-|Selected size|Data access|Network contribution|
+|Storage size|Data access|Network contribution|
 |-|-|-|
 |Smaller|Slower|Less|
 |Larger|Faster|More|
 
-See the `--mb` flag.
 
+## Select which networks to join
+
+Eventually, by default, trin will connect to all Portal Networks. Each network stores different types of data. Some examples are the consensus-layer network for confirming the latest headers, and several execution-layer networks like:
+
+- **History Network** - blocks & receipts
+- **State Network** - account info
+- **Transaction Gossip Network** - mempool
+- **Canonical Indices Network** - tx lookups
+
+For now, only the history network is on by default, because the others are still under active development. At the moment, the state network has only the first one million blocks of state data.
+
+To try out state access, you can turn it on like this:
+
+```sh
+trin --mb 5000 --portal-subnetworks history,state
+```
+
+Note that to access state, you must also run with history enabled, in order to validate peer responses.
+
+## Advanced flags
+
+The following flags all have reasonable defaults and most people won't need to touch them:
+
+### Bootnodes
+
+Trin automatically connects to some standard Portal Network bootnodes.
+Use the `--bootnodes` cli flag to connect to a specific node
+or to none.
 
 ### Private Key management
 
@@ -48,22 +62,9 @@ every time Trin is restarted. The only exceptions are if...
 - User deletes the `TRIN_DATA_DIR` or changes the `TRIN_DATA_DIR`. In which 
   case a new private key will be randomly generated and used.
 
-### Sub-Protocols
-
-Trin can connect to different sub-protocols to have access to
-different types of data. One more more can be selected, but be aware
-that not all sub-protocols are ready:
-
-- Execution State Network
-- Execution History Network
-- Execution Transaction Gossip Network
-- Execution Canonical Indices Network
-
 ### Networking configuration
 
 Optionally one can specify Trin's network properties:
-- What sort of network connections (HTTP vs IPC)
+- What sort of connection to query with (HTTP vs IPC)
 - Port answering Ethereum-related queries
 - Port for connecting to other nodes
-
-These types of flags have defaults.

book/src/users/use/README.md

@@ -1,24 +1,11 @@
-# Use
+# Querying Data
 
-Once Trin is running, it will be serving Ethereum data in response to requests.
-This can be accessed by other programs, such as a wallet in a web browser.
+Once Trin is running, you can access Ethereum data by making requests to its endpoint.
 
-Once Trin is running, another program will be able to communicate with Trin as it
-would any other Ethereum node.
+The interface for these requests is JSON-RPC, which is a standard way to communicate with Ethereum nodes.
 
-Additionally, commands can be made in the terminal to test functionality.
-See sections below for more detail.
+In the following sections, we make queries with:
+- hand-coded JSON-RPC
+- using a Web3 library
 
-## Access from different computer
-
-If Trin is started on `host` computer by `user`, serving data over HTTP `port`
-then the following command can be issued on another computer to send requests to Trin
-and receive responses:
-```sh
-ssh -N -L <port>:127.0.0.1:<port> <user>@<host>
-```
-For example:
-```sh
-ssh -N -L 8545:127.0.0.1:8545 username@mycomputer
-```
-Accessing Trin from another computer using IPC is not covered here.
+Serving data for wallets is not covered here. We hope to get there eventually, but the network is not ready quite yet.