solana_program/loader_upgradeable_instruction.rs
1//! Instructions for the [upgradable BPF loader][ubpfl].
2//!
3//! [ubpfl]: crate::bpf_loader_upgradeable
4
5#[repr(u8)]
6#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
7pub enum UpgradeableLoaderInstruction {
8 /// Initialize a Buffer account.
9 ///
10 /// A Buffer account is an intermediary that once fully populated is used
11 /// with the `DeployWithMaxDataLen` instruction to populate the program's
12 /// ProgramData account.
13 ///
14 /// The `InitializeBuffer` instruction requires no signers and MUST be
15 /// included within the same Transaction as the system program's
16 /// `CreateAccount` instruction that creates the account being initialized.
17 /// Otherwise another party may initialize the account.
18 ///
19 /// # Account references
20 /// 0. `[writable]` source account to initialize.
21 /// 1. `[]` Buffer authority, optional, if omitted then the buffer will be
22 /// immutable.
23 InitializeBuffer,
24
25 /// Write program data into a Buffer account.
26 ///
27 /// # Account references
28 /// 0. `[writable]` Buffer account to write program data to.
29 /// 1. `[signer]` Buffer authority
30 Write {
31 /// Offset at which to write the given bytes.
32 offset: u32,
33 /// Serialized program data
34 #[serde(with = "serde_bytes")]
35 bytes: Vec<u8>,
36 },
37
38 /// Deploy an executable program.
39 ///
40 /// A program consists of a Program and ProgramData account pair.
41 /// - The Program account's address will serve as the program id for any
42 /// instructions that execute this program.
43 /// - The ProgramData account will remain mutable by the loader only and
44 /// holds the program data and authority information. The ProgramData
45 /// account's address is derived from the Program account's address and
46 /// created by the DeployWithMaxDataLen instruction.
47 ///
48 /// The ProgramData address is derived from the Program account's address as
49 /// follows:
50 ///
51 /// ```
52 /// # use solana_program::pubkey::Pubkey;
53 /// # use solana_program::bpf_loader_upgradeable;
54 /// # let program_address = &[];
55 /// let (program_data_address, _) = Pubkey::find_program_address(
56 /// &[program_address],
57 /// &bpf_loader_upgradeable::id()
58 /// );
59 /// ```
60 ///
61 /// The `DeployWithMaxDataLen` instruction does not require the ProgramData
62 /// account be a signer and therefore MUST be included within the same
63 /// Transaction as the system program's `CreateAccount` instruction that
64 /// creates the Program account. Otherwise another party may initialize the
65 /// account.
66 ///
67 /// # Account references
68 /// 0. `[signer]` The payer account that will pay to create the ProgramData
69 /// account.
70 /// 1. `[writable]` The uninitialized ProgramData account.
71 /// 2. `[writable]` The uninitialized Program account.
72 /// 3. `[writable]` The Buffer account where the program data has been
73 /// written. The buffer account's authority must match the program's
74 /// authority
75 /// 4. `[]` Rent sysvar.
76 /// 5. `[]` Clock sysvar.
77 /// 6. `[]` System program (`solana_sdk::system_program::id()`).
78 /// 7. `[signer]` The program's authority
79 DeployWithMaxDataLen {
80 /// Maximum length that the program can be upgraded to.
81 max_data_len: usize,
82 },
83
84 /// Upgrade a program.
85 ///
86 /// A program can be updated as long as the program's authority has not been
87 /// set to `None`.
88 ///
89 /// The Buffer account must contain sufficient lamports to fund the
90 /// ProgramData account to be rent-exempt, any additional lamports left over
91 /// will be transferred to the spill account, leaving the Buffer account
92 /// balance at zero.
93 ///
94 /// # Account references
95 /// 0. `[writable]` The ProgramData account.
96 /// 1. `[writable]` The Program account.
97 /// 2. `[writable]` The Buffer account where the program data has been
98 /// written. The buffer account's authority must match the program's
99 /// authority
100 /// 3. `[writable]` The spill account.
101 /// 4. `[]` Rent sysvar.
102 /// 5. `[]` Clock sysvar.
103 /// 6. `[signer]` The program's authority.
104 Upgrade,
105
106 /// Set a new authority that is allowed to write the buffer or upgrade the
107 /// program. To permanently make the buffer immutable or disable program
108 /// updates omit the new authority.
109 ///
110 /// # Account references
111 /// 0. `[writable]` The Buffer or ProgramData account to change the
112 /// authority of.
113 /// 1. `[signer]` The current authority.
114 /// 2. `[]` The new authority, optional, if omitted then the program will
115 /// not be upgradeable.
116 SetAuthority,
117
118 /// Closes an account owned by the upgradeable loader of all lamports and
119 /// withdraws all the lamports
120 ///
121 /// # Account references
122 /// 0. `[writable]` The account to close, if closing a program must be the
123 /// ProgramData account.
124 /// 1. `[writable]` The account to deposit the closed account's lamports.
125 /// 2. `[signer]` The account's authority, Optional, required for
126 /// initialized accounts.
127 /// 3. `[writable]` The associated Program account if the account to close
128 /// is a ProgramData account.
129 Close,
130
131 /// Extend a program's ProgramData account by the specified number of bytes.
132 /// Only upgradeable program's can be extended.
133 ///
134 /// The payer account must contain sufficient lamports to fund the
135 /// ProgramData account to be rent-exempt. If the ProgramData account
136 /// balance is already sufficient to cover the rent exemption cost
137 /// for the extended bytes, the payer account is not required.
138 ///
139 /// # Account references
140 /// 0. `[writable]` The ProgramData account.
141 /// 1. `[writable]` The ProgramData account's associated Program account.
142 /// 2. `[]` System program (`solana_sdk::system_program::id()`), optional, used to transfer
143 /// lamports from the payer to the ProgramData account.
144 /// 3. `[signer]` The payer account, optional, that will pay necessary rent exemption costs
145 /// for the increased storage size.
146 ExtendProgram {
147 /// Number of bytes to extend the program data.
148 additional_bytes: u32,
149 },
150
151 /// Set a new authority that is allowed to write the buffer or upgrade the
152 /// program.
153 ///
154 /// This instruction differs from SetAuthority in that the new authority is a
155 /// required signer.
156 ///
157 /// # Account references
158 /// 0. `[writable]` The Buffer or ProgramData account to change the
159 /// authority of.
160 /// 1. `[signer]` The current authority.
161 /// 2. `[signer]` The new authority.
162 SetAuthorityChecked,
163}