This document explains the cron module for the Neutron network. The Cron module allows scheduling automatic smart contract executions at predefined block intervals, similar to Unix cron jobs. This feature enables time-based automation in blockchain applications through governance-controlled schedule management.

​
Table of contents

  • Overview — a high-level description of the module.
  • Explanation — an explanation of the module’s concepts and the reasoning behind its design choices.
  • How To — short guides on performing basic operations with the module.
  • Reference — comprehensive technical details including messages, events, state, client, and API documentation.

​
Concepts

The Cron module serves as an on-chain block-based scheduling system that enables:
  • Scheduled Block Executions: Register messages to be executed at specific block intervals
  • Periodic Tasks: Set up recurring executions every N blocks
  • Governance-Controlled Scheduling: All schedule creation requires governance approval

​
Governance-Gated Access

  • Schedule creation is controlled through governance (Main DAO or Cron SubDAO)
  • Contracts cannot directly create schedules
  • Schedule management requires governance proposals
The Cron module operates within Neutron’s modular governance system, which uses specialized subDAOs to handle different aspects of network management. The Cron SubDAO specifically manages scheduling-related proposals.

​
Block-Based Execution

  • Execution timing is based on block heights, not precise timestamps
  • The module has a limit on how many schedules can be executed per block
  • Schedules are identified by unique names for easy management

​
Operation Flow

A typical workflow using the Cron module consists of:
  1. Governance Proposal: Submit a governance proposal to create a schedule specifying:
    • A unique name
    • The execution period (in blocks)
    • Messages to execute
  2. Schedule Tracking: The module maintains a registry of all schedules and tracks their execution status.
  3. Automatic Execution: When a block is produced, the module:
    • Identifies schedules due for execution
    • Executes up to the per-block limit of schedules
    • Updates their last execution height
  4. Schedule Management: Through governance, schedules can be:
    • Removed when they’re no longer needed

​
Integration with Smart Contracts

The Cron module integrates with smart contracts through:
  • Execution Callbacks: The scheduled messages are sent to target contracts
  • Governance Proposals: Contract owners work with governance to create schedules
This allows developers to implement various block-based functionalities such as:
  • Regular protocol maintenance operations
  • Periodic distribution schedules
  • Block-based DeFi operations
  • Automated governance actions