smarthex 0.2.2

A library for generating and validating SmartHex16 identifiers

SmartHex16: A Mathematical Analysis of Hexadecimal Identifier Generation

Abstract

SmartHex16 is a deterministic hexadecimal identifier generation system implementing a 64-bit entropy space with integrated error detection capabilities. The system employs a 56-bit base identifier coupled with an 8-bit checksum, providing robust error detection while maintaining cryptographic-grade randomness in identifier generation.

Mathematical Foundations

1. System Architecture

The system architecture is defined by the following mathematical components:

• Base Identifier Space (B):

  • Length: 14 hexadecimal characters
  • Entropy: 56 bits (14 × 4)
  • Cardinality: |B| = 2^56 ≈ 7.21 × 10^16

• Checksum Space (C):

  • Length: 2 hexadecimal characters
  • Entropy: 8 bits (2 × 4)
  • Cardinality: |C| = 2^8 = 256

• Total System Space (S):

  • Entropy: 64 bits
  • Cardinality: |S| = |B| × |C| = 2^64 ≈ 1.84 × 10^19

2. Checksum Algorithm

The checksum function C: B → C is defined as:

C(b₁b₂...b₁₄) = (Σ(bᵢ × (i + 1))) mod 256

where:

• bᵢ ∈ {0,1,...,15} represents the ith hexadecimal digit
• i ∈ {1,2,...,14} represents the position index
• mod 256 ensures the result remains within the 8-bit checksum space

3. Error Detection Properties

The system's error detection capabilities are characterized by:

1. Single-Digit Error Detection:

   • Detection Probability: 1
   • Mathematical Basis: Position-weighted checksum ensures unique error signatures

2. Transposition Error Detection:

   • Detection Probability: 255/256
   • Mathematical Basis: Position-dependent weighting creates distinct checksums for transposed digits

3. Burst Error Detection:

   • Maximum Detectable Burst Length: 8 bits
   • Detection Probability: 1 for bursts ≤ 8 bits

4. Collision Analysis

The probability of collision P(N) for N generated identifiers follows:

P(N) ≈ 1 - e^(-N(N-1)/(2×2^64))

This yields:

• P(10^6) ≈ 2.71 × 10^-11
• P(10^9) ≈ 2.71 × 10^-5
• P(10^12) ≈ 0.027

Implementation

The system is implemented in Python 3.x, utilizing the secrets module for cryptographically secure random number generation. The implementation adheres to NIST SP 800-90A guidelines for random number generation.

Security Analysis

1. Entropy Sources:

   • Base identifier: 56 bits from cryptographically secure RNG
   • Checksum: 8 bits derived from deterministic function

2. Security Considerations:

   • Not suitable for cryptographic purposes requiring >64 bits of entropy
   • Checksum provides error detection, not cryptographic authentication
   • Collision resistance suitable for most non-cryptographic applications

References

1. NIST Special Publication 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators
2. Peterson, W. W., & Brown, D. T. (1961). Cyclic Codes for Error Detection
3. Shannon, C. E. (1948). A Mathematical Theory of Communication

Installation

pip install smarthex==0.2.2

Usage

from smarthex import SmartHex

s = SmartHex()
identity = s.generate()  # Returns 16-character hex string
is_valid = s.validate(identy)  # Returns boolean

Development with Bazel

The project uses Bazel for building, testing, and running. Here are the main commands:

Building

# Build all targets
bazel build //...

# Build specific target
bazel build //:smarthex

Testing

# Run all tests
bazel test //...

# Run specific test
bazel test //:smarthex_test

Running

# Generate a new ID
bazel run //:smhex -- --generate

# Validate an ID
bazel run //:smhex -- --validate FBA6C40FCF5FD611

License

This project is licensed under the MIT License. See LICENSE for details.