Line data    Source code

       1             : #ifndef HEADER_fd_src_flamenco_runtime_program_fd_loader_v4_program_h
       2             : #define HEADER_fd_src_flamenco_runtime_program_fd_loader_v4_program_h
       3             : 
       4             : #include "../../fd_flamenco_base.h"
       5             : #include "../context/fd_exec_instr_ctx.h"
       6             : #include "../fd_system_ids.h"
       7             : #include "../fd_executor.h"
       8             : #include "../sysvar/fd_sysvar_rent.h"
       9             : #include "../fd_account.h"
      10             : #include "fd_bpf_loader_program.h"
      11             : 
      12             : /* 
      13             :   Notes about loader v4 since it differs slightly from the previous BPF v3 loader...
      14             :     - There are three possible states for a loader v4 program:
      15             :       - Retracted
      16             :         - This name is a little bit misleading since it applies to programs that are either in the process of deployment,
      17             :           or already deployed and in maintenance (and thus cannot be invoked).
      18             :       - Deployed
      19             :         - This is the normal state for a program that is ready to be invoked.
      20             :         - Programs cannot be retracted within `LOADER_V4_DEPLOYMENT_COOLDOWN_IN_SLOTS` (750) slots of deployment.
      21             :       - Finalized
      22             :         - The program is immutable.
      23             :         - Users must specify a "next version" which, from my inspection, serves no functional purpose besides showing up
      24             :           as extra information on a block explorer.
      25             :     - There is no longer a concept of a program account vs. a program data account. The program account is the program data account.
      26             :       - "Look at me... I'm the programdata account now..."
      27             :     - Buffer accounts are no longer necessary. Instead, the `write` instruction writes directly into the program account.
      28             :       - Optionally, when calling `deploy`, the user can provide a source buffer account to overwrite the program data
      29             :         instead of calling retract -> write -> deploy.
      30             :       - There is no direct `upgrade` instruction anymore. The user must either retract the program, truncate / write new bytes, and redeploy,
      31             :         or write new bytes to a source buffer account and call `deploy`.
      32             :     - There is no `close` instruction anymore. Instead, the user must call `truncate` with a new size of 0 bytes, which automatically closes the program account
      33             :       and resets it into an uninitialized state.
      34             : */
      35             : 
      36             : /* https://github.com/anza-xyz/agave/blob/v2.1.4/builtins-default-costs/src/lib.rs#L33 */
      37             : #define LOADER_V4_DEFAULT_COMPUTE_UNITS (2000UL)
      38             : 
      39             : /* https://github.com/anza-xyz/agave/blob/v2.1.4/sdk/program/src/loader_v4.rs#L15 */
      40             : #define LOADER_V4_DEPLOYMENT_COOLDOWN_IN_SLOTS (750UL)
      41             : 
      42             : /* https://github.com/anza-xyz/agave/blob/v2.1.4/sdk/program/src/loader_v4.rs#L46-L49 */
      43        1248 : #define LOADER_V4_PROGRAM_DATA_OFFSET (48UL)
      44             : 
      45             : /* Serization / deserialization done for the loader v4 state is done using a `std::mem::transmute()` instead of using
      46             :    the standard bincode deserialization. The key difference of doing this is that state deserialization does not fail
      47             :    if the `status` enum within the state is invalid (Retracted, Deployed, Finalized). To stay conformant with their semantics,
      48             :    we represent `status` as a ulong (intentionally instead of a uint because Agave uses `repr(u64)`) and use direct pointer
      49             :    reinterpretation to decode and encode data between the program account and the state object. It also keeps the type size
      50             :    consistent with Agave's for safe transmute operations.
      51             : 
      52             :    https://github.com/anza-xyz/agave/blob/09ef71223b24e30e59eaeaf5eb95e85f222c7de1/sdk/program/src/loader_v4.rs#L16-L26 */
      53         864 : #define FD_LOADER_V4_STATUS_ENUM_RETRACTED (0UL)
      54           0 : #define FD_LOADER_V4_STATUS_ENUM_DELOYED   (1UL)
      55           0 : #define FD_LOADER_V4_STATUS_ENUM_FINALIZED (2UL)
      56             : 
      57             : /* This MUST hold true for safety and conformance. */
      58             : FD_STATIC_ASSERT( sizeof(fd_loader_v4_state_t)==LOADER_V4_PROGRAM_DATA_OFFSET, loader_v4 );
      59             : 
      60             : FD_PROTOTYPES_BEGIN
      61             : 
      62             : FD_FN_PURE uchar
      63             : fd_loader_v4_status_is_deployed( fd_loader_v4_state_t const * state );
      64             : 
      65             : FD_FN_PURE uchar
      66             : fd_loader_v4_status_is_retracted( fd_loader_v4_state_t const * state );
      67             : 
      68             : FD_FN_PURE uchar
      69             : fd_loader_v4_status_is_finalized( fd_loader_v4_state_t const * state );
      70             : 
      71             : int
      72             : fd_loader_v4_get_state( fd_borrowed_account_t const * program,
      73             :                         fd_loader_v4_state_t *        state );
      74             : 
      75             : int
      76             : fd_loader_v4_program_execute( fd_exec_instr_ctx_t * instr_ctx );
      77             : 
      78             : FD_PROTOTYPES_END
      79             : 
      80             : #endif /* HEADER_fd_src_flamenco_runtime_program_fd_loader_v4_program_h */