220 lines
7.6 KiB
Markdown
220 lines
7.6 KiB
Markdown
# 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
|
|
|