block_height.rs

Overview

This file defines the BlockHeight struct, which encapsulates the concept of a block height within a specific thread context in a multi-threaded or sharded system. The BlockHeight struct tracks the position of a block in a sequence, scoped by a ThreadIdentifier. This allows for thread-isolated block height management, ensuring that block heights are meaningful only within their respective threads.

The file provides functionality to obtain the next block height within a thread and to compute a signed distance between two block heights of the same thread. This is useful for comparing progress or ordering within a thread.

Structs and Methods

BlockHeight

pub struct BlockHeight {
    thread_identifier: ThreadIdentifier,
    height: u64,
}

• Purpose: Represents the height (position) of a block within a particular thread.

• Fields:

  • thread_identifier: ThreadIdentifier — Uniquely identifies the thread or shard this block height belongs to.

  • height: u64 — The numeric height or index of the block within the thread.

Derives and Traits

• Serialize, Deserialize — Supports serialization and deserialization, enabling persistence or network transfer.

• Getters — Automatically generates getter methods for the struct fields.

• TypedBuilder — Provides a builder pattern for constructing instances.

• Hash, Eq, PartialEq — Supports hashing and equality comparisons, important for collections or comparisons.

• Clone, Copy, Debug — Enables copying, cloning, and debug printing.

Methods

next(&self, thread_identifier: &ThreadIdentifier) -> Self

• Description: Produces the next BlockHeight based on the current one and a given thread identifier.

• Parameters:

  • thread_identifier: &ThreadIdentifier — The thread identifier for which the next block height is requested.

• Returns: A new BlockHeight instance.

• Behavior:

  • If the provided thread_identifier matches the current BlockHeight's thread, the height is incremented by 1.

  • If it differs, the height resets to 0 for the new thread.

• Usage Example:

  let current = BlockHeight::builder()
      .thread_identifier(some_thread_id)
      .height(5)
      .build();
  let next_block = current.next(&some_thread_id);
  assert_eq!(next_block.height(), 6);
  

signed_distance_to(&self, other: &BlockHeight) -> Option<i128>

• Description: Calculates the signed numerical difference between the heights of two BlockHeight instances, provided they belong to the same thread.

• Parameters:

  • other: &BlockHeight — Another BlockHeight instance to compare against.

• Returns:

  • Some(i128) representing other.height - self.height if both belong to the same thread.

  • None if the thread identifiers differ (no meaningful comparison).

• Usage Example:

  let a = BlockHeight::builder()
      .thread_identifier(thread_id)
      .height(10)
      .build();
  let b = BlockHeight::builder()
      .thread_identifier(thread_id)
      .height(15)
      .build();
  let distance = a.signed_distance_to(&b);
  assert_eq!(distance, Some(5));
  

Implementation Details and Algorithms

• The next method handles thread boundaries by resetting the block height to zero when the thread identifier changes, ensuring block heights are always relative to their thread.

• The signed_distance_to method uses 128-bit signed integers (i128) to safely handle potentially large height differences and avoid overflow in subtraction.

• Equality and hashing are based on both thread identifier and height, ensuring that two BlockHeight instances are identical only if they represent the same height in the same thread.

Interactions with Other Components

• The BlockHeight struct depends on the ThreadIdentifier type, which is imported from crate::types::ThreadIdentifier. This establishes a linkage to thread or shard identification logic elsewhere in the system.

• Serialization and deserialization via serde imply that BlockHeight instances are stored or transmitted, potentially used in networking, persistence layers, or consensus algorithms.

• The builder pattern via TypedBuilder facilitates ergonomic and safe construction of BlockHeight instances, which may be used throughout the system wherever block heights are tracked.

This file is fundamental for any system logic that requires tracking, comparing, or advancing block heights in a multi-threaded or sharded environment.

Structure Diagram

classDiagram
class BlockHeight {
-thread_identifier: ThreadIdentifier
-height: u64
+next()
+signed_distance_to()
+thread_identifier()
+height()
}