# API-001: Re-exports from Upstream Crates

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

---

## Summary

`dig-clvm` serves as a unified facade over the Chia crate ecosystem. Rather than requiring callers to know which upstream crate provides each type, `dig-clvm` re-exports the complete public surface so that `use dig_clvm::*` is sufficient for any DIG validator, mempool, or block-builder code. This is the crate's most fundamental contract: callers depend on `dig-clvm` alone and gain access to the full CLVM runtime, protocol types, consensus engine, BLS signatures, spend construction primitives, and DIG network constants.

The re-export list is exhaustive and intentional. Every type, trait, function, and module listed in SPEC.md Section 5.2 must be available through `dig_clvm::*`. The upstream crate modules themselves (e.g., `clvmr`, `chia_protocol`, `chia_bls`) are also re-exported as namespaces so callers can access additional items not in the flat re-export list. This follows the [L1 pattern](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/consensus/multiprocess_validation.py#L20) where `chia_rs` re-exports the Rust crate surface for Python consumption.

The full re-export surface spans eight upstream crate families plus the sibling `dig-constants` crate, covering the CLVM runtime (`clvmr`), serialization traits (`clvm-traits`), tree hashing and currying (`clvm-utils`), protocol wire types (`chia-protocol`), consensus validation (`chia-consensus`), BLS cryptography (`chia-bls`), SDK types and drivers (`chia-sdk-types`, `chia-sdk-driver`, `chia-sdk-coinset`), puzzle bytecodes (`chia-puzzles`), and DIG network parameters (`dig-constants`).

---

## Specification

The `src/lib.rs` file MUST contain the following re-exports. Each line corresponds to an upstream crate and the specific items that must be accessible via `dig_clvm::*`:

```rust
// ── CLVM Runtime ──
pub use clvmr::{self, Allocator, NodePtr, Cost};
pub use clvm_traits::{self, ToClvm, FromClvm};
pub use clvm_utils::{self, tree_hash, curry_tree_hash, CurriedProgram, TreeHash, ToTreeHash};

// ── Chia Protocol Types ──
pub use chia_protocol::{self, Bytes, Bytes32, Coin, CoinSpend, CoinState, Program, SpendBundle};

// ── Consensus Engine ──
pub use chia_consensus::{self, consensus_constants::ConsensusConstants, opcodes};
pub use chia_consensus::spendbundle_conditions::run_spendbundle;
pub use chia_consensus::spendbundle_validation::validate_clvm_and_signature;
pub use chia_consensus::conditions::{
    SpendBundleConditions, OwnedSpendBundleConditions,
    SpendConditions, OwnedSpendConditions,
};

// ── BLS Signatures ──
pub use chia_bls::{self, PublicKey, SecretKey, Signature, aggregate_verify, BlsCache};

// ── SDK Types & Conditions ──
pub use chia_sdk_types::{self, Condition, Conditions, Mod};

// ── DIG Network Constants ──
pub use dig_constants::{self, DIG_MAINNET, DIG_TESTNET, NetworkConstants};

// ── Spend Construction ──
pub use chia_sdk_driver::{self, SpendContext, Layer, Spend, SpendWithConditions, Puzzle, DriverError};

// ── Coin State ──
pub use chia_sdk_coinset::{self, CoinRecord};

// ── Puzzles ──
pub use chia_puzzles;

// ── Block Generator ──
pub use chia_consensus::run_block_generator::BlockGenerator;
```

### Re-export Categories

| Category | Crate | Items |
|---|---|---|
| CLVM Runtime | `clvmr` | `Allocator`, `NodePtr`, `Cost` |
| Serialization | `clvm-traits` | `ToClvm`, `FromClvm` |
| Tree Hash / Currying | `clvm-utils` | `tree_hash`, `curry_tree_hash`, `CurriedProgram`, `TreeHash`, `ToTreeHash` |
| Protocol Types | `chia-protocol` | `Bytes`, `Bytes32`, `Coin`, `CoinSpend`, `CoinState`, `Program`, `SpendBundle` |
| Consensus Engine | `chia-consensus` | `ConsensusConstants`, `opcodes`, `run_spendbundle`, `validate_clvm_and_signature`, `SpendBundleConditions`, `OwnedSpendBundleConditions`, `SpendConditions`, `OwnedSpendConditions`, `BlockGenerator` |
| BLS | `chia-bls` | `PublicKey`, `SecretKey`, `Signature`, `aggregate_verify`, `BlsCache` |
| SDK Types | `chia-sdk-types` | `Condition`, `Conditions`, `Mod` |
| DIG Constants | `dig-constants` | `DIG_MAINNET`, `DIG_TESTNET`, `NetworkConstants` |
| Spend Construction | `chia-sdk-driver` | `SpendContext`, `Layer`, `Spend`, `SpendWithConditions`, `Puzzle`, `DriverError` |
| Coin State | `chia-sdk-coinset` | `CoinRecord` |
| Puzzles | `chia-puzzles` | (entire crate namespace) |

### Constraints

- The `self` re-export for each crate (e.g., `pub use clvmr::{self, ...}`) allows callers to access additional items via the crate namespace (e.g., `dig_clvm::clvmr::SExp`).
- No re-export may be removed without a breaking version bump.
- Adding new re-exports is a non-breaking change.

---

## Acceptance Criteria

- [ ] `use dig_clvm::*` compiles and brings all listed types, traits, and functions into scope
- [ ] Each individual item (`Allocator`, `Coin`, `SpendBundle`, `BlsCache`, `SpendContext`, `DIG_MAINNET`, etc.) resolves when referenced through `dig_clvm::`
- [ ] Upstream crate namespaces are accessible (e.g., `dig_clvm::clvmr::SExp`, `dig_clvm::chia_protocol::Bytes48`)
- [ ] No name collisions exist between re-exported items that would cause ambiguity errors
- [ ] The `BlockGenerator` type from `chia_consensus::run_block_generator` is accessible as `dig_clvm::BlockGenerator`
- [ ] `dig_clvm::chia_puzzles` provides access to puzzle bytecode constants

---

## Implementation Notes

- `lib.rs` should contain only `pub use` statements and the `pub mod consensus;` declaration. No logic, no types, no functions should be defined directly in `lib.rs`.
- The `pub use crate_name::{self, ...}` pattern is idiomatic Rust for re-exporting both individual items and the namespace.
- If upstream crates rename or remove items in future versions, the re-export list must be updated and the change documented as breaking.
- The `chia-sdk-driver` crate requires the `action-layer` feature flag (see API-003 / Cargo.toml).

---

## Verification

### Test Plan

1. **Compilation test** (`tests/re_export_test.rs`):
   - Write a test file that does `use dig_clvm::*;` and references every listed item by name. Each item must resolve at compile time.
   - Reference types: `let _: Allocator;`, `let _: Coin;`, `let _: SpendBundle;`, etc.
   - Reference functions: `let _ = tree_hash as fn(&mut Allocator, NodePtr) -> TreeHash;`
   - Reference constants: `let _ = DIG_MAINNET; let _ = DIG_TESTNET;`

2. **Namespace access test**:
   - Verify `dig_clvm::clvmr::SExp` compiles.
   - Verify `dig_clvm::chia_protocol::Bytes48` compiles.
   - Verify `dig_clvm::chia_puzzles::P2_DELEGATED_PUZZLE_OR_HIDDEN_PUZZLE` compiles (or equivalent).

3. **No ambiguity test**:
   - Confirm `use dig_clvm::*;` does not produce ambiguity warnings or errors when all items are in scope simultaneously.

4. **Exhaustiveness check**:
   - Cross-reference the test against the table above to ensure no item is missing.

---

## Source Citations

- [SPEC.md Section 5.2](../../../../resources/SPEC.md) — Re-exports listing
- [SPEC.md Section 3.2](../../../../resources/SPEC.md) — What dig-clvm re-exports vs. owns
- [Chia L1 `multiprocess_validation.py:20-21`](https://github.com/Chia-Network/chia-blockchain/blob/main/chia/consensus/multiprocess_validation.py#L20) — Precedent for re-exporting Rust crate surface

---

## References

- [API-002](API-002.md) — Dependency boundary constraints
- [API-003](API-003.md) — Individual chia-sdk-* crate requirement
- [API-008](API-008.md) — Module structure (lib.rs is re-exports only)
- [CON-001](../../constants/specs/CON-001.md) — dig-constants as separate crate
