From 5c9a6c74c4d8d09974e8631e22ccc83231dd9d92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Fri, 20 Oct 2023 09:42:53 +0200 Subject: [PATCH 01/10] docs: Revamp validator-node to use Oasis CLI --- docs/node/run-your-node/validator-node.mdx | 669 ++++++++------------- 1 file changed, 258 insertions(+), 411 deletions(-) diff --git a/docs/node/run-your-node/validator-node.mdx b/docs/node/run-your-node/validator-node.mdx index af67a1dd42..b8f254cc50 100644 --- a/docs/node/run-your-node/validator-node.mdx +++ b/docs/node/run-your-node/validator-node.mdx @@ -3,52 +3,57 @@ import {findSidebarItem} from '@site/src/sidebarUtils'; # Validator Node -This guide will walk you through the process of setting up your **validator node** -for the Oasis Network on either the Mainnet or the Testnet. It is designed for -individuals who have a basic understanding of command line tools. +This guide will walk you through the process of setting up your **validator +node** for the Oasis Network either on Mainnet or Testnet. It is designed for +individuals who have basic understanding of the command line environment. + +We will be using two separate physical machines for deployment: +- your local system, referred to as `localhost`, +- a remote `server` which will function as an Oasis node. + +The guide consists of the following steps: + +1. On the `localhost`, we will use [Oasis CLI] to [Initialize your +Entity](#initialize-entity) which is essential for deploying nodes on the +network. To ensure the security of these private keys, we strongly recommend +to either isolate the `localhost` from any network or internet connectivity, or +use a [hardware wallet] as a secure storage, such as [Ledger]. + +[Oasis CLI]: ../../general/manage-tokens/cli/README.md +[hardware wallet]: + https://en.wikipedia.org/wiki/Hardware_security_module +[Ledger]: + ../../../general/manage-tokens/holding-rose-tokens/ledger-wallet + +2. After the entity has been created, we will move over to the `server` and +[Start the Oasis Node](#starting-the-oasis-node). The server needs to meet +the hardware requirements and have access to the internet. + +[create your entity]: #creating-your-entity +[set up the server in order to start the Oasis node]: + #running-an-oasis-node-on-the-server + +3. Finally, we will [stake assets to your entity, register it on the network, +and attach the unique ID](#staking-and-registering) of the +Oasis Node instance running on your server. ## Prerequisites Before proceeding with this guide, ensure that you have completed the steps -outlined in the [Prerequisites] section so that: +outlined in the [Prerequisites] chapter so that: + * your system meets the [hardware requirements], -* you have the [Oasis Node binary] installed on your systems, +* you have the [Oasis CLI] installed on your `localhost`, +* you have the [Oasis Node binary] installed on your `server`, * you understand what are [Stake requirements] to become a validator on the - Oasis Network. + Oasis Network. [Prerequisites]: prerequisites/ [hardware requirements]: prerequisites/hardware-recommendations.md [Oasis Node binary]: prerequisites/oasis-node.md [Stake requirements]: prerequisites/stake-requirements.md -## Physical Machines - -You will be using two separate physical machines for deployment: your local -system, referred to as `localhost`, and a remote `server` which will function - as an Oasis node. The reason for this is to ensure protection of the keys used - to setup your node. - -**Localhost:** On the localhost, you will [create your entity] which is -essential for deploying nodes on the network. To ensure the security of these -private keys, we strongly recommend to isolate the localhost from any network or -internet connectivity. Once the keys have been generated, it is highly -recommended to use [Hardware Security Modules (HSM)] for secure storage -such as the [Ledger wallet]. - -[Hardware Security Modules (HSM)]: - https://en.wikipedia.org/wiki/Hardware_security_module -[Ledger wallet]: - ../../../general/manage-tokens/holding-rose-tokens/ledger-wallet - -**Server:** After the entity has been created, proceed to [set up the server in - order to start the Oasis node]. The server needs to meet the hardware - requirements and have an acces to the internet. - -[create your entity]: #creating-your-entity -[set up the server in order to start the Oasis node]: - ./#running-an-oasis-node-on-the-server - -## Creating Your Entity on the `localhost` +## Initialize Entity :::danger @@ -63,257 +68,157 @@ of nodes on the network. This guide has been designed with a particular file structure in mind. Nonetheless, feel free to reorganize and rename directories as needed to accommodate your preferences. -### Creating a Working Directory - -Begin by creating a directory named `/localhostdir`. This location will be used -to store generated artifacts. It is important that you securely store the -generated artifacts. - -```bash -mkdir /localhostdir -``` - -Within the `/localhostdir`, create the following subdirectories and set their -permissions to `rwx------`: - -* `entity`: This will store your entity. The private contents in this -directory are safest if used on a machine kept disconnected from the internet. - -* `node`: This will store a node's identity. The private contents of this -directory will be used on the node itself. - -To create the directory structure, use the following commands: - -```bash -cd /localhostdir -mkdir -m700 -p {entity,node} -``` - -### Copying the Genesis File - -To continue, download the most recent `genesis.json` file from the -[Network Parameters] section and save it to your `/localhostdir` working -directory: - -```bash -cd /localhostdir -# replace RELEASE_DATE with actual Mainnet consensus dump date, e.g. 2022-11-04 -curl -L -o genesis.json https://github.com/oasisprotocol/mainnet-artifacts/releases/download/RELEASE_DATE/genesis.json -``` - -Then, set the environment variable that points to its path as follows: - -```bash -GENESIS_FILE_PATH=/localhostdir/genesis.json -``` - -[Network Parameters]: ../mainnet/README.md - -### Initializing an Entity - -An entity is critical to operating nodes on the network as it controls the stake attached to a given individual or organization on the network. We highly recommend using an HSM or [Ledger](../../../oasis-core-ledger) device to protect your entity private key. - -#### Using a Ledger-based Signer - -The Ledger-based signer stores your private keys on your Ledger wallet. It is implemented as an Oasis Core signer plugin. +### Add Entity Account to Oasis CLI -You will need to set it up as described in the [Setup](../../oasis-core-ledger/usage/setup.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). +An entity is critical to operating nodes on the network as it controls the stake +attached to a given individual or organization on the network. The entity is +represented as a consensus-layer account using the Ed25519 encryption scheme. +To protect your entity private key, we strongly recommend using a [hardware +wallet] such as [Ledger]. -As the entity's private key is stored on your Ledger wallet, you only need to export the entity's public key as described in [Exporting Public Key to Entity](../../oasis-core-ledger/usage/entity.md) section of our [Oasis Core Ledger docs](../../../oasis-core-ledger). +We will be using [Oasis CLI] to initialize the entity and later stake our assets +and register the entity on the network. If you haven't already, go ahead and +install it. -This will create 1 file in `/localhostdir/entity`: - -* `entity.json`: The entity descriptor. This is the JSON of the unsigned information to be sent to the registry application on the network. - -:::info - -There will be no signed entity descriptor, i.e. `entity_genesis.json`, created yet. It will get created when you'll update the entity descriptor with your signed node descriptor as described in the [Adding the Node to the Entity Descriptor](#adding-the-node-to-the-entity-descriptor) section. - -::: - -#### Using a File-based Signer +Oasis CLI stores either your entity private key encrypted inside a file or a +reference to an account whose keypair is stored on your hardware wallet. :::danger -We strongly suggest that you do not use any entity that is generated with the file-based signer on the Mainnet. - -When using the file-based signer the use of an [offline/air-gapped machine](https://en.wikipedia.org/wiki/Air_gap_\(networking\)) for this purpose is highly recommended. Gaining access to the entity private key can compromise your tokens. +If you really need to use the file-based wallet using another +[offline/air-gapped machine] for this purpose is highly recommended. Gaining +access to the entity private key can compromise your tokens and the network +security through proposing and signing malicious governance transactions. ::: -To initialize an entity simply run the following from `/localhostdir/entity`: +On the `localhost` add a new entity account to Oasis CLI. This can be done in +one of the following ways: -```bash -oasis-node registry entity init -``` +- Create an account entry in Oasis CLI, but use your Ledger device to store + the actual keypair to sign the transactions by executing + [`oasis wallet create`] and passing the `--kind ledger` flag. For example: -This will generate three files in `/localhostdir/entity`: + ```shell + oasis wallet create my_entity --kind ledger + ``` -* `entity.pem`: The private key of the entity. **NEVER SHARE THIS AS IT CAN BE USED TO TRANSFER STAKE.** -* `entity.json`: The entity descriptor. This is the JSON of the unsigned information to be sent to the registry application on the network. -* `entity_genesis.json`: This JSON object contains the entity descriptor that has been signed with entity's private key, i.e. `entity.pem`. This is meant to be shared for inclusion in the Genesis block. +- Import your existing `entity.pem` into Oasis CLI by executing + [`oasis wallet import-file`] command, for example: -### Initializing a Node + ```shell + oasis wallet import-file my_entity entity.pem + ``` -A node registers itself to the network when the node starts up. However, in order to validate itself, the entity signs a public key associated with the node. This allows the node registration to happen without the uploading entity's private key to the internet. +- Generate a new keypair and store the private key in the encrypted file by + executing [`oasis wallet create`]: -:::info + ```shell + oasis wallet create my_entity + ``` -To get the `$ENTITY_ID` needed below check the value of the `id` field in `entity.json`, e.g. with the following content in `entity.json`: +Similar to the examples above we will assume that you named your entity account +as **`my_entity`** in the remainder of this chapter. -``` -{"v":1,"id":"2D5nSE3uFGvp2UkUY3w8OSjnCCYmQX/3JpJ77+aJGUQ="} -``` - -the entity ID is `2D5nSE3uFGvp2UkUY3w8OSjnCCYmQX/3JpJ77+aJGUQ=`. - -::: - -To initialize a validator node, take note of the static IP of the server where your node will run, and issue the following commands from the `/localhostdir/node` directory: - -```bash -ENTITY_ID= -STATIC_IP= -oasis-node registry node init \ - --node.entity_id $ENTITY_ID \ - --node.consensus_address $STATIC_IP:26656 \ - --node.role validator -``` - -This command will create a validator node's identity so that it can be a self-signed node (this is what allows self-registration). - -:::info +### Write the Entity Descriptor File -There are more options for node initialization that you can explore by running: +On the `localhost` we begin by creating a directory named `/localhostdir` with +the `entity` subdirectory that will contain the entity file descriptor. -```bash -oasis-node registry node init --help +```shell +mkdir -p /localhostdir/entity ``` -The options shown above are just the minimum. +Create a JSON file containing the **public key** of your entity by executing +[`oasis account entity init`] and store it as `entity.json`, for example: -::: - -The command will generate the following files: - -* `consensus.pem`: The node's consensus private key. **DO NOT SHARE** -* `consensus_pub.pem`: The node's consensus public key. -* `identity.pem`: The node's identity private key. **DO NOT SHARE** -* `identity_pub.pem`: The node's identity public key. -* `node_genesis.json`: The node's details if you wish to include this node in the genesis file of the network. -* `p2p.pem`: The node's private key for libp2p. **DO NOT SHARE** -* `p2p_pub.pem`: The node's public key for libp2p. -* `sentry_client_tls_identity.pem`: The node's TLS private key for communicating with sentry nodes. **DO NOT SHARE** -* `sentry_client_tls_identity_cert.pem`: The node's TLS certificate for communicating with sentry nodes. - -### Adding the Node to the Entity Descriptor - -Once the node has been initialized, we need to add it to the entity descriptor so that it can properly register itself when the node starts up. The instructions differ based on what kind of signer was used to generate the entity. - -* **If using the plugin-based signer,** execute the following command in the `/localhostdir/entity` directory (again this assumes the use of the Ledger signer plugin in which case you will need to then confirm the signing operation on the Ledger device): - -```bash -oasis-node registry entity update \ - --signer.backend plugin \ - --signer.plugin.name ledger \ - --signer.plugin.path "$LEDGER_SIGNER_PATH" \ - --signer.plugin.config "wallet_id:$LEDGER_WALLET_ID,index:$LEDGER_INDEX" \ - --entity.node.descriptor /localhostdir/node/node_genesis.json +```shell +oasis account entity init -o /localhostdir/entity/entity.json --account my_entity ``` -* **If using the file-based signer**, execute the following command in the `/localhostdir/entity` directory: +Now, we can move on to configuring our Oasis node with the freshly generated +`entity.json`. -```bash -oasis-node registry entity update \ - --entity.node.descriptor /localhostdir/node/node_genesis.json -``` +[Ledger]: ../../general/manage-tokens/holding-rose-tokens/ledger-wallet.md +[offline/air-gapped machine]: https://en.wikipedia.org/wiki/Air_gap_\(networking\) +[`oasis wallet create`]: ../../general/manage-tokens/cli/wallet.md#create +[`oasis wallet import`]: ../../general/manage-tokens/cli/wallet.md#import +[`oasis wallet import-file`]: ../../general/manage-tokens/cli/wallet.md#import-file +[`oasis account entity init`]: ../../general/manage-tokens/cli/account.md#entity-init -This will update the entity descriptor in `entity.json` and subsequently the `entity_genesis.json` file that contains the signed entity descriptor payload. - -## Running an Oasis Node on the `server` +## Starting the Oasis Node ### Setting up the Oasis Node's Working Directory -Before we run the node on the `server` we need to ensure that we have a place to store necessary files for the node. +Before we run the node on the `server` we need to ensure that we have a place to +store necessary files for the node. :::info -We will reference the working directory on the `server` as `/serverdir` throughout the documentation. +We will reference the working directory on the `server` as `/node` +throughout the documentation. ::: -#### Setting Up the the `/serverdir` Directory +#### Setting Up the the `/node` Directory -In the `/serverdir` directory we will create the following subdirectories: +We will reference the working directory on the `server` as `/node` (with +subdirectories `/node/{etc,bin,runtimes,data}`) throughout the documentation. +In the `/node` directory, create the following subdirectories: -* `etc/` - this is to store the configuration -* `node/` - this is to store the node's data -* `node/entity/` - this is to store the public components of the node's entity +* `etc/`: this is to store the configuration and `entity.json` +* `data/`: this is to store the node's data +* `bin/`: this is to store the `oasis-node` binary +* `runtimes/`: this is to store the ParaTime `.orc` bundles You can make this directory structure by executing the following command: -```bash -mkdir -m700 -p /serverdir/{etc,node,node/entity} +```shell +mkdir -m700 -p /node/{etc,bin,runtimes,data} ``` -#### Copying the Node Artifacts from `/localhostdir` - -In order for the node registration to work properly, as defined in `/localhostdir/entity.json`, you must copy the node's artifacts you generated in the [Initializing a Node](#initializing-a-node) section. To do so, upload the following files from `/localhostdir/node` to `/serverdir/node` over a secure channel (e.g. SSH): - -* `consensus.pem` -* `consensus_pub.pem` -* `identity.pem` -* `identity_pub.pem` -* `p2p.pem` -* `p2p_pub.pem` -* `sentry_client_tls_identity.pem` -* `sentry_client_tls_identity_cert.pem` - -After copying, make sure that all these files have `0600` permissions, i.e. only their owner has `read` and `write` permissions. - -To do so, run the following command: - -```bash -chmod -R 600 /serverdir/node/*.pem -``` - -:::caution - -You may have noticed that some of these files were listed as **DO NOT SHARE** in the [Initializing a Node](#initializing-a-node) section. - -In the future, these keys should be generated and referenced from an HSM. However, until HSM support is implemented, these keys should be kept as secure as possible on the `server`. - -::: - #### Copying the Public Entity Artifacts from `/localhostdir` -We will also need to have the public entity artifacts from the `/localhostdir` present on the `server`. Copy the `/localhostdir/entity/entity.json` file on `localhost` to `/serverdir/node/entity/entity.json` on the `server`. +We will also need to have the public entity artifacts from the `/localhostdir` +present on the `server`. Copy the `/localhostdir/entity/entity.json` file on +`localhost` to `/node/etc/entity.json` on the `server`. #### Copying the Genesis File to the server -The latest Genesis file can be found in the [Network Parameters](../mainnet/README.md). You should download the latest `genesis.json` file and copy it to `/serverdir/etc/genesis.json` on the `server`. +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 `/node/etc/genesis.json` on the `server`. + +[Mainnet]: ../mainnet/README.md +[Testnet]: ../testnet/README.md #### Configuring the Oasis Node -There are a variety of options available when running an Oasis node. The following YAML file is a basic configuration for a validator node on the network. +There are a variety of options available when running an Oasis node. The +following YAML file is a basic configuration for a validator node on the +network. -Before using this configuration you should collect the following information to replace the variables present in the configuration file: +Before using this configuration you should collect the following information to +replace the variables present in the configuration file: -* `{{ external_address }}`: The external IP you used when registering this node. +* `{{ external_ip }}`: The external/public IP address you used when registering + this node. :::info -If you are using a [Sentry Node](sentry-node.md), you should use the public IP of that machine. +If you are using a [Sentry Node](sentry-node.md), you should use the public IP +of that machine. ::: -* `{{ seed_node_address }}`: The seed node address in the form `ID@IP:port`. +* `{{ 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 + ([Mainnet], [Testnet]). -To use this configuration, save it in the `/serverdir/etc/config.yml` file and pass it to the `oasis-node` command as an argument to the `--config` flag. +To use this configuration, save it in the `/node/etc/config.yml` file: -```yaml +```yaml title="/node/etc/config.yml" ## # Oasis Node Configuration # @@ -332,7 +237,7 @@ To use this configuration, save it in the `/serverdir/etc/config.yml` file and p # Set this to where you wish to store node data. The node's artifacts # should also be located in this directory. -datadir: /serverdir/node +datadir: /node/data # Logging. # @@ -357,14 +262,14 @@ log: # Genesis. genesis: # Path to the genesis file for the current version of the network. - file: /serverdir/etc/genesis.json + file: /node/etc/genesis.json # Worker configuration. worker: registration: # In order for the node to register itself, the entity.json of the entity # used to provision the node must be available on the node. - entity: /serverdir/node/entity/entity.json + entity: /node/etc/entity.json # Consensus backend. consensus: @@ -380,7 +285,7 @@ consensus: # The external IP that is used when registering this node to the network. # NOTE: If you are using the Sentry node setup, this option should be # omitted. - external_address: tcp://{{ external_address }}:26656 + external_address: tcp://{{ external_ip }}:26656 # List of seed nodes to connect to. # NOTE: You can add additional seed nodes to this list if you want. @@ -389,23 +294,61 @@ consensus: - "{{ seed_node_address }}" ``` +#### Starting Oasis Node for the First Time + +Execute the Oasis node and pass the config file above by invoking: + +```shell +oasis-node --config /node/etc/config.yml +``` + +After the node starts, it will automatically register itself to the peer-to-peer +network. The following files will be generated in your `/node/data` folder: + +* `consensus.pem`: The node's consensus private key. **DO NOT SHARE** +* `consensus_pub.pem`: The node's consensus public key. +* `identity.pem`: The node's identity private key. **DO NOT SHARE** +* `identity_pub.pem`: The node's identity public key. +* `p2p.pem`: The node's private key for libp2p. **DO NOT SHARE** +* `p2p_pub.pem`: The node's public key for libp2p. +* `sentry_client_tls_identity.pem`: The node's TLS private key for communicating + with sentry nodes. **DO NOT SHARE** +* `sentry_client_tls_identity_cert.pem`: The node's TLS certificate for + communicating with sentry nodes. + #### Ensuring Proper Permissions -Only the owner of the process that runs the Oasis node should have access to the files in the `/serverdir/node` directory. The `oasis-node` binary ensures that the files used by the node are as least privileged as possible so that you don't accidentally shoot yourself in the foot while operating a node. +Only the owner of the process that runs the Oasis node should have access to the +files in the `/node/data` directory. The `oasis-node` binary ensures that +the files used by the node are as least privileged as possible so that you don't +accidentally shoot yourself in the foot while operating a node. -To ensure proper permissions are set, we suggest running the following to remove all non-owner read/write/execute permissions: +To ensure proper permissions are set, we suggest running the following to remove +all non-owner read/write/execute permissions: -```bash -chmod -R go-r,go-w,go-x /serverdir +```shell +chmod -R go-r,go-w,go-x /node ``` :::info -Just so it's clear, the following permissions are expected by the `oasis-node` binary: +Just so it's clear, the following permissions are expected by the `oasis-node` +binary: + +* `700` for the `/node/data` directory +* `700` for the `/node/etc` directory +* `600` for all `/node/data/*.pem` files -* `700` for the `/serverdir/node` directory -* `700` for the `/serverdir/node/entity` directory -* `600` for all `*.pem` files +::: + +:::caution + +You may have noticed that some of these files were listed as **DO NOT SHARE** in +the [Initializing a Node](#initializing-a-node) section. + +In the future, these keys should be generated and referenced from an HSM. +However, until HSM support is implemented, these keys should be kept as secure +as possible on the `server`. ::: @@ -413,8 +356,8 @@ Just so it's clear, the following permissions are expected by the `oasis-node` b You can start the node by running the following command: -```bash -oasis-node --config /serverdir/etc/config.yml +```shell +oasis-node --config /node/etc/config.yml ``` :::tip @@ -425,245 +368,149 @@ We recommend you configure and use it with a process manager like [systemd](http ::: -### Verifying the Connection to the Network - -As part of the starting the server process, the `oasis-node` binary will, by default, setup an internal unix socket in the `datadir` of the Node. This socket can be used to communicate to the node and query details about the network. +### Obtaining the node ID -Run the following command: +Now that the Oasis node is running, you can obtain your unique node ID which is +needed in order to associate your node with your entity in the network registry. -```bash -oasis-node registry entity list -a unix:/serverdir/node/internal.sock +```shell +oasis-node control status -a unix:/node/data/internal.sock | jq .identity.node ``` -If this command fails, you'll receive a non-zero exit code and there's a high likelihood that you are not connected to the network. However, if it does work properly it should respond with output like the following but with potentially many more values: - ``` -CVzqFIADD2Ed0khGBNf4Rvh7vSNtrL1ULTkWYQszDpc= -C5z1jB+FHB/QgtTITr6NKWpUs9QHwD11CG3v8tmuJ0g= -DPbZomOIleFrvcJBZPl7y/wEB1w9Q569vAbb6Krl9fE= -DVobZ8bWlOv2J6oHO0uITr5FPO5rIY2irdPNhByprHk= -D2hqhJcmZnBmhw9TodOdoFPAjmRkpRatANCNHxIDHgA= +"5MsgQwijUlpH9+0Hbyors5jwmx7tTmKMA4c9leV3prI=" ``` -Once you get to a node that's connected you can move on to the next section as your node is not yet registered as a validator on the Oasis Network. - -## Staking and Registering - -:::tip - -This step is not necessary if your entity was fully staked at genesis. - -::: - -:::caution - -If you've submitted staking or registry transactions before, your nonce is likely different than the nonce used in the examples. If you're uncertain, please check your account nonce by using [this guide](../../general/manage-tokens/cli/account.md#show). - -::: - -Once you have been funded, you can complete the process of connecting your node to the network by registering both your entity and your node, as described below. - ### Check that your node is synced -Before you can make any transactions you'll have to make sure that your node is synced. To do so call this command on the server: +Before you can become a validator, you will have to make sure that your node is +synced. To do so call this command on the server: -```bash -oasis-node control is-synced -a unix:/serverdir/node/internal.sock +```shell +oasis-node control is-synced -a unix:/node/data/internal.sock ``` If your node is synced, the above command should output: ``` -node completed initial syncing +"ready" ``` -If your node is not yet synced, you will need to wait before you can move forward. - -### Generating a Staking (Escrow) Transaction on the `localhost` +If your node is not yet synced, you will need to wait before you can move +forward. -Your entity's private key should be disconnected from the internet on the `localhost`. Therefore, you need to generate the following transaction on the `localhost`. +## Staking and Registering {#staking-and-registering} -:::danger - -The entity's private key is used to authorize transactions on your staking account. - -Hence it should never be present on the online `server`. - -::: - -The current minimum stake required to register an entity and register a node as a validator is 200 tokens. So, we will generate an escrow transaction that escrows 200 tokens on your own entity. - -:::info - -The Oasis node's staking application calls the operation of staking tokens "escrow." - -::: +Once you have been funded, you can complete the process of connecting your node +to the network by registering both your entity and your node, as described +below. -Before generating the escrow transaction, you need to set the following environment variables: +### Staking (Escrow) Transaction -* `GENESIS_FILE_PATH`: Path to the Genesis file on the `localhost`, i.e. `/localhostdir/genesis.json`. -* `ENTITY_DIR_PATH`: Path to entity's artifacts directory on the `localhost`, +The current minimum stake required to register an entity and register a node as +a validator is 200 tokens. We will submit the escrow transaction that +delegates 200 tokens from your entity account on the consensus layer to itself +by invoking the [`oasis account delegate`] command. - i.e. `/localhostdir/entity/`. -* `OUTPUT_TX_FILE_PATH`: Path to the file containing the outputted signed transaction. - - For this guide, we will use `/localhostdir/signed-escrow.tx`. -* `ACCOUNT_ADDRESS`: Your staking account address. - - To obtain your staking account address from your Entity's ID, see [Obtaining Account Address From Entity's ID](../../general/manage-tokens/cli/account.md#from-public-key). - -Then execute the following command: - -```bash -oasis-node stake account gen_escrow \ - --genesis.file $GENESIS_FILE_PATH \ - --signer.backend file \ - --signer.dir $ENTITY_DIR_PATH \ - --stake.escrow.account $ACCOUNT_ADDRESS \ - --stake.amount 200000000000 \ - --transaction.file $OUTPUT_TX_FILE_PATH \ - --transaction.fee.gas 2269 \ - --transaction.fee.amount 2000 \ - --transaction.nonce 0 +```shell +oasis account delegate 200 my_entity --no-paratime --account my_entity ``` -:::info - -The option `--stake.amount` looks like a very large number, but this is actually just an equivalent to 200 tokens on the Oasis consensus layer as each unit value used to track the account balance is 1x10^-9 tokens. - -The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../core/oasis-node/cli.md#common-transaction-flags) for details. - -::: - -### Generating Entity Registration Transaction +You can also fund your entity account from a different one. If you haven't yet +invoke the [`oasis wallet import`] command to import the private key of the +funding account to the Oasis CLI and follow the instructions. -Before you can run your node successfully, you'll need to register your entity so that your node registers properly. You could do this process _after_ you submit the escrow transaction, however, to save steps we prepare everything before hand. - -Before generating the register transaction, you need to set the following environment variables: - -* `GENESIS_FILE_PATH`: Path to the Genesis file on the `localhost`, i.e. - - `/localhostdir/genesis.json`. -* `ENTITY_DIR_PATH`: Path to entity's artifacts directory on the `localhost`, - - i.e. `/localhostdir/entity/`. -* `OUTPUT_REGISTER_TX_FILE_PATH`: Path to the file containing the outputted signed transaction. - - For this guide, we will use `/localhostdir/signed-register.tx`. - -Then execute the following command: - -```bash -oasis-node registry entity gen_register \ - --genesis.file $GENESIS_FILE_PATH \ - --signer.backend file \ - --signer.dir $ENTITY_DIR_PATH \ - --transaction.file $OUTPUT_REGISTER_TX_FILE_PATH \ - --transaction.fee.gas 2460 \ - --transaction.fee.amount 1000 \ - --transaction.nonce 1 +```shell +oasis wallet import my_funding_account ``` -:::info +Then, invoke the [`oasis account delegate`] passing the new account name with +the `--account` parameter. For example: -The `--transactions.fee.gas` and `--transaction.fee.amount` options depend on the network configuration, see [Common Transaction Flags](../../core/oasis-node/cli.md#common-transaction-flags) for details. +```shell +oasis account delegate 200 my_entity --no-paratime --account my_funding_account +``` -::: +[`oasis account delegate`]: ../../general/manage-tokens/cli/account.md#delegate -### Submitting Your Transactions on the `server` +### Adding your Node ID to the Entity Descriptor -To complete the staking process we need to copy the generated escrow and registry transactions from your offline `localhost` to the `server` and submit them. +Now we can register our entity on the network and associate it with the node ID +obtained in the [section above](#obtaining-the-node-id). Open the `entity.json` +file we initially generated and add the ID inside the `nodes` block. Your +entity descriptor file should now look like this: -To do so, follow these steps: +```json +{ + "id": "Bx6gOixnxy15tCs09ua5DcKyX9uo2Forb32O6Hyjoc8=", + "nodes": [ + "5MsgQwijUlpH9+0Hbyors5jwmx7tTmKMA4c9leV3prI=" + ], + "v": 2 +} +``` -1. Copy the file `/localhostdir/signed-escrow.tx` on the `localhost` to +### Entity Registration - `/serverdir/signed-escrow.tx` on the `server`. -2. Copy the file `/localhostdir/signed-register.tx` on the `localhost` to +We can submit the fresh entity file descriptor by invoking the +[`oasis account entity register`] command: - `/serverdir/signed-register.tx` on the `server`. -3. Submit both transactions via `oasis-node consensus submit_tx` sub-command: +```shell +oasis account entity register entity.json --account my_entity +``` - ```bash - oasis-node consensus submit_tx \ - --transaction.file /serverdir/signed-escrow.tx \ - -a unix:/serverdir/node/internal.sock - oasis-node consensus submit_tx \ - --transaction.file /serverdir/signed-register.tx \ - -a unix:/serverdir/node/internal.sock - ``` +[`oasis account entity register`]: ../../general/manage-tokens/cli/account.md#entity-register ### Checking that Your Node is Properly Registered -To ensure that your node is properly connected as a validator on the network, you can run the following command: +To ensure that your node is properly connected as a validator on the network, +invoke the following command on your `server`: -```bash -oasis-node control status -a unix:/serverdir/node/internal.sock +```shell +oasis-node control status -a unix:/node/data/internal.sock | jq .consensus.is_validator ``` -If your node is registered and a validator, the above command should output (some fields omitted for clarity): +If your node is registered and became a validator, the above command should +output: -```javascript -{ - "software_version": "20.10", - "identity": { - ... - }, - "consensus": { - "consensus_version": "1.0.0", - "backend": "tendermint", - "features": 3, - "node_peers": [ - ... - ], - "latest_height": 55899, - "latest_hash": "AR34gxwWz1LS5rMDa6E0L1/ThW9E38ySIbRRlRG/shg=", - "latest_time": "2020-08-10T11:38:26+02:00", - "latest_state_root": { - "ns": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", - "version": 55898, - "hash": "h2+8ZryxseOKpuSho1nVSImLF/irVsTF5xryc3I9cRk=" - }, - "genesis_height": 1, - "genesis_hash": "+SIAMCUeZtWuYPg/Ke+zwPRhNRripRgUq1d5Al9ImNA=", - "is_validator": true - }, - "registration": { - ... - } -} ``` - -Pay attention to the `is_validator` field which should have the value of `true`. +true +``` :::info -Nodes are only elected into the validator set at epoch transitions, so you may need to wait for up to an epoch before being considered. +Nodes are only elected into the validator set at epoch transitions, so you may +need to wait for up to an epoch before being considered. ::: :::caution -Note that in order to be elected in the validator set you need to have enough stake to be in the top K entities (where K is a network-specific parameter specified by the `scheduler.max_validators` field in the genesis document). +In order to be elected in the validator set you **need to have enough +stake to be in the top K entities** (where K is a network-specific parameter +specified by the [`scheduler.max_validators`] field in the genesis document). ::: Congratulations, if you made it this far, you've properly connected your node to the network and became a validator on the Oasis Network. +[`scheduler.max_validators`]: ../genesis-doc.md#consensus + ## Oasis Metadata Registry For the final touch, you can add some metadata about your entity to the -[Metadata Registry]. The Metadata Registry is the same for the Mainnet and +[Metadata Registry]. The Metadata Registry is the same for Mainnet and the Testnet. The metadata consists of your entity name, email, Keybase handle, -Twitter handle, etc. This information is also used by third party applications. -For example [Oasis Scan] fetches your image from Keybase and uses it as the node -operator's avatar. +Twitter handle, etc. This information is also used by various applications. +For example the [Oasis Wallet - Web] and the [Oasis Scan] will fetch and show +the node operator's name and the avatar. [Metadata Registry]: https://github.com/oasisprotocol/metadata-registry +[Oasis Wallet - Web]: https://wallet.oasisprotocol.org [Oasis Scan]: https://www.oasisscan.com/validators # See also - + From c7fe1a0fe44ad9e5816e7cd5685f40c6ef7a5482 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Wed, 15 Nov 2023 12:44:11 +0100 Subject: [PATCH 02/10] docs: Replace oasis-node in paratime-node --- docs/node/run-your-node/paratime-node.mdx | 105 +++++++--------------- 1 file changed, 32 insertions(+), 73 deletions(-) diff --git a/docs/node/run-your-node/paratime-node.mdx b/docs/node/run-your-node/paratime-node.mdx index cfb0001323..d6667e6674 100644 --- a/docs/node/run-your-node/paratime-node.mdx +++ b/docs/node/run-your-node/paratime-node.mdx @@ -70,39 +70,18 @@ To be able to register as a ParaTime node on the Oasis Network, you need to have enough tokens staked in your entity's escrow account. Current minimum staking requirements for a specific ParaTime are listed on the -Contribute to the Network section - [Run a ParaTime Node] page. Should you want +Contribute to the Network section—[Run a ParaTime Node] page. Should you want to check the staking requirements for other node roles and registered ParaTimes manually, use the Oasis CLI tools as described in [Common Staking Info]. Finally, to stake the tokens, use our [Oasis CLI tools]. If everything was set -up correctly, you should see something like below when running [Oasis Node -Stake Account Info] command for your entity's account (this is an example for -the Testnet): +up correctly, you should see something like below when running [`oasis account +show`] command for your entity's account (this is an example for +Testnet): -```bash -Balance: - Total: 0.0 TEST - Available: 0.0 TEST - -Active Delegations to this Account: - Total: 20000.0 TEST (20000000000000 shares) - Delegations: - - From: oasis1qrwdwxutpyr9d2m84zh55rzcf99aw0hkts7myvv9 - Amount: 20000.0 TEST (20000000000000 shares) - -Stake Accumulator: - Claims: - - Name: registry.RegisterEntity - Staking Thresholds: - - Global: entity - - Name: registry.RegisterNode.HG5TB3dbY8gtYBBw/R/cHfPaOpe0vT7W1wu/2rtpk/A= - Staking Thresholds: - - Global: node-compute - Staking Thresholds: - - Global: node-storage - -Nonce: 1 -``` +![code shell](../../../external/cli/examples/account/show-delegations.in.static) + +![code](../../../external/cli/examples/account/show-delegations.out.static) :::caution @@ -114,64 +93,33 @@ change in the future. [Run a ParaTime Node]: ../../get-involved/run-node/paratime-node.mdx [Common Staking Info]: ../../general/manage-tokens/cli/network.md#show-native-token [Oasis CLI tools]: ../../general/manage-tokens/cli/account.md#delegate -[Oasis Node Stake Account Info]: ../../general/manage-tokens/cli/account.md#show +[`oasis account show`]: ../../general/manage-tokens/cli/account.md#show ### Register a New Entity or Update Your Entity Registration -If you don't have an entity yet, create a new one by following the [Creating Your Entity](validator-node.mdx#creating-your-entity) instructions. - :::danger -Everything in this section should be done on the `localhost` as there are sensitive items that will be created. - -::: - -If you will be running the ParaTime on a new Oasis Node, initialize a new node by following the [Initializing a Node](validator-node.mdx#initializing-a-node) instructions. - -Then update your entity descriptor by enumerating paths to all your node's descriptors (existing and new ones) in the `--entity.node.descriptor` flag. For example: - -```bash -oasis-node registry entity update \ - ... various signer flags ... \ - --entity.node.descriptor /localhost/node1/node_genesis.json,/localhost/node2/node_genesis.json -``` - -:::info - -To confirm all nodes are added to your entity descriptor, run: - -```bash -cat -``` - -and ensure you see all your nodes' IDs under the `"nodes"` list. - -For example: - -```bash -{ - "v": 2, - "id": "QTg+ZjubD/36egwByAIGC6lMVBKgqo7xnZPgHVoIKzc=", - "nodes": [ - "yT1h8/eN0VInQxn3YKcHxvSgGcsjsTSYmdTLZZMBTWI=", - "HG5TB3dbY8gtYBBw/R/cHfPaOpe0vT7W1wu/2rtpk/A=" - ] -} -``` +Everything in this section should be done on the `localhost` as there are +sensitive items that will be created. ::: -Then generate and submit the new/updated entity descriptor via the entity registration transaction by following the [Generating Entity Registration Transaction](validator-node.mdx#generating-entity-registration-transaction) instructions. +1. If you don't have an entity yet, create a new one by following the + [Initialize Entity] instructions for validators. -:::caution +2. If you will be running the ParaTime on a new Oasis node, also initialize a + new node by following the [Starting the Oasis Node] instructions for + validators. -Make sure your entity descriptor (i.e. `entity.json`) is copied to your online server and saved as `/node/entity/entity.json` to ensure the [node's configuration](paratime-node.mdx#configuration) will find it. +3. Now, [list your node ID] in the entity descriptor file `nodes` field. -::: +4. [Register] the updated entity descriptor. :::tip -You will [configure the node](paratime-node.mdx#configuration) to automatically register for the roles it has enabled (i.e. storage and compute roles) via the `worker.registration.entity` configuration flag. +You will [configure the node](#configuration) to automatically +register for the roles it has enabled (i.e. storage and compute roles) via the +`worker.registration.entity` configuration flag. No manual node registration is necessary. @@ -179,10 +127,21 @@ No manual node registration is necessary. :::info -ParaTime rewards for running the compute node will be sent to your entity address **inside the ParaTime**. To access the rewards on the consensus layer, you will need to withdraw them first. Read the [Deposit/Withdraw Tokens to/from ParaTime](../../general/manage-tokens/cli/account.md) chapter to learn more. +ParaTime rewards for running the compute node will be sent to your entity +address **inside the ParaTime**. To access the rewards on the consensus layer, +you will need to withdraw them first. Use the [`oasis account withdraw`] +command, for example: + +![code shell](../../../external/cli/examples/account/withdraw.y.in) ::: +[Initialize Entity]: validator-node.mdx#initialize-entity +[Starting the Oasis Node]: validator-node.mdx#starting-the-oasis-node +[list your node ID]: validator-node.mdx#adding-your-node-id-to-the-entity-descriptor +[Register]: validator-node.mdx#entity-registration +[`oasis account withdraw`]: ../../general/manage-tokens/cli/account.md#withdraw + ### The ParaTime Bundle In order to run a ParaTime node you need to obtain the ParaTime bundle that From 75e989d573f28bd07d801dee74a3ff61817eed74 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 16 Nov 2023 13:06:15 +0100 Subject: [PATCH 03/10] docs: Replace oasis-node in sync-node-using-state-sync --- .../advanced/sync-node-using-state-sync.md | 96 +++++++++++++------ 1 file changed, 69 insertions(+), 27 deletions(-) diff --git a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md index 6c7a8a1723..4b17e70e44 100644 --- a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md +++ b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md @@ -1,20 +1,31 @@ # Using State Sync for Quick Bootstraping -The State Sync is a way to **quickly bootstrap** a **full Oasis node** (either a [validator node](../validator-node.mdx) or a [non-validator node](../non-validator-node.md)) by using [Tendermint's Light Client protocol](https://docs.tendermint.com/main/tendermint-core/light-client.html). It allows one to initialize a node from a trusted height, its corresponding block's header and a trusted validator set (given in the [genesis document](../../genesis-doc.md)). It does so by securely updating the node's trusted state by requesting and verifying a minimal set of data from the network's full nodes. +The State Sync is a way to **quickly bootstrap** a **full Oasis node** (either a +[validator node](../validator-node.mdx) or a +[non-validator node](../non-validator-node.md)) by using the +[Tendermint's Light Client protocol]. It allows one to initialize a node from a +trusted height, its corresponding block's header and a trusted validator set +(given in the [genesis document](../../genesis-doc.md)). It does so by securely +updating the node's trusted state by requesting and verifying a minimal set of +data from the network's full nodes. :::info -If you have access to an Oasis Node that is synced with the latest height, another option to speed bootstraping a new Oasis Node is to [copy state from one node to the other](copy-state-from-one-node-to-the-other.md). +If you have access to an Oasis node that is synced with the latest height, +another option to speed bootstraping a new Oasis node is to [copy state from one +node to the other]. ::: :::caution -Tendermint's Light Client protocol requires at least 1 full node to be correct to be able to [detect and submit evidence for a light client attack](https://docs.tendermint.com/main/tendermint-core/light-client.html#where-to-obtain-trusted-height-hash). +Tendermint's Light Client protocol requires at least 1 full node to be correct +to be able to [detect and submit evidence for a light client attack]. ::: -To configure your node to use the state sync, amend your node's configuration (i.e. `config.yml`) with (non-relevant fields omitted): +To configure your node to use the state sync, amend your node's configuration +(i.e. `config.yml`) with (non-relevant fields omitted): ```yaml ... trimmed ... @@ -44,28 +55,34 @@ consensus: - "{{ noden_grpc_endpoint }}" ... trimmed ... - ``` and replace the following variables in the configuration snippet: -* `{{ trusted_height }}`: Trusted height defines the height at which your node should trust the chain. -* `{{ trusted_height_hash }}`: Trusted height hash defines the hash of the block header corresponding to the trusted height. -* `{{ node1_grpc_endpoint }}`, `{{ node2_grpc_endpoint }}` , ..., - - `{{ noden_grpc_endpoint }}`: Addresses of a Oasis Nodes' publicly exposed gRPC endpoints of the form: `xAMjfJDcUFUcwgZGEQuOdux8gAdc+IFEqccB2LHdGjU=@34.86.145.181:9001`. +* `{{ trusted_height }}`: Trusted height defines the height at which your node + should trust the chain. +* `{{ trusted_height_hash }}`: Trusted height hash defines the hash of the block + header corresponding to the trusted height. +* `{{ node1_grpc_endpoint }}`, `{{ node2_grpc_endpoint }}` , ..., + `{{ noden_grpc_endpoint }}`: Addresses of a Oasis nodes' publicly exposed gRPC + endpoints of the form: + `xAMjfJDcUFUcwgZGEQuOdux8gAdc+IFEqccB2LHdGjU=@34.86.145.181:9001`. :::caution -You need to provide publicly exposed gRPC endpoints for **at least 2 different consensus nodes** for the state sync to work. +You need to provide publicly exposed gRPC endpoints for **at least 2 different +consensus nodes** for the state sync to work. ::: :::danger -You need to **delete any existing node state** (if it exists), otherwise state sync will be skipped. To do that, follow the [Wiping Node State](../maintenance/wiping-node-state.md#state-wipe-and-keep-node-identity) instructions. +You need to **delete any existing node state** (if it exists), otherwise the +state sync will be skipped. To do that, follow the [Wiping Node State] +instructions. -If existing node state is found and state sync is skipped, you will see something like the following in your node's logs: +If existing node state is found and state sync is skipped, you will see +something like the following in your node's logs: ``` {"caller":"full.go:1233","level":"info","module":"tendermint","msg":"state sync enabled","ts":"2021-06-21T14:40:55.033642763Z"} @@ -74,27 +91,39 @@ If existing node state is found and state sync is skipped, you will see somethin ::: +[Tendermint's Light Client protocol]: + https://docs.tendermint.com/main/tendermint-core/light-client.html +[copy state from one node to the other]: copy-state-from-one-node-to-the-other.md +[detect and submit evidence for a light client attack]: + https://docs.tendermint.com/main/tendermint-core/light-client.html#where-to-obtain-trusted-height-hash +[Wiping Node State]: ../maintenance/wiping-node-state.md#state-wipe-and-keep-node-identity + ### Obtaining Trusted Height and Hash -To obtain the trusted height and the corresponding block header's hash, use one of the following options. +To obtain the trusted height and the corresponding block header's hash, use one +of the following options. #### Block Explorers -Browse to one of our block explorers (e.g. [OASIS SCAN](https://www.oasisscan.com), [Oasis Monitor](https://oasismonitor.com)) and obtain the trusted height and hash there: +Browse to one of our block explorers (e.g. [Oasis Scan], [Oasis Monitor]) and +obtain the trusted height and hash there: 1. Obtain the current block height from the main page, e.g. 4819139. -2. Click on block height's number to view the block's details and obtain its hash, e.g. `377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21`. +2. Click on block height's number to view the block's details and obtain its + hash, e.g. `377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21`. + +[Oasis Scan]: https://www.oasisscan.com +[Oasis Monitor]: https://oasismonitor.com #### A Trusted Node -If you have an existing node that you trust, you can use its status output to retrieve the current block height and hash by running: +If you have an existing node that you trust, you can use its status output to +retrieve the current block height and hash by running: ``` -oasis-node control status -a $ADDR +oasis-node control status -a unix:/serverdir/node/internal.sock ``` -replacing `$ADDR` with the path to your node's internal UNIX socket (e.g. `/srv/oasis/node/internal.sock`). - This will give you output like the following (non-relevant fields omitted): ```json @@ -119,33 +148,46 @@ The values you need are `latest_height` and `latest_hash` . #### Public Rosetta Gateway -Query our public Rosetta Gateway instance and obtain the trusted height and hash there: +Query our public Rosetta Gateway instance and obtain the trusted height and hash +there: 1. _TODO._ #### Oasis Node's gRPC Endpoint -Query our public Oasis Node's gRPC endpoint and obtain the trusted height and hash there: +Query our public Oasis node's gRPC endpoint and obtain the trusted height and +hash there: 1. _TODO._ ### Obtaining Addresses of Oasis Nodes' Publicly Exposed gRPC Endpoints -To find the addresses of Oasis Node's publicly exposed gRPC endpoints, use one of the following options. +To find the addresses of Oasis node's publicly exposed gRPC endpoints, use one +of the following options. #### List Registered Nodes' Descriptors via Oasis CLI from the Local Oasis Node -If you already have a local Oasis Node set up, you can list the descriptors of all registered nodes via Oasis CLI. +If you already have a local Oasis node set up, you can list the descriptors of +all registered nodes via the [`oasis network show nodes`] Oasis CLI command. + +:::info + +To avoid denial-of-service attacks this call is not enabled on public Oasis gRPC +endpoints. You will have to [connect Oasis CLI to your own Oasis node]! + +::: You need to search for the nodes that implement the `consensus-rpc` role. -The publicly exposed gRPC endpoint addresses are found under the node descriptor's `tls.addresses` key. +The publicly exposed gRPC endpoint addresses are found under the node +descriptor's `tls.addresses` key. You can list the relevant addresses by running: ``` -oasis-node registry node list -v -a $ADDR | \ +oasis network show nodes --network mainnet_local | \ jq 'select(.roles | contains("consensus-rpc")) | .tls.addresses' ``` -replacing `$ADDR` with the path to your node's internal UNIX socket (e.g. `/srv/oasis/node/internal.sock`). +[`oasis network show nodes`]: ../../../general/manage-tokens/cli/network.md#show-nodes +[connect Oasis CLI to your own Oasis node]: ../../../general/manage-tokens/cli/network.md#add From 4a020c8aeb365c8ff342d45f58f0b153b11cd266 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 16 Nov 2023 13:06:49 +0100 Subject: [PATCH 04/10] docs: Replace oasis-node in maintenance/adding-or-removing-nodes --- .../maintenance/adding-or-removing-nodes.md | 130 +++++++----------- 1 file changed, 49 insertions(+), 81 deletions(-) diff --git a/docs/node/run-your-node/maintenance/adding-or-removing-nodes.md b/docs/node/run-your-node/maintenance/adding-or-removing-nodes.md index 9bfdcf515e..328c3b7f57 100644 --- a/docs/node/run-your-node/maintenance/adding-or-removing-nodes.md +++ b/docs/node/run-your-node/maintenance/adding-or-removing-nodes.md @@ -18,27 +18,38 @@ entity will not get penalized during node's downtime. The process for adding/removing nodes is similar and has the following steps: -1. Retrieve your up to date entity descriptor (`entity.json`) -2. Update your entity descriptor by adding/removing a node -3. Generate a `register` transaction to update your entity registration on the - network. +1. Obtain the ID of your running Oasis node +2. Download your entity descriptor (`entity.json`) from the network registry +3. Update the entity descriptor by adding/removing a node +4. Submitting the updated entity descriptor to the network [graceful shutdown]: shutting-down-a-node.md -## Retrieving Your Latest Entity Descriptor +## Obtain the ID of your Node + +Connect to your `server` and obtain the ID of your node by running: + +```shell +oasis-node control status -a unix:/node/data/internal.sock | jq .identity.node +``` + +## Download Your Latest Entity Descriptor To ensure that we do not update your entity descriptor (`entity.json`) -incorrectly we should get the latest entity descriptor state. For this -operation, you will need to know the base64 encoding of your entity's +incorrectly we should get the latest entity descriptor state from the network. +For this operation, you will need to know the base64 encoding of your entity's public key. -On your server run this command: +Use [`oasis network show`] command on your `localhost` to get the latest entity +descriptor stored in the network registry. This command is part of [Oasis CLI]. +For example: -```bash -ENTITY_PUBLIC_KEY="some-base64-public-key" -oasis-node registry entity list \ - -a unix:/serverdir/node/internal.sock -v | grep $ENTITY_PUBLIC_KEY -``` +![code shell](../../../../external/cli/examples/network-show/id-entity.in) + +Now store the obtained JSON as `entity.json`. + +[`oasis network show`]: ../../../general/manage-tokens/cli/network.md#show-id +[Oasis CLI]: ../../../general/manage-tokens/cli/README.md ## Updating Your Entity Descriptor @@ -53,34 +64,18 @@ to have multiple nodes. ::: -Adding a node is a simple operation that is directly supported by the -`oasis-node` binary. For this operation you'll need to have initialized a new -node, and you'll need to have the `node_genesis.json` file in order to add it -to the entity descriptor. - -Assuming that the `node_genesis.json` is at `/localhostdir/new_node/node_genesis.json` -the command is the following: - -```bash -NEW_NODE_GENESIS_PATH=/localhostdir/new_node/node_genesis.json -oasis-node registry entity update \ - --signer.dir /localhostdir/entity \ - --entity.node.descriptor /localhostdir/new_node/node_genesis.json -``` - -## To Remove a Node - -Removing a node requires updating the entity descriptor manually. The entity -descriptor file is a simple JSON document that looks something like: +To attach a new node with your entity, add the ID of your node obtained in +the [section above](#obtain-the-id-of-your-node) to the `nodes` field in your +`entity.json`. For example: -```javascript +```json { - "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "v": 2, + "id": "xQN6ffLSdc51EfEQ2BzltK1iWYAw6Y1CkBAbFzlhhEQ=", "nodes": [ - "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" - "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=" - ], - "allow_entity_signed_nodes": false + "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=" + ] } ``` @@ -89,60 +84,33 @@ In the above entity descriptor 2 nodes are attached to the entity: 1. A node with an identity `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=` 2. A node with an identity `BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=` -To remove the Node `BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=` you would -remove it from the array in the `nodes` field, like so: +## To Remove a Node + +To remove node with ID `BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=` from your +entity descriptor, simply remove the record from the array in the `nodes` field. +For example: -```javascript +```json { - "id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", + "v": 2, + "id": "xQN6ffLSdc51EfEQ2BzltK1iWYAw6Y1CkBAbFzlhhEQ=", "nodes": [ "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" ], - "allow_entity_signed_nodes": false } ``` -## Updating Your Entity Registration on the Network +## Submitting Your Entity Registration to the Network -Finally, to commit the changes on the network you'll need to generate a -`register` transaction and submit that transaction to the network. +Finally, to commit the changes on the network, invoke the [`oasis account entity +register`] command on your `localhost`: -### Generating a `register` Transaction - -Run this command on your localhost (as you need your entity's private key): - -```bash -GENESIS_FILE_PATH="path/to/the/current/genesis" -OUTPUT_REGISTER_TX_FILE_PATH="/localhostdir/update_entity_registration.tx" -oasis-node registry entity gen_register \ - --genesis.file $GENESIS_FILE_PATH \ - --signer.backend file \ - --signer.dir $ENTITY_DIR_PATH \ - --transaction.file $OUTPUT_REGISTER_TX_FILE_PATH \ - --transaction.fee.gas 1000 \ - --transaction.fee.amount 1 \ - --transaction.nonce 1 +```shell +oasis account entity register entity.json --account my_entity ``` -Once this has exited with a `0` status, you should have a file at -`$OUTPUT_REGISTER_TX_FILE_PATH`. Upload that file to your server. - -### Submitting the Transaction - -Run this command on your server: - -```bash -oasis-node consensus submit_tx \ - --transaction.file /serverdir/update_entity_registration.tx \ - -a unix:/serverdir/node/internal.sock -``` +The account used to sign the transaction (`my_entity` in the snippet above) must +correspond to the entity ID in `entity.json`. If there are no errors, your entity registration should be updated. You can run -this command to see the changes reflected: - -```bash -ENTITY_PUBLIC_KEY="some-base64-public-key" -oasis-node registry entity list \ - -a unix:/serverdir/node/internal.sock -v | grep $ENTITY_PUBLIC_KEY -``` - +the [`oasis network show`] command again to see the changes. From ba7417518e2c632ee187890da4fe6519350d1d2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 16 Nov 2023 13:07:11 +0100 Subject: [PATCH 05/10] docs: Replace oasis-node in maintenance/handling-network-upgrades --- .../maintenance/handling-network-upgrades.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/node/run-your-node/maintenance/handling-network-upgrades.md b/docs/node/run-your-node/maintenance/handling-network-upgrades.md index 897d2d2fab..c015a13bcd 100644 --- a/docs/node/run-your-node/maintenance/handling-network-upgrades.md +++ b/docs/node/run-your-node/maintenance/handling-network-upgrades.md @@ -271,12 +271,12 @@ document. If you are running a compute or a client ParaTime node, you will often need to upgrade the ParaTime. The required ParaTime versions are stored in the network -registry. The command below queries the registry and extracts the version -information for the Paratime +registry. The [`oasis network show paratimes`] command below queries the +registry and extracts the version information for the Paratime `00000000000000000000000000000000000000000000000072c8215e60d5bca7`: ```bash -oasis-node registry runtime list -v -a unix:/serverdir/node/internal.sock \| +oasis network show paratimes \| jq 'select(.id=="00000000000000000000000000000000000000000000000072c8215e60d5bca7") | .deployments' ``` @@ -319,6 +319,8 @@ runtime: The node will then automatically run the correct version of the ParaTime as specified in the registry. +[`oasis network show paratimes`]: ../../../general/manage-tokens/cli/network.md#show-paratimes + ## Start Your Node This will depend on your process manager. If you don't have a process manager, From 88901b7a46c3292ba5ffe97332c7fed0c75c7f0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Tue, 14 Nov 2023 15:51:34 +0100 Subject: [PATCH 06/10] docs: Fix typo in key-manager-upgrade --- docs/node/run-your-node/keymanager-node/key-manager-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/node/run-your-node/keymanager-node/key-manager-upgrade.md b/docs/node/run-your-node/keymanager-node/key-manager-upgrade.md index e96404bf12..09d2a72e69 100644 --- a/docs/node/run-your-node/keymanager-node/key-manager-upgrade.md +++ b/docs/node/run-your-node/keymanager-node/key-manager-upgrade.md @@ -66,7 +66,7 @@ the `control status` output should show `keymanager.status="ready"` and `registration.descriptor.runtimes.0.extra_info` should contain a hash of the key material state: ``` -$ oasis_node oasis-node -a unix:/storage/node/internal.sock control status +$ oasis-node -a unix:/node/data/internal.sock control status ... "registration": { "last_registration": "2023-02-06T08:40:30Z", From daf7b4ad423a055ee5bba9bd94f9b11b056d75d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Wed, 15 Nov 2023 12:39:44 +0100 Subject: [PATCH 07/10] docs: Fix how-to-transfer-rose-into-paratime CLI reference --- .../how-to-transfer-rose-into-paratime.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx b/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx index a7d9b85ef3..f04ff6bcef 100644 --- a/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx +++ b/docs/general/manage-tokens/how-to-transfer-rose-into-paratime.mdx @@ -188,17 +188,19 @@ the exchange. :::info -Advanced users (e.g. those running ParaTime -[compute nodes](../../node/run-your-node/paratime-node.mdx)) may need to -withdraw ROSE from EVM-compatible ParaTimes stored in their `oasis1` accounts, -for example to claim their ParaTime execution rewards. Oasis Wallet Browser -Extension does not support such withdrawals. Read the -[Oasis CLI Deposit/Withdraw Tokens to/from ParaTime chapter][Oasis CLI] to -learn how to use Oasis CLI instead. +Advanced users (e.g. those running ParaTime [compute nodes] may need to +withdraw ROSE from ParaTimes stored in their `oasis1` accounts, for example to +claim their ParaTime execution rewards. Oasis Wallet Browser Extension does not +support such withdrawals. Use the [`oasis account withdraw`] command which is +part of the [Oasis CLI] instead, for example: + +![code shell](../../../external/cli/examples/account/withdraw.y.in) ::: -[Oasis CLI]: cli/account.md +[compute nodes]: ../../node/run-your-node/paratime-node.mdx +[Oasis CLI]: cli/README.md +[`oasis account withdraw`]: cli/account.md#withdraw ### Verifying ParaTime deposits and withdrawals From 5d9cb3643b03119bd918454bdc4dc10565b18acf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Thu, 16 Nov 2023 13:04:41 +0100 Subject: [PATCH 08/10] docs: Fix wrong link in ledger-wallet --- .../general/manage-tokens/holding-rose-tokens/ledger-wallet.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md index 8ff8146416..8c9895fe8f 100644 --- a/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md +++ b/docs/general/manage-tokens/holding-rose-tokens/ledger-wallet.md @@ -4,7 +4,7 @@ This is a general documentation that will help users setup [Ledger] hadware wallets with Oasis Network. Ledger Live software doesn't support Oasis (ROSE) tokens natively yet. In this guide we will install Oasis app via Ledger Live to open and access wallet with one or multiple accounts via our official -[Oasis Wallet - Web]. +[Oasis Wallet - Web][wallet.oasis.io]. ## Setup your Ledger device and Install Oasis App @@ -146,7 +146,6 @@ Ledger is supported by the Oasis CLI. Follow the instructions in the [Oasis CLI Tools] page to learn more. [Ledger]: https://www.ledger.com -[Oasis Wallet - Web]: https://www.ledger.com [Oasis app]: https://github.com/Zondax/ledger-oasis [Ledger Live]: https://www.ledger.com/ledger-live/ [wallet.oasis.io]: https://wallet.oasis.io From e32066a2833329ef8e90031788207e7b53115884 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Fri, 17 Nov 2023 18:50:17 +0100 Subject: [PATCH 09/10] docs: Change /serverdir/node -> node/data --- docs/node/mainnet/eden-upgrade.md | 4 +-- .../copy-state-from-one-node-to-the-other.md | 2 +- .../advanced/sync-node-using-state-sync.md | 2 +- .../maintenance/handling-network-upgrades.md | 6 ++--- .../maintenance/refreshing-certificates.md | 6 ++--- .../maintenance/wiping-node-state.md | 12 ++++----- .../prerequisites/system-configuration.mdx | 8 +++--- docs/node/run-your-node/sentry-node.md | 26 +++++++++---------- docs/node/run-your-node/troubleshooting.md | 14 +++++----- 9 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/node/mainnet/eden-upgrade.md b/docs/node/mainnet/eden-upgrade.md index c300428bab..48d3f0b9b4 100644 --- a/docs/node/mainnet/eden-upgrade.md +++ b/docs/node/mainnet/eden-upgrade.md @@ -180,7 +180,7 @@ running the following command: ``` bash # specify 'datadir' as your node's data directory oasis-node unsafe-reset \ - --datadir=/serverdir/node \ + --datadir=/node/data \ --dry_run ``` 2. **Wipe blockchain state:** after reviewing the dry run results, proceed with @@ -188,7 +188,7 @@ the reset by running: ``` bash # specify 'datadir' as your node's data directory oasis-node unsafe-reset \ - --datadir=/serverdir/node + --datadir=/node/data ``` Transitioning confidential ParaTimes to the new network requires local state diff --git a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md index fb06fa9bbb..375ce44e9c 100644 --- a/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md +++ b/docs/node/run-your-node/advanced/copy-state-from-one-node-to-the-other.md @@ -28,7 +28,7 @@ If an Oasis Node is **not stopped** before its state is copied, its on-disk stat ::: -* Copy the following directories from your synced Oasis Node's working directory (e.g. `/node/`, `/srv/oasis/node`, `/serverdir/node`) to your new Oasis Node's working directory: +* Copy the following directories from your synced Oasis Node's working directory (e.g. `/node/data`) to your new Oasis Node's working directory: * `tendermint/abci-state` * `tendermint/data` diff --git a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md index 4b17e70e44..7240d7edb9 100644 --- a/docs/node/run-your-node/advanced/sync-node-using-state-sync.md +++ b/docs/node/run-your-node/advanced/sync-node-using-state-sync.md @@ -121,7 +121,7 @@ If you have an existing node that you trust, you can use its status output to retrieve the current block height and hash by running: ``` -oasis-node control status -a unix:/serverdir/node/internal.sock +oasis-node control status -a unix:/node/data/internal.sock ``` This will give you output like the following (non-relevant fields omitted): diff --git a/docs/node/run-your-node/maintenance/handling-network-upgrades.md b/docs/node/run-your-node/maintenance/handling-network-upgrades.md index c015a13bcd..fda549de4f 100644 --- a/docs/node/run-your-node/maintenance/handling-network-upgrades.md +++ b/docs/node/run-your-node/maintenance/handling-network-upgrades.md @@ -64,7 +64,7 @@ While waiting for the network upgrade epoch, you can check the current height and epoch by running: ```bash -oasis-node control status -a unix:/serverdir/node/internal.sock +oasis-node control status -a unix:/node/data/internal.sock ``` and observe the value of the `consensus.latest_height` and @@ -115,7 +115,7 @@ 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 `/serverdir/etc/genesis.json`. +and save it as `/node/etc/genesis.json`. Compare the dumped state with the downloaded genesis file: @@ -328,7 +328,7 @@ you should use one. However, to start the node without a process manager you can start the [Oasis Node](../prerequisites/oasis-node.md) like this: ```bash -oasis-node --config /serverdir/etc/config.yml +oasis-node --config /node/etc/config.yml ``` ## Clean Up diff --git a/docs/node/run-your-node/maintenance/refreshing-certificates.md b/docs/node/run-your-node/maintenance/refreshing-certificates.md index 8435d12e1f..3d41cb45c4 100644 --- a/docs/node/run-your-node/maintenance/refreshing-certificates.md +++ b/docs/node/run-your-node/maintenance/refreshing-certificates.md @@ -4,7 +4,7 @@ ### Steps on the Validator Node -Go to your validator node's data directory, e.g. `/srv/oasis`, `/node`, `/serverdir/node`: +Go to your validator node's data directory, e.g. `/node/data`: ``` cd @@ -85,7 +85,7 @@ The validator node will re-register itself automatically once it's connected to ### Steps on the Sentry Node -Go to your sentry node's data directory, e.g. `/srv/oasis`, `/node`, `/serverdir/node`: +Go to your sentry node's data directory, e.g. `/node/data`: ``` cd @@ -141,7 +141,7 @@ worker: registration: # In order for the node to register itself the entity.json of the entity # used to provision the node must be available on the node. - entity: /serverdir/node/entity/entity.json + entity: /node/etc/entity.json sentry: address: - "{{ sentry_node_grpc_public_key }}@{{ sentry_node_private_ip }}:9009" diff --git a/docs/node/run-your-node/maintenance/wiping-node-state.md b/docs/node/run-your-node/maintenance/wiping-node-state.md index 713f13ce18..5b6808147d 100644 --- a/docs/node/run-your-node/maintenance/wiping-node-state.md +++ b/docs/node/run-your-node/maintenance/wiping-node-state.md @@ -7,7 +7,7 @@ severe corruption, it's important to note that your node will need some time to catch up with the rest of the network. The following instructions are based on the assumption that you have defined -your `datadir` as `/serverdir/node` in your node's configuration. +your `datadir` as `/node/data` in your node's configuration. ## State Wipe and Keep Node Identity @@ -28,12 +28,12 @@ setup). ```bash # Do a dry run first to see which files will get deleted. oasis-node unsafe-reset \ - --datadir=/serverdir/node \ + --datadir=/node/data \ --dry_run # Delete. oasis-node unsafe-reset \ - --datadir /serverdir/node + --datadir /node/data ``` 3. Start the `oasis-node` server process. @@ -43,14 +43,14 @@ setup). encounter the following error: ``` -common/Mkdir: path '/serverdir/node' has invalid owner: 1000. Expected owner: 0 +common/Mkdir: path '/node/data' has invalid owner: 1000. Expected owner: 0 ``` you need to run the `oasis-node` command as the exact user that owns the files, e.g.: ``` -sudo --user=#1000 -- oasis-node unsafe-reset --datadir=/serverdir/node --dry_run --log.level info +sudo --user=#1000 -- oasis-node unsafe-reset --datadir=/node/data --dry_run --log.level info ``` ::: @@ -70,6 +70,6 @@ To perform a full state wipe follow these steps: 1. Stop the `oasis-node` server process (this will depend on your own deployment setup) -2. Remove the `/serverdir/node` directory. +2. Remove the `/node/data` directory. 3. Redeploy your node. You'll need to copy your Node artifacts or create brand new ones. diff --git a/docs/node/run-your-node/prerequisites/system-configuration.mdx b/docs/node/run-your-node/prerequisites/system-configuration.mdx index 2e8ba00d50..4b74ef9f7c 100644 --- a/docs/node/run-your-node/prerequisites/system-configuration.mdx +++ b/docs/node/run-your-node/prerequisites/system-configuration.mdx @@ -85,7 +85,7 @@ where this is done is a misconfiguration. :::info In these examples, we change the setup to run Oasis Services (e.g. Oasis Node) with a non-root system user named `oasis`. -These instructions also assume that the node's datadir is `/serverdir/node`. +These instructions also assume that the node's datadir is `/node/data`. Adjust these as appropriate to your setup. ::: @@ -139,7 +139,7 @@ logging-in as this user. 3. Transfer ownership of the datadir to the `oasis` user: ```sh -chown -R oasis /serverdir/node +chown -R oasis /node/data ``` See [Invalid Permissions] troubleshooting guide for more information. @@ -168,8 +168,8 @@ After=network.target [Service] Type=simple User=oasis -WorkingDirectory=/serverdir/node -ExecStart=/serverdir/bin/oasis-node --config /serverdir/etc/config.yml +WorkingDirectory=/node/data +ExecStart=/node/bin/oasis-node --config /node/etc/config.yml Restart=on-failure RestartSec=3 LimitNOFILE=1024000 diff --git a/docs/node/run-your-node/sentry-node.md b/docs/node/run-your-node/sentry-node.md index 698dd40175..2c80fc03e8 100644 --- a/docs/node/run-your-node/sentry-node.md +++ b/docs/node/run-your-node/sentry-node.md @@ -21,7 +21,7 @@ Before following this guide, make sure you've read the [Prerequisites](prerequis Sentry node identity keys can be initialized with: ```bash -oasis-node identity init --datadir /serverdir/node +oasis-node identity init --datadir /node/data ``` ### Configuring Sentry Node @@ -37,7 +37,7 @@ Before using this configuration you should collect the following information to * `{{ 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 - oasis-node identity tendermint show-node-address --datadir /serverdir/node + oasis-node identity tendermint show-node-address --datadir /node/data ``` on the validator node. @@ -46,7 +46,7 @@ Before using this configuration you should collect the following information to * `{{ validator_sentry_client_grpc_public_key }}`: This is the public TLS key of the Oasis validator node that will be protected by the sentry node. This public key can be obtained by running: ```bash - oasis-node identity show-sentry-client-pubkey --datadir /serverdir/node + oasis-node identity show-sentry-client-pubkey --datadir /node/data ``` on the validator node. Note that the above command is only available in `oasis-node` from version 20.8.1 onward. @@ -69,8 +69,8 @@ Before using this configuration you should collect the following information to ## # Set this to where you wish to store node data. The node artifacts -# should also be located in this directory (for us this is /serverdir/node) -datadir: /serverdir/node +# should also be located in this directory (for us this is /node/data) +datadir: /node/data # Logging. # @@ -93,7 +93,7 @@ log: # Path to the genesis file for the current version of the network. genesis: - file: /serverdir/etc/genesis.json + file: /node/etc/genesis.json # Worker configuration. worker: @@ -175,7 +175,7 @@ oasis-node registry node init \ `SENTRY_CONSENSUS_ID`: This is the Consensus ID of the sentry node in base64 format. This ID can be obtained from `consensus_pub.pem`: ```bash -sed -n 2p /serverdir/node/consensus_pub.pem +sed -n 2p /node/data/consensus_pub.pem ``` on the sentry node. @@ -207,7 +207,7 @@ Before using this configuration you should collect the following information to * `{{ sentry_node_grpc_public_key }}`: This is the sentry node's control endpoint TLS public key. This ID can be obtained by running: ```bash - oasis-node identity show-tls-pubkey --datadir /serverdir/node + oasis-node identity show-tls-pubkey --datadir /node/data ``` on the sentry node. Note that the above command is only available in `oasis-node` from version 20.8.1 onward. @@ -215,7 +215,7 @@ Before using this configuration you should collect the following information to * `{{ sentry_node_tendermint_id }}`: This is the Tendermint ID (address) of the sentry node that will be configured as a Persistent Peer. This ID can be obtained by running: ```bash - oasis-node identity tendermint show-node-address --datadir /serverdir/node + oasis-node identity tendermint show-node-address --datadir /node/data ``` on the sentry node. @@ -238,8 +238,8 @@ Before using this configuration you should collect the following information to ## # Set this to where you wish to store node data. The node artifacts -# should also be located in this directory (for us this is /serverdir/node) -datadir: /serverdir/node +# should also be located in this directory (for us this is /node/data) +datadir: /node/data # Logging. # @@ -262,14 +262,14 @@ log: # Path to the genesis file for the current version of the network. genesis: - file: /serverdir/etc/genesis.json + file: /node/etc/genesis.json # Worker configuration. worker: registration: # In order for the node to register itself the entity.json of the entity # used to provision the node must be available on the node. - entity: /serverdir/node/entity/entity.json + entity: /node/etc/entity.json sentry: address: - "{{ sentry_node_grpc_public_key }}@{{ sentry_node_private_ip }}:9009" diff --git a/docs/node/run-your-node/troubleshooting.md b/docs/node/run-your-node/troubleshooting.md index c393748803..c509a167dd 100644 --- a/docs/node/run-your-node/troubleshooting.md +++ b/docs/node/run-your-node/troubleshooting.md @@ -34,7 +34,7 @@ Before you begin troubleshooting we suggest you check all of the following: Error Message: ```text -common/Mkdir: path '/serverdir/node' has invalid permissions: -rwxr-xr-x +common/Mkdir: path '/node/data' has invalid permissions: -rwxr-xr-x ``` The `entity` and `node` directories both need to have permissions `rwx------`. Make sure you initialize the directory with correct permissions or change them using `chmod`: @@ -44,8 +44,8 @@ mkdir --mode 700 --parents {entity,node} ``` ```bash -chmod 700 /serverdir/node -chmod 700 /serverdir/entity +chmod 700 /node/data +chmod 700 /node/etc ``` #### Permissions for .pem files @@ -53,7 +53,7 @@ chmod 700 /serverdir/entity Error Message example: ```text -signature/signer/file: invalid PEM file permissions 700 on /serverdir/node/identity.pem +signature/signer/file: invalid PEM file permissions 700 on /node/data/identity.pem ``` All `.pem` files should have the permissions `600`. You can set the permissions for all `.pem` files in a directory using the following command: @@ -62,12 +62,12 @@ All `.pem` files should have the permissions `600`. You can set the permissions chmod -R 600 /path/*.pem ``` -#### Serverdir Ownership +#### Node directory Ownership -Another possible cause of permission issues is not giving ownership of your `serverdir` to the user running the node (e.g. `docker-host` or replace with your user): +Another possible cause of permission issues is not giving ownership of your `node/` to the user running the node (e.g. `docker-host` or replace with your user): ```bash -chown -R docker-host:docker-host /serverdir +chown -R docker-host:docker-host /node ``` In general, to avoid problems when running docker, specify the user when running `docker` commands by adding the flag `--user $(id -u):$(id -g)`. From 0e03196e471d19b1a10eb3aef47d5b3640c5ac93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matev=C5=BE=20Jekovec?= Date: Mon, 20 Nov 2023 15:06:01 +0100 Subject: [PATCH 10/10] README: Add Oasis CLI, Mainnet, Testnet examples to Vocabulary --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 819c51b21a..5abf8856b4 100644 --- a/README.md +++ b/README.md @@ -200,8 +200,8 @@ There are three kinds of image assets currently used in the docs. ## Vocabulary -The following is a consistent case-sensitive collection of Oasis-related terms -and their usage: +The following is a consistent case-sensitive collection of Oasis-related terms, +and their usage including the articles: - c10l Check out the c10l-hello-world folder for the confidential version of the @@ -217,7 +217,11 @@ and their usage: - key manager - key manager node - Mainnet + This feature is also enabled on Mainnet. - Testnet + This only runs on Testnet. +- Oasis CLI + You can use the Oasis CLI to set up your wallet. - Oasis Core - OPL Oasis Privacy Layer supports privacy of dApps on all EVM chains.