Merge #4382

4382: Update docs r=CarlosLopezDeLara a=CarlosLopezDeLara - Link to new environment config files - reorder stakepool operations to a more logical sequence - rename mainnet-config.json and mainnet-topology-json to config.json and topology.json in line with file names in cardano-world - rename cold.counter to opcert.counter - rename node.cert to opcert.cert Co-authored-by: CarlosLopezDeLara <[email protected]>
IntersectMBO · Aug 25, 2022 · 83c8f8c · 83c8f8c
2 parents e36c1a7 + 8c57090
commit 83c8f8c
Show file tree

Hide file tree

Showing 16 changed files with 63 additions and 40 deletions.
diff --git a/configuration/readme.md b/configuration/readme.md
@@ -0,0 +1,7 @@
+### Configuration
+
+Configuration files on this directory are only used for tests.
+
+Download configuration files for **MAINNET**, **PREPRODUCTION**, and **PREVIEW** networks from:
+
+* [https://book.world.dev.cardano.org/environments.html](https://book.world.dev.cardano.org/environments.html)
diff --git a/doc/getting-started/cli.md b/doc/getting-started/cli.md
@@ -27,6 +27,6 @@ by typing
         cardano-cli node key-gen \
             --cold-verification-key-file cold.vkey \
             --cold-signing-key-file cold.skey \
-            --operational-certificate-issue-counter-file cold.counter
+            --operational-certificate-issue-counter-file opcert.counter
 
 ![`cardano-cli` command hierarchy](images/cli.png)
diff --git a/doc/logging-monitoring/logging.md b/doc/logging-monitoring/logging.md
@@ -4,7 +4,7 @@ Here we will look at various ways to control _log output_ generated by the node
 
 When you start the node using the default configuration, logging is switched on, log output is directed to the console, minimal severity is `Info`, and verbosity is _normal_.
 
-You can change these configurations in the node's config file, for example: mainnet-config.json`
+You can change these configurations in the node's config file, for example: config.json`
 
 #### Enable and disable logs
 We can disable logging completely by setting `TurnOnLoggin` to `False`:

diff --git a/doc/stake-pool-operations/core_relay.md → doc/stake-pool-operations/0_core_relay.md b/doc/stake-pool-operations/core_relay.md → doc/stake-pool-operations/0_core_relay.md
@@ -6,7 +6,7 @@ Before you start your nodes, you need to prepare the topology files.
 
 Make the __block-producing__ node to "talk" only to __YOUR__ relay node. Do not forget to configure your firewall also:
 
-    nano mainnet-topology.json
+    nano topology.json
 
     {
       "Producers": [
@@ -23,7 +23,7 @@ Make the __block-producing__ node to "talk" only to __YOUR__ relay node. Do not
 Make your __relay node__ `talk` to your __block-producing__ node and __other relays__ in the network by editing the `topology.json` file:
 
 
-    nano mainnet-topology.json
+    nano topology.json
 
     {
       "Producers": [
@@ -45,6 +45,7 @@ Make your __relay node__ `talk` to your __block-producing__ node and __other rel
       ]
     }
 
-**Note**: If you want to connect to IPv4 and IPv6 relays, you must either not
-specify host addresses when starting `cardano-node` or make sure to specify
+**Note**: If you want to connect to IPv4 and IPv6 relays, you must either not specify host addresses when starting `cardano-node` or make sure to specify
 both an IPv4 and IPv6 host address.
+
+Please see [Understanding configuration files](../getting-started/understanding-config-files.md) to learn about P2P topology.
diff --git a/doc/stake-pool-operations/query_stakepool.md → ...ake-pool-operations/10_query_stakepool.md b/doc/stake-pool-operations/query_stakepool.md → ...ake-pool-operations/10_query_stakepool.md
diff --git a/...stake-pool-operations/withdraw-rewards.md → ...ke-pool-operations/11_withdraw-rewards.md b/...stake-pool-operations/withdraw-rewards.md → ...ke-pool-operations/11_withdraw-rewards.md
@@ -74,3 +74,5 @@ You'll withdraw rewards into a payment.addr which will pay for the transaction f
     cardano-cli transaction submit \
     --tx-file withdraw_rewards.signed \
     --mainnet
+
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/...stake-pool-operations/retire_stakepool.md → ...ke-pool-operations/12_retire_stakepool.md b/...stake-pool-operations/retire_stakepool.md → ...ke-pool-operations/12_retire_stakepool.md
@@ -2,11 +2,11 @@
 
 To retire a pool we need to:
 
-0. Make sure that any pool owners are aware of your retirement intention and will not remove their Pledge until the pool has retired. 
+0. Make sure that any pool owners are aware of your retirement intention and will not remove their Pledge until the pool has retired.
 1. Create a **deregistration certificate** and specify an epoch when your pool will retire. There is a limit on how far in the future this can be (given by a protocol parameter - see below). Make sure you give sufficient time for delegators to switch pools
 2. Submit the certificate to the blockchain with a **transaction**
 3. Notify your delegators of your intention to retire the pool using your usual communication mechanisms. Wallets and other tools should highlight that the pool is retiring and discourage new delegations.
-4. Keep your system working normally until we reach the epoch you chose on the certificate for the pool to expire. Retirement takes place when the first block of the selected epoch is processed (before the transactions for that block are processed.) 
+4. Keep your system working normally until we reach the epoch you chose on the certificate for the pool to expire. Retirement takes place when the first block of the selected epoch is processed (before the transactions for that block are processed.)
 5. Move your funds out from your pledge address to a different wallet.  
 6. When the pool is effectively retired, the pool deposit is sent back to the rewards account.
 7. **Wait for any pending rewards to be paid.**
@@ -137,3 +137,5 @@ And submit to the blockchain:
 The pool will retire at the end of epoch 52.
 
 If we change our mind, we can create and submit a new registration certificate before epoch 53, which will then overrule the deregistration certificate.
+
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/...-operations/getConfigFiles_AND_Connect.md → ...perations/1_getConfigFiles_AND_Connect.md b/...-operations/getConfigFiles_AND_Connect.md → ...perations/1_getConfigFiles_AND_Connect.md
@@ -8,26 +8,34 @@ Starting the node and connecting it to the network requires 3 configuration file
 
 You can download the configuration files from:
 
- [https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/index.html](https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/index.html)
+ [https://book.world.dev.cardano.org/environments.html](https://book.world.dev.cardano.org/environments.html)
 
 
 From the CLI you can use
 
-For Cardano testnet
+For Preview Testnet
 
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-config.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-byron-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-shelley-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-alonzo-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/testnet-topology.json
+    wget https://book.world.dev.cardano.org/environments/preview/config.json
+    wget https://book.world.dev.cardano.org/environments/preview/topology.json
+    wget https://book.world.dev.cardano.org/environments/preview/byron-genesis.json
+    wget https://book.world.dev.cardano.org/environments/preview/shelley-genesis.json
+    wget https://book.world.dev.cardano.org/environments/preview/alonzo-genesis.json
+
+For Preproduction testnets
+
+    wget https://book.world.dev.cardano.org/environments/preprod/config.json
+    wget https://book.world.dev.cardano.org/environments/preprod/topology.json
+    wget https://book.world.dev.cardano.org/environments/preprod/byron-genesis.json
+    wget https://book.world.dev.cardano.org/environments/preprod/shelley-genesis.json
+    wget https://book.world.dev.cardano.org/environments/preprod/alonzo-genesis.json
 
 For Mainnet:
 
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-config.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-byron-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-shelley-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-alonzo-genesis.json
-    wget https://hydra.iohk.io/job/Cardano/cardano-node/cardano-deployment/latest-finished/download/1/mainnet-topology.json
+    wget https://book.world.dev.cardano.org/environments/mainnet/config.json
+    wget https://book.world.dev.cardano.org/environments/mainnet/topology.json
+    wget https://book.world.dev.cardano.org/environments/mainnet/byron-genesis.json
+    wget https://book.world.dev.cardano.org/environments/mainnet/shelley-genesis.json
+    wget https://book.world.dev.cardano.org/environments/mainnet/alonzo-genesis.json
 
 Starting the node uses the command `cardano-node run` and a set of options.
 
@@ -50,12 +58,12 @@ Get the complete list of available options with `cardano-node run --help`
 To start a passive node:
 
      cardano-node run \
-       --topology path/to/mainnet-topology.json \
+       --topology path/to/topology.json \
        --database-path path/to/db \
        --socket-path path/to/db/node.socket \
        --host-addr x.x.x.x \
        --port 3001 \
-       --config path/to/mainnet-config.json
+       --config path/to/config.json
 
 **Replace x.x.x.x with your public IP and indicate the correct paths to the required files.**
 
@@ -74,4 +82,4 @@ Check that the node is syncing by fetching the current tip. When syncing `slot`
         "block": 5580350
     }
 
-**Note**`--mainnet` identifies the Cardano mainnet, for testnets use `--testnet-magic 1097911063` instead.
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/...stake-pool-operations/start_your_nodes.md → ...ake-pool-operations/2_start_your_nodes.md b/...stake-pool-operations/start_your_nodes.md → ...ake-pool-operations/2_start_your_nodes.md
@@ -3,27 +3,27 @@
 Start a __relay node__ with:
 
     cardano-node run \
-    --topology mainnet-topology.json \
+    --topology topology.json \
     --database-path /db \
     --socket-path /db/node.socket \
     --host-addr <PUBLIC IPv4 ADDRESS> \
     --port <PORT> \
-    --config mainnet-config.json
+    --config config.json
 
 Note: Use `--host-ipv6-addr` for IPv6 address.
 
 Start a __block producing__ node with:
 
     cardano-node run \
-    --topology mainnet-topology.json \
+    --topology topology.json \
     --database-path /db \
     --socket-path /db/node.socket \
     --host-addr <PUBLIC IP> \
     --port <PORT> \
-    --config mainnet-config.json \
+    --config config.json \
     --shelley-kes-key kes.skey \
     --shelley-vrf-key vrf.skey \
-    --shelley-operational-certificate node.cert
+    --shelley-operational-certificate opcert.cert
 
 Please note that when running a node, it is important to use process monitoring so that the node can be automatically restarted when it terminates unexpectedly. The node relies on being restarted as part of its mechanism for automatically recovering from disk file corruption or other unexpected conditions. In case the node process is not automatically restarted, the node will not be available. Thus for example, stake pools will not be able to create blocks and exchanges will not be able to get wallet information.
 

diff --git a/...ake-pool-operations/keys_and_addresses.md → ...e-pool-operations/3_keys_and_addresses.md b/...ake-pool-operations/keys_and_addresses.md → ...e-pool-operations/3_keys_and_addresses.md
@@ -78,4 +78,4 @@ cardano-cli query utxo \
 --------------------------------------------------------------------------------------------
 ```
 
-**Note**`--mainnet` identifies the Cardano mainnet, for testnets use `--testnet-magic 1097911063` instead.
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/...ake-pool-operations/simple_transaction.md → ...e-pool-operations/4_simple_transaction.md b/...ake-pool-operations/simple_transaction.md → ...e-pool-operations/4_simple_transaction.md
@@ -146,4 +146,4 @@ We must give it some time to get incorporated into the blockchain, but eventuall
     > b64ae44e1195b04663ab863b62337e626c65b0c9855a9fbb9ef4458f81a6f5ee     0         10000000 lovelace
 
 
-**Note**`--mainnet` identifies the Cardano mainnet, for testnets use `--testnet-magic 1097911063` instead.
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/doc/stake-pool-operations/register_key.md → doc/stake-pool-operations/5_register_key.md b/doc/stake-pool-operations/register_key.md → doc/stake-pool-operations/5_register_key.md
@@ -91,4 +91,4 @@ And submit it:
 
 Your stake key is now registered on the blockchain.
 
-**Note**`--mainnet` identifies the Cardano mainnet, for testnets use `--testnet-magic 1097911063` instead.
+**Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/doc/stake-pool-operations/node_keys.md → doc/stake-pool-operations/6_node_keys.md b/doc/stake-pool-operations/node_keys.md → doc/stake-pool-operations/6_node_keys.md
@@ -44,7 +44,7 @@ Create a directory on your local machine to store your keys:
     cardano-cli node key-gen \
     --cold-verification-key-file cold.vkey \
     --cold-signing-key-file cold.skey \
-    --operational-certificate-issue-counter-file cold.counter
+    --operational-certificate-issue-counter-file opcert.counter
 
 #### Generate VRF Key pair
 
@@ -85,9 +85,9 @@ To generate the certificate:
     cardano-cli node issue-op-cert \
     --kes-verification-key-file kes.vkey \
     --cold-signing-key-file cold.skey \
-    --operational-certificate-issue-counter cold.counter \
+    --operational-certificate-issue-counter opcert.counter \
     --kes-period 7398 \
-    --out-file node.cert
+    --out-file opcert.cert
 
 #### Move the cold keys to secure storage and remove them from your local machine.
 
@@ -108,6 +108,6 @@ Log in to your server and verify that the files are there:
 
     ls pool-keys
 
-    > kes.skey  kes.vkey  node.cert  vrf.skey  vrf.vkey
+    > kes.skey  kes.vkey  opcert.cert  vrf.skey  vrf.vkey
 
 Later on we will learn how to register our pool in the blockchain.
diff --git a/doc/stake-pool-operations/KES_period.md → doc/stake-pool-operations/7_KES_period.md b/doc/stake-pool-operations/KES_period.md → doc/stake-pool-operations/7_KES_period.md
@@ -63,7 +63,7 @@ cardano-cli node issue-op-cert \
 
 ## :warning: Vasil hard fork breaking changes
 
-Note that from the Vasil hard fork onwards there is a new rule for the cold.counter:
+Note that from the Vasil hard fork onwards there is a new rule for the opcert.counter:
 
 A new Operational Certificate will be considered valid only if its counter value is exactly one more than the previous Operational Certificate that has successfully minted at least one block.
 

diff --git a/...ake-pool-operations/register_stakepool.md → ...e-pool-operations/8_register_stakepool.md b/...ake-pool-operations/register_stakepool.md → ...e-pool-operations/8_register_stakepool.md
@@ -12,8 +12,8 @@ First, make sure you have access to:
 | `payment.addr` | funded address linked to `stake` |
 | `cold.vkey` | cold verification key |
 | `cold.skey` | cold signing key |
-| `cold.counter` | issue counter |
-| `node.cert` | operational certificate |
+| `opcert.counter` | issue counter |
+| `opcert.cert` | operational certificate |
 | `kes.vkey` | KES verification key |
 | `kes.skey` | KES signing key |
 | `vrf.vkey` | VRF verification key |
@@ -58,14 +58,14 @@ This validates that JSON fits the required schema, if it does, you will get the
 
 The operator should register their relay nodes on-chain (including them into the pool’s registration certificate) to ensure that other peers on the network have an ability to connect to them. Registered relay nodes are continuously updated and added to a JSON dataset. IOG offers this [list of all registered relays categorized by geographical location](https://explorer.cardano-mainnet.iohk.io/relays/topology.json) for SPOs to consider for connection purposes. It is recommended that SPOs generate a configuration that uses 20 other SPOs as peers. The list allows selecting peers that are both nearby and far away so that there is strong inter-region connectivity.
 
-To register your relay nodes during the creation of the pool registration certificate, specify their IP addresses and/or domain name using: 
+To register your relay nodes during the creation of the pool registration certificate, specify their IP addresses and/or domain name using:
 
 ```
 --pool-relay-ipv4 <IPADDRESS>
 --single-host-pool-relay <DOMAIN_NAME>
 ```
 
-After certificate submission, relay nodes will be added to the topology file enabling other SPOs to connect to them. Additionally, one of the IOG nodes will also establish a connection so that an operator has at least one downstream peer. 
+After certificate submission, relay nodes will be added to the topology file enabling other SPOs to connect to them. Additionally, one of the IOG nodes will also establish a connection so that an operator has at least one downstream peer.
 
 **Related topics:**
 
@@ -207,3 +207,6 @@ Get Pool ID
 Check for the presence of your poolID in the network ledger state, with:
 
     cardano-cli query ledger-state --mainnet | grep publicKey | grep <poolId>
+
+
+    **Note**`--mainnet` identifies the Cardano mainnet, for **preproduction testnet** use `--testnet-magic 1` and for **preview testnet** use `--testnet-magic 2`
diff --git a/...ke-pool-operations/leadership_schedule.md → ...-pool-operations/9_leadership_schedule.md b/...ke-pool-operations/leadership_schedule.md → ...-pool-operations/9_leadership_schedule.md