Move docs from book/ to docs/ (#8469)

automerge
This commit is contained in:
Justin Starry
2020-02-26 23:11:38 +08:00
committed by GitHub
parent 8839dbfe5b
commit 021d0a46f8
140 changed files with 56 additions and 58 deletions

View File

@@ -0,0 +1,32 @@
# 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:
* Developer testnet, devnet.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/).
Also we'd love it if you choose to register your validator node with us at
[https://forms.gle/LfFscZqJELbuUP139](https://forms.gle/LfFscZqJELbuUP139).

View File

@@ -0,0 +1,60 @@
# 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 CLI to populate a validator info account:
```bash
solana validator-info publish --keypair ~/validator-keypair.json <VALIDATOR_INFO_ARGS> <VALIDATOR_NAME>
```
For details about optional fields for VALIDATOR\_INFO\_ARGS:
```bash
solana validator-info publish --help
```
## Example Commands
Example publish command:
```bash
solana validator-info publish "Elvis Validator" -n elvis -w "https://elvis-validates.com"
```
Example query command:
```bash
solana validator-info get
```
which outputs
```text
Validator info from 8WdJvDz6obhADdxpGCiJKZsDYwTLNEDFizayqziDc9ah
Validator pubkey: 6dMH3u76qZ7XG4bVboVRnBHR2FfrxEqTTTyj4xmyDMWo
Info: {"keybaseUsername":"elvis","name":"Elvis Validator","website":"https://elvis-validates.com"}
```
## 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/](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-<PUBKEY>`
* In Keybase, navigate to the Files section, and upload your pubkey file to
a `solana` subdirectory in your public folder: `/keybase/public/<KEYBASE_USERNAME>/solana`
* To check your pubkey, ensure you can successfully browse to
`https://keybase.pub/<KEYBASE_USERNAME>/solana/validator-<PUBKEY>`
3. Add or update your `solana validator-info` with your Keybase username. The
CLI will verify the `validator-<PUBKEY>` file

View File

@@ -0,0 +1,79 @@
# Monitoring a Validator
## Check Gossip
Confirm the IP address and **identity pubkey** of your validator is visible in
the gossip network by running:
```bash
solana-gossip spy --entrypoint devnet.solana.com:8001
```
## Check Your Balance
Your account balance should decrease by the transaction fee amount as your
validator submits votes, and increase after serving as the leader. Pass the
`--lamports` are to observe in finer detail:
```bash
solana balance --lamports
```
## Check Vote Activity
The `solana vote-account` command displays the recent voting activity from
your validator:
```bash
solana vote-account ~/validator-vote-keypair.json
```
## 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://devnet.solana.com:8899
# If your validator is properly voting, it should appear in the list of `current` vote accounts. If staked, `stake` should be > 0
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getVoteAccounts"}' http://devnet.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://devnet.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://devnet.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
```

View File

@@ -0,0 +1,50 @@
# Validator Requirements
## Hardware
* CPU Recommendations
* We recommend a CPU with the highest number of cores as possible. AMD Threadripper or Intel Server \(Xeon\) CPUs are fine.
* We recommend AMD Threadripper as you get a larger number of cores for parallelization compared to Intel.
* Threadripper also has a cost-per-core advantage and a greater number of PCIe lanes compared to the equivalent Intel part. PoH \(Proof of History\) is based on sha256 and Threadripper also supports sha256 hardware instructions.
* SSD size and I/O style \(SATA vs NVMe/M.2\) for a validator
* Minimum example - Samsung 860 Evo 2TB
* Mid-range example - Samsung 860 Evo 4TB
* High-end example - Samsung 860 Evo 4TB
* GPUs
* While a CPU-only node may be able to keep up with the initial idling network, once transaction throughput increases, GPUs will be necessary
* What kind of GPU?
* We recommend Nvidia 2080Ti or 1080Ti series consumer GPU or Tesla series server GPUs.
* We do not currently support OpenCL and therefore do not support AMD GPUs. We have a bounty out for someone to port us to OpenCL. Interested? [Check out our GitHub.](https://github.com/solana-labs/solana)
* Power Consumption
* Approximate power consumption for a validator node running an AMD Threadripper 2950W and 2x 2080Ti GPUs is 800-1000W.
### Preconfigured Setups
Here are our recommendations for low, medium, and high end machine specifications:
| | 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. |
## Software
* We build and run on Ubuntu 18.04. Some users have had trouble when running on Ubuntu 16.04
* See [Validator Software](validator-software.md) for the current Solana software release.
Be sure to ensure that 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.**
For more information on port forwarding with regards to residential networks,
see [this document](http://www.mcs.sdsmt.edu/lpyeatt/courses/314/PortForwardingSetup.pdf).
Prebuilt binaries are available for Linux x86\_64 \(Ubuntu 18.04 recommended\).
MacOS or WSL users may build from source.
## 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](https://developer.nvidia.com/cuda-toolkit-archive). If your machine is using
a different CUDA version then you will need to rebuild from source.

View File

@@ -0,0 +1,79 @@
# Installing the Validator Software
Install the Solana release
[v0.23.1](https://github.com/solana-labs/solana/releases/tag/v0.23.1) on your
machine by running:
```bash
curl -sSf https://raw.githubusercontent.com/solana-labs/solana/v0.23.1/install/solana-install-init.sh | sh -s - 0.23.1
```
If you are connecting to a different testnet, you can replace `0.23.1` with the
release tag matching the software version of your desired testnet, or replace it
with the named channel `stable`, `beta`, or `edge`.
The following output indicates a successful update:
```text
looking for latest release
downloading v0.23.1 installer
Configuration: /home/solana/.config/solana/install/config.yml
Active release directory: /home/solana/.local/share/solana/install/active_release
* Release version: 0.23.1
* Release URL: https://github.com/solana-labs/solana/releases/download/v0.23.1/solana-release-x86_64-unknown-linux-gnu.tar.bz2
Update successful
```
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
```
### macOS
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
```
You can then run the following command to obtain the same result as with
prebuilt binaries:
```bash
solana-install init
```

View File

@@ -0,0 +1,129 @@
# Staking
**By default your validator will have no stake.** This means it will be
ineligible to become leader.
## Monitoring Catch Up
To delegate stake, first make sure your validator is running and has caught up
to the cluster. It may take some time to catch up after your validator boots.
Use the `catchup` command to monitor your validator through this process:
```bash
solana catchup ~/validator-keypair.json
```
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.
## Create Stake Keypair
If you havent already done so, create a staking keypair. If you have completed
this step, you should see the “validator-stake-keypair.json” in your Solana
runtime directory.
```bash
solana-keygen new -o ~/validator-stake-keypair.json
```
## Delegate Stake
Now delegate 1 SOL to your validator by first creating your stake account:
```bash
solana create-stake-account ~/validator-stake-keypair.json 1
```
and then delegating that stake to your validator:
```bash
solana delegate-stake ~/validator-stake-keypair.json ~/validator-vote-keypair.json
```
> Dont delegate your remaining SOL, as your validator will use those tokens to vote.
Stakes can be re-delegated to another node at any time with the same command,
but only one re-delegation is permitted per epoch:
```bash
solana delegate-stake ~/validator-stake-keypair.json ~/some-other-validator-vote-keypair.json
```
Assuming the node is voting, now you're up and running and generating validator
rewards. Rewards are paid automatically on epoch boundaries.
The rewards lamports earned are split between your stake account and the vote
account according to the commission rate set in the vote account. Rewards can
only be earned while the validator is up and running. Further, once staked, the
validator becomes an important part of the network. In order to safely remove a
validator from the network, first deactivate its stake.
At the end of each slot, a validator is expected to send a vote transaction.
These vote transactions are paid for by lamports from a validator's identity
account.
This is a normal transaction so the standard transaction fee will apply. The
transaction fee range is defined by the genesis block. The actual fee will
fluctuate based on transaction load. You can determine the current fee via the
[RPC API “getRecentBlockhash”](../api-reference/jsonrpc-api.md#getrecentblockhash)
before submitting a transaction.
Learn more about [transaction fees here](../implemented-proposals/transaction-fees.md).
## Validator Stake Warm-up
Stakes need to warm up, and warmup increments are applied at Epoch boundaries,
so it can take an hour or more for stake to come fully online.
To monitor your validator during its warmup period:
* View your vote account:`solana vote-account ~/validator-vote-keypair.json` This displays the current state of all the votes the validator has submitted to the network.
* View your stake account, the delegation preference and details of your stake:`solana stake-account ~/validator-stake-keypair.json`
* `solana validators` displays the current active stake of all validators, including yours
* `solana stake-history ` shows the history of stake warming up and cooling down over recent epochs
* Look for log messages on your validator indicating your next leader slot: `[2019-09-27T20:16:00.319721164Z INFO solana_core::replay_stage] <VALIDATOR_IDENTITY_PUBKEY> voted and reset PoH at tick height ####. My next leader slot is ####`
* Once your stake is warmed up, you will see a stake balance listed for your validator on the [Solana Network Explorer](http://explorer.solana.com/validators)
## Monitor Your Staked Validator
Confirm your validator becomes a [leader](../terminology.md#leader)
* After your validator is caught up, use the `solana balance` command to monitor the earnings as your validator is selected as leader and collects transaction fees
* Solana nodes offer a number of useful JSON-RPC methods to return information about the network and your validator's participation. Make a request by using curl \(or another http client of your choosing\), specifying the desired method in JSON-RPC-formatted data. For example:
```bash
// Request
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1, "method":"getEpochInfo"}' http://localhost:8899
// Result
{"jsonrpc":"2.0","result":{"epoch":3,"slotIndex":126,"slotsInEpoch":256},"id":1}
```
Helpful JSON-RPC methods:
* `getEpochInfo`[An epoch](../terminology.md#epoch) is the time, i.e. number of [slots](../terminology.md#slot), for which a [leader schedule](../terminology.md#leader-schedule) is valid. This will tell you what the current epoch is and how far into it the cluster is.
* `getVoteAccounts` This will tell you how much active stake your validator currently has. A % of the validator's stake is activated on an epoch boundary. You can learn more about staking on Solana [here](../cluster/stake-delegation-and-rewards.md).
* `getLeaderSchedule` At any given moment, the network expects only one validator to produce ledger entries. The [validator currently selected to produce ledger entries](../cluster/leader-rotation.md#leader-rotation) is called the “leader”. This will return the complete leader schedule \(on a slot-by-slot basis\) for currently activated stake, the identity pubkey will show up 1 or more times here.
## Deactivating Stake
Before detaching your validator from the cluster, you should deactivate the
stake that was previously delegated by running:
```bash
solana deactivate-stake ~/validator-stake-keypair.json
```
Stake is not deactivated immediately and instead cools down in a similar fashion
as stake warm up. Your validator should remain attached to the cluster while
the stake is cooling down. While cooling down, your stake will continue to earn
rewards. Only after stake cooldown is it safe to turn off your validator or
withdraw it from the network. Cooldown may take several epochs to complete,
depending on active stake and the size of your stake.
Note that a stake account may only be used once, so after deactivation, use the
cli's `withdraw-stake` command to recover the previously staked lamports.

View File

@@ -0,0 +1,184 @@
# Starting a Validator
## Configure Solana CLI
The solana cli includes `get` and `set` configuration commands to automatically
set the `--url` argument for cli commands. For example:
```bash
solana config set --url http://devnet.solana.com:8899
```
\(You can always override the set configuration by explicitly passing the
`--url` argument with a command, eg: `solana --url http://beta.devnet.solana.com:8899 balance`\)
## Confirm The Testnet Is Reachable
Before attaching a validator node, sanity check that the cluster is accessible
to your machine by fetching the transaction count:
```bash
solana transaction-count
```
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
Try running following command to join the gossip network and view all the other
nodes in the cluster:
```bash
solana-gossip spy --entrypoint devnet.solana.com:8001
# Press ^C to exit
```
## Enabling CUDA
If your machine has a GPU with CUDA installed \(Linux-only currently\), include
the `--cuda` argument to `solana-validator`.
When your validator is started look for the following log message to indicate
that CUDA is enabled: `"[<timestamp> solana::validator] CUDA is enabled"`
## Tune System
For Linux validators, the solana repo includes a daemon to adjust system settings to optimize
performance (namely by increasing the OS UDP buffer limits, and scheduling PoH with realtime policy).
The daemon (`solana-sys-tuner`) is included in the solana binary release.
To run it:
```bash
sudo solana-sys-tuner --user $(whoami) > sys-tuner.log 2>&1 &
```
## Generate identity
Create an identity keypair for your validator by running:
```bash
solana-keygen new -o ~/validator-keypair.json
```
The identity public key can now be viewed by running:
```bash
solana-keygen pubkey ~/validator-keypair.json
```
> Note: The "validator-keypair.json” file is also your \(ed25519\) private key.
Your validator identity keypair uniquely identifies your validator within the
network. **It is crucial to back-up this information.**
If you dont back up this information, you WILL NOT BE ABLE TO RECOVER YOUR
VALIDATOR if you lose access to it. If this happens, YOU WILL LOSE YOUR
ALLOCATION OF LAMPORTS TOO.
To back-up your validator identify keypair, **back-up your
"validator-keypair.json” file to a secure location.**
### Vanity Keypair
You can generate a custom vanity keypair using solana-keygen. For instance:
```bash
solana-keygen grind --starts-with e1v1s
```
Depending on the string requested, it may take days to find a match...
## More Solana CLI Configuration
Now that you have a keypair, set the solana configuration to use your validator
keypair for all following commands:
```bash
solana config set --keypair ~/validator-keypair.json
```
You should see the following output:
```text
Wallet Config Updated: /home/solana/.config/solana/wallet/config.yml
* url: http://devnet.solana.com:8899
* keypair: /home/solana/validator-keypair.json
```
## Airdrop & Check Validator Balance
Airdrop yourself some SOL to get started:
```bash
solana airdrop 1000
```
To view your current balance:
```text
solana balance
```
Or to see in finer detail:
```text
solana balance --lamports
```
Read more about the [difference between SOL and lamports here](../introduction.md#what-are-sols).
## Create Vote Account
If you havent already done so, create a vote-account keypair and create the
vote account on the network. If you have completed this step, you should see the
“validator-vote-keypair.json” in your Solana runtime directory:
```bash
solana-keygen new -o ~/validator-vote-keypair.json
```
Create your vote account on the blockchain:
```bash
solana create-vote-account ~/validator-vote-keypair.json ~/validator-keypair.json
```
## Connect Your Validator
Connect to a testnet cluster by running:
```bash
solana-validator --identity-keypair ~/validator-keypair.json --voting-keypair ~/validator-vote-keypair.json \
--ledger ~/validator-ledger --rpc-port 8899 --entrypoint devnet.solana.com:8001 \
--limit-ledger-size
```
To force validator logging to the console add a `--log -` argument, otherwise
the validator will automatically log to a file.
Confirm your validator connected to the network by opening a new terminal and
running:
```bash
solana-gossip spy --entrypoint devnet.solana.com:8001
```
If your validator is connected, its public key and IP address will appear in the list.
### 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, `solana-validator --dynamic-port-range 11000-11010 ...` will restrict
the validator to ports 11000-11011.
### Limiting ledger size to conserve disk space
The `--limit-ledger-size` arg will instruct the validator to only retain the
last couple hours of ledger. To retain the full ledger, simply remove that arg.

View File

@@ -0,0 +1,39 @@
# Choosing a Testnet
Solana maintains several testnets, each featuring a Solana-owned validator
that serves as an entrypoint to the cluster.
Current testnet entrypoints:
* Stable: devnet.solana.com
Application developers should target the Stable testnet. Key differences
between the Stable testnet and what will be mainnet:
* Stable testnet tokens are not real
* Stable testnet includes a token faucet for application testing
* Stable testnet may be subject to ledger resets
* Stable testnet typically runs a newer software version than mainnet
* Stable testnet may be maintained by different validators than mainnet
The Beta testnet is used to showcase and stabilize new features before they
are tagged for release. Application developers are free to target the Beta
testnet, but should expect instability and periodic ledger resets. Regarding
stability, all that can be said is that CI automation was successful.
### Get Testnet Version
You can submit a JSON-RPC request to see the specific software version of the
cluster. Use this to specify [the software version to install](validator-software.md).
```bash
curl -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1, "method":"getVersion"}' devnet.solana.com:8899
```
Example result:
`{"jsonrpc":"2.0","result":{"solana-core":"0.21.0"},"id":1}`
## Using a Different Testnet
This guide is written in the context of devnet.solana.com, our most stable
cluster. To participate in another testnet, modify the commands in the following
pages, replacing `devnet.solana.com` with your desired testnet.

View File

@@ -0,0 +1,19 @@
# Troubleshooting
There is a **\#validator-support** Discord channel available to reach other
testnet participants, [https://discord.gg/pquxPsq](https://discord.gg/pquxPsq).
## Useful Links & Discussion
* [Network Explorer](http://explorer.solana.com/)
* [Testnet Metrics Dashboard](https://metrics.solana.com:3000/d/testnet-edge/testnet-monitor-edge?refresh=60s&orgId=2)
* Validator chat channels
* [\#validator-support](https://discord.gg/rZsenD) General support channel for any Validator related queries.
* [\#tourdesol](https://discord.gg/BdujK2) Discussion and support channel for Tour de SOL participants ([What is Tour de SOL?](https://solana.com/tds/)).
* [\#tourdesol-announcements](https://discord.gg/Q5TxEC) The single source of truth for critical information relating to Tour de SOL
* [\#tourdesol-stage0](https://discord.gg/Xf8tES) Discussion for events within Tour de SOL Stage 0. Stage 0 includes all the dry-run
* [Core software repo](https://github.com/solana-labs/solana)
* [Tour de SOL Docs](https://docs.solana.com/tour-de-sol)
* [TdS repo](https://github.com/solana-labs/tour-de-sol)
* [TdS metrics dashboard](https://metrics.solana.com:3000/d/testnet-edge/testnet-monitor-edge?refresh=1m&from=now-15m&to=now&var-testnet=tds&orgId=2&var-datasource=TdS%20Metrics%20%28read-only%29)
Can't find what you're looking for? Send an email to ryan@solana.com or reach out to @rshea\#2622 on Discord.