diff --git a/.gitignore b/.gitignore index 2dbde8e1bc..de2f9e697b 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,9 @@ /book/html/ /book/src/img/ /book/src/tests.ok +/proposals/html/ +/proposals/src/img/ +/proposals/src/tests.ok **/*.rs.bk .cargo diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3daae2cef..e8095b892b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,16 +92,13 @@ understood. Avoid introducing new 3-letter terms, which can be confused with 3-l 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://solana-labs.github.io/book-edge/proposals.html) chapter. -Here's the full process: +Solana's design proposals are part of a book generated from markdown files in +the `proposals/src/` directory. To add a design proposal: 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 review. + directory `proposals/src/` and references it from the [table of + contents](proposals/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. 3. Submit PRs that implement the proposal. When the implementation reveals the diff --git a/book/README.md b/book/README.md index f7aa8bb762..51fd9681bf 100644 --- a/book/README.md +++ b/book/README.md @@ -1,7 +1,7 @@ Building the Solana book --- -Install the book's dependnecies, build, and test the book: +Install the book's dependencies, build, and test the book: ```bash $ ./build.sh diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 7fb326fdb1..0e6866ab7f 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -33,31 +33,3 @@ - [JSON RPC API](jsonrpc-api.md) - [JavaScript API](javascript-api.md) - [solana-wallet CLI](wallet.md) - -- [Accepted Design Proposals](proposals.md) - - [Ledger Replication](ledger-replication-to-implement.md) - - [Secure Vote Signing](vote-signing-to-implement.md) - - [Staking Rewards](staking-rewards.md) - - [Passive Stake Delegation and Rewards](passive-stake-delegation-and-rewards.md) - - [Fork Selection](fork-selection.md) - - [Reliable Vote Transmission](reliable-vote-transmission.md) - - [Persistent Account Storage](persistent-account-storage.md) - - [Cluster Economics](ed_overview.md) - - [Validation-client Economics](ed_validation_client_economics.md) - - [State-validation Protocol-based Rewards](ed_vce_state_validation_protocol_based_rewards.md) - - [State-validation Transaction Fees](ed_vce_state_validation_transaction_fees.md) - - [Replication-validation Transaction Fees](ed_vce_replication_validation_transaction_fees.md) - - [Validation Stake Delegation](ed_vce_validation_stake_delegation.md) - - [Replication-client Economics](ed_replication_client_economics.md) - - [Storage-replication Rewards](ed_rce_storage_replication_rewards.md) - - [Replication-client Reward Auto-delegation](ed_rce_replication_client_reward_auto_delegation.md) - - [Economic Sustainability](ed_economic_sustainability.md) - - [Attack Vectors](ed_attack_vectors.md) - - [Economic Design MVP](ed_mvp.md) - - [References](ed_references.md) - - [Cluster Test Framework](cluster-test-framework.md) - - [Testing Programs](testing-programs.md) - -- [Implemented Design Proposals](implemented-proposals.md) - - [Leader-to-Leader Transition](leader-leader-transition.md) - - [Leader-to-Validator Transition](leader-validator-transition.md) diff --git a/book/src/proposals.md b/book/src/proposals.md deleted file mode 100644 index a5b884e84f..0000000000 --- a/book/src/proposals.md +++ /dev/null @@ -1,7 +0,0 @@ -# Proposed Architectural Changes - -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. diff --git a/ci/test-checks.sh b/ci/test-checks.sh index 21e33a0e19..f511d52d02 100755 --- a/ci/test-checks.sh +++ b/ci/test-checks.sh @@ -15,5 +15,6 @@ _ cargo clippy --all -- --deny=warnings _ ci/audit.sh _ ci/nits.sh _ book/build.sh +_ proposals/build.sh echo --- ok diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 0000000000..eeeb4655d1 --- /dev/null +++ b/proposals/README.md @@ -0,0 +1,26 @@ +Building the Solana Design Proposals HTML +--- + +Install the book's dependencies, build, and test the book: + +```bash +$ ./build.sh +``` + +Run any Rust tests in the markdown: + +```bash +$ make test +``` + +Render markdown as HTML: + +```bash +$ make build +``` + +Render and view the book: + +```bash +$ make open +``` diff --git a/proposals/book.toml b/proposals/book.toml new file mode 100644 index 0000000000..6e0c23d233 --- /dev/null +++ b/proposals/book.toml @@ -0,0 +1,10 @@ +[book] +title = "Solana Design Proposals" +authors = ["The Solana Team"] + +[build] +build-dir = "html" +create-missing = false + +[output.html] +theme = "../book/theme" diff --git a/proposals/build.sh b/proposals/build.sh new file mode 100755 index 0000000000..14063a5279 --- /dev/null +++ b/proposals/build.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +set -e + +cd "$(dirname "$0")" + +cargo_install_unless() { + declare crate=$1 + shift + + "$@" > /dev/null 2>&1 || \ + cargo install "$crate" +} + +export PATH=$CARGO_HOME/bin:$PATH +cargo_install_unless mdbook mdbook --help +cargo_install_unless svgbob_cli svgbob --help + +make -j"$(nproc)" diff --git a/proposals/makefile b/proposals/makefile new file mode 100644 index 0000000000..14a5aeac2d --- /dev/null +++ b/proposals/makefile @@ -0,0 +1,33 @@ +BOB_SRCS=$(wildcard art/*.bob) +MD_SRCS=$(wildcard src/*.md) + +SVG_IMGS=$(BOB_SRCS:art/%.bob=src/img/%.svg) + +all: html/index.html + +test: src/tests.ok + +open: all + mdbook build --open + +watch: $(SVG_IMGS) + mdbook watch + +src/img/%.svg: art/%.bob + @mkdir -p $(@D) + svgbob < $< > $@ + +src/%.md: %.md + @mkdir -p $(@D) + @cp $< $@ + +src/tests.ok: $(SVG_IMGS) $(MD_SRCS) + mdbook test + touch $@ + +html/index.html: src/tests.ok + mdbook build + +clean: + rm -f $(SVG_IMGS) src/tests.ok + rm -rf html diff --git a/proposals/src/SUMMARY.md b/proposals/src/SUMMARY.md new file mode 100644 index 0000000000..5dc9b92c84 --- /dev/null +++ b/proposals/src/SUMMARY.md @@ -0,0 +1,29 @@ +# Solana Design Proposals + +- [Accepted Design Proposals](proposals.md) + - [Ledger Replication](ledger-replication-to-implement.md) + - [Secure Vote Signing](vote-signing-to-implement.md) + - [Staking Rewards](staking-rewards.md) + - [Passive Stake Delegation and Rewards](passive-stake-delegation-and-rewards.md) + - [Fork Selection](fork-selection.md) + - [Reliable Vote Transmission](reliable-vote-transmission.md) + - [Persistent Account Storage](persistent-account-storage.md) + - [Cluster Economics](ed_overview.md) + - [Validation-client Economics](ed_validation_client_economics.md) + - [State-validation Protocol-based Rewards](ed_vce_state_validation_protocol_based_rewards.md) + - [State-validation Transaction Fees](ed_vce_state_validation_transaction_fees.md) + - [Replication-validation Transaction Fees](ed_vce_replication_validation_transaction_fees.md) + - [Validation Stake Delegation](ed_vce_validation_stake_delegation.md) + - [Replication-client Economics](ed_replication_client_economics.md) + - [Storage-replication Rewards](ed_rce_storage_replication_rewards.md) + - [Replication-client Reward Auto-delegation](ed_rce_replication_client_reward_auto_delegation.md) + - [Economic Sustainability](ed_economic_sustainability.md) + - [Attack Vectors](ed_attack_vectors.md) + - [Economic Design MVP](ed_mvp.md) + - [References](ed_references.md) + - [Cluster Test Framework](cluster-test-framework.md) + - [Testing Programs](testing-programs.md) + +- [Implemented Design Proposals](implemented-proposals.md) + - [Leader-to-Leader Transition](leader-leader-transition.md) + - [Leader-to-Validator Transition](leader-validator-transition.md) diff --git a/book/src/cluster-test-framework.md b/proposals/src/cluster-test-framework.md similarity index 100% rename from book/src/cluster-test-framework.md rename to proposals/src/cluster-test-framework.md diff --git a/book/src/ed_attack_vectors.md b/proposals/src/ed_attack_vectors.md similarity index 100% rename from book/src/ed_attack_vectors.md rename to proposals/src/ed_attack_vectors.md diff --git a/book/src/ed_economic_sustainability.md b/proposals/src/ed_economic_sustainability.md similarity index 100% rename from book/src/ed_economic_sustainability.md rename to proposals/src/ed_economic_sustainability.md diff --git a/book/src/ed_mvp.md b/proposals/src/ed_mvp.md similarity index 100% rename from book/src/ed_mvp.md rename to proposals/src/ed_mvp.md diff --git a/book/src/ed_overview.md b/proposals/src/ed_overview.md similarity index 100% rename from book/src/ed_overview.md rename to proposals/src/ed_overview.md diff --git a/book/src/ed_rce_replication_client_reward_auto_delegation.md b/proposals/src/ed_rce_replication_client_reward_auto_delegation.md similarity index 100% rename from book/src/ed_rce_replication_client_reward_auto_delegation.md rename to proposals/src/ed_rce_replication_client_reward_auto_delegation.md diff --git a/book/src/ed_rce_storage_replication_rewards.md b/proposals/src/ed_rce_storage_replication_rewards.md similarity index 100% rename from book/src/ed_rce_storage_replication_rewards.md rename to proposals/src/ed_rce_storage_replication_rewards.md diff --git a/book/src/ed_references.md b/proposals/src/ed_references.md similarity index 100% rename from book/src/ed_references.md rename to proposals/src/ed_references.md diff --git a/book/src/ed_replication_client_economics.md b/proposals/src/ed_replication_client_economics.md similarity index 100% rename from book/src/ed_replication_client_economics.md rename to proposals/src/ed_replication_client_economics.md diff --git a/book/src/ed_validation_client_economics.md b/proposals/src/ed_validation_client_economics.md similarity index 100% rename from book/src/ed_validation_client_economics.md rename to proposals/src/ed_validation_client_economics.md diff --git a/book/src/ed_vce_replication_validation_transaction_fees.md b/proposals/src/ed_vce_replication_validation_transaction_fees.md similarity index 100% rename from book/src/ed_vce_replication_validation_transaction_fees.md rename to proposals/src/ed_vce_replication_validation_transaction_fees.md diff --git a/book/src/ed_vce_state_validation_protocol_based_rewards.md b/proposals/src/ed_vce_state_validation_protocol_based_rewards.md similarity index 100% rename from book/src/ed_vce_state_validation_protocol_based_rewards.md rename to proposals/src/ed_vce_state_validation_protocol_based_rewards.md diff --git a/book/src/ed_vce_state_validation_transaction_fees.md b/proposals/src/ed_vce_state_validation_transaction_fees.md similarity index 100% rename from book/src/ed_vce_state_validation_transaction_fees.md rename to proposals/src/ed_vce_state_validation_transaction_fees.md diff --git a/book/src/ed_vce_validation_stake_delegation.md b/proposals/src/ed_vce_validation_stake_delegation.md similarity index 100% rename from book/src/ed_vce_validation_stake_delegation.md rename to proposals/src/ed_vce_validation_stake_delegation.md diff --git a/book/src/fork-selection.md b/proposals/src/fork-selection.md similarity index 100% rename from book/src/fork-selection.md rename to proposals/src/fork-selection.md diff --git a/book/src/img/porep_reward.png b/proposals/src/img/porep_reward.png similarity index 100% rename from book/src/img/porep_reward.png rename to proposals/src/img/porep_reward.png diff --git a/book/src/img/solana_economic_design.png b/proposals/src/img/solana_economic_design.png similarity index 100% rename from book/src/img/solana_economic_design.png rename to proposals/src/img/solana_economic_design.png diff --git a/book/src/img/validation_client_interest_rates.png b/proposals/src/img/validation_client_interest_rates.png similarity index 100% rename from book/src/img/validation_client_interest_rates.png rename to proposals/src/img/validation_client_interest_rates.png diff --git a/book/src/implemented-proposals.md b/proposals/src/implemented-proposals.md similarity index 100% rename from book/src/implemented-proposals.md rename to proposals/src/implemented-proposals.md diff --git a/book/src/leader-leader-transition.md b/proposals/src/leader-leader-transition.md similarity index 100% rename from book/src/leader-leader-transition.md rename to proposals/src/leader-leader-transition.md diff --git a/book/src/leader-validator-transition.md b/proposals/src/leader-validator-transition.md similarity index 100% rename from book/src/leader-validator-transition.md rename to proposals/src/leader-validator-transition.md diff --git a/book/src/ledger-replication-to-implement.md b/proposals/src/ledger-replication-to-implement.md similarity index 100% rename from book/src/ledger-replication-to-implement.md rename to proposals/src/ledger-replication-to-implement.md diff --git a/book/src/passive-stake-delegation-and-rewards.md b/proposals/src/passive-stake-delegation-and-rewards.md similarity index 100% rename from book/src/passive-stake-delegation-and-rewards.md rename to proposals/src/passive-stake-delegation-and-rewards.md diff --git a/book/src/persistent-account-storage.md b/proposals/src/persistent-account-storage.md similarity index 100% rename from book/src/persistent-account-storage.md rename to proposals/src/persistent-account-storage.md diff --git a/proposals/src/proposals.md b/proposals/src/proposals.md new file mode 100644 index 0000000000..d55dd9ae6f --- /dev/null +++ b/proposals/src/proposals.md @@ -0,0 +1,7 @@ +# Proposed Architectural Changes + +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 they will be moved from this +section to the following one in a future version of this book. diff --git a/book/src/reliable-vote-transmission.md b/proposals/src/reliable-vote-transmission.md similarity index 100% rename from book/src/reliable-vote-transmission.md rename to proposals/src/reliable-vote-transmission.md diff --git a/book/src/staking-rewards.md b/proposals/src/staking-rewards.md similarity index 100% rename from book/src/staking-rewards.md rename to proposals/src/staking-rewards.md diff --git a/book/src/testing-programs.md b/proposals/src/testing-programs.md similarity index 100% rename from book/src/testing-programs.md rename to proposals/src/testing-programs.md diff --git a/book/src/vote-signing-to-implement.md b/proposals/src/vote-signing-to-implement.md similarity index 100% rename from book/src/vote-signing-to-implement.md rename to proposals/src/vote-signing-to-implement.md