diff --git a/docs/concepts/nodes.md b/docs/concepts/nodes.md new file mode 100644 index 00000000000..7cab46b742a --- /dev/null +++ b/docs/concepts/nodes.md @@ -0,0 +1,55 @@ +--- +id: nodes +title: Nodes +sidebar_label: Nodes +--- + +## What is a node? + +NEAR Protocol runs on a collection of publicly maintained computers or "nodes". All nodes on a network perform and validate transactions, but differ in their ability to produce blocks. + +## Node types + +For simplicities sake, NEAR has two main types of nodes: + - Producing nodes (aka "validator nodes") + - Non-producing nodes (aka "regular nodes") + +### Non-producing node ("regular node") + +Anyone can run a "regular node" by following one of the methods mentioned in [this guide](/docs/local-setup/running-a-node). + +You may decide to run a node of your own for a few reasons: + + - To view, process, and validate transactions on `MainNet`, `TestNet` or `BetaNet` (†) + - To view, process, and validate transactions on an independent / isolated local NEAR network (sometimes called "LocalNet"). (††) + - To join `BetaNet` or `MainNet` as a producing node, aka "Validator Node" (see "[Running a Validator Node](/docs/validator/staking)") + + _( † ) `TestNet` is intended to operate as similarly to `MainNet` as possible with only stable releases, while `BetaNet` follows a weekly release cycle._ + +_( †† ) `LocalNet` would be the right choice if you prefer to avoid leaking information about your work during the development process since `TestNet` and `BetaNet` are *public* networks. `LocalNet` also gives you total control over accounts, economics, and other factors for more advanced use cases (i.e. making changes to `nearcore`)._ + + +### Producing node ("validator node") + +Producing nodes, also referred to as "[Validator Nodes](/docs/validator/staking-overview)" contribute to the network by producing blocks or chunks. + +To run a producing node, you must have a validator key and be included among the set of block producers. After each [epoch](/docs/concepts/epoch), "validator nodes" are shuffled and randomly selected for the next epoch. + +See "[How do I become a validator](/docs/validator/validator-faq#how-do-i-become-a-validator)" and [validator selection process](https://nomicon.io/Economics/README.html?validator-selection#validator-selection) for more information. + +
+Note

+ +Non-producing nodes still validate every block and are very important to the network. This network of nodes, that view all transactions taking place, help us to be certain that the chain is correct and no invalid state transitions / forks are occurring. + +
+ +### Archival vs. Non-archival nodes + +Both producing ("validator") and non-producing ("regular") nodes can be configured to be either archival or non-archival. All nodes are non-archival by default, but you can easily set your node to archival by updating your `config.json` changing `archive` to `true`. + +Its important to note that: + + - Archival nodes store all data, from genesis to present. Anytime a new archival node is created, it begins by first syncing all data from genesis to current, then begins to record all future transactions. + + - Non-archival nodes will do a state sync to a recent point, and will only validate from that point forward. They will continue to maintain a recent set of blocks locally, discarding older ones as the chain grows in height. diff --git a/docs/local-setup/running-testnet.md b/docs/local-setup/running-a-node.md similarity index 54% rename from docs/local-setup/running-testnet.md rename to docs/local-setup/running-a-node.md index cdbddc634cf..58e2ecb18f1 100644 --- a/docs/local-setup/running-testnet.md +++ b/docs/local-setup/running-a-node.md @@ -1,68 +1,64 @@ --- -id: running-testnet +id: running-a-node title: Running a node sidebar_label: Running a node --- -## Why? +## Running a node using `nearcore` -NEAR Protocol runs on a collection of publicly maintained computers (or "nodes"). +1) If you haven't already, you will need to clone [`nearcore`](https://github.com/nearprotocol/nearcore) as well as compile and run the `neard` package using Rust. Please reference [this guide](https://docs.near.org/docs/contribution/nearcore#docsNav) for assistance. -You may decide to run a node of your own for a few reasons: +2) Download the genesis file: + - TestNet [`genesis.json`](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/testnet/genesis.json) + - BetaNet [`genesis.json`](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/betanet/genesis.json) + - MainNet does not require you to download the `genesis.json` file as it is embedded into `nearcore` -- To develop and deploy contracts on a node connected to `MainNet`, `TestNet` or `BetaNet` (†) -- To develop and deploy contracts on a local (independent and isolated) node (sometimes called "LocalNet"). (††) -- To join a network as a validator running a "validator node" (see [staking](/docs/validator/staking)) +3) Download the config file: + - TestNet [`config.json`](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/testnet/config.json) + - BetaNet [`config.json`](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/betanet/config.json) + - MainNet [`config.json`](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/config.json) -_( † ) `TestNet` is intended to operate as closely (similarly) to `MainNet` as possible with only stable releases while `BetaNet` follows a weekly release cycle._ +4) Run the following command replacing the paths & networkId: + ```bash + neard --home= init --chain-id= --genesis= + ``` + example: + ```bash + neard --home=/HOME/USER/near/my-near-node init --chain-id=testnet --genesis=/HOME/USER/near/genesis.json + ``` -_( †† ) `LocalNet` would be the right choice if you prefer to avoid leaking information about your work during the development process since `TestNet` and `BetaNet` are *public* networks. `LocalNet` also gives you total control over accounts, economics and other factors for more advanced use cases (ie. making changes to `nearcore`)._ +5) Either copy the downloaded `config.js` file to the home location chosen above, or only copy paste the `boot_nodes` from the downloaded `config.js` file to the one created by the `neard init`. -## `nearup` Installation +6) Run: + ```bash + neard --home= run + ``` -You can install `nearup` by following the instructions at https://github.com/near/nearup. - -
-heads up

- -The README for `nearup` (linked above) may be **all you need to get a node running**. - -This page is made available to clarify a few points of confusion along the way for those who need it. +## Running a node using `nearup` and Docker +**Note**: The following guides are only for `betanet` and `testnet`. -
- -The steps in the rest of this document will require `nearup` - - -## Running an Official Node using Docker +### Install `nearup` +You can install `nearup` by following the instructions at https://github.com/near/nearup. ### Install Docker -By default we use Docker to run the client. +By default, we use Docker to run the client. Follow these instructions to install Docker on your machine: -Follow these instructions to install Docker on your machine: +* [MacOS Docker Install](https://docs.docker.com/docker-for-mac/install/) +* [Ubuntu Docker Install](https://docs.docker.com/install/linux/docker-ce/ubuntu/) -* [MacOS](https://docs.docker.com/docker-for-mac/install/) -* [Ubuntu](https://docs.docker.com/install/linux/docker-ce/ubuntu/) - -NOTE: You can run a node without Docker by adding the `--nodocker` flag to the `nearup` command and specifying the compiled binary path. See how to do this in the next section: [Compiling and Running an Official Node without Docker](/docs/local-setup/running-testnet#compiling-and-running-official-node-testnetbetanet-without-docker). +**Note**: You can run a node without Docker by adding the `--nodocker` flag to the `nearup` command and specifying the compiled binary path. See how to do this in the next section: [Compiling and Running an Official Node without Docker](/docs/local-setup/running-a-node#compiling-and-running-official-node-without-docker). ### Running `nearup` -Once `nearup` and Docker are installed (by following instructions in previous section), just run: - -```sh -nearup betanet -``` +Once `nearup` and Docker are installed, run either `nearup testnet` or `nearup betanet` in your terminal, depending on your preferred network. -_(If you prefer to use `TestNet` then just replace `betanet` with `testnet` in the command above)_ - -You will then be prompted for an Account ID. You can leave this empty if you would just like to run a node. Validators should use the account ID of the account you want to stake with. See [staking](/docs/validator/staking) if you would like to become a validator. +You will then be prompted for an Account ID. You can leave this empty if you would just like to run a regular node. Validators should use the account ID of the account you want to stake with. See [staking](/docs/validator/staking) if you would like to become a validator. ```text -Enter your account ID (leave empty if not going to be a validator): +Enter your account ID: (leave empty if not going to be a validator) ``` A node will then start in the background with Docker. @@ -79,8 +75,7 @@ To check the logs inside Docker, run `docker logs --follow nearcore`. | `0/0/40` | connected peers / up to date peers / max peers | - -## Compiling and Running Official Node without Docker +## Compiling and running a node without Docker Alternatively, you can build and run a node without Docker by compiling `nearcore` locally and pointing `nearup` to the compiled binaries. Steps in this section provide details of how to do this. @@ -125,13 +120,13 @@ If you are running a validator in production you may find it more efficient to j cargo build -p neard --release ``` -NB. Please ensure you include the `--release` flag. Omitting this will lead to an unoptimized binary being produced that is too slow for a validator to function effectively. +**Note**: Please ensure you include the `--release` flag. Omitting this will lead to an unoptimized binary being produced that is too slow for a validator to function effectively. Finally: On MacOS or Linux ```bash -nearup betanet --nodocker --binary-path path/to/nearcore/target/release +nearup betanet --nodocker --binary-path ``` If you want to run `TestNet` instead of `BetaNet` then replace `betanet` with `testnet` in the command above. diff --git a/docs/overview/basics-orientation.md b/docs/overview/basics-orientation.md index 9800658183a..51109914f12 100644 --- a/docs/overview/basics-orientation.md +++ b/docs/overview/basics-orientation.md @@ -11,7 +11,7 @@ If you are ready to dive straight into application and smart contract developmen If you are **not** an app developer, we recommend the following paths instead: 1. **For the non-technical person or NEAR noob,** see the [Beginner's Guide to NEAR](https://near.org/blog/the-beginners-guide-to-the-near-blockchain/). For a slightly more technical introduction, begin with [What is NEAR?](/docs/overview/what-is-near). -2. **To run a validating node,** which means taking part in the operation of the core network itself, see [running a testnet node](/docs/local-setup/running-testnet) or, for a full staking overview, see [the staking overview](/docs/validator/staking-overview). This is not necessary for developing smart contracts or apps but it can be a good way to feel connected to the "bare metal" of how the network works. +2. **To run a validating node,** which means taking part in the operation of the core network itself, see [running a testnet node](/docs/local-setup/running-a-node) or, for a full staking overview, see [the staking overview](/docs/validator/staking-overview). This is not necessary for developing smart contracts or apps but it can be a good way to feel connected to the "bare metal" of how the network works. 3. **To integrate with NEAR,** for example if you are running an exchange, a wallet, or other project that needs to integrate on a deeper level, please see [integrating with NEAR](/docs/roles/integrator/integrating). 4. **To contribute to the core code base yourself,** see [contributing to NEAR](/docs/contribution/contribution-overview). To suggest changes to these docs, [view them on Github](https://github.com/near/docs) or just click the "Edit" button in the top to get started submitting your pull request. diff --git a/docs/roles/integrator/exchange-integration.md b/docs/roles/integrator/exchange-integration.md index 7a0db46c6ea..b212c1355e0 100644 --- a/docs/roles/integrator/exchange-integration.md +++ b/docs/roles/integrator/exchange-integration.md @@ -488,7 +488,7 @@ The rest two are refunds. - See [Blockchain Finality](/docs/roles/integrator/integrating#finality) for more information. ## Running an Archival Node -- Setting up an archival node is the same as a [regular node](https://docs.near.org/docs/local-setup/running-testnet), but modifying your `config.json` by changing `archive` to `true`. +- Setting up an archival node is the same as a [regular node](/docs/local-setup/running-a-node), but modifying your `config.json` by changing `archive` to `true`. ## Staking and Delegation - [https://github.com/nearprotocol/stakewars](https://github.com/nearprotocol/stakewars) diff --git a/docs/roles/integrator/integrating.md b/docs/roles/integrator/integrating.md index 38771e3d4bb..0ec3b45ffb0 100644 --- a/docs/roles/integrator/integrating.md +++ b/docs/roles/integrator/integrating.md @@ -25,7 +25,7 @@ The Near team recommends that custody wallets and exchanges track all shards to ### Server Setup -Please see [hardware requirements](/docs/roles/validator/hardware) and details of how to [run a NEAR node](/docs/local-setup/running-testnet). +Please see [hardware requirements](/docs/roles/validator/hardware) and details of how to [run a NEAR node](/docs/local-setup/running-a-node). ## Blockchain diff --git a/docs/validator/validator-faq.md b/docs/validator/validator-faq.md index 5778598101a..ddb107ad8cf 100644 --- a/docs/validator/validator-faq.md +++ b/docs/validator/validator-faq.md @@ -19,7 +19,7 @@ The collection of transactions for the shard is called a chunk. Once a chunk and ### How do I become a validator? You need an account with sufficient amount of funds. -Follow the docs [here](/docs/validator/staking) to understand how to become a validator, and [here](/docs/local-setup/running-testnet) to run a node. +Follow the docs [here](/docs/validator/staking) to understand how to become a validator, and [here](/docs/local-setup/running-a-node) to run a node. More specific steps: 1. Create a new key pair that will be used for staking for given account, and load it with the funds you want to put at stake @@ -72,7 +72,7 @@ Large validators will have to generate blocks signing across multiple shards, th ### How do I run a node? -Follow [this tutorial.](local-setup/running-testnet.md) +Follow [this tutorial.](local-setup/running-a-node.md) ### Do validators receive incentives for testing the protocol? diff --git a/website/sidebars.json b/website/sidebars.json index d52b130a668..7d422eab4df 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -11,6 +11,7 @@ "Key Concepts": [ "concepts/overview", "concepts/account", + "concepts/nodes", "concepts/epoch", "concepts/storage", "concepts/gas", @@ -93,9 +94,10 @@ } ], "Machine Setup": [ + "local-setup/running-a-node", "local-setup/local-dev-testnet", - "local-setup/local-dev-node", - "local-setup/running-testnet" + "local-setup/local-dev-node" + ], "FAQ": [ "roles/developer/faq"