diff --git a/book/src/programs.md b/book/src/programs.md index 14177970fe..6b6ad83612 100644 --- a/book/src/programs.md +++ b/book/src/programs.md @@ -1,32 +1,46 @@ # Programming Model -With the Solana runtime, we can execute on-chain programs concurrently, and -written in the client’s choice of programming language. +The Solana *runtime* can execute untrusted on-chain programs written in any +programming language that can target the Berkley Packet Filter (BPF) safe +execution environment. The Solana SDK offers the best support for C programs, +which is compiled to BPF using the [LLVM compiler +infrastructure](https://llvm.org). Alternatively, a client might choose to +bypass LLVM and use Python, Lua or C++ to generate BPF directly via the [BPF +Compiler Collection](https://github.com/iovisor/bcc) (BCC). -## Client Interactions with Solana +## Deploying Programs to a Cluster SDK tools -As shown in the diagram above an untrusted client, creates a program in the -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. +As shown in the diagram above a client creates a program and compiles it to an +ELF shared object containing BPF bytecode and sends it to the Solana cluster. +The cluster stores the program locally and makes it available to clients via a +*program ID*. The program ID is a public key generated by the client and is +used to reference the program in subsequent transactions. -## Persistent Storage +## Interacting with On-chain Programs -Solana supports several kinds of persistent storage, called *accounts*: +After a program has been deployed, a client utilizes it by sending transactions +to the Solana cluster. A transaction contains one or more *instructions*. Each +instruction references the program ID that coresponds to the program that the +runtime should use to execute it. Instructions are executed atomically. If any +instruction is invalid, any changes made within the transaction are discarded. + +## Storing State between Transactions + +If the the program needs to store state between transactions, it does so using +*accounts*. Solana supports several kinds of accounts: 1. Executable 2. Owned by a client 3. Owned by a program 4. Credit-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 credit-only accounts are discarded -unless the write was to credit tokens. Any user may credit other accounts -tokens, regardless of account permission. +All accounts are identified by public keys and may hold arbitrary data. When +the client sends messages to programs, it requests access to accounts using +those keys. The runtime loads the account 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 credit-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/book/src/terminology.md b/book/src/terminology.md index 859086be20..dd2c0afabd 100644 --- a/book/src/terminology.md +++ b/book/src/terminology.md @@ -125,6 +125,10 @@ The number of [fullnodes](#fullnode) participating in a [cluster](#cluster). The code that interprets [instructions](#instruction). +#### program ID + +The public key of the [account](#account) containing a [program](#program). + #### public key The public key of a [keypair](#keypair). @@ -204,6 +208,10 @@ A type of [client](#client) that can verify it's pointing to a valid [cluster](# Millions of [instructions](#instruction) per second. +#### runtime + +The component of a [fullnode](#fullnode) responsible for [program](#program) execution. + #### thin client A type of [client](#client) that trusts it is communicating with a valid [cluster](#cluster).