Metadata-Version: 2.4
Name: smarthex
Version: 0.2.2
Summary: A library for generating and validating SmartHex16 identifiers
Author-email: Victor Matos <contact@byteram.co>
License: MIT
Project-URL: Homepage, https://byteram.co/opensource/smarthex16
Project-URL: Documentation, https://byteram.co/opensource/smarthex16
Project-URL: Repository, https://github.com/Byteram/SmartHex16
Project-URL: Bug Tracker, https://github.com/Byteram/SmartHex16/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install smarthex==0.2.2
```

## Usage

```python
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

```bash
# Build all targets
bazel build //...

# Build specific target
bazel build //:smarthex
```

### Testing

```bash
# Run all tests
bazel test //...

# Run specific test
bazel test //:smarthex_test
```

### Running

```bash
# 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. 
