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.
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.
3. Specification
3.1 Timer Data Structure
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: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 rawpvm_host binding or the SDK wrapper. The raw extended
binding takes six positional arguments; it has no Python keyword/default
arguments or bid parameters:
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:
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
heightMUST 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_payloadis omitted, the outer object minus_handleris delivered. A payload that matches neither valid envelope useshandle_timerwith the original bytes. timer.schedule(..., handler=...)andruntime.schedule_after(...)always emit the CBOR envelope. The SDK checks the handler’s UTF-8 byte length and normalizes non-emptyfee_payeraddresses before the host call.handler=Nonekeeps the raw payload. Timer targets that expect byte payloads must declaredecode="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_payerat schedule time:ZERO(burn address) is rejected.- The reserved system-actor band
0x01..=0xFF(every address belowRESERVED_SYSTEM_ADDRESS_LIMIT = 0x100) is rejected as a third-partyfee_payer. This covers every currently assigned system actor (runner registry / dispatcher / verifier / secrets / TEE / token registry / entitlement registry / RAS / basefee / governance / event-subscription0x1D) plus the reserved slots up to0xFF. An actor cannot delegate payment to a system actor.- A system actor MAY name itself as
fee_payer(i.e.fee_payer == actor_addresswithin 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 uses0x0Aas the selector for the0x0Bchallenge pool (§6.3; CIP-9 §5.6), with no debit from0x0A. The exemption is strictlyfee_payer == actor_address: one system actor still cannot name a different system actor. No exception below permits a third party to name a system-bandfee_payer.
- A system actor MAY name itself as
- For ordinary actors,
fee_payerMUST be the executingactor_address(actor pays itself). Any third-party address, including the currenttx_sender, is rejected withInvalidInput, 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_payerpre-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_payerfor initial registration and owner-triggeredrestart_dispatch_timer, only through its exact-code native path, which MUST authenticateconfig.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_payerdefaults toactor_address.
- At scheduling,
gas_limit_per_fireMUST be ≤TimerConfig.max_cycles_per_fire; fromTIMER_FIRE_CYCLES_FOLLOW_CONFIG_ACTIVATION_HEIGHT, it MUST also be ≤ 2,200,000 (§4.1). expires_atMUST satisfyexpires_at ≤ current_height + TimerConfig.max_ttl_blocks. A timer whoseexpires_athas passed is destroyed on its next scheduled fire without executing (see §5.4).- An actor may hold at most
TimerConfig.max_timers_per_actorlive timers at any time (maintained via a per-actor secondary index). - The PVM host permits
cancel_timeronly wheretimer.actor_address == executing_actor. Cross-actor cancellation returnsUnauthorized, 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_timersand 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-chargedmax_costis 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 withinprocess_block() is:
- Execute all user transactions (TX phase).
- Select the bounded FIFO window from the committed due-height queue head, or from
current_heightwhen that queue is empty. At mostTIMER_DUE_WINDOW_PER_BLOCK = 8Timer 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. - 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 underTIMER_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.
- If the TTL expired (
- 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.
- Execute the enqueued deferred transactions; refund any over-reserved gas to
fee_payer(§6.3 step 6).
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 theheight > 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.-
At a natural fire (§5.2, §6.3),
heightarrives andfee_payerhas sufficient funds. The handler runs, and the timer is removed whether the handler succeeds or reverts. Every completed fire appendstimer.firedto the timer actor’s event log, including when execution fails. Its existing binary fee payload is unchanged. FromTIMER_FIRE_FAILED_ACTIVATION_HEIGHT, an unsuccessful fire also appendstimer.fire_failedimmediately after it in the same actor-event append. This Upgrade 4 gate uses CIP-50 not-before activation and is initiallyNOT_SCHEDULEDon every network. Below activation, onlytimer.firedis 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;reasonanderrorare always strings, nevernull. Integers are unsigned base-10 digits without a sign, fractional part, exponent or leading zeros, except that zero is0. Escape the handler as a JSON string:\"for a double quote,\\for a backslash, and\b,\t,\n,\f,\rfor backspace, tab, line feed, form feed and carriage return. Encode every other U+0000–U+001F control character as\u00xxwith 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 notimer.fire_failed. Above the gate, a failing fire consumes two of the actor log’sMAX_ACTOR_EVENTSslots, 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@everyschedule. Events the timer handler itself emits, including the SDK’scowboy.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. -
A timer self-destructs for insufficient funds if
balance(fee_payer) < max_costat fire time (see §6.3). The timer is removed without executing. The event topic istimer.cancelled_insufficient_funds, and its data istimer_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. -
The TTL has expired if
current_height > expires_atat fire time. The timer is removed without executing. The event topic istimer.expired, and its data is the raw timer ID.expires_atandcurrent_heightare tracing fields, not fields appended to the actor-event data. Also under the GC budget. -
Either of these paths explicitly cancels the timer:
- The actor calls the
pvm_host.cancel_timer(timer_id)PVM syscall. The host-call layer requirestimer.actor_address == executing_actor; cross-actor cancellation at this path is rejected asUnauthorized. - For a validator-set emergency, use
SystemInstruction::CancelTimer { timer_id }(opcodeSYS_CANCEL_TIMER = 48). The instruction requiressender ∈ system_deployers(the same gate asUpgradeActorandUpdateBasefeeConfig). Cancelling a timer that has already self-destructed (TTL / insufficient funds, §5.4 paths 2–3) succeeds as a no-op. Emitstimer.cancelled_by_governancewith thetimer_idas event data.
- The actor calls the
- 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 }(opcodeSYS_EXTEND_TIMER = 50). Samesystem_deployersgate asCancelTimer. For timers whose actor can no longer self-extend (bricked code, unreachable owner). Emitstimer.extended_by_governance.
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:
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 explicitgas_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 bytimer.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.
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 namesfee_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:
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_CYCLESbounds the aggregate cycles that fired timer handlers (path 1 in §5.4) may consume in one block. A timer whosegas_limit_per_fire(capped atper_fire_cycle_cap) exceeds the remaining lane budget is carried forward: it is removed from the current height index and re-bucketed atcurrent_height + 1(re-checking it at the same height would lose it), and askip_counton the timer record is incremented.skip_countis a serialized field of theTimer(§3.1) and therefore part of the state root. AfterTIMER_MAX_CARRY_FORWARD = 256consecutive carry-forwards the protocol removes the timer from storage and emits atimer.dead_letteredevent whose data istimer_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 separateretry_countup toMAX_TIMER_RETRY_BLOCKS = 3before dead-lettering.) The carried-forward timer still costs its owner nothing in the skipped block.TIMER_GC_CYCLES = TimerConfig.gc_cycles_per_blockseparately bounds removal of expired and insufficient-funds timers (paths 2 and 3). This isolation prevents a resume-after-outage storm (manyexpires_at < current_heightat once) from crowding out live-timer execution.
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.
TimerConfigis 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: boolandinline_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: theboolbyte, then a big-endianu64count, then eachtimer_idlength-prefixed with a big-endianu64. - Canonical ordering is derived from the bounded window in §5.1, after excluding actors under resumable rent eviction. Let
due_prefixbe that ordered candidate list: on verify,inline_timer_ids[i]MUST equaldue_prefix[i].timer_idfor every manifest entry. The window comes from the persisted queue head when a backlog exists, which may be older than block heightH; it is not a full-bucket query atH. 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.
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_payerand 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 = 200cycles),TimerConfig.max_timers_per_actorcap (default 1,024), andLANE_TIMER_CYCLESblock budget limit these spikes. A future revision MAY add a globalMAX_FIRES_PER_BLOCK. - If the chain halts for
Nblocks, on resume every timer withexpires_at < current_heightwould try to clear at once. §6.5 isolates expired/self-destruct clearing intoTIMER_GC_CYCLES, separate fromLANE_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 anytimer_idtocancelled_timersand silently delete another actor’s timer. §4.2 requirestimer.actor_address == executing_actorat the host-call layer; cross-actor cancellation is only possible via theCancelTimersystem 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_fireis actor-chosen, an actor can schedule cheaply-priced timers. The scheduling fee and thefee_payerbalance check at each fire limit spam. A zero-balancefee_payerproduces 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 chargesfee_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. Callschedule_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).