From 6eefa0b72de8e47c9c1256a8c3e2b553a2f549a8 Mon Sep 17 00:00:00 2001 From: Greg Fitzgerald Date: Tue, 21 Jan 2020 17:44:05 -0700 Subject: [PATCH] Integrate transaction chapter into programming model chapter (#7911) automerge --- book/makefile | 2 +- book/src/SUMMARY.md | 1 - book/src/programs/README.md | 16 +++++++++++++++- book/src/transaction.md | 17 ----------------- 4 files changed, 16 insertions(+), 20 deletions(-) delete mode 100644 book/src/transaction.md diff --git a/book/makefile b/book/makefile index 132a12f58..89967d1d4 100644 --- a/book/makefile +++ b/book/makefile @@ -1,6 +1,6 @@ BOB_SRCS=$(wildcard art/*.bob) MSC_SRCS=$(wildcard art/*.msc) -MD_SRCS=$(wildcard src/*.md) +MD_SRCS=$(wildcard src/*.md src/*/*.md) SVG_IMGS=$(BOB_SRCS:art/%.bob=src/.gitbook/assets/%.svg) $(MSC_SRCS:art/%.msc=src/.gitbook/assets/%.svg) diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 62c8dc10d..614c74edd 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -22,7 +22,6 @@ * [Blockstore](validator/blockstore.md) * [Gossip Service](validator/gossip.md) * [The Runtime](validator/runtime.md) -* [Anatomy of a Transaction](transaction.md) * [Running a Validator](running-validator/README.md) * [Validator Requirements](running-validator/validator-reqs.md) * [Choosing a Testnet](running-validator/validator-testnet.md) diff --git a/book/src/programs/README.md b/book/src/programs/README.md index 5b20ee6ef..f413890b9 100644 --- a/book/src/programs/README.md +++ b/book/src/programs/README.md @@ -1,6 +1,20 @@ # Programming Model -A client _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed atomically. If any instruction is invalid, any changes made within the transaction are discarded. +A client _app_ interacts with a Solana cluster by sending it _transactions_ with one or more _instructions_. The Solana _runtime_ passes those instructions to user-contributed _programs_. An instruction might, for example, tell a program to transfer _lamports_ from one _account_ to another or create an interactive contract that governs how lamports are transfered. Instructions are executed sequentially and atomically. If any instruction is invalid, any changes made within the transaction are discarded. + +### Accounts and Signatures + +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 _read-only accounts_. The runtime permits read-only accounts to be read concurrently. If a program attempts to modify a read-only account, the transaction is rejected by the runtime. + +### Recent Blockhash + +A Transaction includes a recent blockhash to prevent duplication and to give transactions lifetimes. Any transaction that is completely identical to a previous one is rejected, so adding a newer blockhash allows multiple transactions to repeat the exact same action. Transactions also have lifetimes that are defined by the blockhash, as any transaction whose blockhash is too old will be rejected. + +### Instructions + +Each instruction specifies a single program account \(which must be marked executable\), a subset of the transaction's accounts that should 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. ## Deploying Programs to a Cluster diff --git a/book/src/transaction.md b/book/src/transaction.md deleted file mode 100644 index f458c1acd..000000000 --- a/book/src/transaction.md +++ /dev/null @@ -1,17 +0,0 @@ -# Anatomy of a Transaction - -Transactions encode lists of instructions that are executed sequentially, and only committed if all the instructions complete 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 read only, a recent blockhash, the instructions, and any signatures. - -## Accounts and Signatures - -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 _read-only accounts_. The runtime permits read-only accounts to be read concurrently. If a program attempts to modify a read-only account, the transaction is rejected by the runtime. - -## Recent Blockhash - -A Transaction includes a recent blockhash to prevent duplication and to give transactions lifetimes. Any transaction that is completely identical to a previous one is rejected, so adding a newer blockhash allows multiple transactions to repeat the exact same action. Transactions also have lifetimes that are defined by the blockhash, as any transaction whose blockhash is too old will be rejected. - -## Instructions - -Each instruction specifies a single program account \(which must be marked executable\), a subset of the transaction's accounts that should 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.