Skip to content

MESS Implementation Summary

Overview

This document summarizes the implementation of MESS (Modified Exponential Subjective Scoring) in Fukuii, as described in ECIP-1097/ECBP-1100 (https://github.com/ethereumclassic/ECIPs/pull/373).

What Was Implemented

1. Architecture Documentation (CON-004)

Created comprehensive Architecture Decision Record documenting: - Context and problem statement - Design decisions and rationale - Implementation architecture - Security considerations - Rollout strategy - Best practices from core-geth

File: docs/adr/consensus/CON-004-mess-implementation.md

2. Core Infrastructure

Storage Layer

  • BlockFirstSeenStorage trait for tracking block observation times
  • BlockFirstSeenRocksDbStorage implementation using RocksDB
  • Added BlockFirstSeenNamespace to database namespaces
  • Files:
  • src/main/scala/com/chipprbots/ethereum/db/storage/BlockFirstSeenStorage.scala
  • src/main/scala/com/chipprbots/ethereum/db/storage/BlockFirstSeenRocksDbStorage.scala
  • src/main/scala/com/chipprbots/ethereum/db/storage/Namespaces.scala (updated)

MESS Configuration

  • MESSConfig case class with parameter validation
  • Default values based on core-geth implementation
  • File: src/main/scala/com/chipprbots/ethereum/consensus/mess/MESSConfig.scala

MESS Scoring Algorithm

  • MESSScorer implementing exponential decay function
  • Time-based penalty calculation
  • First-seen time recording
  • File: src/main/scala/com/chipprbots/ethereum/consensus/mess/MESSScorer.scala

3. Consensus Integration

Enhanced ChainWeight

  • Added optional messScore field to ChainWeight
  • Updated comparison logic to prefer MESS scores when available
  • Maintains backward compatibility with non-MESS weights
  • File: src/main/scala/com/chipprbots/ethereum/domain/ChainWeight.scala (updated)

Configuration Integration

  • Added messConfig field to BlockchainConfig
  • Configuration parsing from HOCON files
  • File: src/main/scala/com/chipprbots/ethereum/utils/BlockchainConfig.scala (updated)

4. Configuration Files

Added MESS configuration to network chain files: - etc-chain.conf: ETC mainnet configuration - mordor-chain.conf: Mordor testnet configuration

Both default to enabled = false for backward compatibility.

Files: src/main/resources/conf/chains/{etc,mordor}-chain.conf (updated)

5. Test Coverage

Unit Tests

  • MESSConfigSpec: Configuration validation
  • MESScorerSpec: Scoring algorithm tests
  • BlockFirstSeenStorageSpec: Storage layer tests
  • ChainWeightSpec: Enhanced ChainWeight tests

Files: - src/test/scala/com/chipprbots/ethereum/consensus/mess/MESScorerSpec.scala - src/test/scala/com/chipprbots/ethereum/db/storage/BlockFirstSeenStorageSpec.scala - src/test/scala/com/chipprbots/ethereum/domain/ChainWeightSpec.scala

Integration Tests

  • MESSIntegrationSpec: End-to-end MESS scenarios
  • Recent chain vs. old chain with same difficulty
  • High difficulty overcoming time penalty
  • Minimum weight multiplier enforcement
  • Chain reorganization attack simulation
  • First-seen time recording

File: src/it/scala/com/chipprbots/ethereum/consensus/mess/MESSIntegrationSpec.scala

6. Documentation

  • CON-004: Comprehensive architectural decision record
  • Configuration Guide: User-facing documentation with:
  • Quick start guide
  • Configuration parameter reference
  • How MESS works explanation
  • Use cases and examples
  • Monitoring recommendations
  • Troubleshooting guide
  • Security considerations

Files: - docs/adr/consensus/CON-004-mess-implementation.md - docs/guides/mess-configuration.md - docs/adr/README.md (updated with CON-004 reference)

Design Highlights

Security

  • Opt-in by default: MESS is disabled by default to prevent unexpected behavior
  • Backward compatible: Non-MESS nodes can coexist with MESS-enabled nodes
  • Configurable: All parameters can be tuned for different network conditions
  • Persistent storage: First-seen times survive node restarts
  • Minimum weight floor: Prevents weights from going to zero

Performance

  • Lightweight: Only tracks one timestamp per block
  • Efficient lookup: O(1) hash-based storage
  • No network overhead: MESS is purely local scoring
  • Optional: Can be disabled with zero overhead

Correctness

  • Checkpoint priority: Checkpoints always take precedence over MESS scores
  • Fallback handling: Uses block timestamp if first-seen time is missing
  • Exponential decay: Well-understood mathematical model
  • Parameter validation: Config values are validated at startup

Implementation Status

✅ Completed

  1. Research: MESS best practices from core-geth and ECIP-373
  2. Architecture: CON-004 documenting implementation plan
  3. Core Infrastructure: Storage, config, scorer implementation
  4. Consensus Integration: ChainWeight enhancement with MESS support
  5. Configuration: Added to BlockchainConfig and chain files
  6. Testing: Comprehensive unit and integration tests
  7. Documentation: ADR, configuration guide, code comments

❌ Not Implemented (Future Work)

These items are documented in CON-004 but not yet implemented:

  1. CLI Flags: --enable-mess, --disable-mess, --mess-decay-constant
  2. Status: Not yet available in this release
  3. Note: Configuration examples showing CLI flags in documentation are for future reference only
  4. Requires CLI argument parser updates

  5. Should override config file settings

  6. Metrics: Prometheus/Micrometer metrics for MESS

  7. Block age distribution
  8. Penalty application counts
  9. MESS multiplier gauge

  10. Chain weight MESS scores

  11. Actual Consensus Usage: Integration into ConsensusImpl

  12. Hook into block reception to record first-seen times
  13. Calculate MESS scores during consensus evaluation
  14. Use MESS-enhanced ChainWeight in branch comparison

  15. Requires careful integration to avoid breaking existing consensus

  16. Storage Cleanup: Cleanup of old first-seen entries

  17. Automatic removal of very old entries

  18. Configurable retention period

  19. Advanced Features:

  20. Multi-node time synchronization
  21. Checkpoint sync service integration
  22. Dynamic parameter adjustment

How to Use (When Fully Integrated)

For Node Operators

  1. Enable MESS in etc-chain.conf: 

    mess {
  enabled = true
}

  2. Start node as normal: 

    ./bin/fukuii etc

  3. Monitor via logs and metrics (when implemented)

For Developers

  1. Import MESS components: 

    import com.chipprbots.ethereum.consensus.mess.{MESSConfig, MESSScorer}
import com.chipprbots.ethereum.db.storage.BlockFirstSeenStorage

  2. Record first-seen times when blocks arrive: 

    val scorer = new MESSScorer(config.messConfig, blockFirstSeenStorage)
scorer.recordFirstSeen(block.hash)

  3. Calculate MESS scores during consensus: 

    val messAdjusted = scorer.calculateMessDifficulty(header)
val newWeight = currentWeight.increase(header, Some(messAdjusted))

  4. Compare chains using enhanced ChainWeight: 

    if (newChainWeight > currentChainWeight) {
  // New chain is heavier (considering MESS if enabled)
  switchToNewChain()
}

Testing

Run Unit Tests

sbt test

Tests include: - MESS configuration validation - Scoring algorithm correctness - Storage operations - ChainWeight comparisons

Run Integration Tests

sbt IntegrationTest/test

Tests include: - Complete MESS workflow - Attack scenario simulations - Chain reorganization handling

Security Considerations

Implemented Protections

  1. Parameter validation: Invalid configs rejected at startup
  2. Minimum weight floor: Prevents zero-weight attacks
  3. Maximum time delta: Prevents numerical overflow
  4. Persistent storage: First-seen times survive restarts
  5. Checkpoint priority: MESS doesn't override checkpoints

Operator Responsibilities

  1. NTP synchronization: Accurate clocks required for MESS
  2. Storage integrity: Protect RocksDB from tampering
  3. Gradual rollout: Test on Mordor before mainnet
  4. Monitoring: Watch for unusual MESS penalties

Next Steps for Complete Integration

To complete the MESS implementation:

  1. Integrate into ConsensusImpl:
  2. Add BlockFirstSeenStorage to node initialization
  3. Record first-seen times in block reception handlers
  4. Calculate MESS scores in consensus evaluation

  5. Use MESS-enhanced ChainWeight in branch comparison

  6. Add CLI Support:

  7. Parse --enable-mess and related flags
  8. Override config file settings

  9. Document in help text

  10. Implement Metrics:

  11. Add Prometheus metrics for MESS behavior
  12. Export to Grafana dashboards

  13. Monitor MESS penalties in production

  14. Testing on Networks:

  15. Deploy to Mordor testnet
  16. Monitor behavior and gather feedback
  17. Adjust parameters if needed

  18. Gradual rollout to mainnet

  19. Community Review:

  20. Share implementation with ETC community
  21. Gather feedback from other client developers
  22. Coordinate MESS adoption across clients

References

  • ECIP-1097/ECBP-1100: https://github.com/ethereumclassic/ECIPs/pull/373
  • core-geth: https://github.com/etclabscore/core-geth
  • CON-004: docs/adr/consensus/CON-004-mess-implementation.md
  • Configuration Guide: docs/guides/mess-configuration.md

Conclusion

This implementation provides a complete, well-tested, and documented foundation for MESS in Fukuii. The infrastructure is in place and ready to be integrated into the consensus layer. The opt-in design ensures backward compatibility while providing operators with the choice to enable enhanced security.

The implementation follows best practices from core-geth and the ETC community, with comprehensive testing and documentation to support safe deployment.