# BLK-012: Storage Statistics (`stats`)

| Link | Path |
|------|------|
| **Normative** | [NORMATIVE.md](../NORMATIVE.md) |
| **Verification** | [VERIFICATION.md](../VERIFICATION.md) |
| **Tracking** | [TRACKING.yaml](../TRACKING.yaml) |
| **Spec** | [SPEC.md](../../../../resources/SPEC.md) Section 3.5, 15.7 |

---

## Summary

`stats(&self) -> Result<StorageStats>` returns aggregate storage statistics for monitoring and diagnostics. Each field of `StorageStats` is populated from the corresponding column family or metadata entry.

---

## Specification

```rust
pub fn stats(&self) -> Result<StorageStats> {
    Ok(StorageStats {
        block_count: self.count_cf_entries(CF_BLOCKS)?,
        canonical_block_count: self.count_cf_entries(CF_CANONICAL)?,
        header_count: self.count_cf_entries(CF_HEADERS)?,
        checkpoint_count: self.count_cf_entries(CF_CHECKPOINTS)?,
        attested_count: self.count_cf_entries(CF_ATTESTED)?,
        tip_height: self.tip().map(|t| t.height),
        min_height: self.min_retained_height_opt()?,
        total_size_bytes: self.estimate_total_size()?,
    })
}
```

### Field Population

| Field | Source |
|-------|--------|
| `block_count` | Count of entries in `CF_BLOCKS` (all forks) |
| `canonical_block_count` | Count of entries in `CF_CANONICAL` |
| `header_count` | Count of entries in `CF_HEADERS` |
| `checkpoint_count` | Count of entries in `CF_CHECKPOINTS` |
| `attested_count` | Count of entries in `CF_ATTESTED` |
| `tip_height` | From in-memory tip cache |
| `min_height` | From `CF_METADATA` `META_MIN_HEIGHT` |
| `total_size_bytes` | RocksDB `GetApproximateSizes` or SST file metadata |

---

## Acceptance Criteria

- [ ] All 8 fields of `StorageStats` are populated
- [ ] `block_count` reflects total blocks across all forks
- [ ] `canonical_block_count` reflects only canonical chain entries
- [ ] `tip_height` is `None` on empty store, `Some` after blocks are added
- [ ] `min_height` is `None` when no pruning has occurred
- [ ] `total_size_bytes` is a reasonable estimate of disk usage

---

## Test Plan

| Test Name | Type | Description |
|-----------|------|-------------|
| `test_stats_empty_store` | unit | Verify all counts are 0 and options are None on empty store |
| `test_stats_after_blocks` | integration | Store N blocks, verify block_count, header_count, canonical_block_count |
| `test_stats_after_pruning` | integration | Prune blocks, verify min_height is set |
| `test_stats_total_size` | integration | Store blocks, verify total_size_bytes > 0 |

---

## Expected Test Files

- `tests/blk_012_tests.rs`
