From 2c11bf2e661273d48716bf5d7a8b07636310c7b2 Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Sat, 17 Nov 2018 18:01:21 -0700 Subject: [PATCH] Various book cleanup * Merge Leader and Validator diagrams * New sdk-tools diagram * Move terminology to just after introduction * Purge use of LAMPORT as an acronym * Add notes about persistent storage --- art/fullnode.bob | 65 ++----- art/{lamport.bob => runtime.bob} | 0 art/sdk-tools.bob | 44 ++--- src/SUMMARY.md | 3 +- src/img/fullnode.svg | 273 ++++----------------------- src/img/{lamport.svg => runtime.svg} | 0 src/img/sdk-tools.svg | 205 +++++++++++++------- src/programs.md | 42 +++-- src/runtime.md | 2 +- src/terminology.md | 5 +- 10 files changed, 248 insertions(+), 391 deletions(-) rename art/{lamport.bob => runtime.bob} (100%) rename src/img/{lamport.svg => runtime.svg} (100%) diff --git a/art/fullnode.bob b/art/fullnode.bob index 50d4e277f2..1a3b0586e1 100644 --- a/art/fullnode.bob +++ b/art/fullnode.bob @@ -1,46 +1,21 @@ - .---------------------. - | Leader | - | | - .--------. | .----------------. | - | |---->| | | - | Client | | | JsonRpcService | | - | |<----| | | - `----+---` | `----------------` | - | | ^ | - | | | | - | | .--+---. | - | | | Bank | | - | | `------` | - | | ^ | - | | | | .------------. - | | .--+--. .-----. | | | - `-------->| Tpu +-->| Ncp +------>| Validators | - | `-----` `-----` | | | - | | `------------` - `---------------------` + .------------------------. + | Fullnode | + | | + .--------. | .----------------. | + | |---->| | | + | Client | | | JsonRpcService | | + | |<----| | | + `----+---` | `----------------` | + | | ^ | + | | | | + | | .--+---. .-----. | + | | | Bank |<--| Tvu | | + | | `------` `-----` | + | | ^ ^ | + | | | | | .------------. + | | .--+--. .--+--. | | | + `-------->| Tpu +-->| Ncp |<-------->| Validators | + | `-----` `-----` | | | + | | `------------` + `------------------------` - .-------------------------------. - | Validator | - | | - .--------. | .----------------. | - | |-------------->| | | - | Client | | | JsonRpcService | | - | |<--------------| | | - `--------` | `----------------` | - | ^ | - | | | - | .--+---. | - | | Bank | | - | `------` | - | ^ | - .--------. | | | .------------. - | | | .--+--. | | | - | Leader |<------------->| Tvu +<--------------->| | - | | | `-----` | | Validators | - | | | ^ | | | - | | | | | | | - | | | .--+--. | | | - | |<------------->| Ncp +<--------------->| | - | | | `-----` | | | - `--------` | | `------------` - `-------------------------------` diff --git a/art/lamport.bob b/art/runtime.bob similarity index 100% rename from art/lamport.bob rename to art/runtime.bob diff --git a/art/sdk-tools.bob b/art/sdk-tools.bob index 5bbac7146b..5ad2b5dc52 100644 --- a/art/sdk-tools.bob +++ b/art/sdk-tools.bob @@ -1,24 +1,20 @@ - +---------------------+ +---------------------+ - | | | | - | +------------+ | | +------------+ | - | | | | | | | | - | | frontend | | | | verifier | | - | | | | | | | | - | +-----+------+ | | +-----+------+ | - | | | | | | - | | | | | | - | +-----+------+ | | +-----+------+ | - | | | | | | | | - | | llvm | | | | loader | | - | | | +------>+ | | | - | +-----+------+ | | +-----+------+ | - | | | | | | - | | | | | | - | +-----+------+ | | +-----+------+ | - | | | | | | | | - | | ELF | | | | runtime | | - | | | | | | | | - | +------------+ | | +------------+ | - | | | | - | client | | solana | - +---------------------+ +---------------------+ + + .----------------------------------------. + | Solana Runtime | + | | + | .------------. .------------. | + | | | | | | + .-------->| Verifier +-->| Accounts | | + | | | | | | | + .----------. | | `------------` `------------` | + | +--------` | ^ | + | Client | | LoadAccounts | | + | +--------. | .----------------` | + `----------` | | | | + | | .------+-----. .-------------. | + | | | | | | | + `-------->| Loader +-->| Interpreter | | + | | | | | | + | `------------` `-------------` | + | | + `----------------------------------------` diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2f20e32375..bd4f35ab0b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,6 +2,8 @@ - [Introduction](introduction.md) +- [Terminology](terminology.md) + - [Synchronization](synchronization.md) - [Introduction to VDFs](vdf.md) - [Proof of History](poh.md) @@ -22,7 +24,6 @@ ## Appendix - [Appendix](appendix.md) - - [Terminology](terminology.md) - [JSON RPC API](jsonrpc-api.md) - [solana-wallet CLI](wallet.md) diff --git a/src/img/fullnode.svg b/src/img/fullnode.svg index 874fb71e96..bed2672213 100644 --- a/src/img/fullnode.svg +++ b/src/img/fullnode.svg @@ -1,4 +1,4 @@ - + @@ -56,7 +56,7 @@ } - + @@ -74,32 +74,6 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -109,31 +83,10 @@ - - - - - - - - - - - - - - - - - - - - - @@ -148,37 +101,12 @@ - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - + + @@ -238,12 +166,18 @@ + + + + - + + + @@ -251,151 +185,55 @@ - - - + + + - - - + + - - - + + - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - + - - - + + - + - - + - - + + + - + + - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + @@ -403,23 +241,8 @@ Client - -Client - - - - -Leader - - - -Leader - - - - -Validator +Fullnode @@ -443,32 +266,12 @@ Ncp - -JsonRpcService - - - - -Bank - - - - + Tvu - -Ncp - - - - -Validators - - - - + Validators diff --git a/src/img/lamport.svg b/src/img/runtime.svg similarity index 100% rename from src/img/lamport.svg rename to src/img/runtime.svg diff --git a/src/img/sdk-tools.svg b/src/img/sdk-tools.svg index e9f946986f..629a3feaa3 100644 --- a/src/img/sdk-tools.svg +++ b/src/img/sdk-tools.svg @@ -1,4 +1,4 @@ - + @@ -56,109 +56,182 @@ } - + - - - - - - + + + - - - - - - - - + + - - - - - - - + + - - - + + + + + + + - - - - - - + + - - - - - - - - + + - - - - - - - + - - - + - -frontend + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Client - -llvm + +Verifier - -ELF + +Loader - -client + +Solana - -verifier + +LoadAccounts - -loader + +Runtime - -runtime + +Interpreter - -solana + +Accounts diff --git a/src/programs.md b/src/programs.md index 334927231e..97a6869506 100644 --- a/src/programs.md +++ b/src/programs.md @@ -1,26 +1,34 @@ -# The LAMPORT execution environment +# The Solana SDK ## Introduction -With LAMPORT (Language-Agnostic, Memory-oriented, Parallel-friendly, Optimized -Run-Time), we can execute smart contracts concurrently, and written in the -client’s choice of programming language. Furthermore, we demonstrate Solana’s -built-in smart contract language Budget can target LAMPORT without any loss in -performance. The two features that allow LAMPORT to work: +With the Solana runtime, we can execute on-chain programs concurrently, and +written in the client’s choice of programming language. -Client-owned memory identified by public keys. By declaring ownership upfront -and separating the program’s state from the program, the runtime knows which -contracts can safely be executed concurrently. Solana’s blockchain-encoded VDF -tells validator nodes at precisely what times they need to end up in the same -state. Between those times, they are free to introduce non-deterministic -behavior as-needed to improve execution times. - -## Toolchain Stack +## Client interactions with Solana SDK tools As shown in the diagram above an untrusted client, creates a program in the -front-end language of her choice, (like C/C++/Rust/Lua), and compiles it with -LLVM to a position independent shared object ELF, targeting BPF bytecode. -Solana will safely load and execute the ELF. +language of their choice, (i.e. C/C++/Rust/Lua), and compiles it with LLVM to a +position independent shared object ELF, targeting BPF bytecode, and sends it to +the Solana cluster. Next, the client sends messages to the Solana cluster, +which target that program. The Solana runtime loads the previously submitted +ELF and passes it the client's message for interpretation. +## Persistent Storage + +Solana supports several kinds of persistent storage, called *accounts*: + +1. Executable +2. Writable by a client +3. Writable by a program +4. Read-only + +All accounts are identified by public keys and may hold arbirary data. +When the client sends messages to programs, it requests access to storage +using those keys. The runtime loads the account data and passes it to the +program. The runtime also ensures accounts aren't written to if not owned +by the client or program. Any writes to read-only accounts are discarded +unless the write was to credit tokens. Any user may credit other accounts +tokens, regardless of account permission. diff --git a/src/runtime.md b/src/runtime.md index b74f04bc42..4a715d4096 100644 --- a/src/runtime.md +++ b/src/runtime.md @@ -39,7 +39,7 @@ routs them to the `program_id` entry point. Transactions are batched and processed in a pipeline -LAMPORT pipeline +Runtime pipeline At the `execute` stage, the loaded pages have no data dependencies, so all the programs can be executed in parallel. diff --git a/src/terminology.md b/src/terminology.md index b627f768fe..718b9d05ba 100644 --- a/src/terminology.md +++ b/src/terminology.md @@ -1,4 +1,4 @@ -## Appendix A: Terminology +## Terminology ### Teminology Currently in Use @@ -12,7 +12,6 @@ The following list contains words commonly used throughout the Solana architectu * entry - an entry on the ledger - either a tick or a transactions entry * instruction - the smallest unit of a program that a client can include in a transaction * keypair - a public and secret key -* mips - millions of instructions per second * node count - the number of fullnodes participating in a cluster * program - the code that interprets instructions * pubkey - the public key of a keypair @@ -28,6 +27,8 @@ The following list contains words commonly used throughout the Solana architectu The following keywords do not have any functionality but are reserved by Solana for potential future use. +* epoch - the time in which a leader schedule is valid * mips - millions of instructions per second * public key - We currently use `pubkey` +* slot - the time in which a single leader may produce entries * secret key - Users currently only use `keypair`