Describe executable and owner account metadata

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.

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).