MIMD 0011 Ephemeral Crank

[Dodecahedr0x]

Ephemeral Crank

Abstract

Developers need to implement custom cranking solutions for executing transactions periodically or conditionally. This requires external infrastructure and increases complexity for developers building on MagicBlock.

This proposal introduces a task scheduling system that enables developers to schedule arbitrary transactions for execution by the validator at specific intervals or when certain conditions are met. The target properties of this system are:

• Flexible scheduling: Support for both time-based (periodic) and condition-based triggers
• Low latency: Tasks executed at the beginning of each slot to minimize delay

The proposed solution introduces a set of instructions in the MagicBlock program that write tasks to a dedicated task context account. A dedicated task scheduling service then takes tasks from the context and maintains them in a local database.

Proposed Design

Sequence overview

Below are the sequence diagrams of the different interactions between system components.

Task scheduler initialization

Upon initialization, the scheduler retrieves the task context from the bank and creates any tasks it does not already have in its database. It also retrieves an account subscription for the task context from the geyser_rpc_service to detect any changes in the context, indicating that an instruction has created or cancelled a task.

sequenceDiagram
    TaskScheduler->>TaskContext: Get existing tasks
    TaskScheduler->>SchedulerDB: Initialize with tasks
    TaskScheduler->>TaskScheduler: Schedule tasks
    TaskScheduler->>Validator: Subscribe to TaskContext

Loading

Scheduling tasks

Scheduling tasks can only occur through a program using CPI. This stores the definition of the task in the task context.

sequenceDiagram
    User->>Program: Interacts
    activate Program
    Program->>MagicProgram: Schedule task
    activate MagicProgram
    MagicProgram->>TaskContext: Store task
    MagicProgram-->>Program: Return
    deactivate MagicProgram
    Program-->>User: Return
    deactivate Program

Loading

Cancel task

Similarly, the task authority defined during scheduling can call the Magic program to cancel the task. It removes it from the context so that the scheduler can detect it.

sequenceDiagram
    User->>Program: Interacts
    activate Program
    Program->>MagicProgram: Cancel
    activate MagicProgram
    MagicProgram->>TaskContext: Remove task
    MagicProgram-->>Program: Return
    deactivate MagicProgram
    Program-->>User: Return
    deactivate Program

Loading

Updating scheduler DB

When the scheduler is notified that the task context has changed, it fetches the context account, reads the tasks, and updates its local DB accordingly: removes cancelled tasks and adds scheduled ones.

sequenceDiagram
    Validator-->>TaskScheduler: TaskContext notification
    activate TaskScheduler
    TaskScheduler->>SchedulerDB: (Un)register tasks in local DB
    deactivate TaskScheduler

Loading

Executing scheduled tasks

The scheduler has its own tick period, during which it checks if any tasks in the database should now be executed. If so, it runs the tasks' instructions and updates the corresponding rows in the DB.

sequenceDiagram
    loop Every scheduler tick
        activate TaskScheduler
        TaskScheduler<<->>SchedulerDB: Get executable tasks
        TaskScheduler->>TaskScheduler: Prepare transactions

        activate Validator
        TaskScheduler->>Validator: Execute transactions
        Validator-->>TaskScheduler: Return
        deactivate Validator

        TaskScheduler->>SchedulerDB: Update tasks
        deactivate TaskScheduler
    end

Loading

Data Structure

Solana Accounts

Data stored in accounts is written only once, to avoid serialization too frequently, which is expensive given the size of the account. The on-chain account is used to register requests that the task scheduling service will process. These requests provide the initial state of the task.

#[derive(Debug, Default, Serialize, Deserialize)]
pub struct TaskContext {
    /// Tree containing tasks indexed by their ID
    pub tasks: BTreeMap<u64, Task>,
}

pub struct Task {
    /// Unique identifier for this task
    pub id: u64,
    /// Unsigned transactions to execute when triggered
    pub transactions: Vec<Transaction>,
    /// Authority that can modify or cancel this task
    pub authority: Pubkey,
    /// Period of the task in milliseconds
    pub period_millis: i64,
    /// Number of times this task will be executed
    pub n_executions: u64,
}

Scheduler Database

Tasks in the database are updated on every execution.

pub struct DbTask {
    /// Unique identifier for this task
    pub id: u64,
    /// Unsigned transactions to execute when triggered
    pub transactions: Vec<Transaction>,
    /// Authority that can modify or cancel this task
    pub authority: Pubkey,
    /// Period of the task in milliseconds
    pub period_millis: i64,
    /// Number of times this task still needs to be executed.
    pub executions_left: u64,
    /// Timestamp of the next execution of this task in milliseconds
    pub next_execution_millis: i64,
}

Configuration

The task scheduler can

pub struct TaskSchedulerConfig {
/// Path the SQLite db file
pub db_path: String,
/// Whether to reset the local scheduler database
pub reset_db: bool,
/// How frequently we check for executable tasks
pub millis_per_tick: u64,
}

Future evolutions

Scheduling costs

The proposal currently does not price the execution of tasks. This can lead to potential abuses.

In subsequent iterations of this proposal, users will need to provision a budget related to the compute unit used by their tasks.

Conditional executions

In the current proposal, the same transactions are executed periodically. This does not allow for more complex use cases, such as limit orders that execute once an account reaches a specific value, or game collision detection that writes to an account only if it matches certain conditions.

Considered Alternatives

Extending MagicContext

Using the existing MagicContext account to store tasks alongside scheduled commits. This approach was rejected because:

• Mixed concerns: Combining commit scheduling with general task scheduling creates confusion
• Size constraints: MagicContext is already sized for commits; adding tasks would require significant resizing
• Separation of data: Tasks have different lifecycle patterns than commits

External Crank Services

Relying on external crank services (like Clockwork or TukTuk) to handle scheduled execution. This approach was rejected because:

• Latency overhead: External services add network round-trips and processing delays
• Infrastructure burden: Developers must deploy and maintain additional services
• Consistency issues: External cranks may miss slots or fail to execute in the ER environment

Geyser Plugin Approach

Using a Geyser plugin to monitor on-chain state and trigger transactions. This approach was rejected because:

• Implementation complexity: Plugins are harder to develop and debug than on-chain programs
• Transaction submission: Plugins must submit transactions through RPC, adding latency
• Validator performance: Geyser plugins process all account updates, creating unnecessary overhead

[notdanilo]

@Dodecahedr0x I have been thinking about the requirements from the consumer developer perspective and I need few things:

1. A delta-time between executions
2. A way to update the instruction data
3. A way to insert and remove the account metas
   3.1 The game loop takes the player pda for each player in the match
   3.2 The match join and match leave programs should be able to add and remove these accounts from the game loop scheduled transaction

Extra considerations:
4. Permissioning might be required (only certain programs can change the scheduled transaction)
5. If there are costs involved, anyone should be able to send funds (and get refunded if someone else added the required funds for X transactions)

[Dodecahedr0x]

Thanks a lot @notdanilo , I'll update the proposal to take that into account