Skip to main content

CIP-1: Actor Message Scheduler

Status: Revised for regenesis — auction retired; CIP-5 FIFO is normative Type: Standards Track
Category: Core
Created: 2025-10-01
Cowboy Cloud and Cowboy Chain. This CIP specifies the Cowboy protocol. Cowboy Cloud runs on this protocol today. Cowboy Chain, a public network on the same protocol, is under consideration for a future release. Where the two differ, this CIP says so.

Abstract

Background

Actors need bounded, deterministic execution of future work.

Goal

CIP-5 FIFO scheduling is the normative timer contract. Regenesis removes the CIP-1 auction, its activation parameter, priority tips, Gas Bidding Agents (GBAs), and fairness-weight ordering. There is no future activation height for these rules. The scheduler retains the timer-lane basefee, per-fire fee-payer pre-charge and refund, bounded due-window admission, and successful-fire FairnessCounter writes. Timer codec v6 and the reserved bid fields remain unchanged; bids have no effect on admission, ordering, or fees.

1. Motivation

CIP-5 supplies this through FIFO ordering, independently capped execution and cleanup budgets, and live-basefee payment at fire time. Congestion carries a bounded queue prefix forward without introducing bidding or priority boosts.

2. Height-Indexed FIFO Queue

Timers are indexed by due height and kept in insertion order within each height. Under CIP-5 §5.1, the native phase MUST materialize at most eight Timer records from the committed due-height FIFO head (or the current height when the backlog is empty), using fixed pages and a persisted head-page cursor. An ID in a later page MUST NOT leapfrog an ID in an earlier page. The all-quarantined prefix advances before its due height rotates as specified there; persisted Timer rows remain unchanged by that queue advance. The former tiered Calendar Queue proposal is not required by the FIFO contract.

3. Integration with the State Transition Function

The block executes transactions before the end-of-block timer phase, as specified by CIP-5 §5.1.
  1. Select a bounded FIFO due window and apply lifecycle/admission checks.
  2. Classify and pre-charge all admitted timers against pre-handler state. TTL expiry and insufficient-funds cleanup consume the independent GC budget.
  3. Reserve each complete cycle and charged-access request. A request that cannot fit carries forward intact; it does not execute against a partial remainder.
  4. Execute the admitted prefix, settle the live-basefee cost, burn the basefee portion, and refund unused escrow. Natural timer fires pay no proposer priority tip.
  5. Apply CIP-5 removal, retry, and native PoR re-arm rules. Persist the successful-fire counts described in §8 and advance the due-height cursor.
Reserved bid fields and stale auction governance values MUST NOT affect these steps.

4. Same-Block Prohibition

Timers created within the current block’s transactions MUST NOT execute in the same block. This avoids reentrancy via timer scheduling and ambiguity about the execution block. Consensus-critical.

5. Timer-Lane EIP-1559 Pricing

The Timer-lane basefee adjusts per block over the prior block’s timer-lane utilisation:
  • Target utilisation: 0.5 (50%) of the 8,800,000-cycle Timer lane.
  • Max basefee adjustment per block: ±12.5%.
  • 100% of the basefee is burned (consistent with CIP-3 §2.4 and WP §6 “100% basefee burn”). The lane basefee replaces the CIP-3 cycle-basefee meter for timer fires — timer cycles are metered against basefee_lane_timer only and are not double-charged against the global cycle basefee. The two meters are tracked separately (the timer lane runs its own EIP-1559 utilisation curve and its own burn tally) to preserve per-lane burn telemetry.
  • Per-lane fee multiplier is pinned at 1.0× at launch (CIP-3 §2.2.3 + WP §6 / §17.9; no subsidy). Tier-0 governance-tunable.
Natural timer fires pay only the applicable live-basefee charges. They have no priority-tip component and do not credit the proposer. FIFO admission is independent of the retained bid fields.

6. schedule_timer API

The classic and extended scheduling APIs, payer selection, per-fire resource requests, expiry, and schedule-time checks are specified by CIP-5. The Python SDK exposes no bid arguments. The host ABI retains optional max_fee_per_cycle and max_priority_fee_per_cycle slots, and Timer codec v6 retains the corresponding two u64 fields. The scheduler ignores these reserved slots. Their encoding stays unchanged and they do not enable bidding. Scheduling costs remain payable at scheduling time. Per-fire escrow is charged only when a timer is admitted to fire.

7. Gas Bidding Agents — Retired

The protocol does not call a GBA, compute a median-tip estimator, or expose a priority-tier hint. The auction’s GBA contract and priority-tier multipliers are removed from this specification.

8. Per-Actor Fire Counters

The FIFO path records successful timer fires in the actor’s FairnessCounter: CIP-4 §4.3 assigns StateValue::FairnessCounter tag 0x10, stored under the actor’s StatePrefix::Fairness key (0x1B, CIP-4 §4.2). The counter has fields last_height: u64, total: u64, and slots: Vec<u64>, a ring containing exactly 1,000 entries. For a successful fire at height h, load the actor’s counter (or initialize all fields to zero if absent), advance the window to h, then add one to slots[h % 1000] and total, using saturating u64 addition. Advancing clears each expired slot and subtracts its count from total with saturating subtraction; it updates last_height to h when h > last_height. The window is (h − 1000, h]; a gap of at least 1,000 blocks clears the entire ring. The FIFO path aggregates successful fires per actor within the block and persists their count in one load-modify-store in the active batch. Failed or skipped fires do not increment it. An empty window alone does not delete the stored row. The complete StateValue encoding is tag 0x10, counter codec version 0x01, last_height (big-endian u64), total (big-endian u64), slot count 1,000 (big-endian u32), then the 1,000 slots in index order (each big-endian u64). This defines the concrete storage contract; the former recent_executions[actor] description did not specify these bytes. These counters do not affect timer admission, order, or fees. The former W(actor) formula and network-median ranking are removed. Counter deletion or a timer codec change is a separate consensus change and is not part of auction retirement.

9. Lane Budgets and the Three-Path Timer Lifecycle

Per CIP-5 §6.5, the timer subsystem has two independent per-block cycle budgets: Natural timer execution consumes LANE_TIMER_CYCLES. GC draws from TIMER_GC_CYCLES, so a resume-after-outage storm of expired timers cannot starve live timer execution. The three-path lifecycle for any due timer (CIP-5 §5.4), plus explicit cancellation:
  1. When fee_payer is solvent and TTL has not expired, the scheduler pre-charges the fee, executes the timer and refunds the unused amount.
  2. When expires_at has passed, the scheduler destroys the timer under the GC lane.
  3. When balance(fee_payer) < max_cost, the scheduler destroys the timer under the GC lane and emits TimerCancelledInsufficientFunds.
  4. The actor cancels its own timer through a host syscall, or the validator set cancels it through emergency SYS_CANCEL_TIMER (§12).

10. Per-Timer Cycle Cap

Natural timer execution follows the CIP-5 per-fire cycle policy. Below TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, the fire cap is 550,000 cycles before the timer-lane bound. From that height, the governed fire cap is clamped to [550,000, 2,200,000] and then bounded by the selected timer lane. A fire also respects its persisted request; scheduling may declare a smaller request. From the gate, the ordinary default is 550,000, or a lower governed scheduling maximum; below the gate, scheduling defaults to the governed max_cycles_per_fire itself. The auction’s 250,000-cycle ceiling and governance override are removed.

11. DoS Mitigation and Congestion Handling

  • The dedicated execution lane and bounded native due window cap per-block timer work.
  • Per-fire pre-charge and the timer-lane basefee price resource consumption.
  • Complete reservations that cannot fit carry forward under CIP-5’s bounded retry/carry rules.
  • Independent GC capacity isolates TTL-expiry and insufficient-funds cleanup.
  • FIFO supplies no bid-based priority or per-actor anti-starvation boost.

12. System Instructions

This spec introduces no new system-instruction opcodes. The existing schedule_timer, schedule_timer_ex, cancel_timer, and extend_timer host calls retain their ABI. The supporting timer-management system instructions use the following opcodes: The canonical opcode allocation table is maintained in CIP-13.

13. Funding

Each scheduling actor MUST fund itself or a designated fee_payer with at least one max_cost reserve per pending timer. Long-running heartbeat actors SHOULD use schedule_timer_ex with an explicit fee_payer (default actor_self) and monitor its balance. Actors and watchtowers SHOULD subscribe to TimerCancelledInsufficientFunds. TTL-protected abandoned timers are cleaned up automatically.

14. Integration Requirements

  • CIP-5 §5.1 is normative for bounded FIFO selection and cursor rotation; §7.1 defines its committed manifest and admission cap. CIP-5 §§5.4 and 6 govern lifecycle and fee-payer accounting, and CIP-43 §5.3.1 defines the separate native-work allowance.
  • Reserved bid fields MUST NOT affect admission, ordering, execution caps, or settlement.
  • Successful-fire counters and existing Timer encoding remain byte-identical to FIFO behavior.
  • System instruction opcodes 48, 49, and 50 retain the functions in §12.
  • Transactions execute before timers; a newly scheduled timer cannot fire in its creating block.

15. Governance Parameters

cip1.auction.activation_height and cip1.auction.max_cycles_per_fire are removed from the recognized governance parameter paths. They cannot be set through SetGovParam or genesis gov_params. The former cip1.priority_tier_multipliers.{economy,standard,fast,urgent} and cip1.fairness_window_blocks paths are also unrecognized; GovParams rejects them as unknown, so governance proposals setting them are rejected. No finite activation height replaces the gate. Existing lane fee multipliers and CIP-5 configuration retain their own governance rules.

16. Validation Requirements

Regression coverage must show FIFO order and zero proposer tips even when reserved bid fields are nonzero or stale auction values exist in storage. Successful-fire counter writes, native item reservations, timer encoding, and FIFO settlement bytes must remain unchanged.