aitbc/docs/tutorials/custom-proposer.md

Building Custom Proposers in AITBC

This tutorial guides you through creating custom proposers for the AITBC blockchain network. Custom proposers allow you to implement specialized block proposal logic tailored to your specific use case.

Overview

In AITBC, proposers are responsible for creating new blocks in the Proof of Authority (PoA) consensus. While the default proposer works for most cases, you might need custom logic for:

• Priority-based transaction ordering
• Specialized transaction selection
• Custom block validation rules
• Integration with external systems

Prerequisites

• Python 3.8+
• AITBC blockchain node running
• Understanding of PoA consensus
• Development environment set up

Step 1: Create a Custom Proposer Class

Start by creating a new file for your custom proposer:

# custom_proposer.py
from typing import List, Optional
from datetime import datetime
from aitbc_chain.models import Block, Transaction
from aitbc_chain.consensus.base import BaseProposer
from aitbc_chain.config import ProposerConfig

class PriorityProposer(BaseProposer):
    """
    A custom proposer that prioritizes transactions by fee and priority score.
    """
    
    def __init__(self, config: ProposerConfig):
        super().__init__(config)
        self.min_priority_score = config.get("min_priority_score", 0)
        self.max_block_size = config.get("max_block_size", 1000)
    
    async def select_transactions(
        self, 
        pending_txs: List[Transaction],
        current_block: Optional[Block] = None
    ) -> List[Transaction]:
        """
        Select and order transactions based on priority.
        """
        # Filter transactions by minimum priority
        filtered_txs = [
            tx for tx in pending_txs
            if self._calculate_priority(tx) >= self.min_priority_score
        ]
        
        # Sort by priority (highest first)
        sorted_txs = sorted(
            filtered_txs,
            key=self._calculate_priority,
            reverse=True
        )
        
        # Limit block size
        return sorted_txs[:self.max_block_size]
    
    def _calculate_priority(self, tx: Transaction) -> int:
        """
        Calculate transaction priority score.
        """
        # Base priority from fee
        fee_priority = tx.fee or 0
        
        # Bonus for specific transaction types
        type_bonus = {
            "computation": 10,
            "settlement": 5,
            "transfer": 1
        }.get(tx.type, 0)
        
        # Time-based priority (older transactions get higher priority)
        age_bonus = max(0, (datetime.utcnow() - tx.timestamp).seconds // 60)
        
        return fee_priority + type_bonus + age_bonus

Step 2: Implement Custom Block Validation

Add custom validation logic for your blocks:

# custom_proposer.py (continued)
from aitbc_chain.consensus.exceptions import InvalidBlockException

class PriorityProposer(BaseProposer):
    # ... previous code ...
    
    async def validate_block(
        self, 
        block: Block,
        parent_block: Optional[Block] = None
    ) -> bool:
        """
        Validate block with custom rules.
        """
        # Run standard validation first
        if not await super().validate_block(block, parent_block):
            return False
        
        # Custom validation: check minimum priority threshold
        if block.transactions:
            min_priority = min(
                self._calculate_priority(tx) 
                for tx in block.transactions
            )
            
            if min_priority < self.min_priority_score:
                raise InvalidBlockException(
                    f"Block contains transactions below priority threshold"
                )
        
        # Custom validation: ensure proposer diversity
        if parent_block and block.proposer == parent_block.proposer:
            # Allow consecutive blocks only if underutilized
            utilization = len(block.transactions) / self.max_block_size
            if utilization > 0.5:
                raise InvalidBlockException(
                    "Consecutive blocks from same proposer not allowed"
                )
        
        return True

Step 3: Register Your Custom Proposer

Register your proposer with the blockchain node:

# node_config.py
from custom_proposer import PriorityProposer
from aitbc_chain.config import ProposerConfig

def create_custom_proposer():
    """Create and configure the custom proposer."""
    config = ProposerConfig({
        "min_priority_score": 5,
        "max_block_size": 500,
        "proposer_address": "0xYOUR_PROPOSER_ADDRESS",
        "signing_key": "YOUR_PRIVATE_KEY"
    })
    
    return PriorityProposer(config)

# In your node initialization
proposer = create_custom_proposer()
node.set_proposer(proposer)

Step 4: Add Monitoring and Metrics

Track your proposer's performance:

# custom_proposer.py (continued)
from prometheus_client import Counter, Histogram, Gauge

class PriorityProposer(BaseProposer):
    # ... previous code ...
    
    def __init__(self, config: ProposerConfig):
        super().__init__(config)
        
        # Metrics
        self.blocks_proposed = Counter(
            'blocks_proposed_total',
            'Total number of blocks proposed',
            ['proposer_type']
        )
        self.tx_selected = Histogram(
            'transactions_selected_per_block',
            'Number of transactions selected per block'
        )
        self.avg_priority = Gauge(
            'average_transaction_priority',
            'Average priority of selected transactions'
        )
    
    async def propose_block(
        self, 
        pending_txs: List[Transaction]
    ) -> Optional[Block]:
        """
        Propose a new block with metrics tracking.
        """
        selected_txs = await self.select_transactions(pending_txs)
        
        if not selected_txs:
            return None
        
        # Create block
        block = await self._create_block(selected_txs)
        
        # Update metrics
        self.blocks_proposed.labels(proposer_type='priority').inc()
        self.tx_selected.observe(len(selected_txs))
        
        if selected_txs:
            avg_prio = sum(
                self._calculate_priority(tx) 
                for tx in selected_txs
            ) / len(selected_txs)
            self.avg_priority.set(avg_prio)
        
        return block

Step 5: Test Your Custom Proposer

Create tests for your proposer:

# test_custom_proposer.py
import pytest
from custom_proposer import PriorityProposer
from aitbc_chain.models import Transaction
from datetime import datetime, timedelta

@pytest.fixture
def proposer():
    config = ProposerConfig({
        "min_priority_score": 5,
        "max_block_size": 10
    })
    return PriorityProposer(config)

@pytest.fixture
def sample_transactions():
    txs = []
    for i in range(20):
        tx = Transaction(
            id=f"tx_{i}",
            fee=i * 2,
            type="computation" if i % 3 == 0 else "transfer",
            timestamp=datetime.utcnow() - timedelta(minutes=i)
        )
        txs.append(tx)
    return txs

async def test_transaction_selection(proposer, sample_transactions):
    """Test that high-priority transactions are selected."""
    selected = await proposer.select_transactions(sample_transactions)
    
    # Should select max_block_size transactions
    assert len(selected) == 10
    
    # Should be sorted by priority (highest first)
    priorities = [proposer._calculate_priority(tx) for tx in selected]
    assert priorities == sorted(priorities, reverse=True)
    
    # All should meet minimum priority
    assert all(p >= 5 for p in priorities)

async def test_priority_calculation(proposer):
    """Test priority calculation logic."""
    high_fee_tx = Transaction(id="1", fee=100, type="computation")
    low_fee_tx = Transaction(id="2", fee=1, type="transfer")
    
    high_priority = proposer._calculate_priority(high_fee_tx)
    low_priority = proposer._calculate_priority(low_fee_tx)
    
    assert high_priority > low_priority

Advanced Features

1. Dynamic Priority Adjustment

class AdaptiveProposer(PriorityProposer):
    """Proposer that adjusts priority based on network conditions."""
    
    async def adjust_priority_threshold(self):
        """Dynamically adjust minimum priority based on pending transactions."""
        pending_count = await self.get_pending_transaction_count()
        
        if pending_count > 1000:
            self.min_priority_score = 10  # Increase threshold
        elif pending_count < 100:
            self.min_priority_score = 1   # Lower threshold

2. MEV Protection

class MEVProtectedProposer(PriorityProposer):
    """Proposer with MEV (Maximum Extractable Value) protection."""
    
    async def select_transactions(self, pending_txs):
        """Select transactions while preventing MEV extraction."""
        # Group related transactions
        tx_groups = self._group_related_transactions(pending_txs)
        
        # Process groups atomically
        selected = []
        for group in tx_groups:
            if self._validate_mev_safety(group):
                selected.extend(group)
        
        return selected[:self.max_block_size]

3. Cross-Shard Coordination

class ShardAwareProposer(BaseProposer):
    """Proposer that coordinates across multiple shards."""
    
    async def coordinate_with_shards(self, block):
        """Coordinate block proposal with other shards."""
        # Get cross-shard dependencies
        dependencies = await self.get_cross_shard_deps(block.transactions)
        
        # Wait for confirmations from other shards
        await self.wait_for_shard_confirmations(dependencies)
        
        return block

Deployment

1. Package your proposer:

pip install -e .

2. Update node configuration:

# config.yaml
proposer:
  type: custom
  module: my_proposers.PriorityProposer
  config:
    min_priority_score: 5
    max_block_size: 500

3. Restart the node:

sudo systemctl restart aitbc-node

Monitoring

Monitor your proposer's performance with Grafana dashboards:

• Block proposal rate
• Transaction selection efficiency
• Average priority scores
• MEV protection metrics

Best Practices

1. Keep proposers simple - Complex logic can cause delays
2. Test thoroughly - Use testnet before mainnet deployment
3. Monitor performance - Track metrics and optimize
4. Handle edge cases - Empty blocks, network partitions
5. Document behavior - Clear documentation for custom logic

Troubleshooting

Common Issues

1. Blocks not being proposed

   • Check proposer registration
   • Verify signing key
   • Review logs for errors

2. Low transaction throughput

   • Adjust priority thresholds
   • Check block size limits
   • Optimize selection logic

3. Invalid blocks

   • Review validation rules
   • Check transaction ordering
   • Verify signatures

Conclusion

Custom proposers give you fine-grained control over block production in AITBC. This tutorial covered the basics of creating, testing, and deploying custom proposers. You can now extend these examples to build sophisticated consensus mechanisms tailored to your specific needs.

For more advanced examples and community contributions, visit the AITBC GitHub repository.