From ed69a41fd2c7583e169ced50e6cdbd8bf7000e0f Mon Sep 17 00:00:00 2001 From: "Reuven V. Gonzales" Date: Wed, 13 Nov 2019 01:41:56 -0800 Subject: [PATCH 01/14] Merge latest docs from private operator docs --- src/operators/architectural-overview.md | 114 +++- src/operators/current-testnet-parameters.md | 8 + ...rements.md => hardware-recommendations.md} | 40 +- src/operators/joining-the-testnet.md | 542 ++++++++++++++++++ .../maintenance/wiping-node-state.md | 34 ++ src/operators/prerequisites.md | 46 ++ 6 files changed, 754 insertions(+), 30 deletions(-) create mode 100644 src/operators/current-testnet-parameters.md rename src/operators/{hardware-requirements.md => hardware-recommendations.md} (55%) create mode 100644 src/operators/joining-the-testnet.md create mode 100644 src/operators/maintenance/wiping-node-state.md create mode 100644 src/operators/prerequisites.md diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index 167e2f69..f867b799 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -7,24 +7,101 @@ is used to provide enough guidance to be useful for the purposes of getting started as a Node Operator. For more information, see [our whitepaper](https://www.oasislabs.com/whitepaper). +## Definitions + +### Entity + +An Entity is an organization or individual with stake on the network. Each +Entity has a private key that controls access to the wallet of the Entity. See +[Entities and Key Management](#entities-and-key-management) for further +information. + +### Node + +A Node is a device (VM, Bare Metal, Container, etc.) that is participating in a +committee on the network. Each Node has a private key that is used for signing +operations during block production and a public key, or Node Identity, used for +identification. See [Entities and Key Management](#entities-and-key-management) +for further information. + +### Committee + +A Committee is a set of Nodes that are participating in the same service layer +of oasis. Committees are described in more detail in the [Modular +Architecture](#modular-architecture) Section. + ## Modular Architecture The Oasis Network uses a modular architecture similar to that of a Service -Oriented Archiecture or a Microservices Architecture. Any given node +Oriented Archiecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis -Network. The responsibilities of these committees can be mapped to a set of 4 -different layers: Consensus, Compute (Confidential and Non-confidential), -Storage, and Key Management. For a Node Operator, these layers map distinctly to -different classes Nodes and potentially to different hardware. +Network. In this section, we explore the different committees and their +responsibilities. + +### Committee Responsibilities + +![Transaction Processing](./operator_images/web3_diagram_v2.png) + +In the figure above, we see the flow of transactions in each committee. The +details of each committee is best described in our [blockchain +paper](https://www.oasislabs.com/whitepaper), but we provide this section here +as a high level introduction. It should be noted that some aspects of the system +are yet to be completed. So the testnet that you might deploy in the [Quick +Start Guide](./quick-start.md) won't yet function as it is described here. + +#### Registry + +Although not pictured, the Registry maintains a list of valid Entities, Nodes, +the Committees that each Node has registered to participate, and the lifetime of +each Node. + +#### Committee Scheduler + +While not a committee unto itself, the Committee Scheduler assigns eligible +nodes to specific committees for some duration of epochs. The pool of Nodes to +be scheduled are chosen from the Registry. + +It is possible that a Node can register for more than one committee to make +efficient use of hardware. If, for instance, a Node registers with the +possibility of operating as a Storage or Compute Node, the Committee Scheduler +will assign it a single job during a given lifetime. -### Transaction Processing Diagram +#### Transaction Scheduler Committee -![Transaction Processing](/operator_images/web3_diagram_v2.png) +The Transaction Scheduler Committee schedules batches of transactions into the +Compute Committee. In order to ensure maximum throughput, the Transaction +Scheduler batches transactions for execution that should be conflict free. + +#### Compute Committee + +The Compute Committee executes transactions. + +#### Merge Committee + +The output from the Compute Committee are merged into a single application state +and submitted to the Consensus Committee to agree upon the final application +state after a batch of transactions execute. + +#### Storage Committee + +Stores application state from the compute and merge committee. + +#### Consensus Committee + +The Consensus Committee is the BFT consensus layer. It's primary function during +transaction processing is to reach consensus on the final state of the +application that it receives from the Merge Committees. + +_As a note, the MainNet Beta will only be released with a Consensus Committee._ + +#### Key Manager Committee + +Provides a key management for Confidential Compute Committees. ## Networking Protocols -The Oasis Network uses 3 main protocols for communication: +The Oasis Network uses 3 different protocols for communication: * [Tendermint](https://github.com/tendermint/tendermint) * [grpc](https://grpc.io/) @@ -34,5 +111,22 @@ The Oasis Network uses 3 main protocols for communication: Confidentiality is achieved in the Oasis Network by relying on trusted execution environments (TEEs) to secure the execution of any given smart contract. -Initially, the Oasis Network will utilize [Intel SGX](https://software.intel.com/en-us/sgx). -As more TEE technologies mature, we expect to support more than TEEs than Intel SGX. +Initially, the Oasis Network will utilize [Intel +SGX](https://software.intel.com/en-us/sgx). As more TEE technologies mature, we +expect to support more than TEEs than Intel SGX. + +## Entities and Key Management + +Every Node that participates on the network is owned by a specific Entity. This +Entity is not only a logical abstraction but is also a critical aspect of the +key management model for node operators. The model is as follows: + +* Entity + * An Entity is an organization or individual with stake on the network + * Each Entity's key pair is used for: + * Registering Node IDs (Node's Public Key) + * Token transfers +* Node + * A Node is a block producing node on the Oasis Network + * Each Node's key pair is used for: + * Signing actions during block production diff --git a/src/operators/current-testnet-parameters.md b/src/operators/current-testnet-parameters.md new file mode 100644 index 00000000..cc1660d0 --- /dev/null +++ b/src/operators/current-testnet-parameters.md @@ -0,0 +1,8 @@ +# Current Testnet Parameters + +This page is meant to be kept up to date with the information from the currently +released testnet. Use the information here to deploy or upgrade your node on the +testnet. + +* [Link to Genesis Document]() +* Oasis Seed Node Address (feel free to use other seed nodes): diff --git a/src/operators/hardware-requirements.md b/src/operators/hardware-recommendations.md similarity index 55% rename from src/operators/hardware-requirements.md rename to src/operators/hardware-recommendations.md index 0252c262..d0af0a7e 100644 --- a/src/operators/hardware-requirements.md +++ b/src/operators/hardware-recommendations.md @@ -1,54 +1,54 @@ -# Node Hardware Requirements +# Node Hardware Recommendations -_The hardware requirements listed on this page are recommended minimum +_The hardware configurations listed on this page are recommended minimum configurations. It might be possible to configure a system with less resources, but you run the risk of being underprovisioned and thereby prone to loss of stake._ -## Minimum System Requirements +## Suggested Minimum Configurations As noted in the [Architectural Overview](./architectural-overview.md), the Oasis -Network is composed of multiple classes of Nodes that perform specific -functions. The majority of Node classes have common system requirements. All -node types should support the following minimum requirements: +Network is composed of multiple classes of Nodes that participate in different +committees. The majority of committees have common system configurations for the +participant Nodes. We suggest the following minimum recommendations: * 2.0 GHz x86-64 * Must have AES-NI support -* 4 GB ECC RAM +* 2 GB ECC RAM * 500GB High Speed Storage -### Node Class Additional Requirements +### Additional Attributes By Committee -Beyond the common system requirements, the following section details -additional requirements for operating the different Node classes. +Beyond the common system configurations, the following section details +additional requirements or recommendations for operating Nodes to participate in +different committees. -#### Confidential Compute Layer Nodes +#### Confidential Compute Committee Nodes As part of supporting confidential smart contracts in the future, the Oasis Network will utilize SGX in order to ensure privacy preserving computation. At this time, supporting SGX hardware is optional for Node Operators. However, for Node Operators who want to be to prepared for the eventual release of the -confidential runtime, the following requirements should be met: +confidential runtime, the network will require at least the following hardware: * CPU supports SGXv1 Support * BIOS supports enabling SGX * EPC limits should be set to the maximum 128MB + * Setting this value to the maximum is recommended but is not required. -#### Storage Nodes +#### Storage Committee Nodes -At this time, the growth rate of state stored on storage nodes is unknown. Node -operators should expect the minimum recommendations for storage to change over -time. - -Recommended Minimum Configuration: +At this time, the growth rate of state stored on storage nodes is unknown. We +suggest that Node Operators configure their systems with the following +hardware in order to handle storage growth over time: * 2TB High Speed Storage -#### Key Management Nodes +#### Key Manager Committee Nodes At this time, Key Management Nodes will only be operated by Oasis. However system requirements for the Key Manager nodes are currently identical to the -confidential compute worker nodes. +Confidential Compute Committee nodes. ### HSMs diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md new file mode 100644 index 00000000..85d7a294 --- /dev/null +++ b/src/operators/joining-the-testnet.md @@ -0,0 +1,542 @@ +# Joining the Testnet + +This guide will cover setting up your nodes on the public testnet. There is some +assumption of knowledge on the use of basic command line tools and docker. + +## Prerequisites + +Before following this guide, make sure you've followed the [Prerequisites +Guide](./prerequisites.md) and understand how to use the `oasis-node` binary. + +### Systems + +This guide assumes that you have two different physical machines that you will +use for deployment. These machines are the following: + +* Your local system, henceforth called the `localhost`. +* A remote system to run as an Oasis node, henceforth called the `server`. + +The reason for this is to ensure protection of the keys used to +setup your node. This guide does not include the use of HSMs, but +should be used in the future. + +## Creating your entity + +Everything in this section should be done on the `localhost` as there are +sensitive items that will be created. + +### Creating a working directory + +During this entity initialization process, we will create keys and other +important artifacts that are necessary for the deployment of nodes on the +network. It is important that you save and protect the generated artifacts in +this directory if you intend to use them to register your entity and nodes. We +will reference the working directory on `localhost` as `/localhostdir` +throughout the documentation. Inside `/localhostdir` you should create the +following directories: + +* `entity` - This will store your entity. The private contents in this directory + are safest if used on a machine kept disconnected from the internet. The + directory permissions should be `rwx------` +* `node1` - This will store a node we are calling "node1". The name is not + important. It simply represents one of your nodes. You can rename it to whatever you + wish. The private contents of this directory will be used on the node itself. + You should initialize this information on a system with access to the entity's + private key. The directory permissions should be `rwx------` + +To create the directory structure, use the following command: + +```bash +$ mkdir -m700 -p {entity,node} +``` + +### Initializing an Entity + +The entity, as [described +here](../architectural-overview.md#entities-and-key-management) is critical to +operating nodes on the network as it controls the stake attached to a given +individual or organization on the network. In the future we will support using +entity keys through HSMs to ensure that entity keys cannot be easily +compromised. We strongly suggest that you do not use any entity that is generated +with the current process on the Mainnet. During the public testnet and staking +competition we would also suggest that you generate the entity on a system that has +no network connection to provide rudimentary protection for the entity key. +However, it is up to you to determine your own security practices. + +To initialize an entity simply run the following from `/localhostdir/entity`: + +``` +$ oasis-node registry entity init +``` + +This will generate 3 files in `/localhostdir/entity` + +* `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 the the `entity.pem`. This is meant to be shared for + inclusion on the genesis block. + +### Initializing a Node + +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 to the +node. This allows the node registration to happen without the uploading entity key +to the internet. To initialize a validator node, run the following from +the `/localhostdir/node1` directory. + +```bash +$ export STATIC_IP= +$ oasis-node registry node init \ + --entity /localhostdir/entity \ + --node.consensus_address $STATIC_IP:26656 \ + --node.is_self_signed \ + --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). There are more options +for this that you can explore by running `oasis-node registry node init --help`. +The options shown above are the minimum. + +The command will generate the following files: + +* `consensus.pem` - The node's private key used for consensus. **DO NOT SHARE** +* `consensus_pub.pem` - The node's public key for consensus +* `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 on + 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. +* `tls_identity.pem` - The node's TLS key for grpc's TLS . **DO NOT SHARE** +* `tls_identity_cert.pem` - The node's TLS cert for grpc's TLS. + +#### Add 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. + +Execute the following command in the `/localhostdir/node1` directory: + +``` +$ oasis-node registry entity update \ + --datadir /localhostdir/entity \ + --entity.node.descriptor node_genesis.json +``` + +This will update the entity descriptor `entity.json` and subsequently the +`entity_genesis.json` file that contains the signed entity descriptor payload. + +#### Initializing additional nodes + +At the time of Public Testnet, the network will only have validators and no +other committees (no compute, no key management, no storage, etc.). At this time +this documentation does not include instructions in configuring anything beyond +a single validator. If you'd like to create more validator nodes you can simply +repeat the process above to initialize the artifacts for an additional node (and +renaming the proper things). Each node will require at least the network's +defined minimum staking amount (at this time this is 100 tokens). + +## Running an Oasis Node on the `server` + +### 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. For this guide, we will call this working +directory `/serverdir` directory. + +#### Setting up the the `/serverdir` directory + +In the `/serverdir` directory we will 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 + +You can make this directory structure by calling the following command: + +```bash +$ mkdir -p /serverdir/{etc,node/entity} +``` + +#### Copy 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](https://github.com/) section. To do so upload the +following files from `/localhostdir/node1` to `/serverdir/node` over a secure channel: + +* `consensus.pem` +* `consensus_pub.pem` +* `identity.pem` +* `identity_pub.pem` +* `node_genesis.json` +* `p2p.pem` +* `p2p_pub.pem` +* `tls_identity.pem` +* `tls_identity_cert.pem` + +_You may notice that some of these files were listed as **DO NOT SHARE**. In the +future these keys should be generated and referenced from HSM. Before we have +HSM support, these keys should be kept as secure as possible on the `server`. + +#### Copy the public Entity artifacts from `/localhostdir` + +We will also need to have public entity artifacts from the `/localhostdir`. Copy +the file from `/localhostdir/entity/entity.json` to +`/serverdir/node/entity/entity.json`. + +#### Copy the genesis files + +The latest genesis files can be found [here](./current-testnet-parameters.md). +You should download the latest `genesis.json` file and copy it to +`/serverdir/etc/genesis.json`. + +#### 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. + +Before using this configuration you should collect the following information to +replace the `{{ var }}` variables present in the configuration file: + +* `{{ external_address }}` - This is the external IP you wish to use when + registering this node. If you are using a Sentry Node, you should use the + public IP of that machine. +* `{{ seed_node_address }}` - This the seed node address in the form `{{ ID + }}@{{ IP }}:{{ PORT }}` this is published + [here](./current-testnet-parameters.md) + +Create a file, `/serverdir/etc/config.yml`, with the following +contents: + +```yaml +## +# Oasis Node Configuration +# +# This file's configurations are derived from the command line args found in the +# root command of the oasis-node binary. For more information execute: +# +# oasis-node --help +# +# Settings on the command line that are separated by a dot all belong to the +# same nested object. So "--foo.bar.baz hello" would translate to: +# +# foo: +# bar: +# baz: hello +## + +# 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 + +## THESE NEXT 3 LINES ARE TEMPORARY YOU SHOULD NOT EXPOSE THIS PORT IN ANY WAY +grpc: + debug: + port: "42261" + +# Logging. +# +# Per-module log levels are defined below. If you prefer just one unified log +# level, you can use: +# +# log: +# level: debug +log: + level: + # Per-module log levels. Longest prefix match will be taken. Fallback to + # "default", if no match. + default: debug + tendermint: warn + tendermint/context: error + format: JSON + # By default logs are output to stdout. If you're running this in docker keep the + # default + #file: /var/log/oasis-node.log + +# Path to the genesis file for the current version of the network. +genesis: + file: /serverdir/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 + +# Consensus backend. +consensus: + # Setting this to true will mean that the node you're deploying will attempt + # to register as a validator. + validator: True + +# Tendermint backend configuration. +tendermint: + abci: + prune: + strategy: keep_n + num_kept: 86400 + core: + listen_address: tcp://0.0.0.0:26656 + + # The external_address option is used when registering this node to the + # network. If you are using a sentry node then this should be the public + # ip of the sentry node. + external_address: tcp://{{ external_address }}:26656 + + db: + backend: boltdb + debug: + addr_book_lenient: False + seeds: "{{ seed_node_address }}" +``` + +### Starting the Oasis Node + +#### Starting with docker + +For those of you who are relying on the +[oasis-node](https://hub.docker.com/r/oasislabs/oasis-node) docker container, +the command to start the oasis-node is: + +```bash +$ docker run --entrypoint /oasis/bin/oasis-node \ + --name oasis_node \ + --volume /serverdir:/serverdir \ + --workdir /serverdir/node \ + -p 26656:26656 \ + -p 42261:42261 \ + oasislabs/oasis-node:$OASIS_NODE_TAG \ + --config /servernode/etc/config.yml +``` + +_Note: the `-p 42261:42261` port binding is temporary. We will notify all of you +when this no longer needs to be bound._ + +This will create a docker container named `oasis_node`. This is useful to have a +named container so it can be referenced later. If you name it something else, +then be aware that the docs will reference `oasis_node` for this docker +container. + +_It is up to you to configure these options how you see fit. This invocation of +the server process will not restart automatically. If you'd like to run this in +the background add the docker flag `--detach`_ + +#### Starting without docker + +If you have built the `oasis-node` binary on your own, you can start the server +by running the command below. Please note, the node is, by default, configured to run in the +foreground. You will need to use a process supervisor like +[supervisord](http://supervisord.org/), +[systemd](https://github.com/systemd/systemd), etc. + +``` +$ oasis-node --config /serverdir/etc/config.yml +``` + +### 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. + +```bash +$ oasis-node registry entity list -a /serverdir/node/internal.sock +``` + +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: + +``` +2317a8eef10e470434411aebac8f1a8c0f1c6a0d35ff53921f8bc70588bb66b2 +8e3873f84f7f2250eb456dc598dc56b812f561137fe41c383128e6c14e0e2e74 +cf3b004bd98f3e1eab92e97c5fa6cbe4d42a00133c515a2440fefaca514a48ff +``` + +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 Testnet. + +## Signing up for Testnet Tokens + +_This won't be necessary if you are in the genesis file or already have tokens +through some other means. For most people this, will not be true._ + +In order to participate on the Testnet you'll need to have tokens. You'll use +these tokens to register your entity and stake on the network. To get tokens, +you'll need to sign up with [this +form](https://oasisfoundation.typeform.com/to/dlcekq). While filling out the +form, it will ask for your Entity Public Key. This is the same as your Entity +Account ID and can be found in the `/localhostdir/entity/entity.json`. In this +JSON file, the Entity Public Key is the `id` field. + +### Example + +In the following example `entity.json`, the Entity Public key is +`TszGIrC1X08czcik0DgAnmGPzjf8pfQ47bgrjpTmbro=`. + +```json +{ + "id": "TszGIrC1X08czcik0DgAnmGPzjf8pfQ47bgrjpTmbro=", + "nodes": [ + "C93lKVNNkca3Oo9m1exiz22NvMBxxYjkyBrt2+eFAds=" + ], + "registration_time": 1573585972, + "allow_entity_signed_nodes": false +} +``` + +## Staking and Registering + +_This won't be necessary if your Entity is in the genesis file._ + +Once you have been funded, you can now complete the process of connecting your +node by staking so that you can register your entity and register your node. + +### Generate a Staking (Escrow) transaction on the `localhost` + +Your Entity private key should ideally be disconnected from the internet on the +`localhost`. You want this because the Entity private key is used to authorize +transactions on your staking account. To ensure that the Entity private key +isn't sent to the `server` we will generate a transaction on the `localhost`. +The staking application calls "staking" an escrow. For the testnet, the current +minimum stake required to register an entity and register a node as a validator +is 100 tokens. So we will generate an escrow transaction that escrows 100 tokens +on your own Entity. + +``` +$ oasis-node stake account gen_escrow \ + --entity $ENTITY_DIR_PATH \ + --stake.escrow.account $ACCOUNT_ID \ + --stake.transaction.amount 100000000000000000000 \ + --stake.transaction.file $OUTPUT_TX_FILE_PATH \ + --stake.transaction.nonce 0 +``` + +The parameters are as follows: + +* `$ENTITY_DIR_PATH` - For this guide this would be `/localhostdir/entity/` +* `$OUTPUT_TX_FILE_PATH` - This is where you wish to output the signed + transaction file. For this guide we will use `/localhostdir/signed-escrow.tx` +* `$ACCOUNT_ID` - This is the hex encoding of the Entity Public Key. To derive this you + can use the following python3 code: + + ``` + import binascii, base64 + + def account_id_from_b64(base64_id): + """base64_id can be found in entity.json in the `id` field""" + return binascii.hexlify(base64.b64decode(base64_id)) + + account_id_from_b64("") + >>> "deadbeefdeadbeefdeadbeef..." + ``` + +Note that the option `--stake.transaction.amount` looks like a very large +number. This is actually equivalent to 100 tokens on the Testnet as each unit +value used to track the account balance is 1x10^-18 tokens. + +### Submitting your transaction on the `server` + +To complete the staking process we need to submit your escrow transaction: + +1. Copy the file `/localhostdir/signed-escrow.tx` on the `localhost` to + `/serverdir/signed-escrow.tx` on the `server`. +2. Call `oasis-node` like so: + + If you're using docker use: + + ``` + $ docker exec -it oasis_node /bin/bash + $ oasis-node stake account submit \ + --stake.transaction.file /serverdir/signed-escrow.tx \ + -a /serverdir/node/internal.sock + ``` + + Without docker + ``` + $ oasis-node stake account submit \ + --stake.transaction.file /serverdir/signed-escrow.tx \ + -a /serverdir/node/internal.sock + ``` + +### Registering you entity + +As a final step, you now need to register your entity onto the network. + +**TEMPORARY FIX**: At this time many of these instructions are a temporary fix +due to missing features on the current `oasis-node` cli. + +#### Port Forward + +On one instance of a terminal on the `localhost` execute the following to handle +a port forwarding so you can make entity requests. _Unfortunately, if you're +using docker on your `localhost` you will also have to ssh to your `server` +within your the docker container. We apologize for the inconvenience this is a +temporary measure._ + +``` +$ ssh $USER@$SERVER_IP -L 42261:127.0.0.1:42261 -N +``` + +#### Register your node onto the network + +On a different terminal from your ssh port forward above, execute the following: + +``` +$ oasis-node registry entity register --datadir /localhostdir/entity +``` + +If everything is successful you will get a zero exit code. + +### Checking that your node is properly registered + +_We understand these instructions for verification need to improve. Any +assistance is welcome ;)_ + +To ensure that your node is properly connected as a Validator on the network, We +can check to see the node's identity on in the registry's node list. +Unfortunately, at this time this is a bit of a manual process. + +### Get the node's consensus_pub.pem identity + +``` +cat /serverdir/node/consensus_pub.pem +``` + +This will look like: + +``` +-----BEGIN ED25519 PUBLIC KEY----- +s+vZ71qeZnlq0HmQSDBiWn2OKcy3fXOuPMu76/5GkUI= +-----END ED25519 PUBLIC KEY----- +``` + +We will use `s+vZ71qeZnlq0HmQSDBiWn2OKcy3fXOuPMu76/5GkUI=`. As the key to search for. + +### grep for the node's identity + +Finally to see if the node is properly registered, run the command (you may need +to be in a docker container if you are using that): + +``` +$ export NODE_PUB_KEY="s+vZ71qeZnlq0HmQSDBiWn2OKcy3fXOuPMu76/5GkUI=" +$ oasis-node registry node list -v -a /serverdir/node/internal.sock | grep $NODE_PUB_KEY +``` + +If `grep` found the key, then you're properly connected! + +## You're a Validator! + +If you've made it this far you've properly connected your node to the network +and you're now a Validator on the public testnet. + +### Maintenance Guides + +* [Wiping Node State](./maintenance/wiping-node-state.md) diff --git a/src/operators/maintenance/wiping-node-state.md b/src/operators/maintenance/wiping-node-state.md new file mode 100644 index 00000000..97772301 --- /dev/null +++ b/src/operators/maintenance/wiping-node-state.md @@ -0,0 +1,34 @@ +# Wiping node state + +In some cases you might want (or need) to do a full redeploy with clean state +before deploying a new version of the network. This should never actually be +used during a Mainnet unless there is some serious corruption, but your node +will have to spend time catching up to the rest of the network. + +The following instructions assume that your `datadir` is defined as +`/serverdir/node` in your node's config. + +## State Wipe and Keep Node Identity + +1. Stop the `oasis-node` server process (this will depend on your own deployment + setup) +2. Remove blockchain state + + ```bash + $ rm -rf /serverdir/node/tendermint + $ rm -rf /serverdir/node/bleve-tag-index.bleve.db + $ rm /serverdir/node/abci-mux-state.bolt.db + ``` + +3. Restart the oasis-node server process + +## Full State Wipe + +A full state wipe will also mean that you'll need to generate a new node +identity (or copy the old one). This is likely not what you want. + +1. Stop the `oasis-node` server process (this will depend on your own deployment + setup) +2. Remove the the `/serverdir/node` directory. +3. Redeploy your node. You'll need to copy your Node artifacts or create brand + new ones. diff --git a/src/operators/prerequisites.md b/src/operators/prerequisites.md new file mode 100644 index 00000000..97b7c988 --- /dev/null +++ b/src/operators/prerequisites.md @@ -0,0 +1,46 @@ +# Prerequisites Guide + +## Installing/Using oasis-node + +Any time the `oasis-node` binary is referenced, we are refering to the binary +that is created from the [oasis-core](https://github.com/oasislabs/oasis-core) +repository's `go/` path. This binary contains both the logic for running a +validator node and also provides a CLI for handling registry and staking +operations. + +### Building from source + +Although highly suggested, building from source is currently beyond the scope of +the documentation. See [oasis-core](https://github.com/oasislabs/oasis-core) for +details. + +As the release management of our open source repositories improves, we will +provide further details to so that building a specific version can be done in a +coordinated way across the network. + +### Using inside docker + +For those that wish to use the Oasis provided docker container, the `oasis-node` +binary can be accessed by running inside the context of a the +[oasis-node](https://hub.docker.com/r/oasislabs/oasis-node) docker container. + +You will need to have docker v18.x.y installed. Once you have docker, you can +execute inside the docker container by using the following: + +``` +$ docker run -it --rm \ + --entrypoint /bin/bash \ + --volume $(pwd):/workdir \ + --workdir /workdir \ + oasislabs/oasis-node:$VERSION +$ oasis-node --help +``` + +This invocation will set `/workdir` in the docker container to the current +working directory of the host. It is up to you to set this working directory +correctly. If there are any strange errors, this is a common source of problems. + +While the `latest` tag is available with the `oasis-node`, we suggest currently +using one of the `master-YYYYMMDDHHMMSS` tags so that your node doesn't drift. +Also, when deploying nodes on the testnet Oasis will publish the correct version +of the node to use on [this documentation](./current-testnet-parameters.md). From 9428add3df027ba1ab3d7a96013eed895a20fa8d Mon Sep 17 00:00:00 2001 From: "Reuven V. Gonzales" Date: Wed, 13 Nov 2019 01:52:59 -0800 Subject: [PATCH 02/14] Add quick navigation to the quick nav --- src/operators/overview.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/operators/overview.md b/src/operators/overview.md index 3f8a8f90..73e4649a 100644 --- a/src/operators/overview.md +++ b/src/operators/overview.md @@ -14,6 +14,9 @@ continuously updated as more information becomes available. ![Oasis Network Roadmap](/operator_images/roadmap.png) -## Next Steps +## Quick Navigation -* [Architectural Overview](./architectural-overview) +* [Architectural Overview](./architectural-overview.md) +* [Hardware Recommendations](./hardware-recommendations.md) +* [Joining The Testnet](./joining-the-testnet.md) +* [Current Testnet Parameters](./current-testnet-parameters.md) From 2b59962647b268e4344c4c5fa2f34ed9844582da Mon Sep 17 00:00:00 2001 From: david-yan Date: Wed, 13 Nov 2019 08:44:46 -0800 Subject: [PATCH 03/14] Update joining-the-testnet.md --- src/operators/joining-the-testnet.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index 85d7a294..ff147d6b 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -166,7 +166,7 @@ $ mkdir -p /serverdir/{etc,node/entity} 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](https://github.com/) section. To do so upload the +the [Initializing a Node](#initialzing-a-Node) section. To do so upload the following files from `/localhostdir/node1` to `/serverdir/node` over a secure channel: * `consensus.pem` @@ -366,7 +366,7 @@ your node is not yet registered as a validator on the Oasis Testnet. ## Signing up for Testnet Tokens _This won't be necessary if you are in the genesis file or already have tokens -through some other means. For most people this, will not be true._ +through some other means. For most people, this will not be true._ In order to participate on the Testnet you'll need to have tokens. You'll use these tokens to register your entity and stake on the network. To get tokens, From 789749fe305d40765c13fc0fd442166b84055e82 Mon Sep 17 00:00:00 2001 From: Jernej Kos Date: Wed, 13 Nov 2019 17:45:10 +0100 Subject: [PATCH 04/14] Update for latest changes --- src/operators/joining-the-testnet.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index ff147d6b..2cf182b5 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -50,6 +50,17 @@ To create the directory structure, use the following command: $ mkdir -m700 -p {entity,node} ``` +### Copy the genesis file + +The latest genesis file can be found [here](./current-testnet-parameters.md). +You should download the latest `genesis.json` file, copy it to the working +directory and save its path into an environment variable: +```bash +$ export GENESIS_FILE_PATH=/localhostdir/genesis.json +``` + +This will be needed later when generating transactions. + ### Initializing an Entity The entity, as [described @@ -412,6 +423,7 @@ on your own Entity. ``` $ oasis-node stake account gen_escrow \ + --genesis.file $GENESIS_FILE_PATH \ --entity $ENTITY_DIR_PATH \ --stake.escrow.account $ACCOUNT_ID \ --stake.transaction.amount 100000000000000000000 \ From bf74a68ed95bc0b018a55c0e948af5ee338cd9b6 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 08:47:44 -0800 Subject: [PATCH 05/14] Update architectural overview --- src/operators/architectural-overview.md | 34 ++++--------------------- 1 file changed, 5 insertions(+), 29 deletions(-) diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index f867b799..efc32334 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -36,8 +36,10 @@ The Oasis Network uses a modular architecture similar to that of a Service Oriented Archiecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis -Network. In this section, we explore the different committees and their -responsibilities. +Network. The responsibilities of these committees can be mapped to a set of 4 +different layers: Consensus, Compute (Confidential and Non-confidential), +Storage, and Key Management. For a Node Operator, these layers map distinctly to +different classes Nodes and potentially to different hardware. ### Committee Responsibilities @@ -67,37 +69,11 @@ efficient use of hardware. If, for instance, a Node registers with the possibility of operating as a Storage or Compute Node, the Committee Scheduler will assign it a single job during a given lifetime. -#### Transaction Scheduler Committee - -The Transaction Scheduler Committee schedules batches of transactions into the -Compute Committee. In order to ensure maximum throughput, the Transaction -Scheduler batches transactions for execution that should be conflict free. - -#### Compute Committee - -The Compute Committee executes transactions. - -#### Merge Committee - -The output from the Compute Committee are merged into a single application state -and submitted to the Consensus Committee to agree upon the final application -state after a batch of transactions execute. - -#### Storage Committee - -Stores application state from the compute and merge committee. - #### Consensus Committee The Consensus Committee is the BFT consensus layer. It's primary function during transaction processing is to reach consensus on the final state of the -application that it receives from the Merge Committees. - -_As a note, the MainNet Beta will only be released with a Consensus Committee._ - -#### Key Manager Committee - -Provides a key management for Confidential Compute Committees. +application that it receives from the Compute layer. ## Networking Protocols From 59ee6b3799f31e6fec66e73fa1bb704d42ddf472 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 08:54:04 -0800 Subject: [PATCH 06/14] Update src/operators/architectural-overview.md --- src/operators/architectural-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index efc32334..c4280f3c 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -33,7 +33,7 @@ Architecture](#modular-architecture) Section. ## Modular Architecture The Oasis Network uses a modular architecture similar to that of a Service -Oriented Archiecture or a Microservices Architecture. Any given Node +Oriented Architecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis Network. The responsibilities of these committees can be mapped to a set of 4 From 8637fd1394b93c608ff2c07a99d67610c9c87b25 Mon Sep 17 00:00:00 2001 From: david-yan Date: Wed, 13 Nov 2019 08:54:36 -0800 Subject: [PATCH 07/14] Update joining-the-testnet.md --- src/operators/joining-the-testnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index 2cf182b5..c56f2033 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -177,7 +177,7 @@ $ mkdir -p /serverdir/{etc,node/entity} 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](#initialzing-a-Node) section. To do so upload the +the [Initializing a Node](#initializing-a-node) section. To do so upload the following files from `/localhostdir/node1` to `/serverdir/node` over a secure channel: * `consensus.pem` From 6c402bbf19690dda5ddbd2babb82267a180c430a Mon Sep 17 00:00:00 2001 From: Andrew Miller <44983417+armiller123@users.noreply.github.com> Date: Wed, 13 Nov 2019 09:04:54 -0800 Subject: [PATCH 08/14] Minor copy changes Made some minor grammar changes, and added a caveat to the first paragraph. --- src/operators/architectural-overview.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index c4280f3c..cc63070f 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -4,8 +4,8 @@ As an operator of a Node on the Oasis Network, it is suggested that you have an understanding of the system architecture of the Oasis Network. Here we will provide a high level overview of the Oasis Network's architecture. This overview is used to provide enough guidance to be useful for the purposes of getting -started as a Node Operator. For more information, see -[our whitepaper](https://www.oasislabs.com/whitepaper). +started as a Node Operator. Note that not all of these features are available in the Public Testnet, and their design may change in later phases. For more information on our proposed design, see +[our research papers](https://www.oasis-protocol.org/researchpapers). ## Definitions @@ -19,7 +19,7 @@ information. ### Node A Node is a device (VM, Bare Metal, Container, etc.) that is participating in a -committee on the network. Each Node has a private key that is used for signing +committee on the Network. Each Node has a private key that is used for signing operations during block production and a public key, or Node Identity, used for identification. See [Entities and Key Management](#entities-and-key-management) for further information. @@ -27,13 +27,13 @@ for further information. ### Committee A Committee is a set of Nodes that are participating in the same service layer -of oasis. Committees are described in more detail in the [Modular -Architecture](#modular-architecture) Section. +of the Oasis Network. Committees are described in more detail in the [Modular +Architecture](#modular-architecture) section. ## Modular Architecture The Oasis Network uses a modular architecture similar to that of a Service -Oriented Architecture or a Microservices Architecture. Any given Node +Oriented Archiecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis Network. The responsibilities of these committees can be mapped to a set of 4 @@ -46,8 +46,8 @@ different classes Nodes and potentially to different hardware. ![Transaction Processing](./operator_images/web3_diagram_v2.png) In the figure above, we see the flow of transactions in each committee. The -details of each committee is best described in our [blockchain -paper](https://www.oasislabs.com/whitepaper), but we provide this section here +details of each committee is best described in our [research +paper](https://www.oasis-protocol.org/researchpapers), but we provide this section here as a high level introduction. It should be noted that some aspects of the system are yet to be completed. So the testnet that you might deploy in the [Quick Start Guide](./quick-start.md) won't yet function as it is described here. From 19dd5a2b004add04b588b564365db7902bd7352e Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 09:06:23 -0800 Subject: [PATCH 09/14] Update src/operators/architectural-overview.md --- src/operators/architectural-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index cc63070f..536fb508 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -33,7 +33,7 @@ Architecture](#modular-architecture) section. ## Modular Architecture The Oasis Network uses a modular architecture similar to that of a Service -Oriented Archiecture or a Microservices Architecture. Any given Node +Oriented Architecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis Network. The responsibilities of these committees can be mapped to a set of 4 From 7e3f1a6124dfdaeef14f5eaa1b7de652d835d577 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 09:07:11 -0800 Subject: [PATCH 10/14] Update src/operators/maintenance/wiping-node-state.md --- src/operators/maintenance/wiping-node-state.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/operators/maintenance/wiping-node-state.md b/src/operators/maintenance/wiping-node-state.md index 97772301..2ac88c88 100644 --- a/src/operators/maintenance/wiping-node-state.md +++ b/src/operators/maintenance/wiping-node-state.md @@ -1,4 +1,4 @@ -# Wiping node state +# Wiping Node State In some cases you might want (or need) to do a full redeploy with clean state before deploying a new version of the network. This should never actually be From 9638b3ddd0107c18cd012a569ee320eaacfba276 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 09:21:25 -0800 Subject: [PATCH 11/14] Consistent headings --- src/operators/joining-the-testnet.md | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index c56f2033..0055ae95 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -20,12 +20,12 @@ The reason for this is to ensure protection of the keys used to setup your node. This guide does not include the use of HSMs, but should be used in the future. -## Creating your entity +## Creating Your Entity Everything in this section should be done on the `localhost` as there are sensitive items that will be created. -### Creating a working directory +### Creating a Working Directory During this entity initialization process, we will create keys and other important artifacts that are necessary for the deployment of nodes on the @@ -50,7 +50,7 @@ To create the directory structure, use the following command: $ mkdir -m700 -p {entity,node} ``` -### Copy the genesis file +### Copying the Genesis File The latest genesis file can be found [here](./current-testnet-parameters.md). You should download the latest `genesis.json` file, copy it to the working @@ -125,7 +125,7 @@ The command will generate the following files: * `tls_identity.pem` - The node's TLS key for grpc's TLS . **DO NOT SHARE** * `tls_identity_cert.pem` - The node's TLS cert for grpc's TLS. -#### Add the node to the Entity descriptor +#### 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. @@ -141,7 +141,7 @@ $ oasis-node registry entity update \ This will update the entity descriptor `entity.json` and subsequently the `entity_genesis.json` file that contains the signed entity descriptor payload. -#### Initializing additional nodes +#### Initializing Additional Nodes At the time of Public Testnet, the network will only have validators and no other committees (no compute, no key management, no storage, etc.). At this time @@ -153,13 +153,13 @@ defined minimum staking amount (at this time this is 100 tokens). ## Running an Oasis Node on the `server` -### Setting up the Oasis Node's working directory +### 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. For this guide, we will call this working directory `/serverdir` directory. -#### Setting up the the `/serverdir` directory +#### Setting up the the `/serverdir` Directory In the `/serverdir` directory we will create the following subdirectories: @@ -173,7 +173,7 @@ You can make this directory structure by calling the following command: $ mkdir -p /serverdir/{etc,node/entity} ``` -#### Copy the Node artifacts from `/localhostdir` +#### 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 @@ -194,13 +194,13 @@ _You may notice that some of these files were listed as **DO NOT SHARE**. In the future these keys should be generated and referenced from HSM. Before we have HSM support, these keys should be kept as secure as possible on the `server`. -#### Copy the public Entity artifacts from `/localhostdir` +#### Copying the Public Entity Artifacts from `/localhostdir` We will also need to have public entity artifacts from the `/localhostdir`. Copy the file from `/localhostdir/entity/entity.json` to `/serverdir/node/entity/entity.json`. -#### Copy the genesis files +#### Copying the Genesis Files The latest genesis files can be found [here](./current-testnet-parameters.md). You should download the latest `genesis.json` file and copy it to @@ -351,7 +351,7 @@ foreground. You will need to use a process supervisor like $ oasis-node --config /serverdir/etc/config.yml ``` -### Verifying the connection to the network +### 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 @@ -410,7 +410,7 @@ _This won't be necessary if your Entity is in the genesis file._ Once you have been funded, you can now complete the process of connecting your node by staking so that you can register your entity and register your node. -### Generate a Staking (Escrow) transaction on the `localhost` +### Generating a Staking (Escrow) Transaction on the `localhost` Your Entity private key should ideally be disconnected from the internet on the `localhost`. You want this because the Entity private key is used to authorize @@ -454,7 +454,7 @@ Note that the option `--stake.transaction.amount` looks like a very large number. This is actually equivalent to 100 tokens on the Testnet as each unit value used to track the account balance is 1x10^-18 tokens. -### Submitting your transaction on the `server` +### Submitting Your Transaction on the `server` To complete the staking process we need to submit your escrow transaction: @@ -478,14 +478,14 @@ To complete the staking process we need to submit your escrow transaction: -a /serverdir/node/internal.sock ``` -### Registering you entity +### Registering Your Entity As a final step, you now need to register your entity onto the network. **TEMPORARY FIX**: At this time many of these instructions are a temporary fix due to missing features on the current `oasis-node` cli. -#### Port Forward +#### Port Forwarding On one instance of a terminal on the `localhost` execute the following to handle a port forwarding so you can make entity requests. _Unfortunately, if you're @@ -497,7 +497,7 @@ temporary measure._ $ ssh $USER@$SERVER_IP -L 42261:127.0.0.1:42261 -N ``` -#### Register your node onto the network +#### Registering Your Node on the Network On a different terminal from your ssh port forward above, execute the following: @@ -507,7 +507,7 @@ $ oasis-node registry entity register --datadir /localhostdir/entity If everything is successful you will get a zero exit code. -### Checking that your node is properly registered +### Checking that Your Node is Properly Registered _We understand these instructions for verification need to improve. Any assistance is welcome ;)_ @@ -516,7 +516,7 @@ To ensure that your node is properly connected as a Validator on the network, We can check to see the node's identity on in the registry's node list. Unfortunately, at this time this is a bit of a manual process. -### Get the node's consensus_pub.pem identity +### Getting the Node's consensus_pub.pem Identity ``` cat /serverdir/node/consensus_pub.pem @@ -532,7 +532,7 @@ s+vZ71qeZnlq0HmQSDBiWn2OKcy3fXOuPMu76/5GkUI= We will use `s+vZ71qeZnlq0HmQSDBiWn2OKcy3fXOuPMu76/5GkUI=`. As the key to search for. -### grep for the node's identity +### grepping for the Node's Identity Finally to see if the node is properly registered, run the command (you may need to be in a docker container if you are using that): From f0f67378becaa11515cc554f8ed4dc96b3ac8d4e Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 09:27:17 -0800 Subject: [PATCH 12/14] Consistent capitalization --- src/operators/joining-the-testnet.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index 0055ae95..39aaa9a9 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -1,6 +1,6 @@ # Joining the Testnet -This guide will cover setting up your nodes on the public testnet. There is some +This guide will cover setting up your nodes on the Public Testnet. There is some assumption of knowledge on the use of basic command line tools and docker. ## Prerequisites @@ -69,7 +69,7 @@ operating nodes on the network as it controls the stake attached to a given individual or organization on the network. In the future we will support using entity keys through HSMs to ensure that entity keys cannot be easily compromised. We strongly suggest that you do not use any entity that is generated -with the current process on the Mainnet. During the public testnet and staking +with the current process on the Mainnet. During the Public Testnet and staking competition we would also suggest that you generate the entity on a system that has no network connection to provide rudimentary protection for the entity key. However, it is up to you to determine your own security practices. @@ -547,7 +547,7 @@ If `grep` found the key, then you're properly connected! ## You're a Validator! If you've made it this far you've properly connected your node to the network -and you're now a Validator on the public testnet. +and you're now a Validator on the Public Testnet. ### Maintenance Guides From d0853bcf4b8db34a14234dfb40a052c6c46ee9b8 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 09:48:59 -0800 Subject: [PATCH 13/14] Nits --- src/operators/architectural-overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/operators/architectural-overview.md b/src/operators/architectural-overview.md index 536fb508..0a4f0045 100644 --- a/src/operators/architectural-overview.md +++ b/src/operators/architectural-overview.md @@ -36,7 +36,7 @@ The Oasis Network uses a modular architecture similar to that of a Service Oriented Architecture or a Microservices Architecture. Any given Node participates in one of many different committees. These committees each have different responsibilities in the execution of smart contracts on the Oasis -Network. The responsibilities of these committees can be mapped to a set of 4 +Network. The responsibilities of these committees can be mapped to a set of four different layers: Consensus, Compute (Confidential and Non-confidential), Storage, and Key Management. For a Node Operator, these layers map distinctly to different classes Nodes and potentially to different hardware. @@ -71,13 +71,13 @@ will assign it a single job during a given lifetime. #### Consensus Committee -The Consensus Committee is the BFT consensus layer. It's primary function during +The Consensus Committee is the BFT consensus layer. Its primary function during transaction processing is to reach consensus on the final state of the application that it receives from the Compute layer. ## Networking Protocols -The Oasis Network uses 3 different protocols for communication: +The Oasis Network uses three different protocols for communication: * [Tendermint](https://github.com/tendermint/tendermint) * [grpc](https://grpc.io/) From 25388c963f145a4b69b05d0b29d0fc8ab8fbc4f9 Mon Sep 17 00:00:00 2001 From: Peter Gilbert Date: Wed, 13 Nov 2019 10:00:11 -0800 Subject: [PATCH 14/14] Nits --- src/operators/joining-the-testnet.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/operators/joining-the-testnet.md b/src/operators/joining-the-testnet.md index 39aaa9a9..2e9439a6 100644 --- a/src/operators/joining-the-testnet.md +++ b/src/operators/joining-the-testnet.md @@ -389,7 +389,7 @@ JSON file, the Entity Public Key is the `id` field. ### Example -In the following example `entity.json`, the Entity Public key is +In the following example `entity.json`, the Entity Public Key is `TszGIrC1X08czcik0DgAnmGPzjf8pfQ47bgrjpTmbro=`. ```json @@ -471,7 +471,8 @@ To complete the staking process we need to submit your escrow transaction: -a /serverdir/node/internal.sock ``` - Without docker + Without docker: + ``` $ oasis-node stake account submit \ --stake.transaction.file /serverdir/signed-escrow.tx \