rnd_seed.rs

Overview

This file defines the RndSeed struct, representing a fixed-size 32-byte random seed used primarily for deterministic pseudorandom computations related to block processing. The seed supports serialization/deserialization, hashing, comparison, and bitwise operations, enabling its use as a cryptographic or deterministic random value in the system.

The core functionality includes:

• Construction and conversion from byte arrays and strings.

• A custom "bucketing" mechanism (not_a_modulus) to assign blocks into buckets.

• Bitwise XOR operations with a BlockIdentifier.

• Hex and base64 string formatting and parsing.

The RndSeed plays a role in how blocks and identifiers are processed, likely within consensus or block selection mechanisms, interacting particularly with the BlockIdentifier type.

Structs and Implementations

RndSeed

Definition

pub struct RndSeed([u8; 32]);

Encapsulates a 32-byte array representing a random seed.

Derives

• Deserialize, Serialize: For JSON or other serde-compatible serialization.

• Clone, PartialEq, Eq, Hash, Ord, PartialOrd: Enables copying, equality checks, hashing, and ordering.

• Default: Provides a default zeroed seed.

Attributes

• Uses serde_with::Bytes for efficient binary serialization of the internal byte array.

Methods

not_a_modulus(&self, divider: u32) -> u32

• Purpose: Produces a bucket index for a block using a quick, non-standard bucketing method.

• Parameters:

  • divider: The number of buckets to divide into.

• Returns: A bucket index between 0 and divider - 1.

• Details: Extracts the last 4 bytes of the seed, interprets them as a big-endian u32, then computes modulo divider.

• Usage Example:

let seed = RndSeed::from([0u8; 32]);
let bucket = seed.not_a_modulus(10); // returns a value between 0-9

• Note: Despite the name, this method internally uses modulo; the comment suggests it's a heuristic rather than a mathematically rigorous modulo operation.

Trait Implementations

Debug & LowerHex Formatting

• Implements Debug by delegating to lowercase hexadecimal (LowerHex) formatting.

• LowerHex supports two formats:

  • Normal: Outputs a plain hex string of the seed bytes.

  • Alternate (# flag): Outputs a hex string prefixed with 0x.

Example:

println!("{:?}", seed);       // prints hex string
println!("{:#x}", seed);      // prints 0x-prefixed hex string

From<[u8; 32]> for RndSeed

• Allows creation of a RndSeed from a fixed-size 32-byte array.

Example:

let bytes = [0u8; 32];
let seed = RndSeed::from(bytes);

AsRef<[u8]> for RndSeed

• Allows borrowing the internal byte slice for use in byte processing APIs.

Example:

let bytes_ref: &[u8] = seed.as_ref();

FromStr for RndSeed

• Parses a string into a RndSeed.

• Supports:

  • 64-character hex strings (no prefix)

  • 66-character hex strings prefixed with 0x

  • 44-character base64 strings

• Returns an error if the string length or format is invalid.

• Uses hex crate for hex decoding, and tvm_types::base64_decode_to_slice for base64 decoding.

• Errors are wrapped in anyhow::Error.

Example:

let seed: RndSeed = "0xabcdef...".parse()?;

BitXor<BlockIdentifier> for RndSeed

• Defines bitwise XOR between a RndSeed and a BlockIdentifier.

• Returns a new RndSeed where each byte is the XOR of corresponding bytes.

• Size is fixed at 32 bytes.

• Enables combining randomness of a seed with block-specific identifiers.

Example:

let new_seed = seed ^ block_identifier;

Important Implementation Details

• The RndSeed is internally a fixed 32-byte array, ensuring consistent size and high entropy.

• XOR operation with BlockIdentifier suggests deterministic mixing of seed and block data.

• Parsing supports multiple encoding formats, providing flexibility in input representation.

• The not_a_modulus function uses the last 4 bytes of the seed, focusing on a quick hash-based bucketing approach rather than full modular arithmetic on the entire seed.

Interaction With Other Components

• RndSeed depends on BlockIdentifier for bitwise XOR operations, linking randomness seeds to block identifiers.

• Serialization and deserialization enable RndSeed to be used in network protocols or storage.

• Used in contexts requiring deterministic yet pseudorandom distribution of blocks, such as bucketing or selection algorithms.

• The file imports crate::types::BlockIdentifier, indicating it belongs to a system handling blockchain or ledger data structures.

Diagram: Structure and Functionality of RndSeed

classDiagram
class RndSeed {
- bytes: [u8; 32]
+ not_a_modulus(divider: u32): u32
+ from_str(value: &str) -> Result<RndSeed, Error>
+ as_ref() -> &[u8]
+ bitxor(BlockIdentifier) -> RndSeed
+ fmt::Debug
+ fmt::LowerHex
}
RndSeed ..> BlockIdentifier : bitxor with
RndSeed ..> [u8;32] : contains