diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index c9d0186b3c..5e9f75bbea 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,8 +6,7 @@ - [Getting Started](getting-started.md) - [Testnet Participation](testnet-participation.md) - - [Testnet Replicator](testnet-replicator.md) - - [Example: Web Wallet](webwallet.md) + - [Example Client: Web Wallet](webwallet.md) - [Programming Model](programs.md) - [Example: Tic-Tac-Toe](tictactoe.md) @@ -30,9 +29,22 @@ - [Blocktree](blocktree.md) - [Gossip Service](gossip.md) - [The Runtime](runtime.md) - + - [Anatomy of a Transaction](transaction.md) +- [Running a Validator](running-validator.md) + - [Hardware Requirements](validator-hardware.md) + - [Choosing a Testnet](validator-testnet.md) + - [Installing the Validator Software](validator-software.md) + - [Starting a Validator](validator-start.md) + - [Staking](validator-stake.md) + - [Monitoring a Validator](validator-monitor.md) + - [Publishing Validator Info](validator-info.md) + - [Troubleshooting](validator-troubleshoot.md) + - [FAQ](validator-faq.md) + +- [Running a Replicator](running-replicator.md) + - [API Reference](api-reference.md) - [Transaction](transaction-api.md) - [Instruction](instruction-api.md) @@ -73,7 +85,7 @@ - [Passive Stake Delegation and Rewards](passive-stake-delegation-and-rewards.md) - [Persistent Account Storage](persistent-account-storage.md) - [Reliable Vote Transmission](reliable-vote-transmission.md) - - [Repair Service](repair-service.md) + - [Repair Service](repair-service.md) - [Testing Programs](testing-programs.md) - [Credit-only Accounts](credit-only-credit-debit-accounts.md) - [Embedding the Move Langauge](embedding-move.md) diff --git a/book/src/testnet-replicator.md b/book/src/running-replicator.md similarity index 99% rename from book/src/testnet-replicator.md rename to book/src/running-replicator.md index d8a55446bb..2cd2bbaa69 100644 --- a/book/src/testnet-replicator.md +++ b/book/src/running-replicator.md @@ -1,4 +1,4 @@ -## Testnet Replicator +## Running a Replicator This document describes how to setup a replicator in the testnet Please note some of the information and instructions described here may change diff --git a/book/src/running-validator.md b/book/src/running-validator.md new file mode 100644 index 0000000000..93b7ff48c5 --- /dev/null +++ b/book/src/running-validator.md @@ -0,0 +1,35 @@ +# Running a Validator +This document describes how to participate in the Solana testnet as a +validator node. + +Please note some of the information and instructions described here may change +in future releases, and documentation will be updated for mainnet participation. + +## Overview +Solana currently maintains several testnets, each featuring a validator that can +serve as the entrypoint to the cluster for your validator. + +Current testnet entrypoints: +- Stable, testnet.solana.com +- Beta, beta.testnet.solana.com +- Edge, edge.testnet.solana.com + +Solana may launch special testnets for validator participation; we will provide +you with a specific entrypoint URL to use. + +Prior to mainnet, the testnets may be running different versions of solana +software, which may feature breaking changes. For information on choosing a +testnet and finding software version info, jump to +[Choosing a Testnet](validator-testnet.md). + +The testnets are configured to reset the ledger daily, or sooner, +should the hourly automated cluster sanity test fail. + +There is a network explorer that shows the status of solana testnets available +at [http://explorer.solana.com/](https://explorer.solana.com/). + +There is a **#validator-support** Discord channel available to reach other +testnet participants, [https://discord.gg/pquxPsq](https://discord.gg/pquxPsq). + +Also we'd love it if you choose to register your validator node with us at +[https://forms.gle/LfFscZqJELbuUP139](https://forms.gle/LfFscZqJELbuUP139). diff --git a/book/src/testnet-participation.md b/book/src/testnet-participation.md index 510f431c20..1ca4ba3af6 100644 --- a/book/src/testnet-participation.md +++ b/book/src/testnet-participation.md @@ -1,349 +1,5 @@ ## Testnet Participation -This document describes how to participate in the testnet as a -validator node. - -Please note some of the information and instructions described here may change -in future releases. - -### Overview -The testnet features a validator running at testnet.solana.com, which -serves as the entrypoint to the cluster for your validator. - -Additionally there is a blockexplorer available at -[http://testnet.solana.com/](http://testnet.solana.com/). - -The testnet is configured to reset the ledger daily, or sooner -should the hourly automated cluster sanity test fail. - -There is a **#validator-support** Discord channel available to reach other -testnet participants, [https://discord.gg/pquxPsq](https://discord.gg/pquxPsq). - -Also we'd love it if you choose to register your validator node with us at -[https://forms.gle/LfFscZqJELbuUP139](https://forms.gle/LfFscZqJELbuUP139). - -### Machine Requirements -Since the testnet is not intended for stress testing of max transaction -throughput, a higher-end machine with a GPU is not necessary to participate. - -However ensure the machine used is not behind a residential NAT to avoid NAT -traversal issues. A cloud-hosted machine works best. **Ensure that IP ports -8000 through 10000 are not blocked for Internet inbound and outbound traffic.** - -Prebuilt binaries are available for Linux x86_64 (Ubuntu 18.04 recommended). -MacOS or WSL users may build from source. - -For a performance testnet with many transactions we have some preliminary recommended setups: - -| | Low end | Medium end | High end | Notes | -| --- | ---------|------------|----------| -- | -| CPU | AMD Threadripper 1900x | AMD Threadripper 2920x | AMD Threadripper 2950x | Consider a 10Gb-capable motherboard with as many PCIe lanes and m.2 slots as possible. | -| RAM | 16GB | 32GB | 64GB | | -| OS Drive | Samsung 860 Evo 2TB | Samsung 860 Evo 4TB | Samsung 860 Evo 4TB | Or equivalent SSD | -| Accounts Drive(s) | None | Samsung 970 Pro 1TB | 2x Samsung 970 Pro 1TB | | -| GPU | 4x Nvidia 1070 or 2x Nvidia 1080 Ti or 2x Nvidia 2070 | 2x Nvidia 2080 Ti | 4x Nvidia 2080 Ti | Any number of cuda-capable GPUs are supported on Linux platforms. | - -#### GPU Requirements -CUDA is required to make use of the GPU on your system. The provided Solana -release binaries are built on Ubuntu 18.04 with CUDA Toolkit 10.1 -update 1". If your machine is using a different CUDA version then you will -need to rebuild from source. - -#### Confirm The Testnet Is Reachable -Before attaching a validator node, sanity check that the cluster is accessible -to your machine by running some simple commands. If any of the commands fail, -please retry 5-10 minutes later to confirm the testnet is not just restarting -itself before debugging further. - -Fetch the current transaction count over JSON RPC: -```bash -$ curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1, "method":"getTransactionCount"}' http://testnet.solana.com:8899 -``` - -Inspect the blockexplorer at [http://testnet.solana.com/](http://testnet.solana.com/) for activity. - -View the [metrics dashboard]( -https://metrics.solana.com:3000/d/testnet-beta/testnet-monitor-beta?var-testnet=testnet) -for more detail on cluster activity. - -### Validator Setup -#### Obtaining The Software -##### Bootstrap with `solana-install` - -The `solana-install` tool can be used to easily install and upgrade the cluster -software on Linux x86_64 and mac OS systems. - -```bash -$ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v0.16.5/install/solana-install-init.sh | sh -s -``` - -Alternatively build the `solana-install` program from source and run the -following command to obtain the same result: -```bash -$ solana-install init -``` - -After a successful install, `solana-install update` may be used to easily update the cluster -software to a newer version at any time. - -##### Download Prebuilt Binaries -If you would rather not use `solana-install` to manage the install, you can manually download and install the binaries. - -###### Linux -Download the binaries by navigating to -[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), -download **solana-release-x86_64-unknown-linux-gnu.tar.bz2**, then extract the -archive: -```bash -$ tar jxf solana-release-x86_64-unknown-linux-gnu.tar.bz2 -$ cd solana-release/ -$ export PATH=$PWD/bin:$PATH -``` -###### mac OS -Download the binaries by navigating to -[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), -download **solana-release-x86_64-apple-darwin.tar.bz2**, then extract the -archive: -```bash -$ tar jxf solana-release-x86_64-apple-darwin.tar.bz2 -$ cd solana-release/ -$ export PATH=$PWD/bin:$PATH -``` - -##### Build From Source -If you are unable to use the prebuilt binaries or prefer to build it yourself -from source, navigate to -[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), -and download the **Source Code** archive. Extract the code and build the -binaries with: -```bash -$ ./scripts/cargo-install-all.sh . -$ export PATH=$PWD/bin:$PATH -``` - -If building for CUDA (Linux only), fetch the perf-libs first then include the -`cuda` feature flag when building: -```bash -$ ./fetch-perf-libs.sh -$ source ./target/perf-libs/env.sh -$ ./scripts/cargo-install-all.sh . cuda -$ export PATH=$PWD/bin:$PATH -``` - -### Starting The Validator -Sanity check that you are able to interact with the cluster by receiving a small -airdrop of lamports from the testnet drone: -```bash -$ solana-wallet airdrop 123 -$ solana-wallet balance -``` - -Also try running following command to join the gossip network and view all the other nodes in the cluster: -```bash -$ solana-gossip --entrypoint testnet.solana.com:8001 spy -# Press ^C to exit -``` - -Now create an identity keypair for your validator by running: -```bash -$ solana-keygen new -o ~/validator-keypair.json -``` -and airdrop yourself some lamports to get started: -```bash -$ solana-wallet --keypair ~/validator-keypair.json airdrop 1000 -``` - -Your validator will need a vote account. Create it now with the following -commands: -```bash -$ solana-keygen new -o ~/validator-vote-keypair.json -$ VOTE_PUBKEY=$(solana-keygen pubkey ~/validator-vote-keypair.json) -$ IDENTITY_PUBKEY=$(solana-keygen pubkey ~/validator-keypair.json) -$ solana-wallet create-vote-account "$VOTE_PUBKEY" "$IDENTITY_PUBKEY" 1 -``` - - -Then use one of the following commands, depending on your installation -choice, to start the node: - -If this is a `solana-install`-installation: -```bash -$ validator.sh --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --ledger ~/validator-config --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com -``` - -Alternatively, the `solana-install run` command can be used to run the validator -node while periodically checking for and applying software updates: -```bash -$ solana-install run validator.sh -- --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --ledger ~/validator-config --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com -``` - -If you built from source: -```bash -$ NDEBUG=1 USE_INSTALL=1 ./multinode-demo/validator.sh --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com -``` - -#### Enabling CUDA -By default CUDA is disabled. If your machine has a GPU with CUDA installed, -define the SOLANA_CUDA flag in your environment *before* running any of the -previusly mentioned commands -```bash -$ export SOLANA_CUDA=1 -``` - -When your validator is started look for the following log message to indicate that CUDA is enabled: -`"[ solana::validator] CUDA is enabled"` - -#### Controlling local network port allocation -By default the validator will dynamically select available network ports in the -8000-10000 range, and may be overridden with `--dynamic-port-range`. For -example, `validator.sh --dynamic-port-range 11000-11010 ...` will restrict the -validator to ports 11000-11011. - -#### Limiting ledger size to conserve disk space -By default the validator will retain the full ledger. To conserve disk space -start the validator with the `--limit-ledger-size`, which will instruct the -validator to only retain the last couple hours of ledger. - -### Validator Monitoring -When `validator.sh` starts, it will output a validator configuration that looks -similar to: -```bash -======================[ validator configuration ]====================== -identity pubkey: 4ceWXsL3UJvn7NYZiRkw7NsryMpviaKBDYr8GK7J61Dm -vote pubkey: 2ozWvfaXQd1X6uKh8jERoRGApDqSqcEy6fF1oN13LL2G -ledger: ... -accounts: ... -====================================================================== -``` - -The **identity pubkey** for your validator can also be found by running: -```bash -$ solana-keygen pubkey ~/validator-keypair.json -``` - -From another console, confirm the IP address and **identity pubkey** of your validator is visible in the -gossip network by running: -```bash -$ solana-gossip --entrypoint testnet.solana.com:8001 spy -``` - -Provide the **vote pubkey** to the `solana-wallet show-vote-account` command to view -the recent voting activity from your validator: -```bash -$ solana-wallet show-vote-account 2ozWvfaXQd1X6uKh8jERoRGApDqSqcEy6fF1oN13LL2G -``` - -The vote pubkey for the validator can also be found by running: -```bash -$ solana-keygen pubkey ~/validator-vote-keypair.json -``` - -#### Has my validator caught up? -After your validator boots, it may take some time to catch up with the cluster. -Use the `get-slot` wallet command to view the current slot that the cluster is -processing: -```bash -$ solana-wallet get-slot -``` - -The current slot that your validator is processing can then been seen with: -```bash -$ solana-wallet --url http://127.0.0.1:8899 get-slot -``` - -Until your validator has caught up, it will not be able to vote successfully and -stake cannot be delegated to it. - -Also if you find the cluster's slot advancing faster than yours, you will likely -never catch up. This typically implies some kind of networking issue between -your validator and the rest of the cluster. - -#### Validator Metrics -Metrics are available for local monitoring of your validator. - -Docker must be installed and the current user added to the docker group. Then -download `solana-metrics.tar.bz2` from the Github Release and run -```bash -$ tar jxf solana-metrics.tar.bz2 -$ cd solana-metrics/ -$ ./start.sh -``` - -A local InfluxDB and Grafana instance is now running on your machine. Define -`SOLANA_METRICS_CONFIG` in your environment as described at the end of the -`start.sh` output and restart your validator. - -Metrics should now be streaming and visible from your local Grafana dashboard. - -#### Timezone For Log Messages -Log messages emitted by your validator include a timestamp. When sharing logs -with others to help triage issues, that timestamp can cause confusion as it does -not contain timezone information. - -To make it easier to compare logs between different sources we request that -everybody use Pacific Time on their validator nodes. In Linux this can be -accomplished by running: -```bash -$ sudo ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime -``` - -#### Publishing Validator Info - -You can publish your validator information to the chain to be publicly visible -to other users. - -Run the solana-validator-info CLI to populate a validator-info account: -```bash -$ solana-validator-info publish ~/validator-keypair.json -``` -Optional fields for VALIDATOR_INFO_ARGS: -* Website -* Keybase Username -* Details - -##### Keybase - -Including a Keybase username allows client applications (like the Solana Network -Explorer) to automatically pull in your validator public profile, including -cryptographic proofs, brand identity, etc. To connect your validator pubkey with -Keybase: - -1. Join https://keybase.io/ and complete the profile for your validator -2. Add your validator **identity pubkey** to Keybase: - * Create an empty file on your local computer called `validator-` - * In Keybase, navigate to the Files section, and upload your pubkey file to - a `solana` subdirectory in your public folder: `/keybase/public//solana` - * To check your pubkey, ensure you can successfully browse to - `https://keybase.pub//solana/validator-` -3. Add or update your `solana-validator-info` with your Keybase username. The -CLI will verify the `validator-` file - -### Staking -When your validator starts it will have no stake, which means it will ineligible to become leader. - -Adding stake can be accomplished by using the `solana-wallet` command. First -obtain the public key for your validator's vote account with: -```bash -$ solana-keygen pubkey ~/validator-config/vote-keypair.json -``` -This will output a base58-encoded value that looks similar to -`DhUYZR98qFLLrnHg2HWeGhBQJ9tru7nwdEfYm8L8HdR9`. Then create a stake account -keypair with `solana-keygen`: -```bash -$ solana-keygen new -o ~/validator-config/stake-keypair.json -``` -and use the wallet's `delegate-stake` command to stake your validator with 42 lamports: -```bash -$ solana-wallet delegate-stake ~/validator-config/stake-keypair.json [VOTE PUBKEY] 42 -``` - -Note that stake changes are applied at Epoch boundaries so it can take an hour -or more for the change to take effect. - -Stake can be deactivate by running: -```bash -$ solana-wallet deactivate-stake ~/validator-config/stake-keypair.json -``` -Note that a stake account may only be used once, so after deactivation use the -wallet's `withdraw-stake` command to recover the previously staked lamports. +Participate in our testnet: + * [Running a Validator](running-validator.md) + * [Running a Replicator](running-replicator.md) diff --git a/book/src/validator-faq.md b/book/src/validator-faq.md new file mode 100644 index 0000000000..92b5189952 --- /dev/null +++ b/book/src/validator-faq.md @@ -0,0 +1,2 @@ +# Validator FAQ +Coming soon... diff --git a/book/src/validator-hardware.md b/book/src/validator-hardware.md new file mode 100644 index 0000000000..eca964f7f0 --- /dev/null +++ b/book/src/validator-hardware.md @@ -0,0 +1,28 @@ +# Validator Hardware Requirements +Since the testnet is not intended for stress testing of max transaction +throughput, a higher-end machine with a GPU is not necessary to participate. + +However ensure the machine used is not behind a residential NAT to avoid NAT +traversal issues. A cloud-hosted machine works best. **Ensure that IP ports +8000 through 10000 are not blocked for Internet inbound and outbound traffic.** + +Prebuilt binaries are available for Linux x86_64 (Ubuntu 18.04 recommended). +MacOS or WSL users may build from source. + +## Recommended Setups +For a performance testnet with many transactions we have some preliminary recommended setups: + +| | Low end | Medium end | High end | Notes | +| --- | ---------|------------|----------| -- | +| CPU | AMD Threadripper 1900x | AMD Threadripper 2920x | AMD Threadripper 2950x | Consider a 10Gb-capable motherboard with as many PCIe lanes and m.2 slots as possible. | +| RAM | 16GB | 32GB | 64GB | | +| OS Drive | Samsung 860 Evo 2TB | Samsung 860 Evo 4TB | Samsung 860 Evo 4TB | Or equivalent SSD | +| Accounts Drive(s) | None | Samsung 970 Pro 1TB | 2x Samsung 970 Pro 1TB | | +| GPU | 4x Nvidia 1070 or 2x Nvidia 1080 Ti or 2x Nvidia 2070 | 2x Nvidia 2080 Ti | 4x Nvidia 2080 Ti | Any number of cuda-capable GPUs are supported on Linux platforms. | + +## GPU Requirements +CUDA is required to make use of the GPU on your system. The provided Solana +release binaries are built on Ubuntu 18.04 with CUDA Toolkit 10.1 +update 1". If your machine is using a different CUDA version then you will +need to rebuild from source. diff --git a/book/src/validator-info.md b/book/src/validator-info.md new file mode 100644 index 0000000000..ccc6245681 --- /dev/null +++ b/book/src/validator-info.md @@ -0,0 +1,31 @@ +# Publishing Validator Info + +You can publish your validator information to the chain to be publicly visible +to other users. + +## Run solana-validator-info +Run the solana-validator-info CLI to populate a validator-info account: +```bash +$ solana-validator-info publish ~/validator-keypair.json +``` +Optional fields for VALIDATOR_INFO_ARGS: +* Website +* Keybase Username +* Details + +## Keybase + +Including a Keybase username allows client applications (like the Solana Network +Explorer) to automatically pull in your validator public profile, including +cryptographic proofs, brand identity, etc. To connect your validator pubkey with +Keybase: + +1. Join https://keybase.io/ and complete the profile for your validator +2. Add your validator **identity pubkey** to Keybase: + * Create an empty file on your local computer called `validator-` + * In Keybase, navigate to the Files section, and upload your pubkey file to + a `solana` subdirectory in your public folder: `/keybase/public//solana` + * To check your pubkey, ensure you can successfully browse to + `https://keybase.pub//solana/validator-` +3. Add or update your `solana-validator-info` with your Keybase username. The +CLI will verify the `validator-` file diff --git a/book/src/validator-monitor.md b/book/src/validator-monitor.md new file mode 100644 index 0000000000..f03a978ee9 --- /dev/null +++ b/book/src/validator-monitor.md @@ -0,0 +1,106 @@ +# Validator Monitoring +When `validator.sh` starts, it will output a validator configuration that looks +similar to: +```bash +======================[ validator configuration ]====================== +identity pubkey: 4ceWXsL3UJvn7NYZiRkw7NsryMpviaKBDYr8GK7J61Dm +vote pubkey: 2ozWvfaXQd1X6uKh8jERoRGApDqSqcEy6fF1oN13LL2G +ledger: ... +accounts: ... +====================================================================== +``` + +## Check Gossip +The **identity pubkey** for your validator can also be found by running: +```bash +$ solana-keygen pubkey ~/validator-keypair.json +``` + +From another console, confirm the IP address and **identity pubkey** of your +validator is visible in the gossip network by running: +```bash +$ solana-gossip --entrypoint testnet.solana.com:8001 spy +``` + +## Check Vote Activity +The vote pubkey for the validator can also be found by running: +```bash +$ solana-keygen pubkey ~/validator-vote-keypair.json +``` + +Provide the **vote pubkey** to the `solana-wallet show-vote-account` command to view +the recent voting activity from your validator: +```bash +$ solana-wallet show-vote-account 2ozWvfaXQd1X6uKh8jERoRGApDqSqcEy6fF1oN13LL2G +``` + +## Check Your Balance +Your lamport balance should decrease by the transaction fee amount as your +validator submits votes, and increase after serving as the leader: +```bash +$ solana-wallet --keypair ~/validator-keypair.json +``` + +## Check Slot Number +After your validator boots, it may take some time to catch up with the cluster. +Use the `get-slot` wallet command to view the current slot that the cluster is +processing: +```bash +$ solana-wallet get-slot +``` + +The current slot that your validator is processing can then been seen with: +```bash +$ solana-wallet --url http://127.0.0.1:8899 get-slot +``` + +Until your validator has caught up, it will not be able to vote successfully and +stake cannot be delegated to it. + +Also if you find the cluster's slot advancing faster than yours, you will likely +never catch up. This typically implies some kind of networking issue between +your validator and the rest of the cluster. + +## Get Cluster Info +There are several useful JSON-RPC endpoints for monitoring your validator on the +cluster, as well as the health of the cluster: + +```bash +# Similar to solana-gossip, you should see your validator in the list of cluster nodes +$ curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getClusterNodes"}' http://testnet.solana.com:8899 +# If your validator is properly staked and voting, it should appear in the list of epoch vote accounts +$ curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getEpochVoteAccounts"}' http://testnet.solana.com:8899 +# Returns the current leader schedule +$ curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getLeaderSchedule"}' http://testnet.solana.com:8899 +# Returns info about the current epoch. slotIndex should progress on subsequent calls. +curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getEpochInfo"}' http://testnet.solana.com:8899 +``` + +## Validator Metrics +Metrics are available for local monitoring of your validator. + +Docker must be installed and the current user added to the docker group. Then +download `solana-metrics.tar.bz2` from the Github Release and run +```bash +$ tar jxf solana-metrics.tar.bz2 +$ cd solana-metrics/ +$ ./start.sh +``` + +A local InfluxDB and Grafana instance is now running on your machine. Define +`SOLANA_METRICS_CONFIG` in your environment as described at the end of the +`start.sh` output and restart your validator. + +Metrics should now be streaming and visible from your local Grafana dashboard. + +## Timezone For Log Messages +Log messages emitted by your validator include a timestamp. When sharing logs +with others to help triage issues, that timestamp can cause confusion as it does +not contain timezone information. + +To make it easier to compare logs between different sources we request that +everybody use Pacific Time on their validator nodes. In Linux this can be +accomplished by running: +```bash +$ sudo ln -sf /usr/share/zoneinfo/America/Los_Angeles /etc/localtime +``` diff --git a/book/src/validator-software.md b/book/src/validator-software.md new file mode 100644 index 0000000000..bce6c40f58 --- /dev/null +++ b/book/src/validator-software.md @@ -0,0 +1,63 @@ +# Installing the Validator Software + +## Bootstrap with `solana-install` + +The `solana-install` tool can be used to easily install and upgrade the validator +software on Linux x86_64 and mac OS systems. + +```bash +$ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v0.16.5/install/solana-install-init.sh | sh -s +``` + +Alternatively build the `solana-install` program from source and run the +following command to obtain the same result: +```bash +$ solana-install init +``` + +After a successful install, `solana-install update` may be used to easily update the cluster +software to a newer version at any time. + +## Download Prebuilt Binaries +If you would rather not use `solana-install` to manage the install, you can manually download and install the binaries. + +### Linux +Download the binaries by navigating to +[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), +download **solana-release-x86_64-unknown-linux-gnu.tar.bz2**, then extract the +archive: +```bash +$ tar jxf solana-release-x86_64-unknown-linux-gnu.tar.bz2 +$ cd solana-release/ +$ export PATH=$PWD/bin:$PATH +``` +### mac OS +Download the binaries by navigating to +[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), +download **solana-release-x86_64-apple-darwin.tar.bz2**, then extract the +archive: +```bash +$ tar jxf solana-release-x86_64-apple-darwin.tar.bz2 +$ cd solana-release/ +$ export PATH=$PWD/bin:$PATH +``` + +## Build From Source +If you are unable to use the prebuilt binaries or prefer to build it yourself +from source, navigate to +[https://github.com/solana-labs/solana/releases/latest](https://github.com/solana-labs/solana/releases/latest), +and download the **Source Code** archive. Extract the code and build the +binaries with: +```bash +$ ./scripts/cargo-install-all.sh . +$ export PATH=$PWD/bin:$PATH +``` + +If building for CUDA (Linux only), fetch the perf-libs first then include the +`cuda` feature flag when building: +```bash +$ ./fetch-perf-libs.sh +$ source /home/mvines/ws/solana/target/perf-libs/env.sh +$ ./scripts/cargo-install-all.sh . cuda +$ export PATH=$PWD/bin:$PATH +``` diff --git a/book/src/validator-stake.md b/book/src/validator-stake.md new file mode 100644 index 0000000000..426b6d88da --- /dev/null +++ b/book/src/validator-stake.md @@ -0,0 +1,29 @@ +## Staking a Validator +When your validator starts, it will have no stake, which means it will +ineligible to become leader. + +Adding stake can be accomplished by using the `solana-wallet` CLI. First +obtain the public key for your validator's vote account with: +```bash +$ solana-keygen pubkey ~/validator-config/vote-keypair.json +``` +This will output a base58-encoded value that looks similar to +`DhUYZR98qFLLrnHg2HWeGhBQJ9tru7nwdEfYm8L8HdR9`. Then create a stake account +keypair with `solana-keygen`: +```bash +$ solana-keygen new -o ~/validator-config/stake-keypair.json +``` +and use the wallet's `delegate-stake` command to stake your validator with 42 lamports: +```bash +$ solana-wallet delegate-stake ~/validator-config/stake-keypair.json [VOTE PUBKEY] 42 +``` + +Note that stake changes are applied at Epoch boundaries so it can take an hour +or more for the change to take effect. + +Stake can be deactivate by running: +```bash +$ solana-wallet deactivate-stake ~/validator-config/stake-keypair.json +``` +Note that a stake account may only be used once, so after deactivation, use the +wallet's `withdraw-stake` command to recover the previously staked lamports. diff --git a/book/src/validator-start.md b/book/src/validator-start.md new file mode 100644 index 0000000000..3a554a9e72 --- /dev/null +++ b/book/src/validator-start.md @@ -0,0 +1,94 @@ +# Starting a Validator + +## Confirm The Testnet Is Reachable +Before attaching a validator node, sanity check that the cluster is accessible +to your machine by running some simple commands. If any of the commands fail, +please retry 5-10 minutes later to confirm the testnet is not just restarting +itself before debugging further. + +Fetch the current transaction count over JSON RPC: +```bash +$ curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1, "method":"getTransactionCount"}' http://testnet.solana.com:8899 +``` + +Inspect the network explorer at +[https://explorer.solana.com/](https://explorer.solana.com/) for activity. + +View the [metrics dashboard]( +https://metrics.solana.com:3000/d/testnet-beta/testnet-monitor-beta?var-testnet=testnet) +for more detail on cluster activity. + +## Confirm your Installation +Sanity check that you are able to interact with the cluster by receiving a small +airdrop of lamports from the testnet drone: +```bash +$ solana-wallet airdrop 123 +$ solana-wallet balance +``` + +Also try running following command to join the gossip network and view all the +other nodes in the cluster: +```bash +$ solana-gossip --entrypoint testnet.solana.com:8001 spy +# Press ^C to exit +``` + +## Start your Validator +Now create an identity keypair for your validator by running: +```bash +$ solana-keygen new -o ~/validator-keypair.json +``` +and airdrop yourself some lamports to get started: +```bash +$ solana-wallet --keypair ~/validator-keypair.json airdrop 1000 +``` + +Your validator will need a vote account. Create it now with the following +commands: +```bash +$ solana-keygen new -o ~/validator-vote-keypair.json +$ VOTE_PUBKEY=$(solana-keygen pubkey ~/validator-vote-keypair.json) +$ IDENTITY_PUBKEY=$(solana-keygen pubkey ~/validator-keypair.json) +$ solana-wallet create-vote-account "$VOTE_PUBKEY" "$IDENTITY_PUBKEY" 1 +``` + +Then use one of the following commands, depending on your installation +choice, to start the node: + +If this is a `solana-install`-installation: +```bash +$ validator.sh --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --ledger ~/validator-config --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com +``` + +Alternatively, the `solana-install run` command can be used to run the validator +node while periodically checking for and applying software updates: +```bash +$ solana-install run validator.sh -- --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --ledger ~/validator-config --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com +``` + +If you built from source: +```bash +$ NDEBUG=1 USE_INSTALL=1 ./multinode-demo/validator.sh --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --rpc-port 8899 --poll-for-new-genesis-block testnet.solana.com +``` + +### Enabling CUDA +By default CUDA is disabled. If your machine has a GPU with CUDA installed, +define the SOLANA_CUDA flag in your environment *before* running any of the +previusly mentioned commands +```bash +$ export SOLANA_CUDA=1 +``` + +When your validator is started look for the following log message to indicate that CUDA is enabled: +`"[ solana::validator] CUDA is enabled"` + +### Controlling local network port allocation +By default the validator will dynamically select available network ports in the +8000-10000 range, and may be overridden with `--dynamic-port-range`. For +example, `validator.sh --dynamic-port-range 11000-11010 ...` will restrict the +validator to ports 11000-11011. + +### Limiting ledger size to conserve disk space +By default the validator will retain the full ledger. To conserve disk space +start the validator with the `--limit-ledger-size`, which will instruct the +validator to only retain the last couple hours of ledger. diff --git a/book/src/validator-testnet.md b/book/src/validator-testnet.md new file mode 100644 index 0000000000..77440a9ac9 --- /dev/null +++ b/book/src/validator-testnet.md @@ -0,0 +1,55 @@ +# Choosing a Testnet +As noted in the overview, solana currently maintains several testnets, each featuring a validator that can serve as the entrypoint to the cluster for your validator. + +Current testnet entrypoints: +- Stable, testnet.solana.com +- Beta, beta.testnet.solana.com +- Edge, edge.testnet.solana.com + +Prior to mainnet, the testnets may be running different versions of solana +software, which may feature breaking changes. Generally, the edge testnet tracks +the tip of master, beta tracks the latest tagged minor release, and stable +tracks the most stable tagged release. + +## Using a Different Testnet +This guide is written in the context of testnet.solana.com, our most stable +cluster. To participate in another testnet, you will need to modify some of the +commands in the following pages. + +### Downloading Software +If you are bootstrapping with `solana-install`, you can specify the release tag or named channel to install to match your desired testnet. + +```bash +$ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v0.16.5/install/solana-install-init.sh | sh -s - 0.17.2 +``` + +```bash +$ curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v0.16.5/install/solana-install-init.sh | sh -s - beta +``` + +Similarly, you can add this argument to the `solana-install` command if you've built the program from source: +```bash +$ solana-install init 0.17.2 +``` + +If you are downloading pre-compiled binaries or building from source, simply choose the release matching your desired testnet. + +### Validator Commands +Solana CLI tools like solana-wallet and solana-validator-info point at +testnet.solana.com by default. Include a `--url` argument to point at a +different testnet. For instance: +```bash +$ solana-wallet --url http://beta.testnet.solana.com:8899 balance +``` + +Solana-gossip and solana-validator commands already require an explicit +`--entrypoint` argument. Simply replace testnet.solana.com in the examples with +an alternate url to interact with a different testnet. For example: +```bash +$ validator.sh --identity ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json --ledger ~/validator-config --rpc-port 8899 --poll-for-new-genesis-block beta.testnet.solana.com +``` + +You can also submit JSON-RPC requests to a different testnet, like: +```bash +$ curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1, "method":"getTransactionCount"}' http://beta.testnet.solana.com:8899 +``` diff --git a/book/src/validator-troubleshoot.md b/book/src/validator-troubleshoot.md new file mode 100644 index 0000000000..d9c2c36ebb --- /dev/null +++ b/book/src/validator-troubleshoot.md @@ -0,0 +1,2 @@ +# Troubleshooting Validator Issues +Coming soon...