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