From aae4b33d94bb83e98324c64510d5781420bb9a72 Mon Sep 17 00:00:00 2001 From: Joe C Date: Mon, 17 Jun 2024 07:56:16 -0500 Subject: [PATCH] SVM: update spec (#1757) --- svm/doc/spec.md | 144 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 106 insertions(+), 38 deletions(-) diff --git a/svm/doc/spec.md b/svm/doc/spec.md index c88b6b83f6b268..94b1a6858e02f1 100644 --- a/svm/doc/spec.md +++ b/svm/doc/spec.md @@ -104,10 +104,6 @@ and `program_cache`. needed to check the validity of every transaction in a batch when the transaction accounts are being loaded and checked for compliance with required fees for transaction execution. -- `runtime_config: Arc` is a reference to a - RuntimeConfig struct instance. The `RuntimeConfig` is a collection - of fields that control parameters of runtime, such as compute - budget, the maximal size of log messages in bytes, etc. - `program_cache: Arc>>` is a reference to a ProgramCache instance. All on chain programs used in transaction batch execution are loaded from the program cache. @@ -119,45 +115,117 @@ The main entry point to the SVM is the method `load_and_execute_sanitized_transactions`. The method `load_and_execute_sanitized_transactions` takes the -following arguments - - `callbacks` is a `TransactionProcessingCallback` trait instance - that enables access to data available from accounts-db and from - Bank, - - `sanitized_txs` a slice of `SanitizedTransaction` - - `SanitizedTransaction` contains - - `SanitizedMessage` is an enum with two kinds of messages - - `LegacyMessage` and `LoadedMessage` - Both `LegacyMessage` and `LoadedMessage` consist of - - `MessageHeader` - - vector of `Pubkey` of accounts used in the transaction - - `Hash` of recent block - - vector of `CompiledInstruction` - In addition `LoadedMessage` contains a vector of - `MessageAddressTableLookup` -- list of address table lookups to - load additional accounts for this transaction. - - a Hash of the message - - a boolean flag `is_simple_vote_tx` -- explain - - a vector of `Signature` -- explain which signatures are in this vector - - `check_results` is a mutable slice of `TransactionCheckResult` - - `error_counters` is a mutable reference to `TransactionErrorMetrics` - - `recording_config` is a value of `ExecutionRecordingConfig` configuration parameters - - `timings` is a mutable reference to `ExecuteTimings` - - `account_overrides` is an optional reference to `AccountOverrides` - - `builtin_programs` is an iterator of `Pubkey` that represents builtin programs - - `log_messages_bytes_limit` is an optional `usize` limit on the size of log messages in bytes - - `limit_to_load_programs` is a boolean flag that instruct the function to only load the - programs and do not execute the transactions. - -The method returns a value of -`LoadAndExecuteSanitizedTransactionsOutput` which consists of two -vectors - - a vector of `TransactionLoadResult`, and - - a vector of `TransactionExecutionResult`. +following arguments: + +- `callbacks`: A `TransactionProcessingCallback` trait instance which allows + the transaction processor to summon information about accounts, most + importantly loading them for transaction execution. +- `sanitized_txs`: A slice of sanitized transactions. +- `check_results`: A mutable slice of transaction check results. +- `environment`: The runtime environment for transaction batch processing. +- `config`: Configurations for customizing transaction processing behavior. + +The method returns a `LoadAndExecuteSanitizedTransactionsOutput`, which is +defined below in more detail. An integration test `svm_integration` contains an example of instantiating `TransactionBatchProcessor` and calling its method `load_and_execute_sanitized_transactions`. +### `TransactionProcessingCallback` + +Downstream consumers of the SVM must implement the +`TransactionProcessingCallback` trait in order to provide the transaction +processor with the ability to load accounts and retrieve other account-related +information. + +```rust +pub trait TransactionProcessingCallback { + fn account_matches_owners(&self, account: &Pubkey, owners: &[Pubkey]) -> Option; + + fn get_account_shared_data(&self, pubkey: &Pubkey) -> Option; + + fn get_program_match_criteria(&self, _program: &Pubkey) -> ProgramCacheMatchCriteria { + ProgramCacheMatchCriteria::NoCriteria + } + + fn add_builtin_account(&self, _name: &str, _program_id: &Pubkey) {} +} +``` + +Consumers can customize this plug-in to use their own Solana account source, +caching, and more. + +### `SanitizedTransaction` + +A "sanitized" Solana transaction is a transaction that has undergone the +various checks required to evaluate a transaction against the Solana protocol +ruleset. Some of these rules include signature verification and validation +of account indices (`num_readonly_signers`, etc.). + +A `SanitizedTransaction` contains: + +- `SanitizedMessage`: Enum with two kinds of messages - `LegacyMessage` and + `LoadedMessage` - both of which contain: + - `MessageHeader`: Vector of `Pubkey` of accounts used in the transaction. + - `Hash` of recent block. + - Vector of `CompiledInstruction`. + - In addition, `LoadedMessage` contains a vector of + `MessageAddressTableLookup` - list of address table lookups to + load additional accounts for this transaction. +- A Hash of the message +- A boolean flag `is_simple_vote_tx` - shortcut for determining if the + transaction is merely a simple vote transaction produced by a validator. +- A vector of `Signature` - the hash of the transaction message encrypted using + the signing key (for each signer in the transaction). + +### `TransactionCheckResult` + +Simply stores details about a transaction, including whether or not it contains +a nonce, the nonce it contains (if applicable), and the lamports per signature +to charge for fees. + +### `TransactionProcessingEnvironment` + +The transaction processor requires consumers to provide values describing +the runtime environment to use for processing transactions. + +- `blockhash`: The blockhash to use for the transaction batch. +- `epoch_total_stake`: The total stake for the current epoch. +- `epoch_vote_accounts`: The vote accounts for the current epoch. +- `feature_set`: Runtime feature set to use for the transaction batch. +- `lamports_per_signature`: Lamports per signature to charge per transaction. +- `rent_collector`: Rent collector to use for the transaction batch. + +### `TransactionProcessingConfig` + +Consumers can provide various configurations to adjust the default behavior of +the transaction processor. + +- `account_overrides`: Encapsulates overridden accounts, typically used for + transaction simulation. +- `compute_budget`: The compute budget to use for transaction execution. +- `log_messages_bytes_limit`: The maximum number of bytes that log messages can + consume. +- `limit_to_load_programs`: Whether to limit the number of programs loaded for + the transaction batch. +- `recording_config`: Recording capabilities for transaction execution. +- `transaction_account_lock_limit`: The max number of accounts that a + transaction may lock. + +### `LoadAndExecuteSanitizedTransactionsOutput` + +The output of the transaction batch processor's +`load_and_execute_sanitized_transactions` method. + +- `error_metrics`: Error metrics for transactions that were processed. +- `execute_timings`: Timings for transaction batch execution. +- `execution_results`: Vector of results indicating whether a transaction was + executed or could not be executed. Note executed transactions can still have + failed! +- `loaded_transactions`: Vector of loaded transactions from transactions that + were processed. + # Functional Model In this section, we describe the functionality (logic) of the SVM in