# BLS-004: Uses chia-bls::BlsCache Directly

> **Authoritative requirement:** [BLS-004](../NORMATIVE.md#BLS-004)
> **Verification:** [VERIFICATION.md](../VERIFICATION.md)
> **Tracking:** [TRACKING.yaml](../TRACKING.yaml)
> **Spec reference:** [SPEC.md](../../../../resources/SPEC.md) — Section 2.6

---

## Summary

The `BlsCache` type used throughout `dig-clvm` must be `chia_bls::BlsCache` from the `chia-bls` crate, not a custom implementation. This requirement ensures that DIG's caching behavior is identical to Chia L1's caching behavior, since both systems use the exact same cache implementation. A custom cache could introduce subtle differences in cache key computation, eviction policy, or pairing verification that would break the parity guarantee.

The `chia-bls` crate (v0.26) provides `BlsCache` as a verified-pairing cache for BLS12-381 signatures. Chia L1 imports this type via `chia_rs` and uses it throughout its validation pipeline. By using the same type, `dig-clvm` inherits identical caching semantics including the internal hash function for pairing keys, the storage format, and any future optimizations made by the Chia team. This is consistent with the project's core design principle stated in [SPEC.md Section 1](../../../../resources/SPEC.md): "Maximize reuse -- Use `chia-bls` directly. Never reimplement what they provide."

This requirement also constrains the re-export surface. The `BlsCache` type must be re-exported from the `dig-clvm` crate root so that callers can construct and manage cache instances without adding `chia-bls` as a direct dependency. The re-export path must be `dig_clvm::BlsCache`, resolving to `chia_bls::BlsCache`. This is specified in [SPEC.md Section 3.2](../../../../resources/SPEC.md) where `BlsCache` appears in the re-export list alongside other `chia-bls` types.

---

## Specification

### Type Identity

The following must hold at compile time:

```rust
// In dig-clvm's lib.rs or re-export module:
pub use chia_bls::BlsCache;

// The re-exported type IS the chia-bls type (not a wrapper, newtype, or alias):
// std::any::TypeId::of::<dig_clvm::BlsCache>()
//   == std::any::TypeId::of::<chia_bls::BlsCache>()
```

### Prohibited Patterns

The following patterns are explicitly prohibited:

```rust
// PROHIBITED: Custom cache struct
pub struct BlsCache {
    inner: HashMap<Vec<u8>, bool>,
}

// PROHIBITED: Newtype wrapper
pub struct BlsCache(chia_bls::BlsCache);

// PROHIBITED: Trait object abstraction
pub trait SignatureCache { ... }
pub struct ChiaBlsCache(chia_bls::BlsCache);
impl SignatureCache for ChiaBlsCache { ... }

// PROHIBITED: Type alias with different semantics
pub type BlsCache = HashMap<(PublicKey, Vec<u8>), bool>;
```

### Allowed Patterns

```rust
// ALLOWED: Direct re-export (preferred)
pub use chia_bls::BlsCache;

// ALLOWED: Type alias to the exact same type (redundant but harmless)
pub type BlsCache = chia_bls::BlsCache;
```

### Dependency Configuration

In `Cargo.toml`:

```toml
[dependencies]
chia-bls = "0.26"
```

The `chia-bls` version must match the version used by `chia-consensus` to avoid type incompatibilities. Since `chia-consensus` v0.26 depends on `chia-bls` v0.26, both resolve to the same crate instance.

### Re-export Surface

The `BlsCache` type must be accessible to callers of `dig-clvm`:

```rust
// Caller code (external crate):
use dig_clvm::BlsCache;

let mut cache = BlsCache::default();
let result = dig_clvm::validate_spend_bundle(
    &bundle, &ctx, &cfg, Some(&mut cache)
);
```

---

## Acceptance Criteria

- [ ] `grep -r "struct BlsCache" src/` returns zero matches (no custom definition)
- [ ] `grep -r "pub use chia_bls::BlsCache" src/` returns at least one match (re-export present)
- [ ] `chia-bls` appears in `Cargo.toml` `[dependencies]` with version matching `chia-consensus`
- [ ] External callers can use `dig_clvm::BlsCache` without adding `chia-bls` as a direct dependency
- [ ] `std::any::TypeId::of::<dig_clvm::BlsCache>() == std::any::TypeId::of::<chia_bls::BlsCache>()` holds in a compile-time or runtime assertion

---

## Implementation Notes

- This is primarily a code review requirement. The implementation is a single `pub use` statement.
- Version alignment between `chia-bls` and `chia-consensus` is critical. If the versions diverge, Rust's type system treats them as different types, causing compilation errors when passing a `dig_clvm::BlsCache` to a `chia-consensus` function that expects `chia_bls::BlsCache`.
- The `BlsCache::default()` constructor creates an empty cache. The `BlsCache::new()` constructor (if available) may accept capacity hints.
- No serialization or persistence of `BlsCache` is required. The cache is ephemeral and lives only as long as the process.

---

## Verification

### Test Plan

1. **Code review -- no custom definition**:
   - Run `grep -r "struct BlsCache" src/` on the `dig-clvm` source tree.
   - Assert zero matches. If any match is found, the requirement is violated.

2. **Code review -- re-export present**:
   - Run `grep -r "pub use chia_bls::BlsCache" src/` on the `dig-clvm` source tree.
   - Assert at least one match.

3. **Compilation test -- type identity**:
   ```rust
   #[test]
   fn bls_cache_is_chia_bls_type() {
       use std::any::TypeId;
       assert_eq!(
           TypeId::of::<dig_clvm::BlsCache>(),
           TypeId::of::<chia_bls::BlsCache>(),
       );
   }
   ```

4. **Compilation test -- external usage**:
   - In an integration test (which compiles as an external crate), write:
   ```rust
   use dig_clvm::BlsCache;
   let mut cache = BlsCache::default();
   // Pass to validate_spend_bundle -- must compile without chia-bls in scope
   ```

5. **Dependency audit**:
   - Run `cargo tree -p dig-clvm | grep chia-bls`.
   - Verify exactly one version of `chia-bls` appears in the dependency tree.
   - Verify the version matches the `chia-consensus` dependency.

6. **Version alignment test**:
   - Inspect `Cargo.lock` to confirm `chia-bls` resolves to a single version.
   - If multiple versions are present, the requirement is violated (type mismatch).

### Expected Test Files

- `tests/cache_tests.rs` -- BLS-004 type identity test
- Code review checklist (manual)

---

## Source Citations

- `chia-bls::BlsCache` API: [`chia-bls` crate v0.26](https://crates.io/crates/chia-bls)
- dig-clvm re-export list: [SPEC.md Section 3.2](../../../../resources/SPEC.md)
- dig-clvm design principle: [SPEC.md Section 1 -- "Maximize reuse"](../../../../resources/SPEC.md)
- Chia L1 BLS usage: [`condition_tools.py:74-100`](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/consensus/condition_tools.py#L74)

---

## References

- [BLS-001](BLS-001.md) -- Optional BlsCache parameter (uses this type in function signatures)
- [BLS-003](BLS-003.md) -- Mempool-to-block reuse (relies on consistent cache semantics)
- [BLS-005](BLS-005.md) -- Cache does not affect correctness (depends on upstream correctness)
- [PAR-005](../../parity/specs/PAR-005.md) -- `chia-bls::aggregate_verify()` (same crate, same principle)
