Line data Source code
1 : #ifndef HEADER_fd_src_flamenco_runtime_fd_runtime_h 2 : #define HEADER_fd_src_flamenco_runtime_fd_runtime_h 3 : 4 : #include "fd_runtime_helpers.h" 5 : 6 : /* The general structure for executing transactions in Firedancer can 7 : be thought as a state maching where transaction execution is a 8 : deterministic state transition over various data structures. 9 : 10 : The starting and ending state before a transaction is executed is 11 : represented by the bank, accounts database, and status cache. The 12 : bank holds Solana state not represented by accounts (see fd_bank.c/h 13 : for more details) and each bank is per-slot. The latter two data 14 : structures are contained by the runtime. 15 : 16 : The runtime also owns valid joins to important data structures which 17 : are non-deterministically transitioned through execution such as the 18 : program cache which is a pure cache on top of the accounts database. 19 : The runtime also owns bounded out temporary memory regions used for 20 : transaction execution and valid joins to other scratch memory regions 21 : (e.g. acc_pool). 22 : 23 : So we expect the state of the runtime and the bank to change as a 24 : result of execution. 25 : 26 : The transaction, or the input to said state machine is represented by 27 : a fd_txn_in_t. The fd_txn_in_t is just a parsed transaction message 28 : and any state that may have accrued as a result of bundle execution. 29 : 30 : Executing a transaction produces a set of results. This is 31 : represented by a fd_txn_out_t. The fd_txn_out_t consists of any 32 : information that needs to be applied to the bank and runtime. 33 : 34 : We can execute a fd_txn_in_t against a given fd_runtime_t and a 35 : fd_bank_t and expect to produce a fd_txn_out_t. Then a fd_txn_out_t 36 : can be applied/committed on top of a fd_runtime_t and fd_bank_t. 37 : Execution is done via fd_runtime_prepare_and_execute_txn. If a 38 : transaction is committable, it should be committed via 39 : fd_runtime_commit_txn. If a transaction is not committable, it 40 : should be canceled via fd_runtime_cancel_txn. 41 : 42 : TLDR: The runtime is a state machine that executes transactions and 43 : produces results that are applied to various data structures 44 : including the bank, account database, and status cache. The 45 : transaction is executed via a call to 46 : fd_runtime_prepare_and_execute_txn. If the transaction is 47 : committable, it should be committed via fd_runtime_commit_txn. If 48 : the transaction is not committable (txn_out->err.is_committable is 0), 49 : it should be canceled via fd_runtime_cancel_txn. Two calls to 50 : fd_runtime_prepare_and_execute_txn without a call to 51 : fd_runtime_commit_txn or fd_runtime_cancel_txn in between are not 52 : allowed. 53 : 54 : input output 55 : fd_runtime_t -> 56 : fd_txn_in_t -> fd_runtime_prepare_and_execute_txn() -> fd_txn_out_t 57 : fd_bank_t -> 58 : 59 : fd_txn_out_t is the state transition output of a transaction. 60 : 61 : txn_out (committable) --> fd_runtime_commit_txn() 62 : txn_out (not committable) --> fd_runtime_cancel_txn() 63 : */ 64 : 65 : struct fd_runtime { 66 : fd_accdb_user_t * accdb; 67 : fd_txncache_t * status_cache; 68 : fd_progcache_t * progcache; 69 : fd_acc_pool_t * acc_pool; 70 : 71 : struct { 72 : uchar stack_sz; /* Current depth of the instruction execution stack. */ 73 : fd_exec_instr_ctx_t stack[ FD_MAX_INSTRUCTION_STACK_DEPTH ]; /* Instruction execution stack. */ 74 : /* The memory for all of the instructions in the transaction 75 : (including CPI instructions) are preallocated. However, the 76 : order in which the instructions are executed does not match the 77 : order in which they are allocated. The instr_trace will instead 78 : be used to track the order in which the instructions are 79 : executed. We add a +1 to allow any instructions past the max 80 : instr trace limit to be safely allocated, so that we can fail 81 : out like Agave does later at the stack push step within 82 : fd_execute_instr. 83 : 84 : The caller is responsible for updating the trace_length for the 85 : callee. For CPI, the trace length is updated when preparing a 86 : new instruction within cpi_common. For top-level instructions, 87 : the trace length is updated within fd_execute_txn when preparing 88 : an instruction for execution. */ 89 : fd_instr_info_t trace[ FD_MAX_INSTRUCTION_TRACE_LENGTH+1UL ]; 90 : ulong trace_length; 91 : /* The current instruction index being executed */ 92 : int current_idx; 93 : } instr; 94 : 95 : struct { 96 : /* The sysvar instructions account is a special account that is 97 : modified through the course of transaction execution, but its 98 : results are not committed to the bank or accounts database. */ 99 : uchar sysvar_instructions_mem[ FD_ACC_TOT_SZ_MAX ] __attribute__((aligned(FD_ACCOUNT_REC_ALIGN))); 100 : 101 : /* The executable accounts are derived from the accounts in the 102 : transaction and are used by the bpf loader program to validate 103 : the program data account. */ 104 : ulong executable_cnt; /* Number of BPF upgradeable loader accounts. */ 105 : fd_accdb_ro_t executable[ MAX_TX_ACCOUNT_LOCKS ]; /* Array of BPF upgradeable loader program data accounts */ 106 : 107 : ulong starting_lamports[ MAX_TX_ACCOUNT_LOCKS ]; /* Starting lamports for each account */ 108 : ulong starting_dlen[ MAX_TX_ACCOUNT_LOCKS ]; /* Starting data length for each account */ 109 : ulong refcnt[ MAX_TX_ACCOUNT_LOCKS ]; /* Reference count for each account */ 110 : } accounts; 111 : 112 : struct { 113 : int enable_log_collector; 114 : fd_log_collector_t * log_collector; /* Log collector instance */ 115 : fd_capture_ctx_t * capture_ctx; 116 : fd_dump_proto_ctx_t * dump_proto_ctx; 117 : fd_txn_dump_ctx_t * txn_dump_ctx; 118 : 119 : /* Pointer to buffer used for dumping instructions and transactions 120 : into protobuf files. */ 121 : uchar * dumping_mem; 122 : /* Pointer to buffer used for tracing instructions and transactions 123 : into protobuf files. */ 124 : int enable_vm_tracing; 125 : uchar * tracing_mem; 126 : } log; 127 : 128 : struct { 129 : uchar serialization_mem[ FD_MAX_INSTRUCTION_STACK_DEPTH ][ BPF_LOADER_SERIALIZATION_FOOTPRINT ] __attribute__((aligned(FD_RUNTIME_EBPF_HOST_ALIGN))); 130 : } bpf_loader_serialization; 131 : 132 : struct { 133 : uchar rodata [ FD_RUNTIME_ACC_SZ_MAX ] __attribute__((aligned(FD_SBPF_PROG_RODATA_ALIGN))); 134 : uchar sbpf_footprint[ FD_SBPF_PROGRAM_FOOTPRINT ] __attribute__((aligned(alignof(fd_sbpf_program_t)))); 135 : uchar programdata [ FD_RUNTIME_ACC_SZ_MAX ] __attribute__((aligned(FD_ACCOUNT_REC_ALIGN))); 136 : } bpf_loader_program; 137 : 138 : union { 139 : struct { 140 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 141 : uchar landed_votes_mem [ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 142 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 143 : } authorize; 144 : 145 : struct { 146 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 147 : uchar landed_votes_mem [ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 148 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 149 : } update_validator_identity; 150 : 151 : struct { 152 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 153 : uchar landed_votes_mem [ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 154 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 155 : } update_commission; 156 : 157 : struct { 158 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 159 : uchar landed_votes_mem [ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 160 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 161 : } withdraw; 162 : 163 : struct { 164 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 165 : uchar authorized_voters_mem[ FD_AUTHORIZED_VOTERS_FOOTPRINT ] __attribute__((aligned(FD_AUTHORIZED_VOTERS_ALIGN))); 166 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 167 : } init_account; 168 : 169 : struct { 170 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 171 : uchar vote_state_landed_votes_mem[ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 172 : uchar tower_sync_landed_votes_mem[ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 173 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 174 : } tower_sync; 175 : 176 : struct { 177 : /* Deprecated instructions */ 178 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 179 : uchar landed_votes_mem [ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 180 : uchar vote_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 181 : uchar compact_vs_lockout_mem [ FD_VOTE_LOCKOUTS_FOOTPRINT ] __attribute__((aligned(FD_VOTE_LOCKOUTS_ALIGN))); 182 : uchar vs_update_landed_votes_mem[ FD_LANDED_VOTES_FOOTPRINT ] __attribute__((aligned(FD_LANDED_VOTES_ALIGN))); 183 : } process_vote; 184 : 185 : } vote_program; 186 : 187 : union { 188 : struct { 189 : uchar vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 190 : uchar landed_votes_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(128UL))); 191 : } delegate; 192 : struct { 193 : uchar delinquent_vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 194 : uchar delinquent_landed_votes_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(128UL))); 195 : 196 : uchar reference_vote_state_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(FD_VOTE_STATE_VERSIONED_ALIGN))); 197 : uchar reference_landed_votes_mem [ FD_VOTE_STATE_VERSIONED_FOOTPRINT ] __attribute__((aligned(128UL))); 198 : } deactivate_delinquent; 199 : } stake_program; 200 : 201 : struct { 202 : 203 : /* Ticks spent spent preparing a txn-level VM (zeroing memory, 204 : copying account data, etc) */ 205 : ulong vm_setup_cum_ticks; 206 : 207 : /* Ticks spent committing txn-level VM results (copying account 208 : data, etc) */ 209 : ulong vm_commit_cum_ticks; 210 : 211 : /* Ticks spent in top-levl VM interpreter (includes CPI setup/commit 212 : ticks) */ 213 : ulong vm_exec_cum_ticks; 214 : 215 : /* Ticks spent preparing/committing a cross-program invocation) */ 216 : ulong cpi_setup_cum_ticks; 217 : ulong cpi_commit_cum_ticks; 218 : 219 : /* Number of user txn account transitions */ 220 : 221 : # define FD_RUNTIME_SAVE_UNCHANGED_NONEXIST 0 /* non-existent account not modified */ 222 : # define FD_RUNTIME_SAVE_CREATE 1 /* account previously non-existent, non-zero balance after txn */ 223 : # define FD_RUNTIME_SAVE_DELETE 2 /* account previously existed, non-existent after txn */ 224 84 : # define FD_RUNTIME_SAVE_MODIFY 3 /* existing account modified */ 225 6 : # define FD_RUNTIME_SAVE_UNCHANGED 4 /* existing account not modified */ 226 : # define FD_RUNTIME_SAVE_MAX 5 /* enum variant count */ 227 : ulong txn_account_save[ FD_RUNTIME_SAVE_MAX ]; 228 : 229 : ulong cu_cum; 230 : 231 : } metrics; 232 : 233 : struct { 234 : int enabled; 235 : } fuzz; 236 : }; 237 : typedef struct fd_runtime fd_runtime_t; 238 : 239 : struct fd_txn_in { 240 : fd_txn_p_t const * txn; 241 : 242 : struct { 243 : int is_bundle; 244 : fd_txn_out_t * prev_txn_outs[ FD_PACK_MAX_TXN_PER_BUNDLE ]; 245 : ulong prev_txn_cnt; 246 : } bundle; 247 : }; 248 : typedef struct fd_txn_in fd_txn_in_t; 249 : 250 : struct fd_txn_out { 251 : struct { 252 : int is_committable; 253 : int is_fees_only; 254 : int txn_err; 255 : /* These are error fields produced by instruction execution 256 : when txn_err == FD_RUNTIME_TXN_ERR_INSTRUCTION_ERROR (-9). */ 257 : int exec_err; 258 : int exec_err_kind; 259 : int exec_err_idx; 260 : uint custom_err; 261 : } err; 262 : 263 : struct { 264 : long prep_start_timestamp; 265 : long load_start_timestamp; 266 : long exec_start_timestamp; 267 : long commit_start_timestamp; 268 : 269 : fd_compute_budget_details_t compute_budget; /* Compute budget details */ 270 : fd_transaction_cost_t txn_cost; /* Transaction cost */ 271 : ulong loaded_accounts_data_size; /* The actual transaction loaded data size */ 272 : long accounts_resize_delta; /* Transaction level tracking for account resizing */ 273 : 274 : fd_txn_return_data_t return_data; /* Data returned from `return_data` syscalls */ 275 : 276 : fd_hash_t blake_txn_msg_hash; /* Hash of raw transaction message used by the status cache */ 277 : fd_hash_t blockhash; /* Blockhash of the block that the transaction is being executed in */ 278 : 279 : ulong execution_fee; /* Execution fee paid by the fee payer in the transaction */ 280 : ulong priority_fee; /* Priority fee paid by the fee payer in the transaction */ 281 : ulong tips; /* Jito tips paid during execution */ 282 : 283 : ulong signature_count; /* Number of signatures in the transaction */ 284 : int is_simple_vote; /* Whether the transaction is a simple vote */ 285 : /* When a program is deployed or upgraded, we must queue it to be 286 : updated in the program cache (if it exists already) so that 287 : the cache entry's ELF / sBPF information can be updated for 288 : future executions. We keep an array of pubkeys for the 289 : transaction to track which programs need to be reverified. The 290 : actual queueing for reverification is done in the transaction 291 : finalization step. */ 292 : uchar programs_to_reverify_cnt; 293 : fd_pubkey_t programs_to_reverify[ MAX_TX_ACCOUNT_LOCKS ]; 294 : } details; 295 : 296 : /* During sanitization, v0 transactions are allowed to have up to 256 accounts: 297 : https://github.com/anza-xyz/agave/blob/838c1952595809a31520ff1603a13f2c9123aa51/sdk/program/src/message/versions/v0/mod.rs#L139 298 : Nonetheless, when Agave prepares a sanitized batch for execution and tries to lock accounts, a lower limit is enforced: 299 : https://github.com/anza-xyz/agave/blob/838c1952595809a31520ff1603a13f2c9123aa51/accounts-db/src/account_locks.rs#L118 300 : That is the limit we are going to use here. */ 301 : struct { 302 : /* is_setup is set to 1 if account data buffer resources have been 303 : acquired for the transaction and 0 if they have not. If the flag 304 : has been set, memory resources must be released. */ 305 : int is_setup; 306 : ulong cnt; 307 : fd_pubkey_t keys [ MAX_TX_ACCOUNT_LOCKS ]; 308 : fd_accdb_rw_t account [ MAX_TX_ACCOUNT_LOCKS ]; /* FIXME use accdb_ref_t here for safety - some accounts are readonly */ 309 : uchar is_writable [ MAX_TX_ACCOUNT_LOCKS ]; 310 : /* Flags to demarcate if an account is queued up to update the vote 311 : or stakes caches in the commit stage of a transaction. */ 312 : uchar stake_update[ MAX_TX_ACCOUNT_LOCKS ]; 313 : uchar vote_update [ MAX_TX_ACCOUNT_LOCKS ]; 314 : 315 : /* The fee payer and nonce accounts are treated differently than 316 : other accounts: if an on-transaction fails they are still 317 : committed to the accounts database. However, they are saved at 318 : the point right after a fee is debited or the nonce is advanced 319 : respectively. The rollback accounts store this state because a 320 : failed transaction could have potentially modified the state of 321 : these two accounts. 322 : 323 : The memory for the nonce and fee payer is always provisioned when 324 : the transaction is prepared, but isn't necessarily used. */ 325 : uchar * rollback_fee_payer_mem; 326 : uchar * rollback_nonce_mem; 327 : 328 : ulong nonce_idx_in_txn; /* !=ULONG_MAX if exists */ 329 : fd_account_meta_t * rollback_nonce; 330 : fd_account_meta_t * rollback_fee_payer; 331 : } accounts; 332 : }; 333 : typedef struct fd_txn_out fd_txn_out_t; 334 : 335 : FD_PROTOTYPES_BEGIN 336 : 337 : /* fd_runtime_block_execute_prepare kicks off the execution of a block. 338 : After this function is called, transactions can be executed and 339 : committed against the block. This function handles epoch boundary 340 : and rewards updates if needed and updates sysvars. It assumes that 341 : the bank and accounts database have been setup to execute against 342 : the bank: the bank has already been cloned from the parent bank and 343 : that the database has a transaction that is linked to the parent 344 : block's xid. */ 345 : 346 : void 347 : fd_runtime_block_execute_prepare( fd_banks_t * banks, 348 : fd_bank_t * bank, 349 : fd_accdb_user_t * accdb, 350 : fd_runtime_stack_t * runtime_stack, 351 : fd_capture_ctx_t * capture_ctx, 352 : int * is_epoch_boundary ); 353 : 354 : /* fd_runtime_block_execute_finalize finishes the execution of the block 355 : by paying a fee out to the block leader, updating any sysvars, and 356 : updating the bank hash. The required updates are made to the bank 357 : and the accounts database. */ 358 : 359 : void 360 : fd_runtime_block_execute_finalize( fd_bank_t * bank, 361 : fd_accdb_user_t * accdb, 362 : fd_capture_ctx_t * capture_ctx ); 363 : 364 : /* fd_runtime_prepare_and_execute_txn is responsible for executing a 365 : fd_txn_in_t against a fd_runtime_t and a fd_bank_t. The results of 366 : the transaction execution are set in the fd_txn_out_t. The caller 367 : is responisble for correctly setting up the fd_txn_in_t and the 368 : fd_runtime_t handles. 369 : 370 : TODO: fd_runtime_t and fd_bank_t should be const here. */ 371 : 372 : void 373 : fd_runtime_prepare_and_execute_txn( fd_runtime_t * runtime, 374 : fd_bank_t * bank, 375 : fd_txn_in_t const * txn_in, 376 : fd_txn_out_t * txn_out ); 377 : 378 : /* fd_runtime_commit_txn commits the results of a transaction execution 379 : as represented by the fd_txn_out_t to the bank and the accounts 380 : database. */ 381 : 382 : void 383 : fd_runtime_commit_txn( fd_runtime_t * runtime, 384 : fd_bank_t * bank, 385 : fd_txn_out_t * txn_out ); 386 : 387 : /* fd_runtime_cancel_txn cancels the result of a transaction execution 388 : and frees any resources that may have been acquired. A transaction 389 : should only be canceled when the transaction is not committable. 390 : 1. An invalid transaction that causes a block to be rejected/ 391 : considered invalid/'bad'. 392 : 2. All transactions in a bundle with a failed transaction should be 393 : canceled as they will not be included in the block. */ 394 : 395 : void 396 : fd_runtime_cancel_txn( fd_runtime_t * runtime, 397 : fd_txn_out_t * txn_out ); 398 : 399 : FD_PROTOTYPES_END 400 : 401 : #endif /* HEADER_fd_src_flamenco_runtime_fd_runtime_h */