pop_fork/inherent/

timestamp.rs

// SPDX-License-Identifier: GPL-3.0

//! Timestamp inherent provider for block building.
//!
//! This module provides [`TimestampInherent`] which generates the mandatory
//! timestamp inherent extrinsic for each block. The timestamp pallet requires
//! this inherent to advance the chain's notion of time.
//!
//! # How It Works
//!
//! 1. Look up the Timestamp pallet and `set` call indices from runtime metadata
//! 2. Detect slot duration using the following fallback chain:
//!    - `AuraApi_slot_duration` runtime API (Aura-based chains)
//!    - `Babe::ExpectedBlockTime` metadata constant (Babe-based chains)
//!    - Configured default slot duration
//! 3. Read the current timestamp from `Timestamp::Now` storage
//! 4. Add the slot duration to get the new timestamp
//! 5. Encode a `timestamp.set(new_timestamp)` call using the dynamic indices
//! 6. Wrap it as an unsigned inherent extrinsic
//!
//! # Example
//!
//! ```ignore
//! use pop_fork::inherent::TimestampInherent;
//!
//! // Create with default 6-second slots (relay chain)
//! let provider = TimestampInherent::default_relay();
//!
//! // Create with custom slot duration
//! let provider = TimestampInherent::new(2_000); // 2 seconds
//! ```

use crate::{
	Block, BlockBuilderError, RuntimeExecutor,
	inherent::InherentProvider,
	strings::inherent::timestamp::{
		self as strings,
		slot_duration::{
			PARACHAIN_FALLBACK_MS as DEFAULT_PARA_SLOT_DURATION_MS,
			RELAY_CHAIN_FALLBACK_MS as DEFAULT_RELAY_SLOT_DURATION_MS,
		},
	},
};
use async_trait::async_trait;
use scale::{Compact, Decode, Encode};
use std::sync::atomic::{AtomicU64, Ordering};
use subxt::Metadata;

/// Extrinsic format version for unsigned/bare extrinsics.
/// Version 5 is current; version 4 is legacy.
const EXTRINSIC_FORMAT_VERSION: u8 = 5;

/// Timestamp inherent provider.
///
/// Generates the `timestamp.set(now)` inherent extrinsic that advances
/// the chain's timestamp by the slot duration.
///
/// # Slot Duration Detection
///
/// The provider attempts to detect the slot duration dynamically using
/// the following fallback chain:
/// 1. `AuraApi_slot_duration` runtime API (Aura-based chains)
/// 2. `Babe::ExpectedBlockTime` metadata constant (Babe-based chains)
/// 3. Configured default slot duration (default: 6 seconds)
///
/// # Dynamic Metadata Lookup
///
/// The pallet and call indices are looked up dynamically from the runtime
/// metadata, making this provider work across different runtimes without
/// manual configuration.
pub struct TimestampInherent {
	/// Slot duration in milliseconds (fallback value).
	slot_duration_ms: u64,
	/// Cached slot duration detected from the runtime.
	/// Initialized during warmup or lazily on first `provide()` call.
	/// A value of 0 means "not yet detected".
	cached_slot_duration: AtomicU64,
}

impl TimestampInherent {
	/// Create a new timestamp inherent provider.
	///
	/// # Arguments
	///
	/// * `slot_duration_ms` - Slot duration in milliseconds
	pub fn new(slot_duration_ms: u64) -> Self {
		Self { slot_duration_ms, cached_slot_duration: AtomicU64::new(0) }
	}

	/// Create with default settings for relay chains (6-second slots).
	pub fn default_relay() -> Self {
		Self::new(DEFAULT_RELAY_SLOT_DURATION_MS)
	}

	/// Create with default settings for parachains (12-second slots).
	pub fn default_para() -> Self {
		Self::new(DEFAULT_PARA_SLOT_DURATION_MS)
	}

	/// Compute the storage key for `Timestamp::Now`.
	///
	/// The key is constructed as: `twox_128("Timestamp") ++ twox_128("Now")`
	///
	/// # Returns
	///
	/// A 32-byte storage key.
	pub fn timestamp_now_key() -> Vec<u8> {
		let pallet_hash = sp_core::twox_128(strings::storage_keys::PALLET_NAME);
		let storage_hash = sp_core::twox_128(strings::storage_keys::NOW);
		[pallet_hash.as_slice(), storage_hash.as_slice()].concat()
	}

	/// Encode the `timestamp.set(now)` call.
	///
	/// The call is encoded as: `[pallet_index, call_index, Compact<u64>]`
	fn encode_timestamp_set_call(pallet_index: u8, call_index: u8, timestamp: u64) -> Vec<u8> {
		let mut call = vec![pallet_index, call_index];
		// Timestamp argument is encoded as Compact<u64>
		call.extend(Compact(timestamp).encode());
		call
	}

	/// Wrap a call as an unsigned inherent extrinsic.
	///
	/// Unsigned extrinsics have the format:
	/// - Compact length prefix
	/// - Version byte
	/// - Call data
	fn encode_inherent_extrinsic(call: Vec<u8>) -> Vec<u8> {
		let mut extrinsic = vec![EXTRINSIC_FORMAT_VERSION];
		extrinsic.extend(call);

		// Prefix with compact length
		let len = Compact(extrinsic.len() as u32);
		let mut result = len.encode();
		result.extend(extrinsic);
		result
	}

	/// Get slot duration from the runtime, falling back to the provided default.
	///
	/// This function uses a three-tier detection mechanism:
	/// 1. `AuraApi_slot_duration` runtime API (Aura-based chains)
	/// 2. `Babe::ExpectedBlockTime` metadata constant (Babe-based chains)
	/// 3. Fallback to the provided default value
	///
	/// # Arguments
	///
	/// * `executor` - Runtime executor for calling runtime APIs
	/// * `storage` - Storage layer for state access
	/// * `metadata` - Runtime metadata for constant lookup
	/// * `fallback` - Default slot duration if detection fails (in milliseconds)
	///
	/// # Returns
	///
	/// The slot duration in milliseconds.
	pub async fn get_slot_duration_from_runtime(
		executor: &RuntimeExecutor,
		storage: &crate::LocalStorageLayer,
		metadata: &Metadata,
		fallback: u64,
	) -> u64 {
		// 1. Try AuraApi_slot_duration runtime API
		if let Some(duration) = executor
			.call(strings::slot_duration::AURA_API_METHOD, &[], storage)
			.await
			.ok()
			.and_then(|r| u64::decode(&mut r.output.as_slice()).ok())
		{
			return duration;
		}

		// 2. Try Babe::ExpectedBlockTime metadata constant
		if let Some(duration) = Self::get_constant_from_metadata(
			metadata,
			strings::slot_duration::BABE_PALLET,
			strings::slot_duration::BABE_EXPECTED_BLOCK_TIME,
		) {
			return duration;
		}

		// 3. Fall back to configured default
		fallback
	}

	/// Attempt to read a u64 constant from metadata.
	fn get_constant_from_metadata(
		metadata: &Metadata,
		pallet_name: &str,
		constant_name: &str,
	) -> Option<u64> {
		metadata
			.pallet_by_name(pallet_name)?
			.constant_by_name(constant_name)
			.and_then(|c| u64::decode(&mut &c.value()[..]).ok())
	}
}

impl Default for TimestampInherent {
	fn default() -> Self {
		Self::default_relay()
	}
}

#[async_trait]
impl InherentProvider for TimestampInherent {
	fn identifier(&self) -> &'static str {
		strings::IDENTIFIER
	}

	async fn provide(
		&self,
		parent: &Block,
		executor: &RuntimeExecutor,
	) -> Result<Vec<Vec<u8>>, BlockBuilderError> {
		// Look up pallet and call indices from metadata
		let metadata = parent.metadata().await?;

		let pallet = metadata.pallet_by_name(strings::metadata::PALLET_NAME).ok_or_else(|| {
			BlockBuilderError::InherentProvider {
				provider: self.identifier().to_string(),
				message: format!(
					"{}: {}",
					strings::errors::PALLET_NOT_FOUND,
					strings::metadata::PALLET_NAME
				),
			}
		})?;

		let pallet_index = pallet.index();

		let call_variant = pallet
			.call_variant_by_name(strings::metadata::SET_CALL_NAME)
			.ok_or_else(|| BlockBuilderError::InherentProvider {
				provider: self.identifier().to_string(),
				message: format!(
					"{}: {}",
					strings::errors::CALL_NOT_FOUND,
					strings::metadata::SET_CALL_NAME
				),
			})?;

		let call_index = call_variant.index;

		// Get slot duration from cache (populated during warmup) or detect from runtime.
		let storage = parent.storage();
		let slot_duration = match self.cached_slot_duration.load(Ordering::Acquire) {
			0 => {
				let duration = Self::get_slot_duration_from_runtime(
					executor,
					storage,
					&metadata,
					self.slot_duration_ms,
				)
				.await;
				self.cached_slot_duration.store(duration, Ordering::Release);
				duration
			},
			cached => cached,
		};

		// Read current timestamp from parent block storage
		let key = Self::timestamp_now_key();

		let current_timestamp = match storage.get(parent.number, &key).await? {
			Some(value) if value.value.is_some() => u64::decode(
				&mut value
					.value
					.as_ref()
					.expect("The match guard ensures it's Some; qed;")
					.as_slice(),
			)
			.map_err(|e| BlockBuilderError::InherentProvider {
				provider: self.identifier().to_string(),
				message: format!("{}: {}", strings::errors::DECODE_FAILED, e),
			})?,
			_ => {
				// No timestamp set yet (genesis or very early block)
				// Use current system time as fallback
				std::time::SystemTime::now()
					.duration_since(std::time::UNIX_EPOCH)
					.map(|d| d.as_millis() as u64)
					.unwrap_or(0)
			},
		};

		// Calculate new timestamp
		let new_timestamp = current_timestamp.saturating_add(slot_duration);

		log::debug!(
			"[Timestamp] current_timestamp={current_timestamp}, slot_duration={slot_duration}, new_timestamp={new_timestamp}"
		);

		// Encode the timestamp.set call with dynamic indices
		let call = Self::encode_timestamp_set_call(pallet_index, call_index, new_timestamp);

		// Wrap as unsigned extrinsic
		let extrinsic = Self::encode_inherent_extrinsic(call);

		Ok(vec![extrinsic])
	}

	async fn warmup(&self, parent: &Block, executor: &RuntimeExecutor) {
		let metadata = match parent.metadata().await {
			Ok(m) => m,
			Err(e) => {
				log::warn!("[Timestamp] Warmup: failed to get metadata: {e}");
				return;
			},
		};
		let storage = parent.storage();
		let duration = Self::get_slot_duration_from_runtime(
			executor,
			storage,
			&metadata,
			self.slot_duration_ms,
		)
		.await;
		self.cached_slot_duration.store(duration, Ordering::Release);
		log::debug!("[Timestamp] Warmup: cached slot_duration={duration}ms");
	}

	fn invalidate_cache(&self) {
		self.cached_slot_duration.store(0, Ordering::Release);
		log::debug!("[Timestamp] Cache invalidated (runtime upgrade detected)");
	}
}

#[cfg(test)]
mod tests {
	use super::*;

	/// Custom slot duration for testing (1 second).
	const TEST_SLOT_DURATION_MS: u64 = 1_000;

	/// Test pallet index (arbitrary value for encoding tests).
	const TEST_PALLET_INDEX: u8 = 3;

	/// Test call index (arbitrary value for encoding tests).
	const TEST_CALL_INDEX: u8 = 0;

	#[test]
	fn new_creates_provider_with_slot_duration() {
		let provider = TimestampInherent::new(TEST_SLOT_DURATION_MS);
		assert_eq!(provider.slot_duration_ms, TEST_SLOT_DURATION_MS);
	}

	#[test]
	fn default_relay_uses_configured_slot_duration() {
		let provider = TimestampInherent::default_relay();
		assert_eq!(provider.slot_duration_ms, DEFAULT_RELAY_SLOT_DURATION_MS);
	}

	#[test]
	fn default_para_uses_configured_slot_duration() {
		let provider = TimestampInherent::default_para();
		assert_eq!(provider.slot_duration_ms, DEFAULT_PARA_SLOT_DURATION_MS);
	}

	#[test]
	fn timestamp_now_key_is_32_bytes() {
		let key = TimestampInherent::timestamp_now_key();
		// twox128 produces 16 bytes per hash, storage key = pallet hash + item hash
		const TWOX128_OUTPUT_BYTES: usize = 16;
		const STORAGE_KEY_LEN: usize = TWOX128_OUTPUT_BYTES * 2;
		assert_eq!(key.len(), STORAGE_KEY_LEN);
	}

	#[test]
	fn encode_timestamp_set_call_produces_valid_encoding() {
		let call = TimestampInherent::encode_timestamp_set_call(
			TEST_PALLET_INDEX,
			TEST_CALL_INDEX,
			1_000_000,
		);

		// First byte is pallet index
		assert_eq!(call[0], TEST_PALLET_INDEX);
		// Second byte is call index
		assert_eq!(call[1], TEST_CALL_INDEX);
		// Rest is compact-encoded timestamp
		assert!(call.len() > 2);
	}

	#[test]
	fn encode_inherent_extrinsic_includes_version_and_length() {
		// Create fake call data
		let call = vec![TEST_PALLET_INDEX, TEST_CALL_INDEX, 1, 2, 3];
		let extrinsic = TimestampInherent::encode_inherent_extrinsic(call.clone());

		// Should start with compact length (6 = version byte + 5 call bytes)
		// Compact encoding of 6 is (6 << 2) = 0x18
		const EXPECTED_COMPACT_LEN: u8 = 0x18;
		assert_eq!(extrinsic[0], EXPECTED_COMPACT_LEN);
		// Next byte is extrinsic format version
		assert_eq!(extrinsic[1], EXTRINSIC_FORMAT_VERSION);
		// Rest is the call
		assert_eq!(&extrinsic[2..], &call[..]);
	}

	#[test]
	fn identifier_returns_timestamp() {
		let provider = TimestampInherent::default();
		assert_eq!(provider.identifier(), strings::IDENTIFIER);
	}
}