From c83538a60c89469b5c0e820a7f7e73de7fcea175 Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Wed, 12 Dec 2018 09:13:04 -0700 Subject: [PATCH] Add new proposal process And move replication and enclave proposals there to get a feel for how it'd look. --- CONTRIBUTING.md | 42 ++++++-------- book/src/SUMMARY.md | 4 ++ rfcs/0009-enclave.md => book/src/enclave.md | 0 .../src/ledger-replication.md | 0 book/src/proposals.md | 7 +++ book/src/terminology.md | 58 +------------------ 6 files changed, 33 insertions(+), 78 deletions(-) rename rfcs/0009-enclave.md => book/src/enclave.md (100%) rename rfcs/0003-storage.md => book/src/ledger-replication.md (100%) create mode 100644 book/src/proposals.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 344c0cc399..0861eb8504 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ Rust coding conventions * For function and method names, use `_`. For unit tests, that verb should always be `test` and for benchmarks the verb should always be `bench`. Avoid namespacing - function names with some arbitrary word. Avoid abreviating words in function names. + function names with some arbitrary word. Avoid abbreviating words in function names. * As they say, "When in Rome, do as the Romans do." A good patch should acknowledge the coding conventions of the code that surrounds it, even in the case where that code has not yet been @@ -43,31 +43,27 @@ Terminology 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. -Some terms we currently use regularly in the codebase: - -* fullnode: n. A fully participating network node. -* hash: n. A SHA-256 Hash. -* keypair: n. A Ed25519 key-pair, containing a public and private key. -* pubkey: n. The public key of a Ed25519 key-pair. -* sigverify: v. To verify a Ed25519 digital signature. +[Terms currently in use](book/src/terminology.md) Proposing architectural changes --- -Solana's architecture is described by a book generated from markdown files in the `src/` directory, -currently maintained by @garious. To change the architecture, you'll need to at least propose a change -with an RFC document, and create an issue to track its implementation. Here's the full process: +Solana's architecture is described by a book generated from markdown files in +the `book/src/` directory, maintained by an *editor* (currently @garious). To +change the architecture, you'll need to at least propose a change the content +under the [Proposed +Changes](https://solana-labs.github.io/solana/proposals.html) chapter. Here's +the full process: -1. Propose to a change to the architecture by creating a PR that adds a markdown document called an RFC - (standing for "request for comments") to the directory `rfcs/`. Add at least the maintainer of the - markdown book as a reviewer. -2. The PR being merged indicates your proposed change was accepted and that the Solana maintainers - support your plan of attack. Next, create an issue to track its implementation and create a PR - that updates the RFC with a link to the issue. This link allows anyone to quickly check the - implementation status of any RFC. -3. Submit PRs that implement the RFC. Be sure to reference the issue created above in your PR description. - Feel free to update the RFC as the implementation reveals the need for tweaks to the architecture, - but if you do, be sure to add the maintainer of the markdown book as a reviewer to your PR. -4. Once the implementation is complete, close the issue. Depending on the scope of the RFC, the maintainer - of markdown book may then create a separate ticket to integrate the RFC into the book. +1. Propose to a change to the architecture 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 the editor and any relevant + *maintainers* to the PR review. +2. The PR being merged indicates your proposed change was accepted and that the + editor and maintainers support your plan of attack. +3. Submit PRs that implement the proposal. When the implementation reveals the + need for tweaks to the architecture, be sure to update the proposal and have + that change reviewed by the same people as in step 1. +4. Once the implementation is complete, the editor will then work to integrate + the document into the book. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e22ad9cbea..0c03043eca 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -19,6 +19,10 @@ - [Gossip Service](gossip.md) - [The Runtime](runtime.md) +- [Proposed Architectural Changes](proposals.md) + - [Ledger Replication](ledger-replication.md) + - [Secure Enclave](enclave.md) + ## Appendix - [Appendix](appendix.md) diff --git a/rfcs/0009-enclave.md b/book/src/enclave.md similarity index 100% rename from rfcs/0009-enclave.md rename to book/src/enclave.md diff --git a/rfcs/0003-storage.md b/book/src/ledger-replication.md similarity index 100% rename from rfcs/0003-storage.md rename to book/src/ledger-replication.md diff --git a/book/src/proposals.md b/book/src/proposals.md new file mode 100644 index 0000000000..a5b884e84f --- /dev/null +++ b/book/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 descriptions will be moved from this +section to earlier chapters in a future version of this book. diff --git a/book/src/terminology.md b/book/src/terminology.md index 1e841167bc..3c44be495d 100644 --- a/book/src/terminology.md +++ b/book/src/terminology.md @@ -152,11 +152,10 @@ The public key of the [account](#account) containing a [program](#program). The public key of a [keypair](#keypair). -#### replicator +#### runtime -A type of [client](#client) that stores [ledger](#ledger) segments and -periodically submits storage proofs to the cluster; not a -[fullnode](#fullnode). +The component of a [fullnode](#fullnode) responsible for [program](#program) +execution. #### secret key @@ -225,11 +224,6 @@ for potential future use. A fraction of a [block](#block); the smallest unit sent between [fullnodes](#fullnode). -#### CBC block - -Smallest encrypted chunk of ledger, an encrypted ledger segment would be made of -many CBC blocks; `ledger_segment_size / cbc_block_size` to be exact. - #### curio A scarce, non-fungible member of a set of curios. @@ -239,16 +233,6 @@ A scarce, non-fungible member of a set of curios. The time, i.e. number of [slots](#slot), for which a [leader schedule](#leader-schedule) is valid. -#### fake storage proof - -A proof which has the same format as a storage proof, but the sha state is -actually from hashing a known ledger value which the storage client can reveal -and is also easily verifiable by the network on-chain. - -#### ledger segment - -A sequence of [blocks](#block). - #### light client A type of [client](#client) that can verify it's pointing to a valid @@ -258,42 +242,6 @@ A type of [client](#client) that can verify it's pointing to a valid Millions of [instructions](#instruction) per second. -#### runtime - -The component of a [fullnode](#fullnode) responsible for [program](#program) -execution. - -#### storage proof - -A set of SHA hash states which is constructed by sampling the encrypted version -of the stored [ledger segment](#ledger-segment) at certain offsets. - -#### storage proof challenge - -A [transaction](#transaction) from a [replicator](#replicator) that verifiably -proves that a [validator](#validator) [confirmed](#storage-proof-confirmation) -a [fake proof](#fake-storage-proof). - -#### storage proof claim - -A [transaction](#transaction) from a [validator](#validator) which is after the -timeout period given from the [storage proof -confirmation](#storage-proof-confirmation) and which no successful -[challenges](#storage-proof-challenge) have been observed which rewards the -parties of the [storage proofs](#storage-proof) and confirmations. - -#### storage proof confirmation - -A [transaction](#transaction) from a [validator](#validator) which indicates -the set of [real](#storage-proof) and [fake proofs](#fake-storage-proof) -submitted by a [replicator](#replicator). The transaction would contain a list -of proof hash values and a bit which says if this hash is valid or fake. - -#### storage validation capacity - -The number of keys and samples that a [validator](#validator) can verify each -storage epoch. - #### thin client A type of [client](#client) that trusts it is communicating with a valid