From 48fc35884cde5b47f40843bb137bb839c56ee8f0 Mon Sep 17 00:00:00 2001 From: TristanDebrunner Date: Fri, 19 Jul 2019 16:42:50 -0600 Subject: [PATCH] Add Transaction Documentation (#5115) --- book/src/SUMMARY.md | 4 ++++ book/src/instruction-api.md | 25 +++++++++++++++++++ book/src/transaction-api.md | 48 +++++++++++++++++++++++++++++++++++++ book/src/transaction.md | 43 +++++++++++++++++++++++++++++++++ 4 files changed, 120 insertions(+) create mode 100644 book/src/instruction-api.md create mode 100644 book/src/transaction-api.md create mode 100644 book/src/transaction.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index a16d1af8b4..33b5af2deb 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -30,8 +30,12 @@ - [Blocktree](blocktree.md) - [Gossip Service](gossip.md) - [The Runtime](runtime.md) + +- [Anatomy of a Transaction](transaction.md) - [API Reference](api-reference.md) + - [Transaction](transaction-api.md) + - [Instruction](instruction-api.md) - [Blockstreamer](blockstreamer.md) - [JSON RPC API](jsonrpc-api.md) - [JavaScript API](javascript-api.md) diff --git a/book/src/instruction-api.md b/book/src/instruction-api.md new file mode 100644 index 0000000000..bc35de4945 --- /dev/null +++ b/book/src/instruction-api.md @@ -0,0 +1,25 @@ +# Instructions + +For the purposes of building a [Transaction](transaction.md), a more +verbose instruction format is used: + +* **Instruction:** + * **program_id:** The pubkey of the on-chain program that executes the + instruction + * **accounts:** An ordered list of accounts that should be passed to + the program processing the instruction, including metadata detailing + if an account is a signer of the transaction and if it is a credit + only account. + * **data:** A byte array that is passed to the program executing the + instruction + +A more compact form is actually included in a `Transaction`: + +* **CompiledInstruction:** + * **program_id_index:** The index of the `program_id` in the + `account_keys` list + * **accounts:** An ordered list of indices into `account_keys` + specifying the accounds that should be passed to the program + processing the instruction. + * **data:** A byte array that is passed to the program executing the + instruction \ No newline at end of file diff --git a/book/src/transaction-api.md b/book/src/transaction-api.md new file mode 100644 index 0000000000..f10b06664b --- /dev/null +++ b/book/src/transaction-api.md @@ -0,0 +1,48 @@ +# The Transaction + +### Components of a `Transaction` + +* **Transaction:** + * **message:** Defines the transaction + * **header:** Details the account types of and signatures required by + the transaction + * **num_required_signatures:** The total number of signatures + required to make the transaction valid. + * **num_credit_only_signed_accounts:** The last + `num_credit_only_signed_accounts` signatures refer to signing + credit only accounts. Credit only accounts can be used concurrently + 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 + to non-signing credit only accounts + * **account_keys:** List of pubkeys used by the transaction, including + by the instructions and for signatures. The first + `num_required_signatures` pubkeys 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 + run sequentially and committed in one atomic transaction if all + 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`. + The list is initialized with empty signatures (i.e. zeros), and + populated as signatures are added. + +### Transaction Signing + +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 +`account_keys`. + +### Transaction Serialization + +`Transaction`s (and their `message`s) are serialized and deserialized +using the [bincode](https://crates.io/crates/bincode) crate with a +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 diff --git a/book/src/transaction.md b/book/src/transaction.md new file mode 100644 index 0000000000..134e6dcbc4 --- /dev/null +++ b/book/src/transaction.md @@ -0,0 +1,43 @@ +# Anatomy of a Transaction + +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 +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. + +## 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. \ No newline at end of file