Merge pull request #630 from oasisprotocol/gw0/network-parameters-imp…

…rovements

docs/node: Rename to Runtime bundle and improve links to Network Parameters page

docs/node/genesis-doc.md

@@ -1,12 +1,8 @@
 # Genesis Document
 
-A genesis document contains a set of parameters that outline the initial state
-of an Oasis network.
-
-The state defined in the network's genesis document contains all the necessary
-information for launching that particular network (i.e. Mainnet,
-[Testnet](testnet/README.md)), including initial token allocations, network
-parameters, and more.
+A genesis document contains the initial state of an Oasis Network, and all the
+necessary information for launching that particular network (i.g. [Mainnet],
+[Testnet]).
 
 :::info
 
@@ -31,8 +27,11 @@ When Oasis Node loads a genesis file, it converts it to a genesis document.
 :::info
 
 Up to date information about the current genesis file and the current genesis
-document's hash can be found on the [Network Parameters](mainnet/README.md)
-page.
+document's hash can be found on the Network Parameters page ([Mainnet],
+[Testnet]).
+
+[Mainnet]: mainnet/README.md
+[Testnet]: testnet/README.md
 
 :::
 
@@ -42,9 +41,8 @@ This sections explains some of the key parameters of the genesis document.
 
 :::caution
 
-The concrete parameter values in the following sections pertain to the Mainnet.
-Other Oasis networks (e.g. [Testnet](testnet/README.md)) might use different
-values.
+The concrete parameter values in the following sections pertain to the [Mainnet].
+Other Oasis networks (e.g. [Testnet]) might use different values.
 
 :::
 

docs/node/mainnet/README.md

@@ -51,7 +51,7 @@ This section contains parameters for various ParaTimes known to be deployed on t
   * [22.2.11](https://github.com/oasisprotocol/oasis-core/releases/tag/v22.2.11)
 * Runtime identifier:
   * `000000000000000000000000000000000000000000000000e199119c992377cb`
-* Runtime binary version:
+* Runtime bundle version:
   * [2.6.2](https://github.com/oasisprotocol/cipher-paratime/releases/tag/v2.6.2)
 * IAS proxy address:
   * `[email protected]:8650`
@@ -69,7 +69,7 @@ Feel free to use other IAS proxies besides the one provided here or [run your ow
   * [22.2.11](https://github.com/oasisprotocol/oasis-core/releases/tag/v22.2.11)
 * Runtime identifier:
   * `000000000000000000000000000000000000000000000000e2eaa99fc008f87f`
-* Runtime binary version (or [build your own](https://github.com/oasisprotocol/emerald-paratime/tree/v10.0.0#building)):
+* Runtime bundle version (or [build your own](https://github.com/oasisprotocol/emerald-paratime/tree/v10.0.0#building)):
   * [10.0.0](https://github.com/oasisprotocol/emerald-paratime/releases/tag/v10.0.0)
 * Web3 Gateway version:
   * [3.4.0](https://github.com/oasisprotocol/oasis-web3-gateway/releases/tag/v3.4.0)
@@ -86,7 +86,7 @@ Check the [Emerald ParaTime page](/dapp/emerald/#web3-gateway) on how to access
   * [22.2.11](https://github.com/oasisprotocol/oasis-core/releases/tag/v22.2.11)
 * Runtime identifier:
   * `000000000000000000000000000000000000000000000000f80306c9858e7279`
-* Runtime binary version:
+* Runtime bundle version:
   * [0.5.2](https://github.com/oasisprotocol/sapphire-paratime/releases/tag/v0.5.2)
   * [0.6.4](https://github.com/oasisprotocol/sapphire-paratime/releases/tag/v0.6.4)
 * Oasis Web3 Gateway version:
@@ -107,7 +107,7 @@ Feel free to use other IAS proxies besides the one provided here or [run your ow
   * [22.2.11](https://github.com/oasisprotocol/oasis-core/releases/tag/v22.2.11)
 * Runtime identifier:
   * `4000000000000000000000000000000000000000000000008c5ea5e49b4bc9ac`
-* Runtime binary version:
+* Runtime bundle version:
   * [0.3.4](https://github.com/oasisprotocol/keymanager-paratime/releases/tag/v0.3.4)
 * IAS proxy address:
   * `[email protected]:8650`

docs/node/run-your-node/advanced/install-oasis-remote-signer-binary.md

@@ -26,7 +26,10 @@ We suggest that you build Oasis Remote Signer from source yourself for a product
 
 :::
 
-For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the [Network Parameters](../../mainnet/README.md) page.
+For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the Network Parameters page ([Mainnet], [Testnet]).
+
+[Mainnet]: ../../mainnet/README.md
+[Testnet]: ../../testnet/README.md
 
 ## Building From Source
 
@@ -38,12 +41,14 @@ See [Oasis Core's Build Environment Setup and Building](../../../core/developmen
 
 The code in the [`master` branch](https://github.com/oasisprotocol/oasis-core/tree/master/) might be incompatible with the code used by other nodes in the Mainnet.
 
-Make sure to use the version specified in the [Network Parameters](../../mainnet/README.md).
+Make sure to use the version specified in the Network Parameters page ([Mainnet], [Testnet]).
 
 :::
 
 ## Adding `oasis-remote-signer` Binary to `PATH`
 
+To install the `oasis-node` binary next to your Oasis node data directory, copy/symlink it to e.g. `/node/bin`.
+
 To install the `oasis-remote-signer` binary for the current user, copy/symlink it to `~/.local/bin`.
 
 To install the `oasis-remote-signer` binary for all users of the system, copy it to `/usr/local/bin`.

docs/node/run-your-node/keymanager-node/README.md

@@ -24,13 +24,16 @@ Before following this guide, make sure you've followed the [Prerequisites](../pr
   * `data`: This will store the data directory needed by Oasis Node, including your node identity and the blockchain state. The directory permissions should be `rwx------`.
   * `bin`: This will store binaries needed by Oasis Node for running the ParaTimes.
   * `runtimes`: This will store the ParaTime bundles.
-* Downloaded or compiled the correct versions of everything according to [Mainnet Network Parameters](../../mainnet/README.md):
+* Downloaded or compiled the correct versions of everything according to Network Parameters page ([Mainnet], [Testnet]).
   * The genesis file copied to `/node/etc/genesis.json`.
   * The binaries needed by Oasis Node for running the ParaTimes copied to `/node/bin/`.
   * The key manager ParaTime bundle (`.orc` extension) copied to `/node/runtimes/`.
 * Initialized a new node and updated your entity registration by following the [Register a New Entity or Update Your Entity Registration](../paratime-node.mdx#register-a-new-entity-or-update-your-entity-registration) instructions.
   * The entity descriptor file copied to `/node/etc/entity.json`.
 
+[Mainnet]: ../../mainnet/README.md
+[Testnet]: ../../testnet/README.md
+
 :::tip
 
 Reading the rest of the [validator node setup instructions](../validator-node.mdx) and [ParaTime node setup instructions](../paratime-node.mdx) may also be useful.
@@ -116,13 +119,13 @@ Before using this configuration you should collect the following information to
 
 * `{{ external_address }}`: The external IP you used when registering this node.
 * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`.
-  * You can find the current Oasis Seed Node address in the [Network Parameters](../../mainnet/README.md).
+  * You can find the current Oasis Seed Node address in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ keymanager_runtime_orc_path }}`: Path to the key manager [ParaTime bundle](../paratime-node.mdx#the-paratime-bundle) of the form `/node/runtimes/foo-paratime.orc`.
-  * You can find the current Oasis-supported key manager ParaTime in the [Mainnet Network Paramers](../../mainnet/README.md#paratimes).
+  * You can find the current Oasis-supported key manager ParaTime in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ keymanager_runtime_id }}`: Runtime identified for the key manager ParaTime.
-  * You can find the current Oasis-supported key manager ParaTime identifiers in the [Mainnet Network Paramers](../../mainnet/README.md#paratimes).
+  * You can find the current Oasis-supported key manager ParaTime identifiers in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ ias_proxy_address }}`: The IAS proxy address in the form `ID@HOST:port`.
-  * You can find the current Oasis IAS proxy address in the [Mainnet Network Parameters](../../mainnet/README.md#cipher-paratime).
+  * You can find the current Oasis IAS proxy address in the Network Parameters page ([Mainnet], [Testnet]).
   * If you want, you can also [run your own IAS proxy](../ias-proxy.md).
 
 :::caution

docs/node/run-your-node/maintenance/handling-network-upgrades.md

@@ -23,7 +23,7 @@ The specific Oasis Core version requirements also impact the way how you
   and then sequentially perform seamless upgrade(s).
 
 For example, at time of writing this guide in order to sync your node from
-scratch on the [Testnet network][Testnet Parameters] you needed to do the
+scratch on the [Testnet Network Parameters][Testnet] you needed to do the
 following:
 
 - Download the genesis document and run Oasis Core 22.0.x which synced
@@ -33,7 +33,7 @@ following:
 
 The expected versions of the Oasis Core to sync your node from the latest
 genesis document on the Mainnet and Testnet are always published on the
-[Network Parameters] and [Testnet Parameters] pages respectively.
+Network Parameters page ([Mainnet], [Testnet]).
 
 ## Reaching Upgrade Epoch
 
@@ -78,8 +78,8 @@ Once the upgrade epoch is reached, follow the instructions in the corresponding
 [upgrade log].
 
 [upgrade log]: ../../mainnet/upgrade-log.md
-[Network Parameters]: ../../mainnet/README.md
-[Testnet Parameters]: ../../testnet/README.md
+[Mainnet]: ../../mainnet/README.md
+[Testnet]: ../../testnet/README.md
 [Testnet upgrade 2022-04-04]: ../../testnet/upgrade-log.md#2022-04-04-upgrade
 [Testnet upgrade 2022-03-03]: ../../testnet/upgrade-log.md#2022-03-03-upgrade
 [Testnet upgrade 2021-08-11]: ../../testnet/upgrade-log.md#2021-08-11-upgrade
@@ -114,8 +114,8 @@ State Changes], [Cobalt upgrade's Proposed State Changes]).
 
 ### Download and Verify the Provided Genesis File {#verify-genesis}
 
-In addition, download the new genesis file linked in the [Network Parameters]
-and save it as `/node/etc/genesis.json`.
+In addition, download the new genesis file linked in the Network Parameters
+page ([Mainnet], [Testnet]) and save it as `/node/etc/genesis.json`.
 
 Compare the dumped state with the downloaded genesis file:
 

docs/node/run-your-node/non-validator-node.md

@@ -29,7 +29,10 @@ mkdir -m700 -p /node/{etc,data}
 
 ### Copying the Genesis File
 
-The latest genesis file can be found in [Network Parameters](../mainnet/README.md). You should download the latest `genesis.json` file and copy it to the `/node/etc` directory we just created.
+The latest genesis file can be found in the Network Parameters page ([Mainnet], [Testnet]). You should download the latest `genesis.json` file and copy it to the `/node/etc` directory we just created.
+
+[Mainnet]: ../mainnet/README.md
+[Testnet]: ../testnet/README.md
 
 ## Configuration
 
@@ -68,7 +71,7 @@ Before using this configuration you should collect the following information to
 
 * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`.
 
-  You can find the current Oasis Seed Node address in the [Network Parameters](../mainnet/README.md).
+  You can find the current Oasis Seed Node address in the Network Parameters page ([Mainnet], [Testnet]).
 
 ## Starting the Oasis Node
 

docs/node/run-your-node/paratime-client-node.mdx

@@ -74,12 +74,15 @@ For example, running a ParaTime client node for an SGX-enabled ParaTime like Cip
 
 ### The ParaTime Bundle
 
-In order to run a ParaTime node you need to obtain the ParaTime bundle that
-needs to come from a trusted source. The bundle (usually with an `.orc`
+In order to run a ParaTime node you need to obtain an active ParaTime bundle,
+see the Network Parameters page ([Mainnet], [Testnet]). The bundle (`.orc`
 extension that stands for Oasis Runtime Container) contains all the needed
 ParaTime binaries together with the identifier and version metadata to ease
 deployment.
 
+[Mainnet]: ../mainnet/README.md
+[Testnet]: ../testnet/README.md
+
 When the ParaTime is running in a trusted execution environment (TEE) the bundle
 will also contain all the required artifacts (e.g. SGXS version of the binary
 and any enclave signatures).
@@ -207,9 +210,9 @@ runtime:
 Before using this configuration you should collect the following information to replace  the  variables present in the configuration file:.
 
 * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`.
-  * You can find the current Oasis Seed Node address in the [Network Parameters](../mainnet/README.md).
+  * You can find the current Oasis Seed Node address in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ runtime_orc_path }}`: Path to the [ParaTime bundle](paratime-client-node.mdx#the-paratime-bundle) of the form `/node/runtimes/foo-paratime.orc`.
-  * You can find the current Oasis-supported ParaTimes in the [Network Paramers](../mainnet/README.md#paratimes).
+  * You can find the current Oasis-supported ParaTimes in the Network Parameters page ([Mainnet], [Testnet]).
 
 ## Starting the Oasis Node
 

docs/node/run-your-node/paratime-node.mdx

@@ -177,10 +177,13 @@ in the consensus layer will not work and will be rejected by the network.
 
 For ParaTimes running inside [Intel SGX trusted execution environment](paratime-node.mdx#setting-up-trusted-execution-environment-tee), you will need to install the Oasis Core Runtime Loader.
 
-The Oasis Core Runtime Loader binary (`oasis-core-runtime-loader`) is part of Oasis Core binary releases, so make sure you download the appropriate version specified the [Network Parameters](../mainnet/README.md) page.
+The Oasis Core Runtime Loader binary (`oasis-core-runtime-loader`) is part of Oasis Core binary releases, so make sure you download the appropriate version specified the Network Parameters page ([Mainnet], [Testnet]).
 
 Install it to `bin` subdirectory of your node's working directory, e.g. `/node/bin/oasis-core-runtime-loader`.
 
+[Mainnet]: ../mainnet/README.md
+[Testnet]: ../testnet/README.md
+
 ### Install ParaTime Bundle
 
 For each ParaTime, you need to obtain its bundle and install it to the
@@ -327,11 +330,11 @@ Before using this configuration you should collect the following information to
 
 * `{{ external_address }}`: The external IP you used when registering this node.
 * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`.
-  * You can find the current Oasis Seed Node address in the [Network Parameters](../mainnet/README.md).
+  * You can find the current Oasis Seed Node address in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ runtime_orc_path }}`: Path to the [ParaTime bundle](paratime-node.mdx#the-paratime-bundle) of the form `/node/runtimes/foo-paratime.orc`.
-  * You can find the current Oasis-supported ParaTimes in the [Network Paramers](../mainnet/README.md#paratimes).
+  * You can find the current Oasis-supported ParaTimes in the Network Parameters page ([Mainnet], [Testnet]).
 * `{{ ias_proxy_address }}`: The IAS proxy address in the form `ID@HOST:port`.
-  * You can find the current Oasis IAS proxy address in the [Network Parameters](../mainnet/README.md#cipher-paratime).
+  * You can find the current Oasis IAS proxy address in the Network Parameters page ([Mainnet], [Testnet]).
   * If you want, you can also [run your own IAS proxy](ias-proxy.md).
 
 :::caution

docs/node/run-your-node/prerequisites/oasis-node.md

@@ -18,7 +18,10 @@ We suggest that you build Oasis Node from source yourself for a production deplo
 
 :::
 
-For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the [Network Parameters](../../mainnet/README.md) page.
+For convenience, we provide binaries that have been built by the Oasis Protocol Foundation. Links to the binaries are provided in the Network Parameters page ([Mainnet], [Testnet]).
+
+[Mainnet]: ../../mainnet/README.md
+[Testnet]: ../../testnet/README.md
 
 ## Building From Source
 
@@ -30,12 +33,14 @@ See [Oasis Core's Build Environment Setup and Building](../../../core/developmen
 
 The code in the [`master` branch](https://github.com/oasisprotocol/oasis-core/tree/master/) might be incompatible with the code used by other nodes in the Mainnet.
 
-Make sure to use the version specified in the [Network Parameters](../../mainnet/README.md).
+Make sure to use the version specified in the Network Parameters page ([Mainnet], [Testnet]).
 
 :::
 
 ## Adding `oasis-node` Binary to `PATH`
 
+To install the `oasis-node` binary next to your Oasis node data directory, copy/symlink it to e.g. `/node/bin`.
+
 To install the `oasis-node` binary for the current user, copy/symlink it to `~/.local/bin`.
 
 To install the `oasis-node` binary for all users of the system, copy it to `/usr/local/bin`.
@@ -46,8 +51,6 @@ If you intend to [run a ParaTime node](../paratime-node.mdx) you will need to ad
 
 * [Bubblewrap](https://github.com/projectatomic/bubblewrap) 0.4.1+, needed for creating process sandboxes.
 
-
-
   On Ubuntu 20.04+, you can install it with:
 
   ```text

docs/node/run-your-node/seed-node.md

@@ -23,7 +23,10 @@ mkdir -m700 -p /node/{etc,data}
 
 ### Copying the Genesis File
 
-The latest genesis file can be found in [Network Parameters](../mainnet/README.md). You should download the latest `genesis.json` file and copy it to the `/node/etc` directory we just created.
+The latest genesis file can be found in the Network Parameters page ([Mainnet], [Testnet]). You should download the latest `genesis.json` file and copy it to the `/node/etc` directory we just created.
+
+[Mainnet]: ../mainnet/README.md
+[Testnet]: ../testnet/README.md
 
 ## Configuration
 

docs/node/run-your-node/sentry-node.md

@@ -33,7 +33,11 @@ An example of full `YAML` configuration of a sentry node is below.
 Before using this configuration you should collect the following information to replace the  variables present in the configuration file:
 
 * `{{ external_address }}`: This is the external IP on which sentry node will be reachable.
-* `{{ seed_node_address }}`: This the seed node address of the form `ID@IP:port`. You can find the current Oasis Seed Node address in the [Network Parameters](../mainnet/README.md).
+* `{{ seed_node_address }}`: This the seed node address of the form `ID@IP:port`. You can find the current Oasis Seed Node address in the Network Parameters page ([Mainnet], [Testnet]).
+
+[Mainnet]: ../mainnet/README.md
+[Testnet]: ../testnet/README.md
+
 * `{{ validator_tendermint_id }}`: This is the Tendermint ID (address) of the Oasis validator node that will be protected by the sentry node. This address can be obtained by running:
 
   ```bash

docs/node/run-your-node/troubleshooting.md

@@ -4,7 +4,7 @@
 
 Before you begin troubleshooting we suggest you check all of the following:
 
-* Check that your current binary version is the latest listed on the [Current Network Parameters](../mainnet/README.md)
+* Check that your current binary version is the latest listed on the Network Parameters page ([Mainnet](../mainnet/README.md), [Testnet](../testnet/README.md))
   * Check the version on your localhost using `oasis-node --version`
   * Check the version on your server using `oasis-node --version`
 * If upgrading, make sure that you've wiped state (unless that is explicitly not required)

docs/node/run-your-node/validator-node.mdx

@@ -214,7 +214,7 @@ of that machine.
 * `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`.
 
   You can find the current Oasis Seed Node address in the Network Parameters
-  ([Mainnet], [Testnet]).
+  page ([Mainnet], [Testnet]).
 
 To use this configuration, save it in the `/node/etc/config.yml` file: