magicblock_magic_program_api/instruction.rs
1use std::collections::HashMap;
2
3use serde::{Deserialize, Serialize};
4use solana_program::pubkey::Pubkey;
5
6use crate::args::{
7 MagicBaseIntentArgs, MagicIntentBundleArgs, ScheduleTaskArgs,
8};
9
10#[derive(Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
11pub enum MagicBlockInstruction {
12 /// Modify one or more accounts
13 ///
14 /// # Account references
15 /// - **0.** `[WRITE, SIGNER]` Validator Authority
16 /// - **1..n.** `[WRITE]` Accounts to modify
17 /// - **n+1** `[SIGNER]` (Implicit NativeLoader)
18 ModifyAccounts {
19 accounts: HashMap<Pubkey, AccountModificationForInstruction>,
20 message: Option<String>,
21 },
22
23 /// Schedules the accounts provided at end of accounts Vec to be committed.
24 /// It should be invoked from the program whose PDA accounts are to be
25 /// committed.
26 ///
27 /// This is the first part of scheduling a commit.
28 /// A second transaction [MagicBlockInstruction::AcceptScheduleCommits] has to run in order
29 /// to finish scheduling the commit.
30 ///
31 /// # Account references
32 /// - **0.** `[WRITE, SIGNER]` Payer requesting the commit to be scheduled
33 /// - **1.** `[WRITE]` Magic Context Account containing to which we store
34 /// the scheduled commits
35 /// - **2..n** `[]` Accounts to be committed
36 ScheduleCommit,
37
38 /// This is the exact same instruction as [MagicBlockInstruction::ScheduleCommit] except
39 /// that the [ScheduledCommit] is flagged such that when accounts are committed, a request
40 /// to undelegate them is included with the same transaction.
41 /// Additionally the validator will refuse anymore transactions for the specific account
42 /// since they are no longer considered delegated to it.
43 ///
44 /// This is the first part of scheduling a commit.
45 /// A second transaction [MagicBlockInstruction::AcceptScheduleCommits] has to run in order
46 /// to finish scheduling the commit.
47 ///
48 /// # Account references
49 /// - **0.** `[WRITE, SIGNER]` Payer requesting the commit to be scheduled
50 /// - **1.** `[WRITE]` Magic Context Account containing to which we store
51 /// the scheduled commits
52 /// - **2..n** `[]` Accounts to be committed and undelegated
53 ScheduleCommitAndUndelegate,
54
55 /// Moves the scheduled commit from the MagicContext to the global scheduled commits
56 /// map. This is the second part of scheduling a commit.
57 ///
58 /// It is run at the start of the slot to update the global scheduled commits map just
59 /// in time for the validator to realize the commits right after.
60 ///
61 /// # Account references
62 /// - **0.** `[SIGNER]` Validator Authority
63 /// - **1.** `[WRITE]` Magic Context Account containing the initially scheduled commits
64 AcceptScheduleCommits,
65
66 /// Records the attempt to realize a scheduled commit on chain.
67 ///
68 /// The signature of this transaction can be pre-calculated since we pass the
69 /// ID of the scheduled commit and retrieve the signature from a globally
70 /// stored hashmap.
71 ///
72 /// We implement it this way so we can log the signature of this transaction
73 /// as part of the [MagicBlockInstruction::ScheduleCommit] instruction.
74 /// Args: (intent_id, bump) - bump is needed in order to guarantee unique transactions
75 ScheduledCommitSent((u64, u64)),
76
77 /// Schedules execution of a single *base intent*.
78 ///
79 /// A "base intent" is an atomic unit of work executed by the validator on the Base layer,
80 /// such as:
81 /// - executing standalone base actions (`BaseActions`)
82 /// - committing a set of accounts (`Commit`)
83 /// - committing and undelegating accounts, optionally with post-actions (`CommitAndUndelegate`)
84 ///
85 /// This instruction is the legacy/single-intent variant of scheduling. For batching multiple
86 /// independent intents into a single instruction, see [`MagicBlockInstruction::ScheduleIntentBundle`].
87 ///
88 /// # Account references
89 /// - **0.** `[WRITE, SIGNER]` Payer requesting the intent to be scheduled
90 /// - **1.** `[WRITE]` Magic Context account
91 /// - **2..n** `[]` Accounts referenced by the intent (including action accounts)
92 ///
93 /// # Data
94 /// The embedded [`MagicBaseIntentArgs`] encodes account references by indices into the
95 /// accounts array (compact representation).
96 ScheduleBaseIntent(MagicBaseIntentArgs),
97
98 /// Schedule a new task for execution
99 ///
100 /// # Account references
101 /// - **0.** `[WRITE, SIGNER]` Payer (payer)
102 /// - **1.** `[WRITE]` Task context account
103 /// - **2..n** `[]` Accounts included in the task
104 ScheduleTask(ScheduleTaskArgs),
105
106 /// Cancel a task
107 ///
108 /// # Account references
109 /// - **0.** `[WRITE, SIGNER]` Task authority
110 /// - **1.** `[WRITE]` Task context account
111 CancelTask { task_id: i64 },
112
113 /// Disables the executable check, needed to modify the data of a program
114 /// in preparation to deploying it via LoaderV4 and to modify its authority.
115 ///
116 /// # Account references
117 /// - **0.** `[SIGNER]` Validator authority
118 DisableExecutableCheck,
119
120 /// Enables the executable check, and should run after
121 /// a program is deployed with the LoaderV4 and we modified its authority
122 ///
123 /// # Account references
124 /// - **0.** `[SIGNER]` Validator authority
125 EnableExecutableCheck,
126
127 /// Noop instruction
128 Noop(u64),
129
130 /// Schedules execution of a *bundle* of intents in a single instruction.
131 ///
132 /// A "intent bundle" is an atomic unit of work executed by the validator on the Base layer,
133 /// such as:
134 /// - standalone base actions
135 /// - an optional `Commit`
136 /// - an optional `CommitAndUndelegate`
137 ///
138 /// This is the recommended scheduling path when the caller wants to submit multiple
139 /// independent intents while paying account overhead only once.
140 ///
141 /// # Account references
142 /// - **0.** `[WRITE, SIGNER]` Payer requesting the bundle to be scheduled
143 /// - **1.** `[WRITE]` Magic Context account
144 /// - **2..n** `[]` All accounts referenced by any intent in the bundle
145 ///
146 /// # Data
147 /// The embedded [`MagicIntentBundleArgs`] encodes account references by indices into the
148 /// accounts array.
149 ScheduleIntentBundle(MagicIntentBundleArgs),
150}
151
152impl MagicBlockInstruction {
153 pub fn try_to_vec(&self) -> Result<Vec<u8>, bincode::Error> {
154 bincode::serialize(self)
155 }
156}
157
158#[derive(Default, Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
159pub struct AccountModification {
160 pub pubkey: Pubkey,
161 pub lamports: Option<u64>,
162 pub owner: Option<Pubkey>,
163 pub executable: Option<bool>,
164 pub data: Option<Vec<u8>>,
165 pub delegated: Option<bool>,
166 pub confined: Option<bool>,
167 pub remote_slot: Option<u64>,
168}
169
170#[derive(Default, Clone, Serialize, Deserialize, Debug, PartialEq, Eq)]
171pub struct AccountModificationForInstruction {
172 pub lamports: Option<u64>,
173 pub owner: Option<Pubkey>,
174 pub executable: Option<bool>,
175 pub data_key: Option<u64>,
176 pub delegated: Option<bool>,
177 pub confined: Option<bool>,
178 pub remote_slot: Option<u64>,
179}