Clarify runtime vs program rules (#5934)

* Clarify runtime vs program rules

And define "smart contract"

* Apply review feedback

* Rename secret key to private key

* Rename pubkey to public key in book

"pubkey" is a great shorthand in code, but it's not common in the
industry or something we want to spend time explaining to users.

book/src/cli.md

@@ -80,7 +80,7 @@ $ solana pay <PUBKEY> 123 \
 // Return
 {signature: <TX_SIGNATURE>, processId: <PROCESS_ID>}
 ```
-*`require-timestamp-from` is optional. If not provided, the transaction will expect a timestamp signed by this wallet's secret key*
+*`require-timestamp-from` is optional. If not provided, the transaction will expect a timestamp signed by this wallet's private key*
 
 #### Authorized Transfer
 
@@ -630,7 +630,7 @@ OPTIONS:
         --require-signature-from <PUBKEY>...    Any third party signatures required to unlock the lamports
 
 ARGS:
-    <PUBKEY>    The pubkey of recipient
+    <PUBKEY>    The public key of recipient
     <AMOUNT>    The amount to send (default unit SOL)
     <unit>      Specify unit to use for request [possible values: SOL, lamports]
 ```
@@ -694,7 +694,7 @@ OPTIONS:
     -k, --keypair <PATH>    /path/to/id.json
 
 ARGS:
-    <PUBKEY>        The pubkey of recipient
+    <PUBKEY>        The public key of recipient
     <PROCESS ID>    The process id of the transfer to authorize
 ```
 
@@ -716,7 +716,7 @@ OPTIONS:
     -k, --keypair <PATH>     /path/to/id.json
 
 ARGS:
-    <PUBKEY>        The pubkey of recipient
+    <PUBKEY>        The public key of recipient
     <PROCESS ID>    The process id of the transfer to unlock
 ```
 
@@ -756,7 +756,7 @@ OPTIONS:
     -o, --output <FILE>     Write the account data to this file
 
 ARGS:
-    <ACCOUNT PUBKEY>    Account pubkey
+    <ACCOUNT PUBKEY>    Account public key
 ```
 
 ```manpage
@@ -776,7 +776,7 @@ OPTIONS:
     -k, --keypair <PATH>    /path/to/id.json
 
 ARGS:
-    <STAKE ACCOUNT PUBKEY>    Stake account pubkey
+    <STAKE ACCOUNT PUBKEY>    Stake account public key
 ```
 
 ```manpage
@@ -796,7 +796,7 @@ OPTIONS:
     -k, --keypair <PATH>    /path/to/id.json
 
 ARGS:
-    <STORAGE ACCOUNT PUBKEY>    Storage account pubkey
+    <STORAGE ACCOUNT PUBKEY>    Storage account public key
 ```
 
 ```manpage
@@ -816,7 +816,7 @@ OPTIONS:
     -k, --keypair <PATH>    /path/to/id.json
 
 ARGS:
-    <VOTE ACCOUNT PUBKEY>    Vote account pubkey
+    <VOTE ACCOUNT PUBKEY>    Vote account public key
 ```
 
 ```manpage

book/src/cluster.md

@@ -13,7 +13,7 @@ buggy and malicious nodes.
 
 Before starting any fullnodes, one first needs to create a *genesis block*.
 The block contains entries referencing two public keys, a *mint* and a
-*bootstrap leader*. The fullnode holding the bootstrap leader's secret key is
+*bootstrap leader*. The fullnode holding the bootstrap leader's private key is
 responsible for appending the first entries to the ledger. It initializes its
 internal state with the mint's account. That account will hold the number of
 native tokens defined by the genesis block. The second fullnode then contacts

book/src/programs.md

@@ -48,18 +48,30 @@ read its data and credit the account.
 
 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
+generates a *keypair* and registers its public key using the `CreateAccount`
-instruction. Once registered, transactions reference account keys to grant
+instruction. The account created by `CreateAccount` is called a *system
-programs access to accounts. The runtime grants programs read access by
+account* and is owned by a built-in program called the System program. The
-default. To grant write access, the client must either assign the account to a
+System program allows clients to transfer lamports and assign account
-program or sign the transaction using the keypair's *secret key*. Since only
+ownership.
-the holder of the secret key can produce valid signatures matching the
+
-account's public key, the runtime recognizes the signature as authorization to
+The runtime only permits the owner to debit the account or modify its data. The
-modify account data or debit the account.
+program then defines additional rules for whether the client can modify
+accounts it owns. In the case of the System program, it allows users to
+transfer lamports by recognizing transaction signatures. If it sees the client
+signed the transaction using the keypair's *private key*, it knows the client
+authorized the token transfer.
 
 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
+account metadata to verify that none of the access rules were violated. If a
-rules were violated. If a program violates an access rule, the runtime discards
+program violates an access rule, the runtime discards all account changes made
-all account changes made by all instructions and marks the transaction as
+by all instructions and marks the transaction as failed.
-failed.
 
+## Smart Contracts
+
+Programs don't always require transaction signatures, as the System program
+does. Instead, the program may manage *smart contracts*. A smart contract is a
+set of constraints that once satisfied, signal to a program that a token
+transfer or account update is permitted. For example, one could use the Budget
+program to create a smart contract that authorizes a token transfer only after
+some date. Once evidence that the date has past, the contract progresses, and
+token transfer completes.

book/src/terminology.md

@@ -136,7 +136,7 @@ in a [transaction](#instruction).
 
 #### keypair
 
-A [public key](#public-key) and corresponding [secret key](#secret-key).
+A [public key](#public-key) and corresponding [private key](#private-key).
 
 #### lamport
 
@@ -208,6 +208,10 @@ See [Proof of History](#proof-of-history).
 
 A weighted [credit](#credit) in a rewards regime.  In the validator [rewards regime](staking-rewards.md), the number of points owed to a stake during redemption is the product of the [vote credits](#vote-credit) earned and the number of lamports staked.
 
+#### private key
+
+The private key of a [keypair](#keypair).
+
 #### program
 
 The code that interprets [instructions](#instruction).
@@ -246,15 +250,16 @@ excluded from consideration for consensus and can be discarded.
 The component of a [fullnode](#fullnode) responsible for [program](#program)
 execution.
 
-#### secret key
-
-The private key of a [keypair](#keypair).
-
 #### slot
 
 The period of time for which a [leader](#leader) ingests transactions and
 produces a [block](#block).
 
+#### smart contract
+
+A set of constraints that once satisfied, signal to a program that some
+predefined account updates are permitted.
+
 #### sol
 
 The [native token](#native-token) tracked by a [cluster](#cluster) recognized

book/src/transaction-api.md

@@ -14,11 +14,11 @@
          by multiple parallel transactions, but their balance may only be
          increased, and their account data is read-only.
       *  **num_credit_only_unsigned_accounts:** The last
-         `num_credit_only_unsigned_accounts` pubkeys in `account_keys` refer
+         `num_credit_only_unsigned_accounts` public keys in `account_keys` refer
          to non-signing credit only accounts
-    * **account_keys:** List of pubkeys used by the transaction, including
+    * **account_keys:** List of public keys used by the transaction, including
       by the instructions and for signatures. The first
-      `num_required_signatures` pubkeys must sign the transaction.
+      `num_required_signatures` public keys must sign the transaction.
     * **recent_blockhash:** The ID of a recent ledger entry. Validators will
       reject transactions with a `recent_blockhash` that is too old.
     * **instructions:** A list of [instructions](instruction.md) that are
@@ -26,7 +26,7 @@
       succeed.
   * **signatures:** A list of signatures applied to the transaction. The
     list is always of length `num_required_signatures`, and the signature
-    at index `i` corresponds to the pubkey at index `i` in `account_keys`.
+    at index `i` corresponds to the public key at index `i` in `account_keys`.
     The list is initialized with empty signatures (i.e. zeros), and
     populated as signatures are added.
   
@@ -34,7 +34,7 @@
 
 A `Transaction` is signed by using an ed25519 keypair to sign the
 serialization of the `message`. The resulting signature is placed at the
-index of `signatures` matching the index of the keypair's pubkey in
+index of `signatures` matching the index of the keypair's public key in
 `account_keys`.
 
 ### Transaction Serialization
@@ -45,4 +45,4 @@ non-standard vector serialization that uses only one byte for the length
 if it can be encoded in 7 bits, 2 bytes if it fits in 14 bits, or 3
 bytes if it requires 15 or 16 bits. The vector serialization is defined
 by Solana's
-[short-vec](https://github.com/solana-labs/solana/blob/master/sdk/src/short_vec.rs).
+[short-vec](https://github.com/solana-labs/solana/blob/master/sdk/src/short_vec.rs).

book/src/transaction.md

@@ -2,26 +2,24 @@
 
 Transactions encode lists of instructions that are executed
 sequentially, and only committed if all the instructions complete
-successfully. All account states are reverted upon the failure of a
+successfully. All account updates are reverted upon the failure of a
-transaction. Each Transaction details the accounts used, including which
+transaction. Each transaction details the accounts used, including which
 must sign and which are credit only, a recent blockhash, the
 instructions, and any signatures.
 
 ## Accounts and Signatures
 
-Each transaction explicitly lists all accounts that it needs access to.
+Each transaction explicitly lists all account public keys referenced by the
-This includes accounts that are transferring tokens, accounts whose user
+transaction's instructions. A subset of those public keys are each accompanied
-data is being modified, and the program accounts that are being called
+by a transaction signature. Those signatures signal on-chain programs that
-by the instructions. Each account that is not an executable program can
+the account holder has authorized the transaction. Typically, the program
-be marked as a requiring a signature and/or as credit only. All accounts
+uses the authorization to permit debiting the account or modifying its
-marked as signers must have a valid signature in the transaction's list
+data.
-of signatures before the transaction is considered valid. Any accounts
+
-marked as credit only may only have their token value increased, and
+The transaction also marks some accounts as *credit-only accounts*. The
-their user data is read only. Accounts are locked by the runtime,
+runtime permits credit-only accounts to be credited concurrently. If a
-ensuring that they are not modified by a concurrent program while the
+program attempts to debit a credit-only account or modify its account
-transaction is running. Credit only accounts can safely be shared, so
+data, the transaction is rejected by the runtime.
-the runtime will allow multiple concurrent credit only locks on an
-account.
 
 ## Recent Blockhash
 
@@ -40,4 +38,4 @@ be passed to the program, and a data byte array instruction that is
 passed to the program. The program interprets the data array and
 operates on the accounts specified by the instructions. The program can
 return successfully, or with an error code. An error return causes the
-entire transaction to fail immediately.
+entire transaction to fail immediately.