diff --git a/configuration/readme.md b/configuration/readme.md new file mode 100644 index 00000000000..015a00f5db6 --- /dev/null +++ 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 index 3b55ea4f5c6..eafaf761c3f 100644 --- 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 index e019b02bb56..eecd828415c 100644 --- 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 b/doc/stake-pool-operations/0_core_relay.md similarity index 80% rename from doc/stake-pool-operations/core_relay.md rename to doc/stake-pool-operations/0_core_relay.md index 19456669b25..3d33fc883b4 100644 --- a/doc/stake-pool-operations/core_relay.md +++ b/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 b/doc/stake-pool-operations/10_query_stakepool.md similarity index 100% rename from doc/stake-pool-operations/query_stakepool.md rename to doc/stake-pool-operations/10_query_stakepool.md diff --git a/doc/stake-pool-operations/withdraw-rewards.md b/doc/stake-pool-operations/11_withdraw-rewards.md similarity index 93% rename from doc/stake-pool-operations/withdraw-rewards.md rename to doc/stake-pool-operations/11_withdraw-rewards.md index 20435a8f039..4de4000c7d5 100644 --- a/doc/stake-pool-operations/withdraw-rewards.md +++ b/doc/stake-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/doc/stake-pool-operations/retire_stakepool.md b/doc/stake-pool-operations/12_retire_stakepool.md similarity index 95% rename from doc/stake-pool-operations/retire_stakepool.md rename to doc/stake-pool-operations/12_retire_stakepool.md index 51980ab7757..cf99c4bf8bc 100644 --- a/doc/stake-pool-operations/retire_stakepool.md +++ b/doc/stake-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/doc/stake-pool-operations/getConfigFiles_AND_Connect.md b/doc/stake-pool-operations/1_getConfigFiles_AND_Connect.md similarity index 57% rename from doc/stake-pool-operations/getConfigFiles_AND_Connect.md rename to doc/stake-pool-operations/1_getConfigFiles_AND_Connect.md index 269ed9684e3..a8ec6c600a9 100644 --- a/doc/stake-pool-operations/getConfigFiles_AND_Connect.md +++ b/doc/stake-pool-operations/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/doc/stake-pool-operations/start_your_nodes.md b/doc/stake-pool-operations/2_start_your_nodes.md similarity index 88% rename from doc/stake-pool-operations/start_your_nodes.md rename to doc/stake-pool-operations/2_start_your_nodes.md index 0dd0fbfdd76..755dc5c4e76 100644 --- a/doc/stake-pool-operations/start_your_nodes.md +++ b/doc/stake-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 \ --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 \ --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/doc/stake-pool-operations/keys_and_addresses.md b/doc/stake-pool-operations/3_keys_and_addresses.md similarity index 93% rename from doc/stake-pool-operations/keys_and_addresses.md rename to doc/stake-pool-operations/3_keys_and_addresses.md index 54427c41441..bc83762c203 100644 --- a/doc/stake-pool-operations/keys_and_addresses.md +++ b/doc/stake-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/doc/stake-pool-operations/simple_transaction.md b/doc/stake-pool-operations/4_simple_transaction.md similarity index 96% rename from doc/stake-pool-operations/simple_transaction.md rename to doc/stake-pool-operations/4_simple_transaction.md index c068447e2fb..1c23896e151 100644 --- a/doc/stake-pool-operations/simple_transaction.md +++ b/doc/stake-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 b/doc/stake-pool-operations/5_register_key.md similarity index 94% rename from doc/stake-pool-operations/register_key.md rename to doc/stake-pool-operations/5_register_key.md index ff8d2278c0b..82f0315f978 100644 --- a/doc/stake-pool-operations/register_key.md +++ b/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 b/doc/stake-pool-operations/6_node_keys.md similarity index 94% rename from doc/stake-pool-operations/node_keys.md rename to doc/stake-pool-operations/6_node_keys.md index c9334243095..d029c99b954 100644 --- a/doc/stake-pool-operations/node_keys.md +++ b/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 b/doc/stake-pool-operations/7_KES_period.md similarity index 99% rename from doc/stake-pool-operations/KES_period.md rename to doc/stake-pool-operations/7_KES_period.md index 06f9e0e44bc..a9dd009573a 100644 --- a/doc/stake-pool-operations/KES_period.md +++ b/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/doc/stake-pool-operations/register_stakepool.md b/doc/stake-pool-operations/8_register_stakepool.md similarity index 96% rename from doc/stake-pool-operations/register_stakepool.md rename to doc/stake-pool-operations/8_register_stakepool.md index 94e0a356912..457874178ae 100644 --- a/doc/stake-pool-operations/register_stakepool.md +++ b/doc/stake-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 --single-host-pool-relay ``` -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 + + + **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/leadership_schedule.md b/doc/stake-pool-operations/9_leadership_schedule.md similarity index 100% rename from doc/stake-pool-operations/leadership_schedule.md rename to doc/stake-pool-operations/9_leadership_schedule.md