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

automerge

.gitbook.yaml

@@ -1,4 +1,4 @@
-root: ./book/src
+root: ./docs/src
 
 structure:
     readme: introduction.md

.gitignore

@@ -1,6 +1,6 @@
-/book/html/
-/book/src/tests.ok
-/book/src/.gitbook/assets/*.svg
+/docs/html/
+/docs/src/tests.ok
+/docs/src/.gitbook/assets/*.svg
 /farf/
 /solana-release/
 /solana-release.tar.bz2

CONTRIBUTING.md

@@ -224,21 +224,20 @@ Inventing new terms is allowed, but should only be done when the term is widely
 used and understood. Avoid introducing new 3-letter terms, which can be
 confused with 3-letter acronyms.
 
-[Terms currently in use](book/src/terminology.md)
+[Terms currently in use](docs/src/terminology.md)
 
 
 ## Design Proposals
 
-Solana's architecture is described by a book generated from markdown files in
-the `book/src/` directory, maintained by an *editor* (currently @garious). To
-add a design proposal, you'll need to at least propose a change the content
-under the [Accepted Design
-Proposals](https://docs.solana.com/book/v/master/proposals) chapter.  Here's
-the full process:
+Solana's architecture is described by docs generated from markdown files in
+the `docs/src/` directory, maintained by an *editor* (currently @garious). To
+add a design proposal, you'll need to include it in the
+[Accepted Design Proposals](https://docs.solana.com/proposals)
+section of the Solana docs.  Here's the full process:
 
 1. Propose a design by creating a PR that adds a markdown document to the
-   directory `book/src/` and references it from the [table of
-   contents](book/src/SUMMARY.md). Add any relevant *maintainers* to the PR
+   `docs/src/proposals` directory and references it from the [table of
+   contents](docs/src/SUMMARY.md). Add any relevant *maintainers* to the PR
    review.
 2. The PR being merged indicates your proposed change was accepted and that the
    maintainers support your plan of attack.

README.md

@@ -23,12 +23,12 @@ It's possible for a centralized database to process 710,000 transactions per sec
 
 Furthermore, and much to our surprise, it can be implemented using a mechanism that has existed in Bitcoin since day one. The Bitcoin feature is called nLocktime and it can be used to postdate transactions using block height instead of a timestamp. As a Bitcoin client, you'd use block height instead of a timestamp if you don't trust the network. Block height turns out to be an instance of what's being called a Verifiable Delay Function in cryptography circles. It's a cryptographically secure way to say time has passed. In Solana, we use a far more granular verifiable delay function, a SHA 256 hash chain, to checkpoint the ledger and coordinate consensus. With it, we implement Optimistic Concurrency Control and are now well en route towards that theoretical limit of 710,000 transactions per second.
 
-Architecture
+Documentation
 ===
 
-Before you jump into the code, review the online book [Solana: Blockchain Rebuilt for Scale](https://docs.solana.com/book/).
+Before you jump into the code, review the documentation [Solana: Blockchain Rebuilt for Scale](https://docs.solana.com).
 
-(The _latest_ development version of the online book is also [available here](https://docs.solana.com/book/v/master/).)
+(The _latest_ development version of the docs is [available here](https://docs.solana.com/v/master).)
 
 Release Binaries
 ===
@@ -121,7 +121,7 @@ $ cargo test
 Local Testnet
 ---
 
-Start your own testnet locally, instructions are in the book [Solana: Blockchain Rebuild for Scale: Getting Started](https://docs.solana.com/book/building-from-source).
+Start your own testnet locally, instructions are in the online docs [Solana: Blockchain Rebuild for Scale: Getting Started](https://docs.solana.com/building-from-source).
 
 Remote Testnets
 ---

RELEASE.md

@@ -138,7 +138,7 @@ There are three release channels that map to branches as follows:
 ### Update documentation
 TODO: Documentation update procedure is WIP as we move to gitbook
 
-Document the new recommended version by updating `book/src/running-archiver.md` and `book/src/validator-testnet.md` on the release (beta) branch to point at the `solana-install` for the upcoming release version.
+Document the new recommended version by updating `docs/src/running-archiver.md` and `docs/src/validator-testnet.md` on the release (beta) branch to point at the `solana-install` for the upcoming release version.
 
 ### Update software on devnet.solana.com
 

book/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md

@@ -1,11 +0,0 @@
-# Replication-validation Transaction Fees
-
-**Subject to change.**
-
-As previously mentioned, validator-clients will also be responsible for validating PoReps submitted into the PoH stream by archiver-clients. In this case, validators are providing compute \(CPU/GPU\) and light storage resources to confirm that these replication proofs could only be generated by a client that is storing the referenced PoH leger block.
-
-While replication-clients are incentivized and rewarded through protocol-based rewards schedule \(see [Replication-client Economics](../ed_replication_client_economics/)\), validator-clients will be incentivized to include and validate PoReps in PoH through collection of transaction fees associated with the submitted PoReps and distribution of protocol rewards proportional to the validated PoReps. As will be described in detail in the Section 3.1, replication-client rewards are protocol-based and designed to reward based on a global data redundancy factor. I.e. the protocol will incentivize replication-client participation through rewards based on a target ledger redundancy \(e.g. 10x data redundancy\).
-
-The validation of PoReps by validation-clients is computationally more expensive than state-validation \(detail in the [Economic Sustainability](../ed_economic_sustainability.md) chapter\), thus the transaction fees are expected to be proportionally higher.
-
-There are various attack vectors available for colluding validation and replication clients, also described in detail below in [Economic Sustainability](../ed_economic_sustainability/README.md). To protect against various collusion attack vectors, for a given epoch, validator rewards are distributed across participating validation-clients in proportion to the number of validated PoReps in the epoch less the number of PoReps that mismatch the archivers challenge. The PoRep challenge game is described in [Ledger Replication](https://github.com/solana-labs/solana/blob/master/book/src/ledger-replication.md#the-porep-game). This design rewards validators proportional to the number of PoReps they process and validate, while providing negative pressure for validation-clients to submit lazy or malicious invalid votes on submitted PoReps \(note that it is computationally prohibitive to determine whether a validator-client has marked a valid PoRep as invalid\).

ci/affects-files.sh

@@ -9,7 +9,7 @@
 #     ./affects-files.sh ^snap/  -- anything under the snap/ subdirectory
 #     ./affects-files.sh snap/   -- also matches foo/snap/
 # Any pattern starting with the ! character will be negated:
-#     ./affects-files.sh !^book/  -- anything *not* under the book/ subdirectory
+#     ./affects-files.sh !^docs/  -- anything *not* under the docs/ subdirectory
 #
 set -e
 cd "$(dirname "$0")"/..

ci/buildkite-secondary.yml

@@ -15,6 +15,6 @@ steps:
   - command: "ci/publish-tarball.sh"
     timeout_in_minutes: 60
     name: "publish tarball"
-  - command: "ci/publish-book.sh"
+  - command: "ci/publish-docs.sh"
     timeout_in_minutes: 15
-    name: "publish book"
+    name: "publish docs"

ci/publish-docs.sh

@@ -11,10 +11,10 @@ if [[ -n $CI_BRANCH ]]; then
     set -x
     (
       . ci/rust-version.sh stable
-      ci/docker-run.sh "$rust_stable_docker_image" make -Cbook -B svg
+      ci/docker-run.sh "$rust_stable_docker_image" make -C docs -B svg
     )
     # make a local commit for the svgs
-    git add -A -f book/src/.gitbook/assets/.
+    git add -A -f docs/src/.gitbook/assets/.
     if ! git diff-index --quiet HEAD; then
       git config user.email maintainers@solana.com
       git config user.name "$me"

ci/test-checks.sh

@@ -25,7 +25,7 @@ _ cargo +"$rust_stable" audit --version
 _ cargo +"$rust_stable" audit --ignore RUSTSEC-2020-0002
 _ ci/nits.sh
 _ ci/order-crates-for-publishing.py
-_ book/build.sh
+_ docs/build.sh
 _ ci/check-ssh-keys.sh
 
 {

ci/test-stable.sh

@@ -13,12 +13,12 @@ annotate() {
 # Run the appropriate test based on entrypoint
 testName=$(basename "$0" .sh)
 
-# Skip if only the book has been modified
+# Skip if only the docs have been modified
 ci/affects-files.sh \
-  \!^book/ \
+  \!^docs/ \
 || {
   annotate --style info \
-    "Skipped $testName as only book files were modified"
+    "Skipped $testName as only docs/ files were modified"
   exit 0
 }
 

core/src/repair_service.rs

@@ -317,7 +317,7 @@ impl RepairService {
         );
     }
 
-    // Update the gossiped structure used for the "Repairmen" repair protocol. See book
+    // Update the gossiped structure used for the "Repairmen" repair protocol. See docs
     // for details.
     fn update_epoch_slots(
         id: Pubkey,

core/tests/fork-selection.rs

@@ -1,6 +1,6 @@
 //! Fork Selection Simulation
 //!
-//! Description of the algorithm can be found in [book/src/fork-selection.md](book/src/fork-selection.md).
+//! Description of the algorithm can be found in [docs/src/fork-selection.md](docs/src/fork-selection.md).
 //!
 //! A test library function exists for configuring networks.
 //! ```

docs/README.md

@@ -1,7 +1,7 @@
 Building the Solana Docs
 ---
 
-Install the book's dependencies, build, and test the book:
+Install dependencies, build, and test the docs:
 
 ```bash
 $ brew install coreutils
@@ -23,7 +23,7 @@ Render markdown as HTML:
 $ make build
 ```
 
-Render and view the book:
+Render and view the docs:
 
 ```bash
 $ make open

docs/src/apps/drones.md

@@ -1,6 +1,6 @@
 # Drones
 
-This chapter defines an off-chain service called a _drone_, which acts as custodian of a user's private key. In its simplest form, it can be used to create _airdrop_ transactions, a token transfer from the drone's account to a client's account.
+This section defines an off-chain service called a _drone_, which acts as custodian of a user's private key. In its simplest form, it can be used to create _airdrop_ transactions, a token transfer from the drone's account to a client's account.
 
 ## Signing Service
 

docs/src/building-from-source.md

@@ -123,7 +123,7 @@ This will dump all the threads stack traces into gdb.txt
 
 ### Blockstreamer
 
-Solana supports a node type called an _blockstreamer_. This validator variation is intended for applications that need to observe the data plane without participating in transaction validation or ledger replication.
+Solana supports a node type called a _blockstreamer_. This validator variation is intended for applications that need to observe the data plane without participating in transaction validation or ledger replication.
 
 A blockstreamer runs without a vote signer, and can optionally stream ledger entries out to a Unix domain socket as they are processed. The JSON-RPC service still functions as on any other node.
 

docs/src/cli/README.md

@@ -1,5 +1,5 @@
 # Using Solana from the Command-line
 
-This chapter describes the command-line tools for interacting with Solana. One
+This section describes the command-line tools for interacting with Solana. One
 could use these tools to send payments, stake validators, and check account
 balances.

docs/src/cluster/README.md

@@ -1,6 +1,6 @@
 # A Solana Cluster
 
-A Solana cluster is a set of validators working together to serve client transactions and maintain the integrity of the ledger. Many clusters may coexist. When two clusters share a common genesis block, they attempt to converge. Otherwise, they simply ignore the existence of the other. Transactions sent to the wrong one are quietly rejected. In this chapter, we'll discuss how a cluster is created, how nodes join the cluster, how they share the ledger, how they ensure the ledger is replicated, and how they cope with buggy and malicious nodes.
+A Solana cluster is a set of validators working together to serve client transactions and maintain the integrity of the ledger. Many clusters may coexist. When two clusters share a common genesis block, they attempt to converge. Otherwise, they simply ignore the existence of the other. Transactions sent to the wrong one are quietly rejected. In this section, we'll discuss how a cluster is created, how nodes join the cluster, how they share the ledger, how they ensure the ledger is replicated, and how they cope with buggy and malicious nodes.
 
 ## Creating a Cluster
 

docs/src/cluster/fork-generation.md

@@ -1,6 +1,6 @@
 # Fork Generation
 
-The chapter describes how forks naturally occur as a consequence of [leader rotation](leader-rotation.md).
+This section describes how forks naturally occur as a consequence of [leader rotation](leader-rotation.md).
 
 ## Overview
 

docs/src/cluster/stake-delegation-and-rewards.md

@@ -1,6 +1,6 @@
 # Stake Delegation and Rewards
 
-Stakers are rewarded for helping to validate the ledger. They do this by delegating their stake to validator nodes. Those validators do the legwork of replaying the ledger and send votes to a per-node vote account to which stakers can delegate their stakes. The rest of the cluster uses those stake-weighted votes to select a block when forks arise. Both the validator and staker need some economic incentive to play their part. The validator needs to be compensated for its hardware and the staker needs to be compensated for the risk of getting its stake slashed. The economics are covered in [staking rewards](../implemented-proposals/staking-rewards.md). This chapter, on the other hand, describes the underlying mechanics of its implementation.
+Stakers are rewarded for helping to validate the ledger. They do this by delegating their stake to validator nodes. Those validators do the legwork of replaying the ledger and send votes to a per-node vote account to which stakers can delegate their stakes. The rest of the cluster uses those stake-weighted votes to select a block when forks arise. Both the validator and staker need some economic incentive to play their part. The validator needs to be compensated for its hardware and the staker needs to be compensated for the risk of getting its stake slashed. The economics are covered in [staking rewards](../implemented-proposals/staking-rewards.md). This section, on the other hand, describes the underlying mechanics of its implementation.
 
 ## Basic Design
 

docs/src/implemented-proposals/ed_overview/README.md

@@ -10,6 +10,6 @@ These protocol-based rewards, to be distributed to participating validation and
 
 Transaction fees are market-based participant-to-participant transfers, attached to network interactions as a necessary motivation and compensation for the inclusion and execution of a proposed transaction \(be it a state execution or proof-of-replication verification\). A mechanism for long-term economic stability and forking protection through partial burning of each transaction fee is also discussed below.
 
-A high-level schematic of Solana’s crypto-economic design is shown below in **Figure 1**. The specifics of validation-client economics are described in sections: [Validation-client Economics](ed_validation_client_economics/), [State-validation Protocol-based Rewards](ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md), [State-validation Transaction Fees](ed_validation_client_economics/ed_vce_state_validation_transaction_fees.md) and [Replication-validation Transaction Fees](ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md). Also, the chapter titled [Validation Stake Delegation](ed_validation_client_economics/ed_vce_validation_stake_delegation.md) closes with a discussion of validator delegation opportunties and marketplace. Additionally, in [Storage Rent Economics](ed_storage_rent_economics.md), we describe an implementation of storage rent to account for the externality costs of maintaining the active state of the ledger. The [Replication-client Economics](ed_replication_client_economics/) chapter will review the Solana network design for global ledger storage/redundancy and archiver-client economics \([Storage-replication rewards](ed_replication_client_economics/ed_rce_storage_replication_rewards.md)\) along with an archiver-to-validator delegation mechanism designed to aide participant on-boarding into the Solana economy discussed in [Replication-client Reward Auto-delegation](ed_replication_client_economics/ed_rce_replication_client_reward_auto_delegation.md). An outline of features for an MVP economic design is discussed in the [Economic Design MVP](ed_mvp.md) section. Finally, in chapter [Attack Vectors](ed_attack_vectors.md), various attack vectors will be described and potential vulnerabilities explored and parameterized.
+A high-level schematic of Solana’s crypto-economic design is shown below in **Figure 1**. The specifics of validation-client economics are described in sections: [Validation-client Economics](ed_validation_client_economics/), [State-validation Protocol-based Rewards](ed_validation_client_economics/ed_vce_state_validation_protocol_based_rewards.md), [State-validation Transaction Fees](ed_validation_client_economics/ed_vce_state_validation_transaction_fees.md) and [Replication-validation Transaction Fees](ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md). Also, the section titled [Validation Stake Delegation](ed_validation_client_economics/ed_vce_validation_stake_delegation.md) closes with a discussion of validator delegation opportunties and marketplace. Additionally, in [Storage Rent Economics](ed_storage_rent_economics.md), we describe an implementation of storage rent to account for the externality costs of maintaining the active state of the ledger. [Replication-client Economics](ed_replication_client_economics/) will review the Solana network design for global ledger storage/redundancy and archiver-client economics \([Storage-replication rewards](ed_replication_client_economics/ed_rce_storage_replication_rewards.md)\) along with an archiver-to-validator delegation mechanism designed to aide participant on-boarding into the Solana economy discussed in [Replication-client Reward Auto-delegation](ed_replication_client_economics/ed_rce_replication_client_reward_auto_delegation.md). An outline of features for an MVP economic design is discussed in the [Economic Design MVP](ed_mvp.md) section. Finally, in [Attack Vectors](ed_attack_vectors.md), various attack vectors will be described and potential vulnerabilities explored and parameterized.
 
 **Figure 1**: Schematic overview of Solana economic incentive design.

docs/src/implemented-proposals/ed_overview/ed_replication_client_economics/README.md

@@ -2,5 +2,5 @@
 
 **Subject to change.**
 
-Replication-clients should be rewarded for providing the network with storage space. Incentivization of the set of archivers provides data security through redundancy of the historical ledger. Replication nodes are rewarded in proportion to the amount of ledger data storage provided, as proved by successfully submitting Proofs-of-Replication to the cluster.. These rewards are captured by generating and entering Proofs of Replication \(PoReps\) into the PoH stream which can be validated by Validation nodes as described above in the [Replication-validation Transaction Fees](../ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md) chapter.
+Replication-clients should be rewarded for providing the network with storage space. Incentivization of the set of archivers provides data security through redundancy of the historical ledger. Replication nodes are rewarded in proportion to the amount of ledger data storage provided, as proved by successfully submitting Proofs-of-Replication to the cluster.. These rewards are captured by generating and entering Proofs of Replication \(PoReps\) into the PoH stream which can be validated by Validation nodes as described in [Replication-validation Transaction Fees](../ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md).
 

docs/src/implemented-proposals/ed_overview/ed_validation_client_economics/ed_vce_replication_validation_transaction_fees.md

@@ -0,0 +1,11 @@
+# Replication-validation Transaction Fees
+
+**Subject to change.**
+
+As previously mentioned, validator-clients will also be responsible for validating PoReps submitted into the PoH stream by archiver-clients. In this case, validators are providing compute \(CPU/GPU\) and light storage resources to confirm that these replication proofs could only be generated by a client that is storing the referenced PoH leger block.
+
+While replication-clients are incentivized and rewarded through protocol-based rewards schedule \(see [Replication-client Economics](../ed_replication_client_economics/README.md)\), validator-clients will be incentivized to include and validate PoReps in PoH through collection of transaction fees associated with the submitted PoReps and distribution of protocol rewards proportional to the validated PoReps. As will be described in detail in the Section 3.1, replication-client rewards are protocol-based and designed to reward based on a global data redundancy factor. I.e. the protocol will incentivize replication-client participation through rewards based on a target ledger redundancy \(e.g. 10x data redundancy\).
+
+The validation of PoReps by validation-clients is computationally more expensive than state-validation \(detailed in the [Economic Sustainability](../ed_economic_sustainability.md) section\), thus the transaction fees are expected to be proportionally higher.
+
+There are various attack vectors available for colluding validation and replication clients, also described in detail in [Economic Sustainability](../ed_economic_sustainability.md). To protect against various collusion attack vectors, for a given epoch, validator rewards are distributed across participating validation-clients in proportion to the number of validated PoReps in the epoch less the number of PoReps that mismatch the archivers challenge. The PoRep challenge game is described in [Ledger Replication](../../../cluster/ledger-replication.md#the-porep-game). This design rewards validators proportional to the number of PoReps they process and validate, while providing negative pressure for validation-clients to submit lazy or malicious invalid votes on submitted PoReps \(note that it is computationally prohibitive to determine whether a validator-client has marked a valid PoRep as invalid\).

docs/src/introduction.md

@@ -4,9 +4,9 @@
 
 Solana is an open source project implementing a new, high-performance, permissionless blockchain. Solana is also the name of a company headquartered in San Francisco that maintains the open source project.
 
-## About this Book
+## Documentation Overview
 
-This book describes the Solana open source project, a blockchain built from the ground up for scale. The book covers why Solana is useful, how to use it, how it works, and why it will continue to work long after the company Solana closes its doors. The goal of the Solana architecture is to demonstrate there exists a set of software algorithms that when used in combination to implement a blockchain, removes software as a performance bottleneck, allowing transaction throughput to scale proportionally with network bandwidth. The architecture goes on to satisfy all three desirable properties of a proper blockchain: it is scalable, secure and decentralized.
+The Solana docs describe the Solana open source project, a blockchain built from the ground up for scale. They cover why Solana is useful, how to use it, how it works, and why it will continue to work long after the company Solana closes its doors. The goal of the Solana architecture is to demonstrate there exists a set of software algorithms that when used in combination to implement a blockchain, removes software as a performance bottleneck, allowing transaction throughput to scale proportionally with network bandwidth. The architecture goes on to satisfy all three desirable properties of a proper blockchain: it is scalable, secure and decentralized.
 
 The architecture describes a theoretical upper bound of 710 thousand transactions per second \(tps\) on a standard gigabit network and 28.4 million tps on 40 gigabit. Furthermore, the architecture supports safe, concurrent execution of programs authored in general purpose programming languages such as C or Rust.
 

docs/src/proposals/README.md

@@ -1,4 +1,3 @@
 # Accepted Design Proposals
 
-The following architectural proposals have been accepted by the Solana team, but are not yet fully implemented. The proposals may be implemented as described, implemented differently as issues in the designs become evident, or not implemented at all. If implemented, the descriptions will be moved from this section to earlier chapters in a future version of this book.
-
+The following architectural proposals have been accepted by the Solana team, but are not yet fully implemented. The proposals may be implemented as described, implemented differently as issues in the designs become evident, or not implemented at all. If implemented, the proposal will be moved to [Implemented Proposals](../implemented-proposals/README.md) and the details will be added to relevant sections of the docs.