Skip to main content
Status: Draft Type: Standards Track Category: Core Created: 2026-01-19 Updated: 2026-10-03 Requires: CIP-1, CIP-3
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.
This document specifies the FIFO timer mechanism (within a block-height bucket, with the per-fire fee_payer model). CIP-5 FIFO is normative. The CIP-1 auction is retired at regenesis; no governance activation switches timers to bidding or priority-tip settlement.

Background

On-chain actors need to schedule execution without external keepers.

Goal

This proposal defines Cowboy’s native timers. Each timer runs once at a specified block height and names its fee payer.

1. Abstract

Actors register timers for a future block height. Each timer records its payer (fee_payer), per-fire gas limit (gas_limit_per_fire), and expiry height (expires_at). At the End of Block (EOB), the protocol collects all timers whose height matches the current block, pre-charges the fee payer, executes the handler, refunds unused gas, and removes the timer. A timer that its fee payer can no longer fund, or that has passed its TTL, is destroyed on the next block without executing. Execution follows insertion order within each height bucket (FIFO). No priority queue or bidding is involved. Metering follows CIP-3’s dual-metered model (Cycles/Cells). Protocol-level timer parameters (max_ttl_blocks, max_cycles_per_fire, max_cells_per_fire, max_timers_per_actor, gc_cycles_per_block) are held in a governed TimerConfig, updated through the same SubmitProposal, CastVote, and ExecuteProposal path as BasefeeConfig.

2. Motivation

Use cases include:
  • An actor creates a heartbeat loop by scheduling its next timer from its handler.
  • After an off-chain computation (CIP-2), an actor schedules a follow-up action at a known future height.
  • Timers execute vesting, escrow release, or governance proposals at predetermined heights.
Timers use bounded FIFO scheduling and per-fire live-basefee payment. The former auction, GBA bidding, and tiered-queue target is retired (§9).

3. Specification

3.1 Timer Data Structure

The current Timer codec version is 6, including the persisted access_limit_per_fire. The decoder requires version 6 and rejects older versions; there is no defaulting of missing fields. The state-row payload is IndexedTimer { timer: Timer, index_page: u64 }, with its own codec version 1, wrapped by StateValue tag 0x05. The page locator bounds cancellation and removal work without searching a height’s entire timer list. The wallet-identity amendment preserves this format.

3.2 Timer Index

The current height index is a bounded, paged FIFO. Its metadata keeps the existing hashed height key; physical pages have a distinct prefix and raw height/page key. Each encoding identifies a separate row. All keys below are exactly 86 bytes, including their prefix and zero padding. TimerIndexMeta contains len: u32, head_page, tail_page, next_page (all u64) and an optional recycled_page. A TimerIndexPage contains optional previous/next page IDs and at most 64 timer IDs, maintained in insertion order. Optional page IDs encode None as u64::MAX. The per-height live count is bounded by 16,384. Removal uses the timer record’s persisted page locator; empty pages are unlinked, and at most one is retained for deterministic reuse. The due-height queue/link rows track unfinished buckets without a global scan. Every row is consensus state in QMDB and contributes to state_root. The earlier monolithic TimerList height-index description is superseded by this existing format. StateValue’s TimerList tag 0x06 remains in use for the per-actor timer-ID roster under key prefix 0x1A; it is not the current payload at the height metadata key 0x06. The per-actor count and roster remain the separate address-keyed rows specified in CIP-4 §12.3. This inventory matches CIP-4 §§4.2–4.3. The wallet-identity release adds only the WalletMark namespace; it does not introduce these timer rows or change timer scheduling semantics.

3.3 Timer ID Generation

Timer IDs are deterministically derived:
Where nonce is the transaction nonce of the calling actor at the time of scheduling. This guarantees uniqueness across all timers.

4. API

4.1 Python Host API

Actors can use the raw pvm_host binding or the SDK wrapper. The raw extended binding takes six positional arguments; it has no Python keyword/default arguments or bid parameters:
For the raw extended call, fee_payer=b"" means the actor pays itself; otherwise it must be a 20-byte address satisfying §4.2. Zero gas_limit selects the cycle default defined below. Zero access_limit and expires_at select DEFAULT_TIMER_ACCESS_PER_FIRE and current_height + max_ttl_blocks, respectively. Reserved fee slots belong to the internal host ABI; the Python binding supplies None for them and exposes no bid arguments. The SDK handles optional arguments and translates None into those sentinels:
Let G = TimerConfig.max_cycles_per_fire. The classic scheduler and an omitted, None, or zero gas_limit use G below TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, and min(550_000, G) from that height. At the ordinary G = 550_000, this remains 550,000. A positive explicit request MUST be at most G below the gate and min(G, 2_200_000) from the gate. The SDK sends None as the raw host’s zero sentinel; an explicit zero reaches that same default path. access_limit precedes expires_at. It is the persisted per-fire structural (unscaled) access request; admission applies the access scalar when reserving it. Omission uses DEFAULT_TIMER_ACCESS_PER_FIRE = 160, including the classic two-argument scheduler. The SDK rejects explicit nonpositive access requests. The current enforced ceiling is TIMER_ACTOR_INTENT_ACCESSES_LIMIT = 375; requests above it are rejected. TIMER_ACCESSES_LIMIT = 322 is the general child-producing tier, not the maximum explicit request. A handler that queues deferred or Runner work may need an explicit larger request; selecting 375 does not guarantee that arbitrary handler work fits its other limits.

4.2 Constraints

  • height MUST be strictly greater than the current block height. Scheduling at the current or past height returns an error.
  • Each timer fires exactly once and is immediately removed. To create recurring behavior, the actor must schedule a new timer from within its handler.
  • The SDK emits a canonical CBOR map with exactly {"_handler": "<name>", "_payload": <byte string>}. The node first recognizes this envelope and persists the named handler and the original payload bytes; firing delivers those bytes unchanged. The map uses definite lengths, shortest heads and canonical key order, with no trailing bytes or extra entries. The handler name must be non-empty and at most 256 UTF-8 bytes.
  • Hand-built JSON envelopes containing {"_handler": "<name>", "_payload": <json-value>} remain accepted. Their inner value is re-serialized as compact JSON bytes; a byte-value list stays JSON text such as [1,2], without base64 or byte-list decoding. If _payload is omitted, the outer object minus _handler is delivered. A payload that matches neither valid envelope uses handle_timer with the original bytes.
  • timer.schedule(..., handler=...) and runtime.schedule_after(...) always emit the CBOR envelope. The SDK checks the handler’s UTF-8 byte length and normalizes non-empty fee_payer addresses before the host call. handler=None keeps the raw payload. Timer targets that expect byte payloads must declare decode="raw"; the ordinary handler default is CBOR decoding (CIP-6 §9.5).
  • The payload can contain at most 1,048,576 bytes (1 MiB).
  • The handler name can contain at most 256 bytes.
  • The host validates fee_payer at schedule time:
    • ZERO (burn address) is rejected.
    • The reserved system-actor band 0x01..=0xFF (every address below RESERVED_SYSTEM_ADDRESS_LIMIT = 0x100) is rejected as a third-party fee_payer. This covers every currently assigned system actor (runner registry / dispatcher / verifier / secrets / TEE / token registry / entitlement registry / RAS / basefee / governance / event-subscription 0x1D) plus the reserved slots up to 0xFF. An actor cannot delegate payment to a system actor.
      • A system actor MAY name itself as fee_payer (i.e. fee_payer == actor_address within the system band). This permits the payer identity at schedule time; it does not determine the funding source. Ordinary timers debit the named account. The native Storage Manager PoR timer instead uses 0x0A as the selector for the 0x0B challenge pool (§6.3; CIP-9 §5.6), with no debit from 0x0A. The exemption is strictly fee_payer == actor_address: one system actor still cannot name a different system actor. No exception below permits a third party to name a system-band fee_payer.
    • For ordinary actors, fee_payer MUST be the executing actor_address (actor pays itself). Any third-party address, including the current tx_sender, is rejected with InvalidInput, except the strictly bound CIP-7 canonical Watchtower Feed paths below.
      • Under sender-pays (CIP-3 §2.5), a signed caller funds transaction gas from its escrow. Invoker-billed timers would let any callee bill its caller, including a Gateway wallet, beyond that escrow.
      • Future opt-in third-party sponsorship (NOT in this revision) would require an explicit on-chain allowance (e.g. fee_payer pre-authorizes the scheduling actor via a storage-based quota) or a signed authorization carried in the scheduling tx. This revision grants no general third-party timer sponsorship.
    • The exact CIP-7 canonical CONSENSUS Feed may name its configured owner as fee_payer for initial registration and owner-triggered restart_dispatch_timer, only through its exact-code native path, which MUST authenticate config.owner == tx_sender. Ordinary actor code, copied/noncanonical Feed code and non-owner calls receive no such authority. This is the Feed owner’s own signed call, not permission for a callee to bill an invoker. Recovery is idempotent while the stored timer is live.
    • During an authentic CIP-7 firing of the exact canonical CONSENSUS Feed artifact, native authority binds the executing Feed, its stored dispatch_timer_id, and its immutable owner/payer to the timer being fired. Only that authority may rearm the next one-block dispatch timer with the same payer. Ordinary calls, copied/noncanonical code, mismatched timer IDs and different payers do not receive this exception. Start/restart uses the separate owner-authenticated native path above. Neither exception grants general third-party sponsorship; all budget, funding, rollback and one-shot rules still apply.
    • An omitted fee_payer defaults to actor_address.
  • At scheduling, gas_limit_per_fire MUST be ≤ TimerConfig.max_cycles_per_fire; from TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, it MUST also be ≤ 2,200,000 (§4.1).
  • expires_at MUST satisfy expires_at ≤ current_height + TimerConfig.max_ttl_blocks. A timer whose expires_at has passed is destroyed on its next scheduled fire without executing (see §5.4).
  • An actor may hold at most TimerConfig.max_timers_per_actor live timers at any time (maintained via a per-actor secondary index).
  • The PVM host permits cancel_timer only where timer.actor_address == executing_actor. Cross-actor cancellation returns Unauthorized, closing the prior ownership-check bug. Only system instructions expose owner and governance cancellation; no host call does (§5.4).

4.3 Side Effect Semantics

Timer scheduling and cancellation are side effects of transaction execution:
  • Scheduled timers pass the §4.2 validation (fee_payer, TTL, gas caps, per-actor cap) during the originating tx’s execution; validation failure reverts the tx. Accepted timers are collected in ExecutionSideEffects.scheduled_timers and persisted to storage after the transaction commits.
  • Cancelled timers pass the §4.2 authorization check (or the §5.4 system-instruction authorization) and are collected in ExecutionSideEffects.cancelled_timers, then removed from storage after the transaction commits. Any pre-charged max_cost is refunded on the same commit.
  • Transaction rollback discards timer schedules, cancellations, and pre-charges.

5. End-of-Block Delivery

5.1 Execution Order

Timer delivery occurs at the end of block, after all user transactions have been executed. The sequence within process_block() is:
  1. Execute all user transactions (TX phase).
  2. Select the bounded FIFO window from the committed due-height queue head, or from current_height when that queue is empty. At most TIMER_DUE_WINDOW_PER_BLOCK = 8 Timer records MUST be materialized in one block. Start at the selected height’s persisted head-page cursor and follow its page links in insertion order; selection may cross sparse pages to fill the window. An ID in a later page MUST NOT leapfrog an ID in an earlier page. Reserved bid fields MUST NOT affect admission or ordering.
  3. Apply the rent-quarantine predicate to the selected window, then classify its admitted prefix per §5.4 and the manifest bounds in §7.1:
    • If the TTL expired (current_height > expires_at) or funds are insufficient, remove the timer under TIMER_GC_CYCLES (§6.5), emit the corresponding event, and skip execution.
    • If the timer is within TTL and funded, pre-charge fee_payer (§6.3 step 4), construct a deferred transaction targeting the actor’s handler, and enqueue it.
  4. Apply the selected timer’s removal, carry-forward, retry, or re-arm rule. Unselected suffix IDs remain in their original pages, are not classified as lane-budget skips, and keep their height due in the committed queue.
  5. Execute the enqueued deferred transactions; refund any over-reserved gas to fee_payer (§6.3 step 6).
Timer-created deferred transactions are ordered before engine and mailbox deferred transactions within the same block. Each height index is a linked sequence of pages holding at most TIMER_INDEX_PAGE_SIZE = 64 IDs. The phase MUST NOT decode, scan, or rewrite a collection proportional to the live timer count at a height. It services only the queue head in a block; an older saturated height ordinarily blocks later due heights while it drains. Queue head/tail and successor links are committed state, so replay resumes from the same head-page cursor. A newly due height is appended behind any remaining backlog. The exception is an all-quarantined selected window. Before rotating that still-nonempty height behind the known due-height suffix, the phase MUST advance its deferred head-page prefix behind that page’s untouched suffix and move the page to the page-chain tail when a successor exists. Quarantined Timer rows and their page locators remain unchanged. This bounded rotation prevents a quarantined head from indefinitely blocking solvent co-tenants; queue endpoints need not remain numeric height extrema. A sole quarantined height remains the head until a later due height supplies a successor.

5.2 Deferred Transaction Construction

Each fired timer produces a deferred transaction with the following properties: The zero-hash origin indicates that the transaction has no parent user transaction. The protocol draws its gas budget directly from fee_payer’s account (§6.3). Timer deferred transactions leave the parent transaction’s deferred_gas_pools entry untouched.

5.3 Same-Block Prohibition

Timers created within the current block’s transactions MUST NOT fire in the same block. This is enforced by the height > current_block_height constraint in schedule_timer.

5.4 Timer Lifecycle

An ordinary timer exits through one of the following paths. The native PoR timer is the explicit exception in §6.3: after a successful fire or an insufficient-pool pause, consensus re-arms the same timer ID; ordinary natural-fire removal and insufficient-funds deletion do not end its cadence.
  1. At a natural fire (§5.2, §6.3), height arrives and fee_payer has sufficient funds. The handler runs, and the timer is removed whether the handler succeeds or reverts. Every completed fire appends timer.fired to the timer actor’s event log, including when execution fails. Its existing binary fee payload is unchanged. From TIMER_FIRE_FAILED_ACTIVATION_HEIGHT, an unsuccessful fire also appends timer.fire_failed immediately after it in the same actor-event append. This Upgrade 4 gate uses CIP-50 not-before activation and is initially NOT_SCHEDULED on every network. Below activation, only timer.fired is appended. The new event has zero transaction hash, the timer actor as emitter, the current block height, and a UTF-8 JSON object with these fields: The payload bytes enter the state root. Encode the object in exactly this field order: timer_id, handler, reason, error, cycles_used, cycles_limit, cells_used, cells_limit, accesses_used, accesses_limit. Emit no whitespace outside string values and no trailing newline. Field names and string values use double quotes; reason and error are always strings, never null. Integers are unsigned base-10 digits without a sign, fractional part, exponent or leading zeros, except that zero is 0. Escape the handler as a JSON string: \" for a double quote, \\ for a backslash, and \b, \t, \n, \f, \r for backspace, tab, line feed, form feed and carriage return. Encode every other U+0000–U+001F control character as \u00xx with lowercase hex digits. Leave / and all remaining Unicode scalar values unescaped, encoded directly as UTF-8. The other string values contain only the ASCII characters defined in the table above. This event records a handler failure, after actual-use charging and refund. Scheduler errors that retry or dead-letter the timer keep their existing lifecycle events. Successful fires emit no timer.fire_failed. Above the gate, a failing fire consumes two of the actor log’s MAX_ACTOR_EVENTS slots, evicting one more old event than a single-event fire when the log is full. The event does not change recurrence: a failed handler’s re-arm rolls back. In particular, exhausting cycles, cells or accesses ends an @every schedule. Events the timer handler itself emits, including the SDK’s cowboy.every.failed, are currently not recorded on chain. A Python exception caught by the SDK can preserve the re-arm and return successfully; that fire produces no protocol failure event.
  2. A timer self-destructs for insufficient funds if balance(fee_payer) < max_cost at fire time (see §6.3). The timer is removed without executing. The event topic is timer.cancelled_insufficient_funds, and its data is timer_id || fee_payer || required || available, with the 20-byte payer address followed by two 16-byte little-endian unsigned amounts. Clearing runs under the GC budget (§6.5), not the execution lane.
  3. The TTL has expired if current_height > expires_at at fire time. The timer is removed without executing. The event topic is timer.expired, and its data is the raw timer ID. expires_at and current_height are tracing fields, not fields appended to the actor-event data. Also under the GC budget.
  4. Either of these paths explicitly cancels the timer:
    • The actor calls the pvm_host.cancel_timer(timer_id) PVM syscall. The host-call layer requires timer.actor_address == executing_actor; cross-actor cancellation at this path is rejected as Unauthorized.
    • For a validator-set emergency, use SystemInstruction::CancelTimer { timer_id } (opcode SYS_CANCEL_TIMER = 48). The instruction requires sender ∈ system_deployers (the same gate as UpgradeActor and UpdateBasefeeConfig). Cancelling a timer that has already self-destructed (TTL / insufficient funds, §5.4 paths 2–3) succeeds as a no-op. Emits timer.cancelled_by_governance with the timer_id as event data.
TTL extension has the same dual path:
  • The actor calls the pvm_host.extend_timer(timer_id, new_expires_at) PVM syscall. Caller must own the timer; new TTL must be strictly greater than the current block height.
  • For a validator-set emergency, use SystemInstruction::ExtendTimer { timer_id, new_expires_at } (opcode SYS_EXTEND_TIMER = 50). Same system_deployers gate as CancelTimer. For timers whose actor can no longer self-extend (bricked code, unreachable owner). Emits timer.extended_by_governance.
Both paths clamp the new TTL to current_height + TimerConfig.max_ttl_blocks to prevent renewal past the unattended-lifespan ceiling. If the fire-time self-destruct check has already debited fee_payer for the next fire’s max_cost, the cancel path refunds the unused portion. Below the respective B1/B3 heights, CancelTimer, ExtendTimer and UpdateTimerConfig retain their current direct system_deployers authorization and events. From B1’s height, emergency cancel/extend use the effective operator role and add fixed operation reasons and authority events, preserving their wire layouts. Actor-self host calls retain their ownership and TTL rules. From B3’s height, timer configuration changes require Tier-0 SetGovParam proposals on the allocated paths; direct UpdateTimerConfig is refused even from a deployer or operator. No Proposal payload field is added. The neocloud B amendment defines the list’s empty-state deployer fallback, activation rules and current core anchors.

6. Metering

6.1 Scheduling and Cancellation Costs

Cell costs for index metadata writes are charged separately by the storage layer per CIP-3. The schedule_timer fee charges the scheduling transaction’s sender. The timer’s fee_payer pays only at fire time.

6.2 Execution Budget

Each timer handler execution receives a per-timer budget: At scheduling, gas_limit_per_fire MUST be ≤ TimerConfig.max_cycles_per_fire and obey §4.1’s request ceiling. At fire time, let L be the selected timer lane’s cycle limit and G the committed max_cycles_per_fire:
The persisted request is an upper bound, not a snapshot of future governance. Lowering G from 1,500,000 to 800,000 shrinks an opted-in 1,500,000-cycle fire to 800,000. The 550,000 floor protects existing 550,000-cycle requests, including the seeded native PoR timer; it does not raise a smaller request or override a smaller selected timer lane. New default requests can be below 550,000 when G is lower (§4.1). The cell limit comes from config. An actor may choose a smaller gas_limit_per_fire to reduce the per-fire max cost (see §6.3). The protocol refunds over-reservation.

Deferred JobSubmit Admission

Handler work and a timer-minted JobSubmit share the timer’s cycle lineage. For timers scheduled from the governed-fire gate, a larger fire requires a positive explicit gas_limit and a sufficiently raised governed maximum. Raising governance alone does not raise such a default timer’s request above 550,000. Pre-activation rows follow the crossing rule in §6.4. From the governed-fire gate, an out-of-cycles deferred transaction containing exactly one system JobSubmit instruction also emits deferred_tx.job_submit_insufficient_cycles when a labelled dispatcher cordon or slot-class admission charge was refused and its required total exceeds the child’s binding budget. This applies to timer and transaction origins. The existing deferred_tx.failed event and OutOfGas status remain unchanged; the additional topic appears on the child receipt and originating actor’s event log. The additive event is a JSON object, in this field order: required_cycles is a lower bound for admission, not an estimate of all remaining work. Ordinary OOG without a labelled admission refusal, a refusal within a stricter nested limit that does not exceed the binding child budget, and the exhausted-lineage guard do not add this event. These field names, order and text are consensus bytes; changing them requires another activation boundary or topic.

6.3 Fee Settlement

Timer execution is not free. Each fire is metered and paid for by timer.fee_payer, with live-basefee burn and no priority tip: Natural-timer cycles use the separate TimerBasefee.cycle_basefee specified in CIP-1 §5. Cells and Accesses use the live global TriBasefee rates; there is no separate timer cell or access curve. The live Timer-lane multiplier, timer_lane_mult_ppm, scales all three rates before either pre-charge or settlement. BasefeeConfig supplies update parameters, not the current prices. For the Access term, access_weight_scalar_ppm is the live access-weight scalar. charged_accesses converts the stored structural request to charged units as specified in CIP-43 §5.0; actual_accesses is metered charged usage.
The same three effective rates price max_cost and actual_cost. Executor preparation loads the separate timer basefee tracker; timer callback reimbursement likewise substitutes its cycle rate before applying the lane multiplier. An ordinary timer’s handler that wants to keep firing must call schedule_timer (or extend_timer on the current timer before returning) from within itself. Each newly scheduled fire has a fresh max_cost check. When fee_payer runs dry, the ordinary subscription ends automatically on the next fire. The native PoR timer below instead uses consensus-managed re-arming and pool funding.

Storage Manager PoR timer — native pool funding

The native PoR genesis timer names fee_payer = STORAGE_MANAGER (0x0A), but this is a native funding selector, not a debit from the Storage Manager’s account. Before handler execution the block timer phase reads and reserves max_cost directly from 0x0B/CHALLENGE_POOL_BALANCE_KEY; unused reservation returns to that same pool, including after handler failure. The net pool debit is the consumed timer fee, with basefee burn and no proposer tip. Challenger bond escrow is separate and cannot fund timer gas or bounties. No transfer into 0x0A is needed. The native selector, affordability check and pool precharge follow these rules. max_cost includes all active timer resource meters; in the Access-meter release it also includes the timer’s Access reservation at the applicable Access price. An insufficient pool or a paused relevant system actor skips the handler, emits por.challenge_paused, and natively re-arms the same timer for the next interval. A successful fire is also natively re-armed (or continued next block for pending bounded work); no handler-side rescheduling is required. These PoR rules override both ordinary natural-fire removal and insufficient-funds deletion. The successful-fire path re-arms the timer, and the pause path re-arms without invoking the handler. Re-arming preserves the timer ID and economics and resets skip/retry counters. The timer is seeded at genesis. Ordinary actors cannot select this system funding source: CIP-5 §4.2 permits a system payer only for its own actor. This is a narrow existing native exception, not general third-party sponsorship.

6.4 TimerConfig — Governed Parameters

Timer economics parameters are held in a governed config, stored under the basefee system actor using the same pattern as BasefeeConfig:
Stored at state:actor:{BASEFEE_SYSTEM_ACTOR}:kv:system:timer_config. Below TIMER_GOVERNANCE_ACTIVATION_HEIGHT, SystemInstruction::UpdateTimerConfig (opcode SYS_UPDATE_TIMER_CONFIG = 49) updates this row with sender in system_deployers, using existing validation and the timer_config.updated event, unchanged. Existing defaults apply when the stored config is absent. From that gate’s per-network height, the five fields are controlled through Tier-0 proposals on the paths specified in neocloud B3. The path allowlist and value validation are gated at submission and enactment. Enactment merges the field into the current stored configuration (defaults if absent), validates the complete candidate, and writes the whole TimerConfig into its existing row. Governance rows retain the audit trail; consumers keep their existing single config-row read. Activation does not reset settings. Validate at both submission and enactment. Direct UpdateTimerConfig is refused from the height, including nested execution. Enactment emits the allocated proposal/reason event; existing timers follow their existing prospective checks, with no sweep. From TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, submission and enactment MUST reject cip5.timer.max_cycles_per_fire outside 1..=2_200_000 with InvalidData. The scheduling default, request ceiling and fire floor are distinct (§§4.1 and 6.2); governance can validly set G below 550,000. A pre-existing row above 2,200,000 is clamped at use, not rewritten. A proposal above 2,200,000 that passed below the gate is refused if enacted after activation: the existing enactment path records terminal ExecutionFailed, with no retry. The governed-fire gate is dormant on every network. Its rollout MUST activate DEFERRED_JOB_SUBMIT_CYCLES_ACTIVATION_HEIGHT no later than TIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, with G still at 550,000; only after the latter is active may governance raise G. Timer rows do not record whether their request was a default or an override. A default timer written below the gate while G = 1_500_000 retains that persisted request and fires at 1,500,000 after activation, subject to the selected lane. The ordering above prevents that unintended increase.

6.5 Lane Budgets — Flow Control, Not Free Gas

Two independent block-level cycle budgets bound timer execution and cleanup:
  • LANE_TIMER_CYCLES bounds the aggregate cycles that fired timer handlers (path 1 in §5.4) may consume in one block. A timer whose gas_limit_per_fire (capped at per_fire_cycle_cap) exceeds the remaining lane budget is carried forward: it is removed from the current height index and re-bucketed at current_height + 1 (re-checking it at the same height would lose it), and a skip_count on the timer record is incremented. skip_count is a serialized field of the Timer (§3.1) and therefore part of the state root. After TIMER_MAX_CARRY_FORWARD = 256 consecutive carry-forwards the protocol removes the timer from storage and emits a timer.dead_lettered event whose data is timer_id || skip_count, with a 4-byte little-endian unsigned skip count. This bounds the lifetime of a permanently over-budget timer. (This is a distinct removal mechanic from the §5.4 exit paths and from the execution-failure retry, which follows a separate retry_count up to MAX_TIMER_RETRY_BLOCKS = 3 before dead-lettering.) The carried-forward timer still costs its owner nothing in the skipped block.
  • TIMER_GC_CYCLES = TimerConfig.gc_cycles_per_block separately bounds removal of expired and insufficient-funds timers (paths 2 and 3). This isolation prevents a resume-after-outage storm (many expires_at < current_height at once) from crowding out live-timer execution.
The timer.dead_lettered topic is also used by the separate child/execution-failure path. That path emits a JSON object with timer_id (hex string), retry_count and reason. The carry-forward path uses a binary skip-count suffix. Consumers must distinguish the two payload forms; the topic alone does not identify a single struct-shaped encoding. Neither budget grants handlers free gas. They only limit how many timers are dispatched per block. Every dispatched fire charges fee_payer per §6.3.

7. Determinism & Replayability

The timer mechanism is fully deterministic:
  • The bounded FIFO window depends only on the committed due-height queue, head-page cursor, page links, and Timer records described in §5.1.
  • Timer IDs are derived from on-chain data only (address, height, payload, nonce).
  • Insertion order within a height bucket is determined by transaction execution order, which is consensus-critical.
  • Classification (natural fire vs TTL expiry vs insufficient funds) is a pure function of (current_height, timer.expires_at, balance(timer.fee_payer), max_cost). All inputs are in consensus state.
  • Pre-charge/refund math (§6.3 steps 4–6) uses integer arithmetic over the separate timer cycle rate, global cell/access rates, and Timer-lane multiplier loaded for the timer phase; no floating-point, no locale-dependent formatting.
  • TimerConfig is read once per block from consensus state; mid-block changes do not apply.
  • Local randomness, VRF, and wall-clock time are prohibited.
  • On reorg, timer state (including pre-charge debits) rolls back with the QMDB state root, and delivery replays identically against the new parent state.

7.1 Inline Timer Manifest (block-digest commitment)

The state root reflects the ordered end-of-block timer candidates. The proposer also commits an inline timer manifest in the block and includes it in the block digest preimage. An independent client MUST reproduce it exactly or it will compute a different block hash and fork.
  • The block carries inline_timer_manifest_committed: bool and inline_timer_ids: Vec<timer_id>, the ordered list of timer IDs the proposer dispatched at EOB.
  • These fields are appended to the block digest preimage after the PresenceInput commitment and before extra_data: the bool byte, then a big-endian u64 count, then each timer_id length-prefixed with a big-endian u64.
  • Canonical ordering is derived from the bounded window in §5.1, after excluding actors under resumable rent eviction. Let due_prefix be that ordered candidate list: on verify, inline_timer_ids[i] MUST equal due_prefix[i].timer_id for every manifest entry. The window comes from the persisted queue head when a backlog exists, which may be older than block height H; it is not a full-bucket query at H. Later physical pages MUST NOT leapfrog earlier pages.
  • The manifest length MUST be at most the candidate-list length, at most eight, and at most the deterministic admission cap below. Its admitted prefix also obeys the deterministic handler-code wall-weight budget when enabled; the first candidate may exceed that budget to permit progress. An oversized or noncanonical manifest is invalid. Replay MUST validate and dispatch the committed prefix in that order, including its cleanup and carry outcomes.
The manifest admission cap includes complete default access reservations:
MAX_INLINE_TIMER_MANIFEST_IDS = 4096 and DEFAULT_TIMER_ACCESS_PER_FIRE = 160 structural accesses. selected_timer_lane_cycles is the selected lane L in §6.2. per_fire_cycle_cap follows §6.2: below the governed-fire gate it is min(550_000, selected timer lane); from the gate it is min(clamp(G, 550_000, 2_200_000), selected timer lane). With the ordinary 550,000 cap and default GC budget, the formula gives 1,005 at the identity scalar and 1,004 at 1,350,000 ppm. With a 2,200,000 cap it gives 1,004 at either scalar. The independent eight-record native window remains the tighter materialization bound. Classification still reserves each timer’s complete declared charged-access request and carries requests that do not fit. The manifest is a cross-check/commitment (any honest proposer and any verifier derive the identical list from state), but because it is digest-covered it is consensus-critical: a spec-only client that omits it cannot match the block hash.

8. Security Considerations

  • Prior to this CIP, timers executed under a system-triggered path that skipped basefee deduction entirely. A single actor writing a few KVs per fire, paired with a deployer whose balance had dropped to zero, ran forever at the validator’s expense. §6.3 removes that branch: every fire is metered against fee_payer and self-destructs when funds run out.
  • A malicious actor could schedule many timers for the same height, causing an EOB spike. The per-timer scheduling cost (SET_TIMER_BASE_CYCLES = 200 cycles), TimerConfig.max_timers_per_actor cap (default 1,024), and LANE_TIMER_CYCLES block budget limit these spikes. A future revision MAY add a global MAX_FIRES_PER_BLOCK.
  • If the chain halts for N blocks, on resume every timer with expires_at < current_height would try to clear at once. §6.5 isolates expired/self-destruct clearing into TIMER_GC_CYCLES, separate from LANE_TIMER_CYCLES, so live-timer execution is not crowded out. Expired timers that remain after one block carry forward for cleanup in the next.
  • The pvm_host.cancel_timer(timer_id) host call previously performed no ownership check, allowing any actor to append any timer_id to cancelled_timers and silently delete another actor’s timer. §4.2 requires timer.actor_address == executing_actor at the host-call layer; cross-actor cancellation is only possible via the CancelTimer system instruction with explicit authorization (owner or governance, §5.4).
  • §4.2 requires ordinary actors to pay for their own timers. Naming the invoker as payer would let a callee create future debits beyond the invoker’s signed transaction escrow. The only owner-paid exception is the exact canonical Watchtower Feed’s native start/restart path, authenticated by config.owner == tx_sender, alongside its existing bound renewal authority. These exceptions cannot be used by ordinary or copied actor code. General opt-in third-party sponsorship remains a future extension (§4.2).
  • Because gas_limit_per_fire is actor-chosen, an actor can schedule cheaply-priced timers. The scheduling fee and the fee_payer balance check at each fire limit spam. A zero-balance fee_payer produces at most one self-destruct event per scheduled timer before removal.
  • The 1 MiB payload limit prevents state bloat from oversized timer payloads.
  • Timer handlers execute in a fresh transaction context. They may schedule new timers, but those timers fire in future blocks only (same-block prohibition, §5.3).
  • Timer IDs include the scheduling transaction’s nonce (§3.3), preventing duplicate registration from replayed transactions.

9. Auction Retirement

CIP-5 FIFO remains the normative scheduler. Regenesis removes the CIP-1 auction and its activation parameter, GBA requirements, fairness-weight ranking, priority tips, and tighter cycle cap. The reserved Timer bid fields and host ABI remain unchanged, as do the FIFO successful-fire counter writes. There is no auction activation path.

Appendix A: End-of-Block Timer Delivery Sequence

Appendix B: Recurring Timer Pattern

Actors implement recurring timers by scheduling the next timer from the handler. Each fire charges fee_payer. If that account runs out of funds, the next fire terminates the loop (§5.4 path 2).

Deployer-funded variant

When the deployer wants to fund a long-lived service actor (e.g. a pricing oracle), fund the actor’s own balance before its first fire. Call schedule_timer_ex from the deploy handler and omit fee_payer so it defaults to actor_address. An ordinary actor cannot name its deployer as payer, even during the deployer’s signed call (§4.2).