smom-dbis-138/docs/architecture/DIRECTORY_STRUCTURE.md

# Directory Structure

This document explains the directory structure of the project, particularly the distinction between `test/` vs `tests/` and `script/` vs `scripts/`.

## Directory Overview

### Foundry Directories (Solidity)

#### `test/` - Foundry Test Files
- **Purpose**: Contains Foundry test files (Solidity)
- **File Pattern**: `*.t.sol`
- **Usage**: `forge test`
- **Contents**:
  - `Aggregator.t.sol` - Oracle aggregator tests
  - `Multicall.t.sol` - Multicall utility tests
  - `WETH.t.sol` - WETH token tests

#### `script/` - Foundry Deployment Scripts
- **Purpose**: Contains Foundry deployment scripts (Solidity)
- **File Pattern**: `*.s.sol`
- **Usage**: `forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast`
- **Contents**:
  - `Deploy.s.sol` - Main deployment script
  - `DeployWETH.s.sol` - WETH deployment script
  - `DeployMulticall.s.sol` - Multicall deployment script
  - `DeployOracle.s.sol` - Oracle deployment script

### Shell Script Directories

#### `tests/` - Shell Script Tests
- **Purpose**: Contains shell script tests for infrastructure and network
- **File Pattern**: `*.sh`
- **Usage**: `./tests/health-check.sh`, `./tests/load-test.sh`
- **Contents**:
  - `health-check.sh` - Network health check script
  - `load-test.sh` - RPC endpoint load test script

#### `scripts/` - Shell Scripts
- **Purpose**: Contains utility shell scripts for deployment, key management, etc.
- **File Pattern**: `*.sh`
- **Usage**: `./scripts/generate-genesis.sh`
- **Contents**:
  - `generate-genesis.sh` - Genesis file generation script
  - `deployment/` - Deployment scripts
    - `deploy-weth.sh` - WETH deployment script
    - `deploy-multicall.sh` - Multicall deployment script
  - `key-management/` - Key management scripts
    - `generate-validator-keys.sh` - Validator key generation
    - `generate-oracle-keys.sh` - Oracle key generation
    - `azure-keyvault-setup.sh` - Azure Key Vault setup

## Why Two Sets of Directories?

### Foundry Convention
- Foundry (the Solidity testing framework) uses **singular** directory names:
  - `test/` for test files
  - `script/` for deployment scripts
- These are Foundry's default directories and should not be renamed

### Shell Scripts Convention
- Shell scripts use **plural** directory names to distinguish from Foundry:
  - `tests/` for shell script tests
  - `scripts/` for shell script utilities
- This avoids confusion and follows common project conventions

## Usage Examples

### Running Foundry Tests
```bash
# Run all Foundry tests
forge test

# Run specific test
forge test --match-test testDeposit

# Run with verbosity
forge test -vvv
```

### Running Foundry Scripts
```bash
# Deploy all contracts
forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast

# Deploy WETH
forge script script/DeployWETH.s.sol --rpc-url $RPC_URL --broadcast

# Deploy with private key
forge script script/DeployOracle.s.sol --rpc-url $RPC_URL --broadcast --private-key $PRIVATE_KEY
```

### Running Shell Script Tests
```bash
# Health check
./tests/health-check.sh

# Load test
./tests/load-test.sh

# With custom RPC URL
RPC_URL=https://rpc.d-bis.org ./tests/health-check.sh
```

### Running Shell Scripts
```bash
# Generate genesis
./scripts/generate-genesis.sh

# Generate validator keys
./scripts/key-management/generate-validator-keys.sh 4

# Deploy WETH (shell script wrapper)
./scripts/deployment/deploy-weth.sh
```

## Makefile Targets

The Makefile provides convenient targets for common operations:

```bash
# Run all tests (Foundry + shell scripts)
make test

# Run only Foundry tests
make contracts

# Generate genesis
make genesis

# Generate keys
make keys
```

## Configuration

### Foundry Configuration (`foundry.toml`)
- `src = "contracts"` - Source directory for contracts
- `test/` - Default test directory (not specified, uses default)
- `script/` - Default script directory (not specified, uses default)

### Test Configuration
- Foundry tests: Configured in `foundry.toml`
- Shell script tests: No special configuration needed

## Best Practices

1. **Foundry Tests**: Place all Solidity test files in `test/`
2. **Foundry Scripts**: Place all deployment scripts in `script/`
3. **Shell Tests**: Place infrastructure/network tests in `tests/`
4. **Shell Scripts**: Place utility scripts in `scripts/`
5. **Naming**: Use descriptive names that indicate purpose
6. **Documentation**: Document complex scripts in their headers

## Adding New Files

### Adding a Foundry Test
1. Create file in `test/` directory
2. Name it `*.t.sol` (e.g., `MyContract.t.sol`)
3. Import from `contracts/` directory
4. Run with `forge test`

### Adding a Foundry Script
1. Create file in `script/` directory
2. Name it `*.s.sol` (e.g., `DeployMyContract.s.sol`)
3. Import from `contracts/` directory
4. Run with `forge script script/DeployMyContract.s.sol --rpc-url $RPC_URL --broadcast`

### Adding a Shell Test
1. Create file in `tests/` directory
2. Name it `*.sh` (e.g., `my-test.sh`)
3. Make it executable: `chmod +x tests/my-test.sh`
4. Run with `./tests/my-test.sh`

### Adding a Shell Script
1. Create file in `scripts/` directory (or appropriate subdirectory)
2. Name it `*.sh` (e.g., `my-script.sh`)
3. Make it executable: `chmod +x scripts/my-script.sh`
4. Run with `./scripts/my-script.sh`

## Summary

| Directory | Type | Purpose | Files |
|-----------|------|---------|-------|
| `test/` | Foundry | Solidity test files | `*.t.sol` |
| `script/` | Foundry | Solidity deployment scripts | `*.s.sol` |
| `tests/` | Shell | Infrastructure/network tests | `*.sh` |
| `scripts/` | Shell | Utility scripts | `*.sh` |

This structure follows Foundry conventions while providing clear separation between Solidity and shell script files.