From 24bae00560870b7d8f5c7868f1a7de4490d4c80d Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Thu, 13 May 2021 18:41:16 +0000 Subject: [PATCH] docs: Add docs for `solana-test-validator` (backport #17199) (#17211) * docs: Add docs for `solana-test-validator` (cherry picked from commit 768a2ebe9d557c8843894baf75a2433475c3d557) * Update docs/src/developing/test-validator.md Co-authored-by: Tyera Eulberg (cherry picked from commit 056c1a7b508f92deb5087dce8b6f4b8f9cf2bef4) * Update docs/src/developing/test-validator.md Co-authored-by: Tyera Eulberg (cherry picked from commit 5b13d4057b2c87ef6cd6850464441446fcb96a09) * Update docs/src/developing/test-validator.md Co-authored-by: Tyera Eulberg (cherry picked from commit 38d7e9a4c4a458e8deace74a44b0a4e4c21efd5e) * Update docs/src/developing/test-validator.md Co-authored-by: Tyera Eulberg (cherry picked from commit e08687acfdba1513b36f3e79377bf74dad446408) * Update docs/src/developing/test-validator.md Co-authored-by: Tyera Eulberg (cherry picked from commit 3214105a21a1e02a5a55ce6026de02a565ed2b6e) * Update docs/src/developing/test-validator.md (cherry picked from commit 7868df321121b9d2cb1aaa33ec0f7193d48f449d) * Update docs/src/developing/test-validator.md (cherry picked from commit 3e0c0abb536f36dd801cdf8af40dac04944ab165) Co-authored-by: Trent Nelson --- docs/sidebars.js | 1 + docs/src/developing/test-validator.md | 125 ++++++++++++++++++++++++++ 2 files changed, 126 insertions(+) create mode 100644 docs/src/developing/test-validator.md diff --git a/docs/sidebars.js b/docs/sidebars.js index cb238ce572..f53d3cb07b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -89,6 +89,7 @@ module.exports = { "developing/on-chain-programs/faq", ], }, + "developing/test-validator", "developing/backwards-compatibility", ], Integrating: ["integrations/exchange"], diff --git a/docs/src/developing/test-validator.md b/docs/src/developing/test-validator.md new file mode 100644 index 0000000000..6168940d11 --- /dev/null +++ b/docs/src/developing/test-validator.md @@ -0,0 +1,125 @@ +--- +title: Solana Test Validator +--- +During early stage development, it is often convenient to target a cluster with +fewer restrictions and more configuration options than the public offerings +provide. This is easily achieved with the `solana-test-validator` binary, which +starts a full-featured, single-node cluster on the developer's workstation. + +## Advantages +- No RPC rate-limits +- No airdrop limits +- Direct [on-chain program](on-chain-programs/overview) deployment +(`--bpf-program ...`) +- Clone accounts from a public cluster, including programs (`--clone ...`) +- Configurable transaction history retention (`--limit-ledger-size ...`) +- Configurable epoch length (`--slots-per-epoch ...`) +- Jump to an arbitrary slot (`--warp-slot ...`) + +## Installation +The `solana-test-validator` binary ships with the Solana CLI Tool Suite. +[Install](/cli/install-solana-cli-tools) before continuing. + +## Running +First take a look at the configuration options +``` +solana-test-validator --help +``` + +Next start the test validator +``` +solana-test-validator +``` + +By default, basic status information is printed while the process is running. +See [Appendix I](#appendix-i-status-output) for details +``` +Ledger location: test-ledger +Log: test-ledger/validator.log +Identity: EPhgPANa5Rh2wa4V2jxt7YbtWa3Uyw4sTeZ13cQjDDB8 +Version: 1.6.7 +Gossip Address: 127.0.0.1:1024 +TPU Address: 127.0.0.1:1027 +JSON RPC URL: http://127.0.0.1:8899 +⠈ 00:36:02 | Processed Slot: 5142 | Confirmed Slot: 5142 | Finalized Slot: 5110 | Snapshot Slot: 5100 | Transactions: 5142 | ◎499.974295000 +``` + +Leave `solana-test-validator` running in its own terminal. When it is no longer +needed, it can be stopped with ctrl-c. + +## Interacting +Open a new terminal to interact with a [running](#running) `solana-test-validator` +instance using other binaries from the Solana CLI Tool Suite or your own client +software. + +#### Configure the CLI Tool Suite to target a local cluster by default +``` +solana config set --url http://127.0.0.1:8899 +``` + +#### Verify the CLI Tool Suite configuration +``` +solana cluster-version +``` + +#### Check the wallet balance +``` +solana balance +``` +* **NOTE:** `Error: No such file or directory (os error 2)` means that the default +wallet does not yet exist. Create it with `solana-keygen new`. +* **NOTE:** If the wallet has a zero SOL balance, airdrop some localnet SOL with +`solana airdrop 10` + +#### Perform a basic transfer transaction +``` +solana transfer EPhgPANa5Rh2wa4V2jxt7YbtWa3Uyw4sTeZ13cQjDDB8 1 +``` + +#### Monitor `msg!()` output from on-chain programs +``` +solana logs +``` +* **NOTE:** This command needs to be running when the target transaction is +executed. Run it in its own terminal + +## Appendix I: Status Output +``` +Ledger location: test-ledger +``` +* File path of the ledger storage directory. This directory can get large. Store +less transaction history with `--limit-ledger-size ...` or relocate it with +`--ledger ...` + +``` +Log: test-ledger/validator.log +``` +* File path of the validator text log file. The log can also be streamed by +passing `--log`. Status output is suppressed in this case. + +``` +Identity: EPhgPANa5Rh2wa4V2jxt7YbtWa3Uyw4sTeZ13cQjDDB8 +``` +* The validator's identity in the [gossip network](/validator/gossip#gossip-overview) + +``` +Version: 1.6.7 +``` +* The software version + +``` +Gossip Address: 127.0.0.1:1024 +TPU Address: 127.0.0.1:1027 +JSON RPC URL: http://127.0.0.1:8899 +``` +* The network address of the [Gossip](/validator/gossip#gossip-overview), +[Transaction Processing Unit](/validator/tpu) and [JSON RPC](clients/jsonrpc-api#json-rpc-api-reference) +service, respectively + +``` +⠈ 00:36:02 | Processed Slot: 5142 | Confirmed Slot: 5142 | Finalized Slot: 5110 | Snapshot Slot: 5100 | Transactions: 5142 | ◎499.974295000 +``` +* Session running time, current slot of the the three block +[commitment levels](clients/jsonrpc-api#configuring-state-commitment), +slot height of the last snapshot, transaction count, +[voting authority](/running-validator/vote-accounts#vote-authority) balance