diff --git a/book/src/programs.md b/book/src/programs.md index 02aecb2302..97a65674c9 100644 --- a/book/src/programs.md +++ b/book/src/programs.md @@ -15,7 +15,7 @@ Compiler Collection](https://github.com/iovisor/bcc) (BCC). 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 +*program ID*. The program ID is a *public key* generated by the client and is used to reference the program in subsequent transactions. ## Interacting with On-chain Programs @@ -31,9 +31,9 @@ instruction is invalid, any changes made within the transaction are discarded. If the program needs to store state between transactions, it does so using *accounts*. Accounts are similar to files in operating systems such as Linux. Like files, an account may hold arbitrary data and that data persists beyond -the liftime of a program. Also like files, an account includes metadata that +the lifetime of a program. Also like files, an account includes metadata that tells the runtime who is allowed to access the data and how. Unlike files, the -account includes metadata for the liftime of the file. That lifetime is +account includes metadata for the lifetime of the file. That lifetime is expressed in "tokens", which is a number of fractional native tokens, called *lamports*. Accounts are held in validator memory and pay "rent" to stay there. Each fullnode periodically scan all accounts and collects rent. Any account @@ -44,16 +44,24 @@ programs. For example, programs compiled to BPF are marked executable and loaded by the BPF loader. No program is allowed to modify the contents of an executable account. -Accounts also include "owner" metadata. The owner is the program ID. The -runtime grants the program write access to the account if its ID is the account -owner. If an account is not owned by a program, the program is permitted to -read its data and credit the account. There's one exception, however, accounts -owned by the `SystemProgram` may be written to and debited if the account -holder signed the transaction. +Accounts also include "owner" metadata. The owner is a program ID. The runtime +grants the program write access to the account if its ID matches the owner. If +an account is not owned by a program, the program is permitted to read its data +and credit the account. -Accounts are identified by client-generated public keys. When the client sends -transactions to programs, it requests access to accounts using those keys. The -runtime loads the account and passes it to the program. After the program -finishes executing, the runtime uses the account metadata to verify that none -of the access rules were violated, and if so, discards those changes, and marks -the transaction as failed. +In the same way that a Linux user uses a path to look up a file, a Solana +client uses public keys to look up accounts. To create an account, the client +generates a *keypair* and registers its public key using the CreateAccount +instruction. Once registered, transactions reference account keys to grant +programs access to accounts. The runtime grants programs read access by +default. To grant write access, the client must either assign the account +to a program ID or sign the transaction using the keypair's *secret key*. Since +only the owner of the secret key can produce valid signatures matching the +account's public key, the runtime recognizes the signature as authorization to +modify account data or debit the account. + +After the runtime executes each of the transaction's instructions, it uses the +account metadata and transaction signatures to verify that none of the access +rules were violated. If a program violates an access rule, the runtime discards +all account changes made by all instructions and marks the transaction as +failed. diff --git a/book/src/terminology.md b/book/src/terminology.md index e272baedcc..111d1c4539 100644 --- a/book/src/terminology.md +++ b/book/src/terminology.md @@ -83,6 +83,11 @@ A [public key](#public-key) and coesponding [secret key](#secret-key). A fractional [native token](#native-token) with the value of approximately 0.0000000000582 [sol](#sol) (2^-34). +#### loader + +A [program](#program) with the ability to interpret the binary encoding +of other on-chain programs. + #### leader The role of a [fullnode](#fullnode) when it is appending [entries](#entry) to