block_seq_no.rs

Overview

This file defines a strongly-typed wrapper around a 32-bit unsigned integer to represent a block sequence number within a blockchain or distributed ledger context. The BlockSeqNo struct encapsulates the sequence number, providing type safety and a set of utility methods and trait implementations to facilitate safe arithmetic operations, comparisons, and conversions. This abstraction helps prevent misuse of raw integers when dealing with block sequence numbers and ensures consistent handling of block sequencing logic across the application.

Structure and Components

BlockSeqNo Struct

• Definition:

  pub struct BlockSeqNo(u32);
  

• Purpose: Represents the block sequence number in a type-safe manner. Internally wraps a u32 value which corresponds to the actual block sequence number.

• Derives:
  Implements common traits including Copy, Clone, Eq, Hash, PartialEq, Serialize, Deserialize, Default, PartialOrd, and Ord. This enables easy copying, comparisons, serialization, and default initialization.

• Default Value: Defaults to 0 for the wrapped sequence number.

Functions and Methods

next_seq_no

pub fn next_seq_no(seq_no: BlockSeqNo) -> BlockSeqNo

• Purpose: Returns the next block sequence number by incrementing the given sequence number by 1.

• Parameters:

  • seq_no: Current BlockSeqNo.

• Returns: A new BlockSeqNo incremented by one.

• Usage Example:

let current = BlockSeqNo::from(42);
let next = next_seq_no(current);
assert_eq!(u32::from(next), 43);

BlockSeqNo::saturating_sub

pub fn saturating_sub(self, other: u32) -> Self

• Purpose: Subtracts a u32 value from the current block sequence number, saturating at zero (never underflows).

• Parameters:

  • self: The current BlockSeqNo.

  • other: The unsigned integer value to subtract.

• Returns: A new BlockSeqNo after subtraction with saturation.

• Usage Example:

let seq = BlockSeqNo::from(10);
let result = seq.saturating_sub(15);
assert_eq!(u32::from(result), 0); // Saturates at zero, no negative values

Trait Implementations

These trait implementations enable idiomatic usage of BlockSeqNo with Rust's standard library features and arithmetic operators.

• From for BlockSeqNo: Allows conversion from raw u32 to BlockSeqNo.

• From for u32: Allows extraction of the internal u32 from BlockSeqNo.

• Display and Debug: Formats the BlockSeqNo by showing the internal u32 value. This simplifies logging and debugging.

• Subtraction (-):

  • BlockSeqNo - BlockSeqNo returns an i64 representing the difference.

  • BlockSeqNo - &BlockSeqNo also returns an i64.

  Note: Subtraction returns a signed integer (i64) to allow negative differences when newer blocks have smaller sequence numbers.

• Addition (+):

  • Adding a u32 to a BlockSeqNo produces a new BlockSeqNo incremented by that amount.

• Remainder (%):

  • Computes the modulus of the internal u32 by a given u32.

Design Considerations

• The file avoids implementing operations like subtraction between BlockSeqNo and u32 directly to prevent ambiguous or unexpected negative results.

• Arithmetic operations are implemented carefully to preserve semantic correctness around block sequencing and prevent errors due to overflow or underflow.

• saturating_sub is provided to allow safe decrements without risk of underflow.

Interaction with Other Parts of the System

• The BlockSeqNo type is likely used wherever block sequence numbers are handled to provide type safety and reduce bugs.

• Serialization and deserialization via serde allow BlockSeqNo instances to be stored or transmitted in JSON, binary, or other formats, facilitating integration with network protocols or persistent storage.

• The type-safe arithmetic operations enable precise management of block indices in consensus algorithms, indexing, or block validation logic.

• The file is foundational for modules that need to track or manipulate block sequences, such as block producers, validators, or chain explorers.

Visual Diagram

classDiagram
class BlockSeqNo {
-u32
+saturating_sub()
+from(u32)
+into<u32>()
+Display
+Debug
+Add<u32>
+Sub<BlockSeqNo>
+Rem<u32>
}
BlockSeqNo : +Copy
BlockSeqNo : +Clone
BlockSeqNo : +Eq
BlockSeqNo : +PartialEq
BlockSeqNo : +Hash
BlockSeqNo : +Serialize
BlockSeqNo : +Deserialize
BlockSeqNo : +Default
BlockSeqNo : +PartialOrd
BlockSeqNo : +Ord
class Functions {
+next_seq_no(BlockSeqNo) BlockSeqNo
}
Functions --> BlockSeqNo : uses

This diagram illustrates the BlockSeqNo struct with its key methods and implemented traits, as well as the standalone next_seq_no function that operates on it.

For further information about serialization and trait implementations, see serde serialization. For details on operator overloading in Rust, refer to Operator Overloading. The concept of type safety wrappers is discussed under Newtype Pattern.