MIMD-0025: Intent Execution Durability

[taco-paco]

Intent Execution Durability

Motivation

When a user schedules a commit, they are delegating an account to the ER with the expectation that its state will be persisted to the base chain. The validator is obligated to fulfill this — an unexecuted commit is a protocol-level breach of trust.

Today, that obligation is not enforced past the accept boundary. Once an Intent is accepted it leaves AccountsDB and lives exclusively in process memory. A validator crash anywhere between acceptance and L1 confirmation silently drops the Intent. There is no recovery, no retry, no report — the commitment is gone.

This proposal closes that gap by anchoring accepted Intents back in AccountsDB for their entire execution lifecycle.

---

Problem

Accepted intents leave AccountsDB and exist only in the in-memory TransactionScheduler global and the CommittorService mpsc channel. Neither survives a process restart.

Current flow

1. User calls ScheduleCommit / ScheduleIntentBundle
   → Intent stored in MagicContext (AccountsDB, survives restart)
2. Validator calls AcceptScheduledCommits
   → Intents popped from MagicContext
   → Moved into TransactionScheduler (in-memory global, lost on restart)
3. CommittorService picks up intents, executes them on L1
4. ScheduledCommitSent ER tx logs the result

The window between step 2 and step 4 is unprotected. Any crash drops all in-flight intents.

---

Proposed Solution

This proposal is similar to the outbox pattern, where AccountsDB itself serves as the durable outbox. Rather than handing an Intent directly to the CommittorService and hoping for the best, the validator first writes the Intent into AccountsDB as a dedicated ephemeral account. The CommittorService then processes it from there and only closes the account once L1 execution is confirmed. A crash at any point leaves the account in AccountsDB; on restart the validator calls getProgramAccounts with a discriminator filter, reads each account's status, and resumes accordingly.

Additionally, just before sending a transaction to L1, the validator records the transaction signature back into the MagicIntentAccount via SetIntentExecutionStage. This lets the restart logic distinguish "prepared but not yet sent" from "sent — check the signature on L1."

No stage is executed twice. Because SetIntentExecutionStage is committed to AccountsDB before the L1 transaction is submitted, any restart that finds status = Executing(...) will always query L1 for the stored signature first. A confirmed & successful tx signature advances or closes the intent. The write-before-send ordering is the invariant that makes this hold.

New execution flow

1. ScheduleCommit / ScheduleIntentBundle
2. AcceptScheduledCommits — moves Intent from MagicContext into a PDA with status Accepted
3. IntentExecutionService takes Intent for execution
4. SetIntentExecutionStage(signature) — updates Intent status with the constructed L1 signature
5. Send TX to Base
6. Close Intent account with report

Crash 1→2

Intent is still in MagicContext. The next AcceptScheduledCommits call picks it up and retries. No state is lost.

Crash 2→3

MagicIntentAccount exists with status = Accepted. On restart: discovered via getProgramAccounts, rescheduled for full execution.

Crash 3→4

MagicIntentAccount exists with status = Accepted — indistinguishable from crash 2→3. The L1 transaction was never sent, so the Intent can safely be re-prepared and re-executed.

Crash 4→5

MagicIntentAccount exists with status = Executing(signature). On restart: check signature on L1.

• Confirmed & successful → close Intent account
• !(Confirmed & successful) → reschedule

Crash 5→6

Same as crash 4→5: status = Executing(signature). Check signature, close or reschedule accordingly.

Note: Two-stage execution (commit + finalize) is a complication of step 5. Each stage has its own signature stored separately in the MagicIntentAccount. This is expanded in Instruction changes.

---

Account Design

MagicIntentAccount ephemeral account

Seeds: ["magic-intent", intent_id.to_le_bytes()]
Owner: MagicBlock builtin program

pub struct MagicIntentAccount {
    pub bundle: ScheduledIntentBundle,
    pub status: MagicIntentStatus,
}

pub enum MagicIntentStatus {
    Accepted,
    Executing(ExecutionStage),
}

pub enum ExecutionStage {
    SingleStage(Signature),
    TwoStage(TwoStageProgress),
}

pub enum TwoStageProgress {
    Committing(Signature),
    Finalizing { commit: Signature, finalize: Signature },
}

---

Instruction Changes

Modified: AcceptScheduledCommits

Removes up to N intents from the front of MagicContext.scheduled_base_intents. For each intent a MagicIntentAccount ephemeral account is created with status = Accepted. N is bounded by the transaction account limit: every new account must be passed as writable in the same transaction.

Accounts:

[validator_auth (signer), magic_context (writable),
 new_pda_0 (writable), new_pda_1 (writable), ...]

Logic (after existing pop from MagicContext): for each accepted intent, create a MagicIntentAccount ephemeral account with status = Accepted.

---

New: SetIntentExecutionStage { intent_id, stage: ExecutionStage }

Sets or advances the execution stage of an intent. Handles the initial transition from Accepted, signature replacement on retry, and advancement from Committing to Finalizing — all through a single instruction with a unified set of transition rules.

Accounts: [validator_auth (signer), intent_pda (writable)]

Transitions:

From	To	Notes
Accepted	Executing(SingleStage(sig))
Accepted	Executing(TwoStage(Committing(sig)))
Executing(SingleStage(_))	Executing(SingleStage(new_sig))	Signature replacement on retry
Executing(TwoStage(Committing(_)))	Executing(TwoStage(Committing(new_sig)))	Signature replacement on retry
Executing(TwoStage(Committing(commit)))	Executing(TwoStage(Finalizing { commit, finalize: sig }))	Advance to finalize phase
Executing(TwoStage(Finalizing { commit, _ }))	Executing(TwoStage(Finalizing { commit, finalize: new_sig }))	Signature replacement on retry; commit must match stored value

Checks:

• From Accepted: rejects TwoStage(Finalizing { .. }) — cannot skip the commit phase.
• From Executing(_): the execution type (SingleStage vs TwoStage) cannot change.
• From Executing(TwoStage(Finalizing { .. })): rejects TwoStage(Committing(_)) — downgrade not permitted. Reaching Finalizing means the commit transaction was confirmed on L1; going back to Committing would re-commit an already-committed account.

---

New: CloseMagicIntentAccount { intent_id }

Deallocates the MagicIntentAccount ephemeral account. Called after L1 execution is confirmed.

Accounts:

[validator_auth (signer), closing_pda (writable)]

Logic:

1. Wipe and deallocate closing_pda

---

Restart Recovery

Discovery

1. getProgramAccounts(magic_program_id, filters=[discriminator(MagicIntentAccount)])
   → returns all open intent accounts
2. Deserialize each account, sort by bundle.id ascending

Cost: one RPC call returning the set of intents that were accepted and not yet closed. No scanning of closed IDs, no range guessing, no dependency on total historical intent count.

Classification and recovery

match intent.status {
    Accepted =>
        reschedule_full(intent.bundle),

    Executing(SingleStage(sig)) =>
        match get_signature_status(sig).await {
            Succeeded => close_intent_account(intent.bundle.id).await,
            _         => reschedule_full(intent.bundle),
        },

    Executing(TwoStage(Committing(sig))) =>
        match get_signature_status(sig).await {
            Succeeded => reschedule_finalize_only(intent.bundle),
            _         => reschedule_full(intent.bundle),
        },

    Executing(TwoStage(Finalizing { finalize, .. })) =>
        match get_signature_status(finalize).await {
            Succeeded => close_intent_account(intent.bundle.id).await,
            _         => reschedule_finalize_only(intent.bundle),
        },
}

---

Intent Discovery: getProgramAccounts

The MagicBlock builtin program owns MagicContext (one singleton) and one MagicIntentAccount per open intent. A getProgramAccounts call filtered by the MagicIntentAccount discriminator returns all intent accounts that were accepted and have not yet been closed. After deserialization, accounts are sorted by bundle.id to restore processing order.

Each account's status field determines how recovery proceeds — an account with status = Accepted means the intent has not yet been sent to L1 and needs full execution; an account with status = Executing(...) requires checking the stored signature(s) on L1 before deciding whether to close or reschedule.

---

Considered Alternatives

Option A: Linked list (MagicIntentList + prev_id/next_id)

Maintain a MagicIntentList singleton (head + tail) and embed prev_id/next_id pointers in each MagicIntentAccount. On restart, traverse from head to tail.

Problem — unnecessary complexity: getProgramAccounts already returns the same set of open intents in one call. The linked list duplicates this with extra fields per account, a shared singleton written on every accept and every close, and more complex close logic (relinking neighbors).

Verdict: Superseded by getProgramAccounts.

---

Option B: Watermark + range scan

Store accepted_intent_watermark: u64 in MagicContext. On restart, scan intent PDAs for IDs in the range [watermark, intent_id).

Mechanism:

• Watermark advances only when the intent at the watermark position closes
• On restart: batch-fetch PDAs via getMultipleAccounts for the range

Problem — stuck watermark: If a single intent fails persistently (e.g., an integrator bug causes repeated execution failure), the watermark is stuck at that intent's ID. Every subsequent restart must scan from that ID through the entire current range. Other intents in the range are discoverable, but the scan grows unboundedly until the stuck intent is resolved.

Furthermore, the watermark advancement logic requires careful coordination: advancing past gaps means scanning forward for the next live PDA, which requires either additional instructions or off-chain bookkeeping.

Verdict: Functionally correct but operationally fragile. A single stuck intent degrades restart performance for all subsequent restarts.

---

Option C: Bitmap pages

Group intent IDs into pages of fixed size (e.g., 256). Each page is a PDA storing a bitmap of which intent IDs within its range are still active.

// PDA: ["magic-intent-page", page_id.to_le_bytes()]
struct ActiveIntentPage {
    page_id: u64,
    base_intent_id: u64,
    active_bitmap: [u64; 4],   // 256 bits
    active_count: u16,
}

On restart: scan page PDAs from min_active_page to current_page, extract set bits, fetch the corresponding intent PDAs.

Problem — hot shared account: Every CloseMagicIntentAccount for any intent in page range [0, 255] writes to the same page 0 PDA. Every AcceptScheduledCommits that allocates into page 0 also writes to page 0. All operations in the same page range serialize on a single shared account.

Problem — page watermark inherits the stuck-intent problem: min_active_page cannot advance past page N until all 256 intents in page N close. One stuck intent holds up the entire page's retirement. The restart scan cost is O(N/256) page fetches — better than a plain watermark, but the underlying problem remains.

Problem — two-level indirection on restart: Pages tell you which IDs were accepted; you still need a second round of PDA fetches to get the actual intent data.

Verdict: Better than a plain watermark for restart scan efficiency (coarser granularity), but introduces a shared hot-account bottleneck and does not fully eliminate the stuck-intent scan problem.

---

Comparison

	getProgramAccounts	Linked list	Bitmap pages	Watermark scan
Restart discovery	One filtered RPC call	O(open) traversal	O(N/PAGE_SIZE) + O(open)	O(gap from watermark)
Stuck-intent impact on restart	None	None	Blocks page retirement	Blocks watermark advancement
Close instruction complexity	Wipe account (2 accounts)	Relink 2 neighbors (3–5 accounts)	Flip 1 bit (2 accounts)	Wipe account (2 accounts)
Shared hot account	None	MagicIntentList singleton	Page PDA (up to 256 intents)	None
Extra state per intent	0	+16 bytes (prev_id, next_id)	~0.2 bytes in page bitmap	0

getProgramAccounts is chosen for its minimal account structure, no shared hot accounts, simplest close logic, and correct stuck-intent behavior.

---

Implementation Scope

Component	Change
magicblock-magic-program-api/src/pda.rs	Add intent_account_pda(id)
magicblock-magic-program-api/src/instruction.rs	Add SetIntentExecutionStage, CloseMagicIntentAccount variants
programs/magicblock/src/	Add MagicIntentAccount, MagicIntentStatus types
programs/magicblock/src/schedule_transactions/process_accept_scheduled_commits.rs	Create intent ephemeral accounts
programs/magicblock/src/schedule_transactions/ (new files)	process_set_intent_execution_stage.rs, process_close_intent_account.rs
programs/magicblock/src/magicblock_processor.rs	Wire new instruction variants
magicblock-committor-service/src/ (new file)	restart_loader.rs — getProgramAccounts fetch, sort by id, classification, recovery dispatch
magicblock-committor-service/src/intent_executor/	Call SetIntentExecutionStage before L1 submission
magicblock-accounts/src/scheduled_commits_processor.rs	Replace register_scheduled_commit_sent with CloseMagicIntentAccount call

[GabrielePicco]

Overall, I like the idea, especially since this gets rid of committor_service.sqlite. A few questions:

• Who pays rent for the PDAs? Sponsor or vault rent escrow?
• The PDA must store the full ScheduledIntentBundle in this new implementation. Otherwise, recovery could lose base actions or standalone actions.
• We should also include a retry mechanism.

[taco-paco]

• Magic fee vault could but then need to be careful with extracting fee as there should always be enough for covering this flow, so I would detach it from this. Could be validator keypair on ER, it will always get funds back as we close accounts on completion and print report
• Correct
• There will be 2 retries mechanics: 1. on restart all uncompleted intents are loaded as per design, 2. exponential retries as we discussed

[Dodecahedr0x]

Additionally, just before sending a transaction to L1, the validator records the transaction signature back into the MagicIntentAccount via SetIntentExecutionStage. This lets the restart logic distinguish "prepared but not yet sent" from "sent — check the signature on L1."

Does it need to wait for confirmation of the ER update before sending?

---

Shouldn't scheduling directly create the PDA? It removes the need for the context and Accepted staus, and accounts could be sponsored. Deriving the PDA from committed account's pubkey + commit ID which is already checked on commits.

But it does put the burden of checking commit ID on users to derive the account

---

Key property: the list contains exactly the open intents. There is no scanning, no approximation, no index lag.

Shouldn't the accountsdb index of Magic program accounts be fairly small and lag-free? Both approaches are O(accepted intents), but the additional parsing to find next list elements should add latency compared to fetching all and then deserializing all.

[taco-paco]

Does it need to wait for confirmation of the ER update before sending?

If you mean update of ER state, then yes. Tx has to be successfully executed on ER and only after that we can send Intent tx to Base

Shouldn't scheduling directly create the PDA? It removes the need for the context and Accepted staus, and accounts could be sponsored. Deriving the PDA from committed account's pubkey + commit ID which is already checked on commits.

But it does put the burden of checking commit ID on users to derive the account

Couple of problems with that

• This breaks all existing integrations as the submit 3 accs
• Users would face constantly failing tx, as there could be many users concurrently scheduling intents. If we derive [magic, intent_id] then only one user will manage to create intent for others tx will fail
• Commit IDs unknown unfortunatly

2, 3 solvable probably, but the main one is making it backward compatible

Shouldn't the accountsdb index of Magic program accounts be fairly small and lag-free? Both approaches are O(accepted intents), but the additional parsing to find next list elements should add latency compared to fetching all and then deserializing all.

Not sure I undestand the alternative. The main issue: to fetch account you need to know address, which isn't always known. Intents may complete out of order, creating holes between completed and not.

For example, we had many cases where user program undelegation callback failed, failing intent. Recently it took user more than 2 days to fix it, while other intent could be succesful or maybe not. So to index it manually you would have to scan 2 days worth of intents.

[Dodecahedr0x]

We could envision "breaking stuff" for the new magic program: keep the current one around for some time, but introduce the new one, split into a user-facing and internal magic program.

But I agree that having to guess the commit ID is not an option.

---

The main issue: to fetch account you need to know address, which isn't always known

getProgramAccounts with filters (e.g. discriminator of intents) does not need to know the addresses. You use it to get all MagicIntentAccount. The accountDB index for this program should contain mostly intents. They are not in order by default but can be reordered when parsed. If the account exists, it means the intent was accepted and should be processed right away.

I'm not sure I understand how the example is related: if the intent was stuck, its account would still be open and the validator (even after a restart) would know it needs to handle it

[taco-paco]

getProgramAccounts with filters (e.g. discriminator of intents) does not need to know the addresses. You use it to get all MagicIntentAccount. The accountDB index for this program should contain mostly intents. They are not in order by default but can be reordered when parsed. If the account exists, it means the intent was accepted and should be processed right away.

I'm not sure I understand how the example is related: if the intent was stuck, its account would still be open and the validator (even after a restart) would know it needs to handle it

Wasn't aware of getProgramAccounts, sounds like it could simplify things a lot, I will check it out.

[snawaz]

This design should work. However, it looks quite complex to me unless there is a strong technical reason for that complexity.

I was thinking about a much simpler alternative:

Instead of creating a PDA for each intent and maintaining a doubly-linked list across those PDAs, why don’t we store the accepted intents in MagicContext itself? Well, we already store scheduled intents there before acceptance. Could we treat MagicContext as the durable list of intents to process, and only remove an intent once it is fully done?

If we need extra metadata for restart recovery, we can add it to the intent entry itself, or globally in the MagicContext, e.g status like Scheduled, Accepted, or Executing(signature/stage). On restart, the validator would just read MagicContext, find unfinished intents, and resume them.

Is there a strong reason this would not work? Size shouldn't be a problem because sizeof(ScheduledIntentBundle) == 456 which means even if we store 10000 intents, it is still around 4.3MB. If so, we should compare:

"one single account/context containing the list of intents + metadata"

vs

"10000 PDAs, their creation and closing logics, complexity of handling doubly-linked-list, additional instructions".

If support for 10,000 in-flight intents is not enough, and we expect more, say closer to 100,000 intents, then we should also ask whether 100,000 PDAs is a good design. 🤔

If for some reason, MagicContext breaks something, then maybe we can have another account, say DurableContext (or InflightIntents) and use the same approach?

[taco-paco]

If the limit is reasonably high and a program still hits it, then that is probably a signal that something is wrong, either on the validator side or on the user-program side, right? Again, not necessarily but could be!

I think we mix in 2 things:

1. Ability to schedule intents, accept and execute them
2. Whatever custom logic user needs on top: Limiter, Optimizer and whatever else

Both Optimizer(not committing same data), Limiter(having some upper bound on frequency capacity) is a build on top of an ability to schedule and progress Intents.

Those could be user(or us) implemented proxy programs or utils. For now it is important to address durable execution flow, scheduling and so on as this is a basic functionality we have to provide and that can be built on top by anyone

[taco-paco]

So I think bounded design gives us explicit backpressure and failure visibility: "this xyz program has too many unfinished intents".

That does not necessarily mean a failure. ER processes TXs much faster than Solana, users could fill proposed account just because Solana can't keep up. This adds an extra error handling on user side, one user may want it and another don't. The one who need it really should address it themself via proxy programs or even easier offchain as we can't account for all needs of users and neither we should. We need just to provide a basic functionality as mention in previos comment.

The diagnostics of failed intents is also pretty straightworfard as we have alerts on the spots the shouldn't really fail, like: commit, finalize. There's also alerts on undelegation that usually is user integration issue.

[snawaz]

That does not necessarily mean a failure.

Yes, I agree. I didn’t say it is necessarily a failure either. But what if it is? Then it could be a useful signal.

Anyway, we should compare both the real pros/cons of each design that we immediately see. We should also compare the potential pros/cons that we could think of, but won’t necessarily take advantage of, at least not immediately.

[taco-paco]

If we protecting from failure smart contracts usually have pause. If there's an issue that(pause) could be triggered to reject commits, designing account just for that is an overkill imo

[snawaz]

If we protecting from failure smart contracts usually have pause. If there's an issue that(pause) could be triggered to reject commits, designing account just for that is an overkill imo

I think "just for that" misrepresents the argument I'm making.

My point is that there are two ways to design the accounts to support the durability/reliability of commit requests, and we seem to agree that both achieve that primary goal.. and honestly neither seems "overkill" to me, as in both cases we're doing almost the same/similar thing.

Once that primary goal is satisfied, I'm comparing the additional trade-offs of each approach. As I mentioned earlier, we may or may not end up taking advantage of those benefits, but I still think they're relevant when evaluating the design, because they keep our doors open.