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
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-fireFairnessCounter 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.- Select a bounded FIFO due window and apply lifecycle/admission checks.
- Classify and pre-charge all admitted timers against pre-handler state. TTL expiry and insufficient-funds cleanup consume the independent GC budget.
- Reserve each complete cycle and charged-access request. A request that cannot fit carries forward intact; it does not execute against a partial remainder.
- 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.
- 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.
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_timeronly 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.
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’sFairnessCounter: 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:
- When
fee_payeris solvent and TTL has not expired, the scheduler pre-charges the fee, executes the timer and refunds the unused amount. - When
expires_athas passed, the scheduler destroys the timer under the GC lane. - When
balance(fee_payer) < max_cost, the scheduler destroys the timer under the GC lane and emitsTimerCancelledInsufficientFunds. - 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. BelowTIMER_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 existingschedule_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 designatedfee_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.