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-proper.sh 4
• Contents:
  • generate-genesis-proper.sh - Canonical QBFT genesis file generation script
  • generate-genesis.sh - Compatibility wrapper for the canonical generator
  • 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

# Run all Foundry tests
forge test

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

# Run with verbosity
forge test -vvv

Running Foundry Scripts

# 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

# 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

# Generate genesis
./scripts/generate-genesis-proper.sh 4

# 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:

# 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)
• For monorepo day-to-day work, prefer the scoped workflow in FOUNDRY_MONOREPO_SCOPES.md so Forge only compiles the contract subtree you are editing.

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.