# Source Project Structure

This document describes the expected structure of the source project (`smom-dbis-138`) that contains Besu configuration files generated by Quorum-Dev-Quickstart or Quorum-Genesis-Tool.

## Directory Structure

### Standard Structure (Flat Config Files)

```
smom-dbis-138/
├── config/
│   ├── genesis.json                  # REQUIRED: Network genesis block
│   ├── permissions-nodes.toml        # REQUIRED: Node allowlist
│   ├── permissions-accounts.toml     # REQUIRED: Account allowlist
│   ├── static-nodes.json             # List of static peer nodes
│   ├── config-validator.toml         # Validator node configuration (template)
│   ├── config-sentry.toml            # Sentry node configuration (optional)
│   ├── config-rpc-public.toml        # RPC node configuration
│   └── config-rpc-core.toml          # Alternative RPC configuration
└── keys/
    └── validators/
        ├── validator-1/               # Validator 1 keys
        │   ├── key.pem
        │   ├── pubkey.pem
        │   ├── address.txt
        │   └── key.priv
        ├── validator-2/               # Validator 2 keys
        ├── validator-3/               # Validator 3 keys
        └── validator-4/               # Validator 4 keys
```

### Enhanced Structure (Node-Specific Directories)

When using Quorum-Genesis-Tool or Quorum-Dev-Quickstart, you may have:

```
smom-dbis-138/
├── config/
│   ├── genesis.json                  # REQUIRED: Network genesis block
│   ├── permissions-nodes.toml        # REQUIRED: Node allowlist
│   ├── permissions-accounts.toml     # REQUIRED: Account allowlist
│   ├── static-nodes.json             # List of static peer nodes
│   └── nodes/                        # Node-specific directories
│       ├── validator-1/              # Validator 1 specific files
│       │   ├── config.toml           # Node-specific config
│       │   ├── nodekey               # Node P2P private key
│       │   ├── nodekey.pub           # Node P2P public key
│       │   └── ...                   # Other node-specific files
│       ├── validator-2/
│       ├── sentry-1/
│       ├── rpc-1/
│       └── ...
└── keys/
    └── validators/
        ├── validator-1/               # Validator signing keys (QBFT)
        ├── validator-2/
        └── ...
```

## File Descriptions

### Required Files

#### `config/genesis.json`
- Network genesis block configuration
- Contains QBFT/IBFT2 consensus settings
- **Generated by**: Quorum-Genesis-Tool or Quorum-Dev-Quickstart
- **Location**: Copied to `/etc/besu/genesis.json` on all nodes

#### `config/permissions-nodes.toml`
- Node allowlist (permissioned network)
- Defines which nodes can join the network
- **Generated by**: Quorum-Genesis-Tool
- **Location**: Copied to `/etc/besu/permissions-nodes.toml` on all nodes

#### `config/permissions-accounts.toml`
- Account allowlist (if using account permissioning)
- Defines which accounts can transact
- **Generated by**: Quorum-Genesis-Tool
- **Location**: Copied to `/etc/besu/permissions-accounts.toml` on all nodes

### Optional Files

#### `config/static-nodes.json`
- List of static peer nodes
- Used for initial peer discovery
- **Note**: Can be generated/updated by deployment scripts
- **Location**: Copied to `/etc/besu/static-nodes.json` on all nodes

#### `config/config-validator.toml`
- Validator node configuration template
- Applied to all validator nodes (106-110)
- **Location**: Copied to `/etc/besu/config-validator.toml` on validators

#### `config/config-sentry.toml`
- Sentry node configuration template
- Applied to all sentry nodes (111-114)
- **Location**: Copied to `/etc/besu/config-sentry.toml` on sentries

#### `config/config-rpc-public.toml` or `config/config-rpc-core.toml`
- RPC node configuration template
- Applied to all RPC nodes (115-117)
- **Location**: Copied to `/etc/besu/config-rpc-public.toml` on RPC nodes

### Node-Specific Directories (`config/nodes/`)

If using Quorum-Genesis-Tool, each node may have its own directory:

#### Structure
```
config/nodes/
├── validator-1/
│   ├── config.toml       # Node-specific configuration
│   ├── nodekey           # Node P2P private key
│   ├── nodekey.pub       # Node P2P public key
│   └── ...               # Other node-specific files
├── validator-2/
├── sentry-1/
├── rpc-1/
└── ...
```

#### Benefits
- Node-specific configurations
- Per-node keys and certificates
- Easier node management
- Matches Quorum-Genesis-Tool output

#### Script Support
The deployment scripts automatically detect and use `config/nodes/` structure if present, otherwise fall back to flat structure.

### Validator Keys (`keys/validators/`)

#### Structure
```
keys/validators/
├── validator-1/          # Validator 1 signing keys (QBFT)
│   ├── key.pem           # Private key (PEM format)
│   ├── pubkey.pem        # Public key (PEM format)
│   ├── address.txt       # Validator address (hex)
│   └── key.priv          # Private key (raw format)
├── validator-2/
├── validator-3/
└── validator-4/
```

#### Purpose
- Validator signing keys for QBFT/IBFT2 consensus
- Used to sign blocks
- **Location**: Copied to `/keys/validators/` on validator nodes only

## Node Name Mapping

The deployment scripts map VMIDs to node names:

| VMID | Node Name   | Type    |
|------|-------------|---------|
| 106  | validator-1 | Validator|
| 107  | validator-2 | Validator|
| 108  | validator-3 | Validator|
| 109  | validator-4 | Validator|
| 110  | validator-5 | Validator|
| 111  | sentry-2    | Sentry  |
| 112  | sentry-3    | Sentry  |
| 113  | sentry-4    | Sentry  |
| 114  | sentry-5    | Sentry  |
| 115  | rpc-1       | RPC     |
| 116  | rpc-2       | RPC     |
| 117  | rpc-3       | RPC     |

When using `config/nodes/` structure, the scripts look for directories matching these node names.

## File Copy Logic

The deployment scripts use the following priority when copying config files:

1. **If `config/nodes/<node-name>/config.toml` exists**: Use node-specific config
2. **If `config/config-<type>.toml` exists**: Use type-specific template
3. **Fallback**: Use container template (created during installation)

Example for validator-1 (VMID 106):
1. Try `config/nodes/validator-1/config.toml`
2. Try `config/config-validator.toml`
3. Fallback to template in container

## Prerequisites Check

Before deployment, run the prerequisites check:

```bash
./scripts/validation/check-prerequisites.sh /path/to/smom-dbis-138
```

This verifies:
- Required directories exist
- Required files exist
- Node-specific directories (if present)
- Validator keys structure
- Provides warnings for optional files

## Generated Files

The following files are typically **generated** by Quorum-Genesis-Tool or Quorum-Dev-Quickstart:

1. **genesis.json** - Network genesis configuration
2. **permissions-nodes.toml** - Node allowlist
3. **permissions-accounts.toml** - Account allowlist (if used)
4. **static-nodes.json** - Static peer list (can be regenerated)
5. **config.toml** (in node directories) - Node-specific configs
6. **nodekey/nodekey.pub** (in node directories) - Node P2P keys
7. **keys/validators/** - Validator signing keys

## Files Modified/Generated by Deployment

The deployment scripts may modify or generate:

1. **static-nodes.json** - Updated with actual enode URLs during bootstrap
2. Node-specific configs - May be customized per container if using templates