diff --git a/book/src/cli.md b/book/src/cli.md index 63f6637663..72d963a01b 100644 --- a/book/src/cli.md +++ b/book/src/cli.md @@ -80,7 +80,7 @@ $ solana pay 123 \ // Return {signature: , processId: } ``` -*`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 ... Any third party signatures required to unlock the lamports ARGS: - The pubkey of recipient + The public key of recipient The amount to send (default unit SOL) Specify unit to use for request [possible values: SOL, lamports] ``` @@ -694,7 +694,7 @@ OPTIONS: -k, --keypair /path/to/id.json ARGS: - The pubkey of recipient + The public key of recipient The process id of the transfer to authorize ``` @@ -716,7 +716,7 @@ OPTIONS: -k, --keypair /path/to/id.json ARGS: - The pubkey of recipient + The public key of recipient The process id of the transfer to unlock ``` @@ -756,7 +756,7 @@ OPTIONS: -o, --output Write the account data to this file ARGS: - Account pubkey + Account public key ``` ```manpage @@ -776,7 +776,7 @@ OPTIONS: -k, --keypair /path/to/id.json ARGS: - Stake account pubkey + Stake account public key ``` ```manpage @@ -796,7 +796,7 @@ OPTIONS: -k, --keypair /path/to/id.json ARGS: - Storage account pubkey + Storage account public key ``` ```manpage @@ -816,7 +816,7 @@ OPTIONS: -k, --keypair /path/to/id.json ARGS: - Vote account pubkey + Vote account public key ``` ```manpage diff --git a/book/src/cluster.md b/book/src/cluster.md index c62e99e6a4..e5728f87e4 100644 --- a/book/src/cluster.md +++ b/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 diff --git a/book/src/programs.md b/book/src/programs.md index 61a55cde71..b7aeaa622c 100644 --- a/book/src/programs.md +++ b/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 -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 or sign the transaction using the keypair's *secret key*. Since only -the holder 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. +generates a *keypair* and registers its public key using the `CreateAccount` +instruction. The account created by `CreateAccount` is called a *system +account* and is owned by a built-in program called the System program. The +System program allows clients to transfer lamports and assign account +ownership. + +The runtime only permits the owner to debit the account or modify its data. The +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 -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. +account metadata 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. +## 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. diff --git a/book/src/terminology.md b/book/src/terminology.md index b6c2a83cfc..e160e58f4b 100644 --- a/book/src/terminology.md +++ b/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 diff --git a/book/src/transaction-api.md b/book/src/transaction-api.md index f10b06664b..2bd241a637 100644 --- a/book/src/transaction-api.md +++ b/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). \ No newline at end of file +[short-vec](https://github.com/solana-labs/solana/blob/master/sdk/src/short_vec.rs). diff --git a/book/src/transaction.md b/book/src/transaction.md index 134e6dcbc4..51c41fe319 100644 --- a/book/src/transaction.md +++ b/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 -transaction. Each Transaction details the accounts used, including which +successfully. All account updates are reverted upon the failure of a +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. -This includes accounts that are transferring tokens, accounts whose user -data is being modified, and the program accounts that are being called -by the instructions. Each account that is not an executable program can -be marked as a requiring a signature and/or as credit only. All accounts -marked as signers must have a valid signature in the transaction's list -of signatures before the transaction is considered valid. Any accounts -marked as credit only may only have their token value increased, and -their user data is read only. Accounts are locked by the runtime, -ensuring that they are not modified by a concurrent program while the -transaction is running. Credit only accounts can safely be shared, so -the runtime will allow multiple concurrent credit only locks on an -account. +Each transaction explicitly lists all account public keys referenced by the +transaction's instructions. A subset of those public keys are each accompanied +by a transaction signature. Those signatures signal on-chain programs that +the account holder has authorized the transaction. Typically, the program +uses the authorization to permit debiting the account or modifying its +data. + +The transaction also marks some accounts as *credit-only accounts*. The +runtime permits credit-only accounts to be credited concurrently. If a +program attempts to debit a credit-only account or modify its account +data, the transaction is rejected by the runtime. ## 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. \ No newline at end of file +entire transaction to fail immediately.