# API-008: Module Structure

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

---

## Summary

The crate's own implementation code MUST be confined to the `src/consensus/` module, consisting of seven source files: `validate.rs`, `block.rs`, `context.rs`, `config.rs`, `result.rs`, `cache.rs`, and `error.rs`. The top-level `src/lib.rs` MUST contain only re-export statements (`pub use`) and the `pub mod consensus;` declaration. This strict separation ensures that the crate's public API surface (re-exports) is clearly distinguished from its implementation (L2 orchestration logic).

The module structure reflects the crate's role as described in [SPEC.md Section 4.1](../../../../resources/SPEC.md): a thin orchestration layer where each file has a single responsibility. `validate.rs` owns spend bundle validation, `block.rs` owns block generator construction and validation, `context.rs` defines the chain state input, `config.rs` defines validation parameters, `result.rs` defines the output, `cache.rs` manages BLS signature caching, and `error.rs` defines the error type. This decomposition matches the L1 pattern where validation, block processing, and error handling are separate concerns.

The `consensus/mod.rs` file serves as the module root, re-exporting public items from the submodules so they are accessible as `dig_clvm::consensus::*` or (via `lib.rs` re-exports) as `dig_clvm::*`. No other top-level modules may exist in `src/` beyond `consensus/` and `lib.rs`.

---

## Specification

### Required File Layout

```
dig-clvm/
  src/
    lib.rs                  -- Re-exports ONLY (pub use + pub mod consensus)
    consensus/
      mod.rs                -- Module root, re-exports from submodules
      validate.rs           -- validate_spend_bundle() orchestration
      block.rs              -- build_block_generator() + validate_block()
      context.rs            -- ValidationContext struct
      config.rs             -- ValidationConfig, L2 cost constants
      result.rs             -- SpendResult struct
      cache.rs              -- BLS signature cache management utilities
      error.rs              -- ValidationError enum
```

### File Responsibilities

| File | Contains | Does NOT Contain |
|---|---|---|
| `lib.rs` | `pub use` re-exports, `pub mod consensus;` | Type definitions, function implementations, constants, logic |
| `consensus/mod.rs` | `pub mod` declarations for submodules, `pub use` re-exports from submodules | Implementation logic |
| `consensus/validate.rs` | `validate_spend_bundle()` function | Block generator logic, error type, config type |
| `consensus/block.rs` | `build_block_generator()`, `validate_block()`, `BlockGeneratorResult` | Spend bundle validation logic |
| `consensus/context.rs` | `ValidationContext` struct definition | Validation logic |
| `consensus/config.rs` | `ValidationConfig` struct, `Default` impl, `L1_MAX_COST_PER_SPEND`, `L2_MAX_COST_PER_BLOCK` | Validation logic |
| `consensus/result.rs` | `SpendResult` struct definition | Validation logic |
| `consensus/cache.rs` | BLS cache utility functions, cache management wrappers | CLVM execution, condition parsing |
| `consensus/error.rs` | `ValidationError` enum, trait impls | Validation logic |

### lib.rs Content

`lib.rs` MUST follow this pattern:

```rust
// Re-exports from upstream crates (see API-001)
pub use clvmr::{self, Allocator, NodePtr, Cost};
pub use clvm_traits::{self, ToClvm, FromClvm};
// ... (all re-exports from API-001)

// The crate's own implementation
pub mod consensus;

// Re-export consensus module's public API for convenience
pub use consensus::{
    validate_spend_bundle, validate_block, build_block_generator,
    ValidationContext, ValidationConfig, SpendResult, BlockGeneratorResult,
    ValidationError,
};
```

### Constraints

- No files outside `src/lib.rs` and `src/consensus/` may exist in `src/`.
- No nested submodules within `consensus/` (e.g., no `consensus/validators/` subdirectory).
- Test files live in `tests/` (integration tests) or inline `#[cfg(test)] mod tests` blocks within source files, not in separate files under `src/`.
- The `consensus/` module MUST NOT re-export upstream crate types. Upstream re-exports are exclusively in `lib.rs`.

---

## Acceptance Criteria

- [ ] `src/lib.rs` contains only `pub use` statements and `pub mod consensus;` (plus optional `pub use consensus::*` re-exports)
- [ ] `src/consensus/mod.rs` exists and declares all seven submodules
- [ ] All seven files exist: `validate.rs`, `block.rs`, `context.rs`, `config.rs`, `result.rs`, `cache.rs`, `error.rs`
- [ ] No other `.rs` files exist directly in `src/` besides `lib.rs`
- [ ] No other modules exist in `src/` besides `consensus/`
- [ ] Each file's content matches its designated responsibility from the table above

---

## Implementation Notes

- The `consensus/mod.rs` file typically looks like:
  ```rust
  pub mod validate;
  pub mod block;
  pub mod context;
  pub mod config;
  pub mod result;
  pub mod cache;
  pub mod error;

  pub use validate::validate_spend_bundle;
  pub use block::{validate_block, build_block_generator, BlockGeneratorResult};
  pub use context::ValidationContext;
  pub use config::{ValidationConfig, L1_MAX_COST_PER_SPEND, L2_MAX_COST_PER_BLOCK};
  pub use result::SpendResult;
  pub use error::ValidationError;
  ```
- Internal (`pub(crate)`) helper functions may exist within the consensus submodules for shared logic between `validate.rs` and `block.rs`.
- If future requirements add new validation concerns (e.g., mempool-specific rules), they should be added as new files within `consensus/` rather than as separate top-level modules.
- The integration test directory (`tests/`) has its own structure defined in SPEC.md Section 4.1 and is outside the scope of this requirement.

---

## Verification

### Test Plan

1. **Filesystem inspection**:
   ```bash
   # List all .rs files in src/
   find dig-clvm/src/ -name "*.rs" -type f | sort
   ```
   Expected output:
   ```
   dig-clvm/src/consensus/block.rs
   dig-clvm/src/consensus/cache.rs
   dig-clvm/src/consensus/config.rs
   dig-clvm/src/consensus/context.rs
   dig-clvm/src/consensus/error.rs
   dig-clvm/src/consensus/mod.rs
   dig-clvm/src/consensus/result.rs
   dig-clvm/src/consensus/validate.rs
   dig-clvm/src/lib.rs
   ```

2. **lib.rs content verification**:
   - Read `src/lib.rs` and verify it contains only `pub use` and `pub mod` statements.
   - No `fn`, `struct`, `enum`, `impl`, `const`, or `static` declarations should exist in `lib.rs` (except possibly `pub use consensus::*` convenience re-exports).

3. **Module declaration verification**:
   - Read `src/consensus/mod.rs` and verify it declares all seven submodules.
   - Verify each declared module corresponds to an existing `.rs` file.

4. **Responsibility verification**:
   - Verify `validate_spend_bundle()` is defined in `validate.rs`, not elsewhere.
   - Verify `ValidationError` is defined in `error.rs`, not elsewhere.
   - Verify `ValidationContext` is defined in `context.rs`, not elsewhere.
   - Verify `ValidationConfig` is defined in `config.rs`, not elsewhere.
   - Verify `SpendResult` is defined in `result.rs`, not elsewhere.

---

## Source Citations

- [SPEC.md Section 4.1](../../../../resources/SPEC.md) — Module layout diagram and file descriptions
- [SPEC.md Section 3.1](../../../../resources/SPEC.md) — Components that dig-clvm owns (maps to consensus/ files)

---

## References

- [API-001](API-001.md) — Re-exports that populate lib.rs
- [API-005](API-005.md) — ValidationError defined in error.rs
- [API-007](API-007.md) — No reimplementation (constrains what goes in consensus/ files)
