# 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:

```nim
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:
```nim
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