Skip to content

Timing Windows

TIMLG rounds are slot-bounded: each phase is gated by Solana slot numbers recorded on-chain.

The timing model is designed to enforce the “Hawking Wall” principle: commitments must be made before the target randomness pulse is knowable.

Round parameters (MVP)

A round is created with parameters that define its timing and target:

Parameter Type Meaning
target_pulse_index u64 Which public randomness pulse is targeted (e.g., NIST index)
commit_deadline_slot u64 End of the commit window (exclusive boundary)
reveal_deadline_slot u64 End of the reveal window (exclusive boundary)
claim_grace_slots u64 Grace period after settlement before sweep is allowed

Exclusive boundary means: an instruction is valid only if current_slot < deadline_slot.

Note

The exact boundaries are implementation-defined, but the docs assume the conservative interpretation: deadline slots are the first slot that is no longer allowed.

Phase gating (what can happen when)

Phase Slot condition Allowed actions (high-level) Notes
Round open slot < commit_deadline_slot Commit tickets (commit_ticket) No pulse is accepted yet.
Commit closed slot ≥ commit_deadline_slot Oracle may publish pulse (set_pulse_signed) Commits are rejected past this boundary.
Reveal window pulse is set and slot < reveal_deadline_slot Reveal tickets (reveal_ticket) Reveals are only meaningful once a pulse exists.
Finalize slot ≥ reveal_deadline_slot Finalize round (finalize_round) Locks the round for settlement.
Settlement after finalize Settle (settle_round_tokens) → enable claims Accounting is computed deterministically.
Claim after settlement Users claim rewards (claim_reward) Claims are gated by token/vault rules.
Sweep slot ≥ settlement_slot + claim_grace_slots Sweep leftovers (sweep_unclaimed) Moves unclaimed funds to the treasury policy path.

The target pulse and “knowability”

The protocol assumes the pulse is derived from a public randomness source that is:

  • publicly observable,
  • time-indexed,
  • and not controllable by participants.

The MVP is designed around sources like the NIST Randomness Beacon, but the on-chain program only needs:

  • a pulse index (target_pulse_index)
  • the pulse bytes (or hash)
  • an oracle signature proving which pulse was chosen

Anti-leakage requirement

The commit window must close before participants can reliably know the targeted pulse.

Edge cases and rules of thumb

1) Late commits / late reveals

  • If a commit lands at or after commit_deadline_slot, it must be rejected.
  • If a reveal lands at or after reveal_deadline_slot, it must be rejected (ticket becomes NO-REVEAL).

2) Pulse arrives “late”

If the oracle does not publish the pulse in time, the round cannot settle. Operationally this is handled off-chain (retry, alternate oracle paths), but the public invariant is simple:

  • settlement only happens after a valid pulse is set

3) Slot-time vs wall-clock time

Slots are the only timing source the program can rely on. User-facing tooling may display approximate wall-clock times, but correctness must be enforced using slots.

For devnet/localnet demos:

  • Choose commit/reveal windows with enough slots to absorb normal network variance.
  • Prefer conservative spacing: commit closes well before the targeted pulse can be known.
  • Keep claim_grace_slots long enough for users in different time zones.

The exact numbers are deployment- and network-dependent, so the docs avoid hardcoding constants.