Skip to content

xdaniortega/optimistic-consensus

BranchesTags

Repository files navigation

Simplified Optimistic Consensus

Overview

The system implements a state inbox approach with modular consensus mechanisms, featuring:

  • Centralized State: TransactionManager as the single source of truth for all proposal states
  • Optimistic Execution: Transactions are assumed valid unless challenged
  • LLM Integration: Mock LLM oracle for transaction validation
  • Validator Staking: Delegated Proof-of-Stake with individual validator contracts
  • Dispute Resolution: Economic challenge-response mechanism with slashing

All state, validations and challenges resolution will bubble-up to change the state into transaction manager that acts as an input box of transactions.

System Architecture Diagram

┌──────────────┐     submit      ┌────────────────────┐
│     User     ├────────────────►│ TransactionManager │◄──── Central State Inbox
└──────────────┘                 └────────┬───────────┘
                                          │
                        ┌─────────────────┼─────────────────┐
                        │                 │                 │
                        ▼                 ▼                 ▼
                ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
                │MockLLMOracle │  │ PoSConsensus │  │    Others    │
                │(ILLMOracle)  │  │(IConsensus)  │  │    (PoA)     │
                └──────────────┘  └──────┬───────┘  └──────────────┘
                                        │
                                        │ coordinates with
                               ┌────────┼───────┐
                               │                │
                               ▼                ▼
                ┌──────────────┐       ┌──────────────┐
                │DisputeManager│       │StakingManager│
                │              │       │              │
                └──────────────┘       └──────┬───────┘
                                              │
                                              │ deploys via BeaconProxy
                                      ┌───────▼───────┐
                                      │ValidatorLogic │
                                      │   (per user)  │
                                      └───────────────┘

Key Architectural Principles

  1. Single Source of Truth: TransactionManager stores all proposal states
  2. Interface-Based: Components communicate through well-defined interfaces
  3. Economic Security: Validator staking with slashing for misbehavior
  4. Challenge-Response: Optimistic execution with dispute mechanisms
  5. Gas Efficiency: BeaconProxy pattern for validator contracts

Security Report

I acknowledge some errors found in REPORT file, please visit it in the root folder.

⚠️ SECURITY WARNING - PENDING CRITICAL FIXES

The following security issues remain unresolved due to time constraints:

DoS Protection - External calls in loops

  • Add MAX_VALIDATORS = 50 limits in loops
  • Implement batch processing for multiple validators
  • Circuit breakers for emergency pause

Enum Comparison Safety

  • Replace direct equality with explicit state checks
  • Comprehensive state validation

Complete CEI Pattern

  • Move ALL events before external calls
  • Verify order in _finalizeProposal() and slashValidator()

Edge Case Handling

  • Handle when insufficient validators available
  • What happens if all validators are slashed
  • Recovery mechanisms for inconsistent states

Parameter Validation

  • Verify valid ranges for SLASH_PERCENTAGE, CONSENSUS_THRESHOLD
  • Prevent division by zero in reward distribution

Core Components

🎯 TransactionManager - Central Orchestrator

Role: Single source of truth for all proposal states and lifecycle management

Key Responsibilities:

  • Proposal submission and state tracking
  • LLM validation coordination
  • Consensus mechanism delegation
  • State update authorization (only consensus can update)

Core Functions:

function submitProposal(string calldata transaction) external returns (bytes32 proposalId);
function updateProposalStatus(bytes32 proposalId, ProposalStatus newStatus) external; // Only consensus
function getProposalStatus(bytes32 proposalId) external view returns (ProposalStatus);
function getProposalBlockNumber(bytes32 proposalId) external view returns (uint256);

✅ PoSConsensus - Consensus Engine

Role: Implements Proof-of-Stake consensus with signature collection and dispute coordination

Key Responsibilities:

  • Validator selection and signature collection
  • Consensus threshold management
  • Challenge initiation and dispute coordination
  • Slashing coordination for resolved disputes

Core Functions:

function initializeConsensus(bytes32 proposalId, string calldata transaction, address proposer) external;
function signProposal(bytes32 proposalId, bytes calldata signature) external;
function challengeProposal(bytes32 proposalId) external;
function onDisputeResolved(bytes32 proposalId, bool upheld, address challenger) external;

💰 StakingManager - Validator Registry

Role: Manages validator staking, selection, and economic incentives

Key Responsibilities:

  • Validator registration and stake management
  • Top validator selection based on stake
  • Slashing execution for misbehavior
  • Reward distribution to honest validators

Core Functions:

function stake(uint256 amount) external;
function unstake(uint256 amount) external; 
function slashValidator(address validator, uint256 amount, string calldata reason) external;
function getTopNValidators(uint256 n) external view returns (address[] memory, uint256[] memory);

⚔️ DisputeManager - Dispute Resolution

Role: Handles challenge-response disputes with validator voting

Key Responsibilities:

  • Dispute initialization and voting coordination
  • Signature verification for votes
  • Voting result calculation (tie-breaking favors original decision)
  • Dispute resolution with economic consequences

Core Functions:

function initializeDispute(bytes32 proposalId, address[] calldata validators, uint256 period, address challenger) external;
function submitVote(bytes32 proposalId, address voter, bool support, bytes calldata signature) external;
function resolveDispute(bytes32 proposalId) external returns (bool upheld);

👤 ValidatorLogic - Individual Validator State

Role: Manages individual validator's staking positions and rewards

Key Responsibilities:

  • Personal stake tracking with multiple positions
  • Individual slashing and reward handling
  • Position management (create, increase, decrease)
  • Integration with ERC20 token transfers

Architecture: Deployed via BeaconProxy pattern for gas efficiency and upgradeability

🤖 MockLLMOracle - Transaction Validator

Role: Simulates LLM-based transaction validation

Key Responsibilities:

  • Deterministic transaction validation (hash-based)
  • Configurable validation rules
  • Statistics tracking for performance analysis

Design Philosophy

1. Centralized State Management

Philosophy: Single source of truth eliminates state synchronization issues

Implementation:

  • TransactionManager owns all proposal states
  • Only consensus contracts can update states (via updateProposalStatus)
  • All other contracts query TransactionManager for authoritative state

Benefits:

  • Eliminates state drift between components
  • Simplifies debugging and monitoring
  • Enables easy state migrations and upgrades

2. Interface-Driven Architecture

Philosophy: Components communicate through well-defined interfaces, not concrete implementations

Key Interfaces:

  • IConsensus: Standardizes consensus mechanism interactions
  • ILLMOracle: Abstracts transaction validation logic
  • ITransactionManager: Defines state management contract

Benefits:

  • Easy to swap consensus mechanisms
  • Clear contract boundaries
  • Simplified testing with mocks

3. Economic Security Model

Philosophy: Economic incentives ensure honest behavior

Implementation:

  • Minimum stake requirements for validators
  • Slashing penalties for dishonest behavior
  • Rewards for honest validators
  • Challenge bonds to prevent spam

Key Parameters:

uint256 public constant MIN_STAKE = 1000 * 1e18;        // 1000 tokens minimum
uint256 public constant SLASH_PERCENTAGE = 10;          // 10% slash for misbehavior  
uint256 public immutable CONSENSUS_THRESHOLD = 3;       // 3 signatures needed
uint256 public immutable CHALLENGE_PERIOD = 10;         // 10 blocks to challenge

4. Optimistic Execution

Philosophy: Assume transactions are valid unless proven otherwise

Flow:

  1. Submission: User submits transaction
  2. LLM Validation: Quick validity check
  3. Optimistic Approval: Assume valid if LLM approves
  4. Signature Collection: Validators sign to finalize
  5. Challenge Window: Period for disputes
  6. Final Execution: After challenge period expires

5. Dispute Resolution with Tie-Breaking

Philosophy: Economic game theory with clear resolution rules

Voting Rules:

  • Tie votes (50%-50%): Uphold original decision (favor status quo)
  • No votes: Uphold original decision (validator apathy = approval)
  • Majority needed: Strict majority (>50%) required to overturn

Economic Consequences:

  • False challenges: Challenger loses stake
  • Valid challenges: Signers lose stake, challenger rewarded
  • Honest validators: Receive rewards from slashed stakes

Test Suite

Test Architecture & Coverage

Our test suite maintains 80%+ coverage across all metrics:

Contract % Lines % Statements % Branches % Funcs
DisputeManager 99.20% 98.64% 90.00% 100.00%
PoSConsensus 87.56% 83.75% 81.82% 90.32%
MockLLMOracle 100.00% 100.00% 100.00% 100.00%
StakingManager 88.71% 86.49% 70.00% 92.86%
TransactionManager 100.00% 100.00% 100.00% 100.00%
Total 91.16% 89.38% 79.49% 92.78%

Test Categories

1. Unit Tests - Component Isolation

  • TransactionManager: Proposal lifecycle, state management
  • StakingManager: Validator registration, beacon proxy deployment
  • PoSConsensus: Signature collection, consensus thresholds
  • DisputeManager: Voting mechanics, tie-breaking logic
  • MockLLMOracle: Deterministic validation, configuration

2. Integration Tests - Cross-Component Flows

  • End-to-end proposal flows (happy path)
  • Challenge-response dispute resolution
  • Cross-contract state synchronization
  • Economic slashing and reward distribution

3. Edge Case Tests - Boundary Conditions

  • Invalid signatures and replay attacks
  • Voting period expiration scenarios
  • Tie-breaking in dispute resolution
  • Validator set changes during proposals

4. Fuzz Tests - Random Input Validation

function testFuzz_ProposalSubmission(string memory transaction) public {
    vm.assume(bytes(transaction).length > 0);
    vm.assume(bytes(transaction).length < 1000);
    
    vm.prank(alice);
    bytes32 proposalId = transactionManager.submitProposal(transaction);
    
    // Verify proposal was created with correct state
    IConsensus.ProposalStatus status = transactionManager.getProposalStatus(proposalId);
    assertTrue(status != IConsensus.ProposalStatus.Proposed); // Should be processed
}

Key Test Scenarios

Happy Path - Optimistic Approval

function test_CompleteProposalLifecycleNoChallenge() public {
    // 1. Submit proposal (LLM validates, consensus initialized)
    bytes32 proposalId = transactionManager.submitProposal(TEST_TRANSACTION);
    
    // 2. Validators sign (auto-finalizes at threshold)
    for (uint i = 0; i < CONSENSUS_THRESHOLD; i++) {
        bytes memory signature = createValidatorSignature(i + 1, proposalId);
        vm.prank(validators[i]);
        posConsensus.signProposal(proposalId, signature);
    }
    
    // 3. Verify final state
    assertEq(uint8(transactionManager.getProposalStatus(proposalId)), 
             uint8(IConsensus.ProposalStatus.Finalized));
}

Dispute Resolution - Challenge Overturns Proposal

function test_DisputeResolution_Overturned_WithSlashing() public {
    // Setup: proposal with signatures
    bytes32 proposalId = setupSignedProposal();
    
    // Challenge the proposal
    vm.prank(charlie);
    posConsensus.challengeProposal(proposalId);
    
    // Vote to overturn (majority says invalid)
    submitMajorityVotes(proposalId, false); // false = overturn
    
    // Verify: original signers slashed, challenger rewarded
    assertTrue(getValidatorStake(alice) < INITIAL_STAKE);
    assertTrue(getValidatorStake(charlie) > INITIAL_STAKE);
    
    assertEq(uint8(transactionManager.getProposalStatus(proposalId)),
             uint8(IConsensus.ProposalStatus.Rejected));
}

Future Extensions

1. Real LLM Oracle Integration

Asynchronous Validation:

interface IRealLLMOracle {
    function requestValidation(string calldata transaction, bytes32 proposalId) external returns (bytes32 requestId);
    function fulfillValidation(bytes32 requestId, bool result) external; // Called by oracle
}

// Enhanced TransactionManager with async LLM
function submitProposalAsync(string calldata transaction) external returns (bytes32 proposalId) {
    proposalId = generateProposalId(transaction);
    bytes32 requestId = llmOracle.requestValidation(transaction, proposalId);
    
    // Store as pending, will be updated when oracle responds
    proposals[proposalId].status = ProposalStatus.PendingLLM;
}

2. Advanced Consensus Mechanisms

Weighted Voting:

function calculateVoteWeight(address validator) internal view returns (uint256) {
    uint256 stake = stakingManager.getValidatorStake(validator);
    uint256 performance = getValidatorPerformanceScore(validator);
    return stake * performance / PERFORMANCE_SCALE;
}

Dynamic Validator Selection:

function selectValidatorsForProposal(bytes32 proposalId) internal returns (address[] memory) {
    // Use VRF for randomness
    // Consider validator performance history
    // Implement rotation mechanisms
}

3. Cross-Chain Integration

Multi-Chain State Management:

interface ICrossChainManager {
    function syncProposalToChain(uint256 chainId, bytes32 proposalId, ProposalStatus status) external;
    function receiveProposalSync(bytes32 proposalId, ProposalStatus status) external;
}

4. Privacy Enhancements

Zero-Knowledge Voting:

interface IZKVoting {
    function submitPrivateVote(bytes32 proposalId, bytes calldata zkProof) external;
    function verifyVoteProof(bytes calldata proof) external returns (bool valid, bool support);
}

5. Gas Optimizations

Batch Operations:

function batchSignProposals(
    bytes32[] calldata proposalIds, 
    bytes[] calldata signatures
) external {
    for (uint i = 0; i < proposalIds.length; i++) {
        signProposal(proposalIds[i], signatures[i]);
    }
}

📊 Project Statistics

Metric Value
Smart Contracts 7 core contracts
Lines of Code ~3,000 Solidity LOC
Test Files 6 comprehensive test suites
Total Tests 158 individual test cases
Coverage 80%+ across all metrics
Security Features Reentrancy protection, access control, signature verification

About

Implementing a Simplified Optimistic Consensus Mechanism for LLM-Inspired Intelligent Contracts

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages