Struct SlotCalculator

pub struct SlotCalculator { /* private fields */ }

A slot calculator, which can calculate slot numbers, windows, and offsets for a given chain.

Typing

slots are indices, and use usize for their type. timestamps are in Unix Epoch seconds, and use u64 for their type.

It is recommended that literal integers passed to these functions be explicitly typed, e.g. 0u64, 12usize, etc., to avoid confusion in calling code.

Behavior

Chain slot behavior is a bit unintuitive, particularly for chains that have a merge or chains that have missed slots at the start of the chain (i.e. Ethereum and its testnets).

Each header occupies a slot, but not all slots contain headers. Headers contain the timestamp at the END of their respective slot.

Chains start with a first header, which contains a timestamp (the start_timestamp) and occupies the initial slot (the slot_offset). The start_timestamp is therefore the END of the initial slot, and the BEGINNING of the next slot. I.e. if the initial slot is 0, then the start of slot 1 is the start_timestamp and the end of slot 1 is start_timestamp + slot_duration.

For a given slot, we normalize its number to n by subtracting the slot offset. n is therefore in the range 1...

• n = normalized(slot) = slot - slot_offset.

As such, we can define the slot_start(n) as

• slot_start(n) = (n - 1) * slot_duration + start_timestamp

and slot_end(n) as

• slot_end(n) = n * slot_duration + start_timestamp

The slot n contains the range of timestamps:

• slot_window(n) = slot_start(n)..slot_end(n)

To calculate the slot number n for a given timestamp t, we can use the following formula:

• slot_for(t) = ((t - start_timestamp) / slot_duration) + slot_offset + 1

The + 1 is added because the first slot is the slot at slot_offset, which ENDS at start_timestamp. I.e. a timestamp at start_timestamp is in slot slot_offset + 1.

Implementations

impl SlotCalculator

pub const fn new( start_timestamp: u64, slot_offset: usize, slot_duration: u64, ) -> Self

Creates a new slot calculator.

pub const fn holesky() -> Self

Creates a new slot calculator for Holesky.

pub const fn pecorino_host() -> Self

Creates a new slot calculator for Pecorino host network.

pub const fn mainnet() -> Self

Creates a new slot calculator for Ethereum mainnet.

pub const fn start_timestamp(&self) -> u64

The timestamp of the first PoS block in the chain.

pub const fn slot_offset(&self) -> usize

The slot number of the first PoS block in the chain.

pub const fn slot_duration(&self) -> u64

The slot duration, usually 12 seconds.

pub const fn slot_containing(&self, timestamp: u64) -> Option<usize>

Calculates the slot that contains a given timestamp.

Returns None if the timestamp is before the chain’s start timestamp.

pub const fn point_within_slot(&self, timestamp: u64) -> Option<u64>

Calculates how many seconds a given timestamp is into its containing slot.

Returns None if the timestamp is before the chain’s start.

pub const fn checked_point_within_slot( &self, slot: usize, timestamp: u64, ) -> Option<u64>

Calculates how many seconds a given timestamp is into a given slot. Returns None if the timestamp is not within the slot.

pub const fn slot_window(&self, slot_number: usize) -> Range<u64>

Calculates the start and end timestamps for a given slot

pub const fn slot_start(&self, slot_number: usize) -> u64

Calculates the start timestamp of a given slot.

pub const fn slot_end(&self, slot_number: usize) -> u64

Calculates the end timestamp of a given slot.

pub const fn slot_timestamp(&self, slot_number: usize) -> u64

Calculate the timestamp that will appear in the header of the block at the given slot number (if any block is produced). This is an alias for Self::slot_end.

pub const fn slot_window_for_timestamp( &self, timestamp: u64, ) -> Option<Range<u64>>

Calculates the slot window for the slot that contains to the given timestamp. Slot windows are ranges start..end, where start is the end timestamp of the slot and end is start + slot_duration.

Returns None if the timestamp is before the chain’s start timestamp.

pub const fn slot_start_for_timestamp(&self, timestamp: u64) -> Option<u64>

Calcuates the start timestamp for the slot that contains the given timestamp.

pub const fn slot_end_for_timestamp(&self, timestamp: u64) -> Option<u64>

Calculates the end timestamp for the slot that contains to the given timestamp.

pub fn current_slot(&self) -> Option<usize>

The current slot number.

Returns None if the current time is before the chain’s start timestamp.

pub fn current_point_within_slot(&self) -> Option<u64>

The current number of seconds into the slot.

pub fn slot_starting_at(&self, timestamp: u64) -> Option<usize>

Calculates the slot that starts at the given timestamp. Returns None if the timestamp is not a slot boundary. Returns None if the timestamp is before the chain’s start timestamp.

pub fn slot_ending_at(&self, timestamp: u64) -> Option<usize>

Calculates the slot that ends at the given timestamp. Returns None if the timestamp is not a slot boundary. Returns None if the timestamp is before the chain’s start timestamp.

Trait Implementations

impl Clone for SlotCalculator

fn clone(&self) -> SlotCalculator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SlotCalculator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SlotCalculator

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl FromEnv for SlotCalculator

type Error = SlotCalculatorEnvError

Error type produced when loading from the environment.

fn inventory() -> Vec<&'static EnvItemInfo>

Get the required environment variable names for this type.

fn from_env() -> Result<Self, FromEnvErr<Self::Error>>

Load from the environment.

fn check_inventory() -> Result<(), Vec<&'static EnvItemInfo>>

Get a list of missing environment variables.

impl PartialEq for SlotCalculator

fn eq(&self, other: &SlotCalculator) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for SlotCalculator

impl Eq for SlotCalculator

impl StructuralPartialEq for SlotCalculator