From 1990501786462f15df7cc97f72819ba5ab434b67 Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Tue, 4 Dec 2018 16:22:49 -0700 Subject: [PATCH] Describe executable and owner account metadata --- book/src/programs.md | 37 +++++++++++++++++++++++++------------ book/src/terminology.md | 36 ++++++++++++++++++++++-------------- 2 files changed, 47 insertions(+), 26 deletions(-) diff --git a/book/src/programs.md b/book/src/programs.md index eaca10db8c..02aecb2302 100644 --- a/book/src/programs.md +++ b/book/src/programs.md @@ -29,18 +29,31 @@ instruction is invalid, any changes made within the transaction are discarded. ## Storing State between Transactions If the program needs to store state between transactions, it does so using -*accounts*. Solana supports several kinds of accounts: +*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 +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 +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 +that drops to zero lamports is purged. -1. Executable -2. Owned by a client -3. Owned by a program -4. Credit-only +If an account is marked "executable", it will only be used by a *loader* to run +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. -All accounts are identified by public keys and may hold arbitrary data. 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. 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. +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 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. diff --git a/book/src/terminology.md b/book/src/terminology.md index dd2c0afabd..e272baedcc 100644 --- a/book/src/terminology.md +++ b/book/src/terminology.md @@ -7,8 +7,8 @@ architecture. #### account -A persistent file addressed by [public key](#public-key) and with tokens -tracking its lifetime. +A persistent file addressed by [public key](#public-key) and with +[lamports](#lamport) tracking its lifetime. #### block @@ -91,8 +91,8 @@ the [ledger](#ledger). #### leader schedule A sequence of [fullnode](#fullnode) [public keys](#public-key). The cluster -uses the leader schedule to determine which fullnode is in the [leader](#leader) -at any moment in time. +uses the leader schedule to determine which fullnode is in the +[leader](#leader) at any moment in time. #### ledger @@ -106,8 +106,8 @@ height](#tick-height). #### lockout -The duration of time in which a [fullnode](#fullnode) is unable to [vote](#vote) on -another [fork](#fork). +The duration of time in which a [fullnode](#fullnode) is unable to +[vote](#vote) on another [fork](#fork). #### native token @@ -135,7 +135,8 @@ The public key of a [keypair](#keypair). #### replicator -A type of [client](#client) that stores copies of segments of the [ledger](#ledger). +A type of [client](#client) that stores copies of segments of the +[ledger](#ledger). #### secret key @@ -152,7 +153,8 @@ by the company Solana. #### stake -Tokens forfeit to the [cluster](#cluster] if malicious [fullnode](#fullnode) behavior can be proven. +Tokens forfeit to the [cluster](#cluster] if malicious [fullnode](#fullnode) +behavior can be proven. #### tick @@ -172,7 +174,8 @@ A scarce, fungible member of a set of tokens. #### transaction -One or more [instructions](#instruction) signed by the [client](#client) and executed atomically. +One or more [instructions](#instruction) signed by the [client](#client) and +executed atomically. #### transactions entry @@ -180,7 +183,8 @@ A set of [transactions](#transaction) that may be executed in parallel. #### validator -The role of a [fullnode](#fullnode) when it is validating the [leader's](#leader) latest [entries](#entry). +The role of a [fullnode](#fullnode) when it is validating the +[leader's](#leader) latest [entries](#entry). ## Terminology Reserved for Future Use @@ -190,7 +194,8 @@ for potential future use. #### blob -A fraction of a [block](#block); the smallest unit sent between [fullnodes](#fullnode). +A fraction of a [block](#block); the smallest unit sent between +[fullnodes](#fullnode). #### curio @@ -202,7 +207,8 @@ The time in which a [leader schedule](#leader-schedule) is valid. #### light client -A type of [client](#client) that can verify it's pointing to a valid [cluster](#cluster). +A type of [client](#client) that can verify it's pointing to a valid +[cluster](#cluster). #### mips @@ -210,8 +216,10 @@ Millions of [instructions](#instruction) per second. #### runtime -The component of a [fullnode](#fullnode) responsible for [program](#program) execution. +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). +A type of [client](#client) that trusts it is communicating with a valid +[cluster](#cluster).