PoA Validator Policy

This document describes the PoA validator policy enforcement mechanism for controlling which validators can participate in consensus during Proof of Authority phases of network operation.

Overview

The PoA policy enforcement allows network operators to restrict consensus participation to a defined set of validators via an allowlist. This is useful during:

• Initial network bootstrap (controlled validator set)
• Network upgrades (limiting participants to trusted validators)
• Emergency situations (excluding potentially malicious validators)

Configuration

PoA policy is configured via the PoaConfig struct in the consensus engine configuration.

Configuration Options

pub struct PoaConfig {
    /// Path to a file containing allowed validator public keys (hex-encoded, one per line).
    pub allowlist_file: Option<PathBuf>,

    /// Inline allowlist of validator public keys (hex-encoded).
    pub allowlist: HashSet<String>,

    /// If true, reject participants not in the allowlist. Default: true.
    pub strict: bool,
}

Allowlist File Format

The allowlist file is a simple text file with one hex-encoded ed25519 public key per line:

# Comments are allowed (lines starting with #)
# Empty lines are ignored

a1b2c3d4e5f6...  # 64 hex characters (32 bytes)
f1e2d3c4b5a6...

Each public key must be:

• Exactly 64 hexadecimal characters
• Lowercase (automatically normalized)
• No prefix (no 0x)

CLI Integration

To enable PoA filtering via CLI:

# Using an allowlist file
node --poa-allowlist /path/to/allowlist.txt

# Using inline allowlist (comma-separated)
node --poa-allowlist-inline a1b2c3...,f1e2d3...

# Permissive mode (log warnings but allow all)
node --poa-allowlist /path/to/allowlist.txt --poa-permissive

Enforcement Modes

Strict Mode (default)

In strict mode (strict: true):

• Only validators in the allowlist can participate in consensus
• Non-allowed validators are excluded from the scheme and validator set
• Warnings are logged for each excluded validator

Permissive Mode

In permissive mode (strict: false):

• All validators can participate regardless of allowlist
• Warnings are logged for validators not in the allowlist
• Useful for monitoring/auditing before enforcing restrictions

Implementation Details

Engine Initialization

During engine initialization (Engine::new):

1. If poa config is provided, load the combined allowlist (file + inline)
2. Filter participants against the allowlist
3. Create the signing scheme with filtered participants only
4. Build the validator set from filtered participants
5. Log summary: total, allowed, rejected counts

SLA Metrics

The following metrics are available for monitoring PoA policy enforcement:

Metric	Type	Description
ashen_poa_allowlist_checks_total	Counter	Total PoA allowlist checks performed
ashen_poa_validators_allowed	Gauge	Validators allowed after filtering
ashen_poa_validators_rejected	Gauge	Validators rejected by filtering
ashen_poa_strict_mode	Gauge	1 if strict, 0 if permissive
ashen_poa_missed_proposals_total	Counter	Missed proposals by validator
ashen_poa_proposal_latency_seconds	Histogram	Proposal latency by validator

Operational Runbook

Adding a New Validator

1. Generate the validator’s ed25519 keypair
2. Add the public key (hex) to the allowlist file
3. Restart nodes or use hot-reload (if supported)
4. Verify in logs: “PoA allowlist filtering applied”

Removing a Validator

1. Remove the public key from the allowlist file
2. Restart nodes
3. Confirm in logs the validator is excluded
4. Monitor for consensus health

Emergency Validator Exclusion

For immediate exclusion without file changes:

# Inline exclusion overrides file
node --poa-allowlist /path/to/allowlist.txt --poa-exclude a1b2c3...

Troubleshooting

Symptom: Consensus not progressing after PoA change

1. Check if enough validators remain (need 2/3+1 for BFT)
2. Verify allowlist syntax (64 hex chars, no 0x prefix)
3. Check logs for “Validator not in PoA allowlist” warnings

Symptom: Validator keeps participating despite exclusion

1. Ensure strict mode is enabled (strict: true)
2. Verify the node was restarted
3. Check the public key format matches exactly

Security Considerations

• The allowlist file should be read-only to the node process
• Use file permissions to restrict access (e.g., chmod 600 allowlist.txt)
• Consider using a configuration management system for distributed deployments
• Audit all allowlist changes through version control

Future Enhancements

• Hot reload: Update allowlist without restart
• On-chain governance: Allowlist controlled by governance contract
• Multi-sig approval: Require multiple signatures to modify allowlist
• Time-based policies: Automatic validator rotation schedules