nip/docs/HASH_ALGORITHM_MIGRATION.md

Hash Algorithm Migration Strategy

Overview

The NIP variant system is designed to support multiple hash algorithms simultaneously, enabling seamless migration from BLAKE2b to BLAKE3 (or future algorithms) without breaking existing installations.

Current Implementation

Supported Algorithms

• BLAKE2b (current): blake2b-[hash]
• BLAKE3 (future): blake3-[hash]

Path Format

Variant paths include the hash algorithm prefix:

/Programs/<PackageName>/<Version>-<Algorithm>-<Hash>/

Examples:

• /Programs/nginx/1.28.0-blake2b-abc123def456/
• /Programs/nginx/1.29.0-blake3-xyz789abc123/

Forward Compatibility

Algorithm Detection

The path manager automatically detects which hash algorithm is used:

let algo = detectHashAlgorithm(path)
# Returns: "blake2b", "blake3", or "" if unknown

Coexistence

Multiple hash algorithms can coexist on the same system:

• Old packages with BLAKE2b hashes remain valid
• New packages with BLAKE3 hashes work alongside them
• All path operations work regardless of algorithm

Migration Scenarios

Scenario 1: Gradual Migration

Routers running for years with BLAKE2b packages:

1. System continues to work with existing BLAKE2b packages
2. New package installations use BLAKE3
3. Both algorithms coexist indefinitely
4. No forced migration required

Scenario 2: Package Updates

When a package is updated:

• Old version: /Programs/nginx/1.27.0-blake2b-old123/
• New version: /Programs/nginx/1.28.0-blake3-new456/
• Both versions can coexist (different versions)
• Rollback to old version always possible

Scenario 3: Same Version, Different Hash

If the same version is rebuilt with a different algorithm:

• /Programs/nginx/1.28.0-blake2b-abc123/
• /Programs/nginx/1.28.0-blake3-xyz789/
• These are treated as different variants
• Both can coexist (different fingerprints)

Implementation Details

Validation

The validateVariantPath() function checks for any supported algorithm:

const SUPPORTED_HASH_PREFIXES* = ["blake2b-", "blake3-"]

Extraction

Version and fingerprint extraction work with any supported algorithm:

• extractVersionFromPath() - tries all supported prefixes
• extractFingerprintFromPath() - returns full hash with algorithm prefix

Adding New Algorithms

To add support for a new hash algorithm:

1. Add prefix to SUPPORTED_HASH_PREFIXES in variant_paths.nim
2. Implement hash calculation in variant_fingerprint.nim
3. No changes needed to path validation or parsing
4. Existing packages continue to work

Testing

Comprehensive tests ensure compatibility:

• 63 tests covering all path operations
• Specific tests for blake2b/blake3 coexistence
• Migration scenario tests
• Algorithm detection tests

Recommendations

1. Don't force migration: Let old packages remain with BLAKE2b
2. Use BLAKE3 for new packages: When available in Nimble
3. Document algorithm in metadata: Store which algorithm was used
4. Monitor both algorithms: System should track usage of each

Future Considerations

• Add algorithm preference configuration
• Implement automatic re-hashing tools (optional)
• Add metrics for algorithm usage
• Consider algorithm-specific optimizations

---

Status: Implemented and tested Compatibility: Full backward and forward compatibility Risk: Low - existing systems unaffected