proxmox/docs/archive/SOURCE_PROJECT_STRUCTURE.md

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:

./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