From 759bc6bbbe0eb073d2144a6645be6e088741fba2 Mon Sep 17 00:00:00 2001 From: dmarzzz Date: Sat, 26 Jul 2025 16:48:27 -0400 Subject: [PATCH] Add BuilderNet protocol specifications - Add comprehensive BuilderNet protocol specifications in Ethereum consensus-specs format - Include protocol_state.md with persistent state definitions - Add p2p_interface.md for node-to-node communication protocols - Create Builder_node.md with node behavior and lifecycle specifications - Add Blockspace_auction.md for MEV-Boost integration and auction mechanics - Include Flashtestations.md as placeholder for future definition - Implement network vs operator configuration distinction - Add relay subscription management and network parameter update procedures - Include TEE integration, Flat Tax Rule, and refund mechanisms - Add comprehensive validation rules and operational procedures --- specs/Blockspace_auction.md | 593 +++++++++++++++++++++++++++ specs/Builder_node.md | 788 ++++++++++++++++++++++++++++++++++++ specs/Flashtestations.md | 3 + specs/p2p_interface.md | 356 ++++++++++++++++ specs/protocol_state.md | 388 ++++++++++++++++++ 5 files changed, 2128 insertions(+) create mode 100644 specs/Blockspace_auction.md create mode 100644 specs/Builder_node.md create mode 100644 specs/Flashtestations.md create mode 100644 specs/p2p_interface.md create mode 100644 specs/protocol_state.md diff --git a/specs/Blockspace_auction.md b/specs/Blockspace_auction.md new file mode 100644 index 0000000..e1b7dcc --- /dev/null +++ b/specs/Blockspace_auction.md @@ -0,0 +1,593 @@ +# BuilderNet Blockspace Auction + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Configuration](#configuration) +- [Data Structures](#data-structures) +- [MEV-Boost Integration](#mev-boost-integration) +- [Bidding Process](#bidding-process) +- [Block Production](#block-production) +- [Refund Distribution](#refund-distribution) +- [Validation Rules](#validation-rules) +- [Notes](#notes) + + + +## Introduction + +This document defines the blockspace auction mechanism used by BuilderNet. BuilderNet participates in the MEV-Boost auction system, competing with other block builders to win block production rights. The system uses the Flat Tax Rule to calculate refunds and distribute MEV value back to orderflow providers. + +## Configuration + +### Constants + +| Name | Value | Unit | +|------|-------|------| +| `MEV_BOOST_RELAY_TIMEOUT` | `8` | seconds | +| `BIDDING_TIMEOUT` | `10` | seconds | +| `REFUND_PROCESSING_DELAY` | `5` | seconds | +| `REFUND_WALLET_ADDRESS` | `0x62A29205f7Ff00F4233d9779c210150787638E7f` | address | + +### Timeouts + +| Name | Value | Unit | +|------|-------|------| +| `BID_SUBMISSION_TIMEOUT` | `8` | seconds | +| `BLOCK_PRODUCTION_TIMEOUT` | `12` | seconds | +| `REFUND_DISTRIBUTION_TIMEOUT` | `60` | seconds | + +## Data Structures + +### Basic Types + +```python +# Block number (uint64) +BlockNumber = uint64 + +# MEV value in wei (uint256) +MevValue = uint256 + +# Gas price in wei (uint256) +GasPrice = uint256 + +# Timestamp (uint64) +Timestamp = uint64 + +# Address (Bytes20) +Address = Bytes20 + +# Transaction hash (Bytes32) +TxHash = Bytes32 + +# Bundle hash (Bytes32) +BundleHash = Bytes32 +``` + +### MEV-Boost Types + +```python +@dataclass +class MevBoostBid: + block_number: BlockNumber + bid_value: MevValue + block_hash: BlockHash + extra_data: Bytes + timestamp: Timestamp + relay_url: str +``` + +```python +@dataclass +class MevBoostResponse: + success: boolean + block_hash: Optional[BlockHash] + error: Optional[str] + timestamp: Timestamp +``` + +### Block Building Types + +```python +@dataclass +class BlockCandidate: + block_number: BlockNumber + transactions: List[OrderflowEntry] + mev_value: MevValue + proposer_payment: MevValue + remainder: MevValue # mev_value - proposer_payment + timestamp: Timestamp + builder: NodeId +``` + +```python +@dataclass +class BlockSubmission: + block_number: BlockNumber + block_hash: BlockHash + transactions: List[OrderflowEntry] + mev_value: MevValue + proposer_payment: MevValue + extra_data: Bytes + timestamp: Timestamp + relay_url: str +``` + +### Refund Types + +```python +@dataclass +class RefundEntry: + recipient: Address + amount: uint256 + transaction_hash: TxHash + block_number: BlockNumber + contribution: uint256 # Marginal contribution to block value + timestamp: Timestamp + status: RefundStatus # "PENDING", "PROCESSED", "FAILED" +``` + +```python +class RefundStatus(Enum): + PENDING = 0 + PROCESSED = 1 + FAILED = 2 +``` + +### Flat Tax Rule Types + +```python +@dataclass +class IdentityGroup: + signer: Address + transactions: List[OrderflowEntry] + total_payment: uint256 + marginal_contribution: uint256 +``` + +```python +@dataclass +class FlatTaxCalculation: + total_value: MevValue + proposer_payment: MevValue + remainder: MevValue + identity_groups: List[IdentityGroup] + refunds: List[RefundEntry] +``` + +## MEV-Boost Integration + +### Relay Selection + +BuilderNet prioritizes relays that are fast, independent, and reliable. The system supports multiple relays for redundancy and competition. + +```python +def select_relay(block_number: BlockNumber) -> str: + """ + Select the best relay for block submission. + """ + # TODO: Implement relay selection logic + # Consider factors like: + # - Relay performance and reliability + # - Geographic proximity + # - Historical success rate + # - Fee structure + + return "https://relay.example.com" +``` + +### Bid Submission + +```python +def submit_bid_to_relay(block_candidate: BlockCandidate, relay_url: str) -> MevBoostResponse: + """ + Submit a bid to an MEV-Boost relay. + """ + # Calculate bid value (proposer payment) + bid_value = block_candidate.proposer_payment + + # Create bid + bid = MevBoostBid( + block_number=block_candidate.block_number, + bid_value=bid_value, + block_hash=calculate_block_hash(block_candidate), + extra_data=b"BuilderNet", + timestamp=get_current_time(), + relay_url=relay_url + ) + + # Submit to relay + response = submit_to_relay(relay_url, bid) + return response +``` + +## Bidding Process + +### Block Candidate Creation + +```python +def create_block_candidate(node: BuilderNode, block_number: BlockNumber) -> Optional[BlockCandidate]: + """ + Create a block candidate for bidding. + """ + # Get orderflow for this block + orderflow = get_orderflow_for_block(node.state, block_number) + + if not orderflow: + return None + + # Build block using rbuilder + block = node.rbuilder.build_block(block_number, orderflow) + if not block: + return None + + # Calculate MEV and proposer payment + mev_value = block.mev_value + proposer_payment = calculate_proposer_payment(mev_value) + remainder = mev_value - proposer_payment + + candidate = BlockCandidate( + block_number=block_number, + transactions=block.transactions, + mev_value=mev_value, + proposer_payment=proposer_payment, + remainder=remainder, + timestamp=get_current_time(), + builder=node.state.node_id + ) + + return candidate +``` + +### Bidding Strategy + +```python +def calculate_proposer_payment(mev_value: MevValue) -> MevValue: + """ + Calculate the payment to the proposer (bid value). + """ + # BuilderNet competes in the MEV-Boost auction + # The goal is to minimize the bid while still winning + # This allows more value to be refunded to users + + # TODO: Implement sophisticated bidding strategy + # Consider factors like: + # - Market conditions + # - Competition from other builders + # - Historical bid patterns + # - Network congestion + + # For now, use a simple strategy + if mev_value > 0: + # Bid 80% of MEV value, keeping 20% for refunds + return mev_value * 8 // 10 + else: + return 0 +``` + +### Block Production + +```python +def produce_block(node: BuilderNode, slot: Slot) -> Optional[BlockSubmission]: + """ + Produce and submit a block for the current slot. + """ + block_number = slot_to_block_number(slot) + + # Create block candidate + candidate = create_block_candidate(node, block_number) + if not candidate: + return None + + # Select relay + relay_url = select_relay(block_number) + + # Submit bid + response = submit_bid_to_relay(candidate, relay_url) + if not response.success: + return None + + # Create block submission + submission = BlockSubmission( + block_number=block_number, + block_hash=response.block_hash, + transactions=candidate.transactions, + mev_value=candidate.mev_value, + proposer_payment=candidate.proposer_payment, + extra_data=b"BuilderNet", + timestamp=get_current_time(), + relay_url=relay_url + ) + + # Record block production + record_block_production(node.state, submission.block_hash, + submission.block_number, submission.mev_value) + + return submission +``` + +## Block Production + +### Block Building Process + +```python +def build_block_with_rbuilder(node: BuilderNode, block_number: BlockNumber, + orderflow: List[OrderflowEntry]) -> Optional[Block]: + """ + Build a block using the rbuilder software. + """ + # rbuilder handles the core block building logic + # It implements the Flat Tax Rule for refund calculations + # and optimizes transaction ordering for maximum MEV + + block = node.rbuilder.build_block(block_number, orderflow) + return block +``` + +### MEV Calculation + +```python +def calculate_block_mev(transactions: List[OrderflowEntry]) -> MevValue: + """ + Calculate the MEV value of a block. + """ + # MEV includes: + # - Gas fees from transactions + # - Value transfers + # - Arbitrage opportunities + # - Liquidations + # - Sandwich attacks (if applicable) + + total_mev = 0 + + for tx in transactions: + # Calculate gas fees + gas_fees = tx.gas_price * tx.gas_limit + + # Calculate value transfer + value_transfer = tx.value + + # Add to total MEV + total_mev += gas_fees + value_transfer + + return total_mev +``` + +## Refund Distribution + +### Flat Tax Rule Implementation + +```python +def calculate_refunds_flat_tax(block_candidate: BlockCandidate) -> List[RefundEntry]: + """ + Calculate refunds using the Flat Tax Rule. + """ + # Group transactions by signer identity + identity_groups = group_transactions_by_signer(block_candidate.transactions) + + # Calculate marginal contributions + for group in identity_groups: + group.marginal_contribution = calculate_marginal_contribution( + group.transactions, block_candidate.transactions, block_candidate.mev_value + ) + + # Apply Flat Tax Rule + refunds = apply_flat_tax_rule(identity_groups, block_candidate.remainder) + + return refunds +``` + +```python +def calculate_marginal_contribution(transactions: List[OrderflowEntry], + all_transactions: List[OrderflowEntry], + total_value: MevValue) -> uint256: + """ + Calculate the marginal contribution of a set of transactions. + """ + # Calculate value with these transactions + value_with = calculate_block_mev(all_transactions) + + # Calculate value without these transactions + transactions_without = [tx for tx in all_transactions if tx not in transactions] + value_without = calculate_block_mev(transactions_without) + + # Marginal contribution is the difference + marginal_contribution = value_with - value_without + + # Bound by total payment to prevent negative net payment + total_payment = sum(tx.gas_price * tx.gas_limit + tx.value for tx in transactions) + marginal_contribution = min(marginal_contribution, total_payment) + + return marginal_contribution +``` + +```python +def apply_flat_tax_rule(identity_groups: List[IdentityGroup], + remainder: MevValue) -> List[RefundEntry]: + """ + Apply the Flat Tax Rule to calculate refunds. + """ + refunds = [] + + # Calculate total marginal contribution + total_marginal = sum(group.marginal_contribution for group in identity_groups) + + if total_marginal == 0: + return refunds + + # Calculate refunds proportionally + for group in identity_groups: + if group.marginal_contribution > 0: + refund_amount = (group.marginal_contribution * remainder) // total_marginal + + refund_entry = RefundEntry( + recipient=group.signer, + amount=refund_amount, + transaction_hash=b"", # Will be set when processed + block_number=0, # Will be set + contribution=group.marginal_contribution, + timestamp=get_current_time(), + status=RefundStatus.PENDING + ) + + refunds.append(refund_entry) + + return refunds +``` + +### Identity Constraint + +```python +def apply_identity_constraint(refunds: List[RefundEntry], + identity_groups: List[IdentityGroup]) -> List[RefundEntry]: + """ + Apply the identity constraint to prevent gaming. + """ + # The identity constraint ensures that no set of identities + # can receive more refunds than their joint marginal contribution + + # TODO: Implement the identity constraint optimization + # This involves solving a constrained optimization problem + + return refunds +``` + +### Refund Processing + +```python +def process_refunds(node: BuilderNode, refunds: List[RefundEntry]) -> None: + """ + Process refunds and send them to recipients. + """ + for refund in refunds: + if refund.status == RefundStatus.PENDING: + # Send refund transaction from BuilderNet refund wallet + success = send_refund_transaction(node, refund) + + if success: + refund.status = RefundStatus.PROCESSED + refund.transaction_hash = get_refund_tx_hash(refund) + else: + refund.status = RefundStatus.FAILED + + # Update state + node.state.pending_refunds.append(refund) +``` + +```python +def send_refund_transaction(node: BuilderNode, refund: RefundEntry) -> boolean: + """ + Send a refund transaction from the BuilderNet refund wallet. + """ + # Refunds are sent from the official BuilderNet refund wallet + # Address: 0x62A29205f7Ff00F4233d9779c210150787638E7f + + # TODO: Implement refund transaction creation and submission + # This involves: + # 1. Creating a transaction to send refund to recipient + # 2. Signing with refund wallet private key + # 3. Submitting to the network + # 4. Waiting for confirmation + + return True +``` + +## Validation Rules + +### Block Candidate Validation + +```python +def is_valid_block_candidate(candidate: BlockCandidate) -> boolean: + """ + Validate a block candidate. + """ + if candidate.block_number == 0: + return False + + if len(candidate.transactions) == 0: + return False + + if candidate.mev_value < 0: + return False + + if candidate.proposer_payment > candidate.mev_value: + return False + + if candidate.remainder != candidate.mev_value - candidate.proposer_payment: + return False + + if candidate.timestamp > get_current_time(): + return False + + return True +``` + +### MEV-Boost Bid Validation + +```python +def is_valid_mev_boost_bid(bid: MevBoostBid) -> boolean: + """ + Validate an MEV-Boost bid. + """ + if bid.bid_value == 0: + return False + + if bid.block_number == 0: + return False + + if bid.timestamp > get_current_time(): + return False + + if not is_valid_block_hash(bid.block_hash): + return False + + return True +``` + +### Refund Validation + +```python +def is_valid_refund(refund: RefundEntry) -> boolean: + """ + Validate a refund entry. + """ + if refund.amount == 0: + return False + + if refund.block_number == 0: + return False + + if refund.timestamp > get_current_time(): + return False + + if refund.status not in [RefundStatus.PENDING, RefundStatus.PROCESSED, RefundStatus.FAILED]: + return False + + return True +``` + +## Notes + +1. **MEV-Boost Integration**: BuilderNet participates in the existing MEV-Boost auction system. + +2. **Flat Tax Rule**: Refunds are calculated using the Flat Tax Rule implemented in rbuilder. + +3. **Refund Wallet**: All refunds are sent from the official BuilderNet refund wallet address. + +4. **Bidding Strategy**: BuilderNet aims to minimize bids while still winning auctions to maximize refunds. + +5. **Identity Constraint**: The system prevents gaming by constraining refunds based on joint marginal contributions. + +6. **TODO**: Implement sophisticated bidding strategies based on market conditions. + +7. **TODO**: Add support for multiple relay selection and redundancy. + +8. **TODO**: Implement the complete identity constraint optimization. + +9. **TODO**: Add support for different MEV extraction strategies. + +10. **TODO**: Implement proper refund transaction creation and submission. \ No newline at end of file diff --git a/specs/Builder_node.md b/specs/Builder_node.md new file mode 100644 index 0000000..0878e6c --- /dev/null +++ b/specs/Builder_node.md @@ -0,0 +1,788 @@ +# BuilderNet Node + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Configuration](#configuration) +- [Data Structures](#data-structures) +- [Node Architecture](#node-architecture) +- [Core Functions](#core-functions) +- [Orderflow Processing](#orderflow-processing) +- [Protocol Synchronization](#protocol-synchronization) +- [Block Building](#block-building) +- [Refund Processing](#refund-processing) +- [Operation](#operation) +- [Validation Rules](#validation-rules) +- [Notes](#notes) + + + +## Introduction + +This document defines the behavior and lifecycle of a BuilderNet node. BuilderNet nodes run in Trusted Execution Environments (TEEs), process orderflow confidentially, build blocks using the rbuilder software, and coordinate through Flashbots infrastructure. + +A BuilderNet node is a decentralized block builder that participates in Ethereum's MEV-Boost auction system. Unlike traditional centralized builders, BuilderNet nodes operate in TEEs to ensure orderflow confidentiality and system integrity. Nodes share orderflow with each other on a best-effort basis and use the Flat Tax Rule to distribute MEV back to users. + +## Configuration + +### Constants + +| Name | Value | Unit | +|------|-------|------| +| `MAX_ORDERFLOW_ENTRIES` | `10000` | entries | +| `REFUND_WALLET_ADDRESS` | `0x62A29205f7Ff00F4233d9779c210150787638E7f` | address | +| `ORDERFLOW_TIMEOUT_SECONDS` | `60` | seconds | +| `MAX_BUNDLE_SIZE` | `100` | transactions | +| `MAX_TRANSACTION_SIZE` | `128` | KB | + +### Timeouts + +| Name | Value | Unit | +|------|-------|------| +| `STARTUP_TIMEOUT` | `60` | seconds | +| `SHUTDOWN_TIMEOUT` | `30` | seconds | +| `ORDERFLOW_TIMEOUT` | `60` | seconds | +| `BUILDERHUB_TIMEOUT` | `30` | seconds | +| `OPERATOR_API_TIMEOUT` | `10` | seconds | +| `LOG_DELAY_SECONDS` | `300` | seconds | + +## Data Structures + +### Node Components + +```python +@dataclass +class BuilderNode: + # Core state + state: BuilderNodeState + genesis: BuilderNetGenesis + network_config: NetworkConfig + operator_config: OperatorConfig + + # TEE environment + tee_interface: TEEInterface + tls_certificate: TlsCertificate + + # Network services + orderflow_proxy: OrderflowProxy + haproxy: HAProxy + cvm_proxy: CvmProxy + + # Block building + rbuilder: RBuilder + bidding_service: BiddingService + + # Consensus and execution + consensus_client: ConsensusClient + execution_client: ExecutionClient + + # External interfaces + builder_hub: BuilderHub + relay_interface: RelayInterface + + # Operator management + operator_api: OperatorAPI + + # Lifecycle state + is_running: boolean + startup_time: uint64 + last_health_check: uint64 +``` + +### BuilderNet Genesis + +The BuilderNet Genesis object contains the foundational configuration and measurements that define the BuilderNet network. This object is created during network initialization and contains immutable network parameters that all nodes must participate in. + +**TEE Measurements** +The genesis object stores the expected TEE measurements for all BuilderNet nodes. These measurements include the expected code hash, configuration hash, and other security parameters that must match for a node to be considered valid. + +**Block Data Parameters** +Network-wide block building parameters are defined in the genesis object. This includes target block times, maximum block sizes, and other consensus parameters that all nodes must follow. + +**Flashbots Infrastructure** +The genesis object contains the addresses and configuration for Flashbots infrastructure components including BuilderHub, the redistribution archive, and other network services. + +**Supported Relays** +The genesis object defines the list of MEV-Boost relays that all BuilderNet nodes must support and subscribe to. This ensures consistent relay participation across the network. + +**Network Identifiers** +Unique network identifiers and version information are stored in the genesis object to ensure all nodes are operating on the same network version. + +### Network Configuration + +Network configuration contains settings that all BuilderNet nodes must participate in and maintain the same values. These are mandatory network-wide parameters that ensure consistent behavior across all nodes. + +**TEE Environment Configuration** +The network configuration specifies the TEE type (TDX, SGX, etc.) and the attestation provider to use for TEE verification. This determines how the node proves its secure execution environment. + +**Block Building Parameters** +Network-wide block building configuration includes target block times and maximum block sizes. These parameters are set at the network level and all nodes must follow them. + +**Relay Subscription Settings** +Network configuration defines the relay subscription parameters including subscription timeouts, retry mechanisms, and connection limits that all nodes must use when connecting to supported relays. + +**Logging and Monitoring** +Network-wide logging levels and metrics collection settings that ensure consistent operational data across all nodes. + +### Operator Configuration + +Operator configuration contains optional settings that operators can choose to enable or configure based on their preferences. These settings do not affect network consensus but allow operators to customize their node behavior. + +**Operator Identity** +The operator configuration contains the operator's address and associated credentials. This information is used for authentication and authorization in the Operator API. + +**Block Filtering Preferences** +Operators can configure address blocklists, transaction type filters, and other content-based filtering rules. These settings allow operators to opt out of processing certain types of transactions or blocks. + +**Management Settings** +Operator-specific settings include API access controls, notification preferences, and other management-related configurations. + +**Security Parameters** +Operator security settings include authentication methods, access restrictions, and audit logging preferences. + +**Performance Tuning** +Operators can configure performance-related settings such as connection pool sizes, timeout values, and resource allocation limits within network-defined bounds. + +### Network Parameter Updates + +Network parameter updates allow the BuilderNet network to evolve and adapt to changing requirements. These updates are coordinated across all nodes to ensure network-wide consistency. + +**Update Authority** +Network parameter updates are authorized by the BuilderNet governance process. This process involves community discussion, proposal submission, and voting by network participants. The governance mechanism ensures that changes are transparent and reflect the network's collective interests. + +**Update Types** +Network parameters can be updated in several categories: +- **Genesis Parameters**: Core network parameters including TEE measurements, supported relays, and network identifiers +- **Configuration Parameters**: Network-wide settings such as block building parameters, relay subscription settings, and logging levels +- **Security Parameters**: TEE configuration, attestation providers, and security-related settings + +**Update Process** +The network parameter update process follows these steps: +1. **Proposal Phase**: A proposal is submitted through the governance process with detailed justification and impact analysis +2. **Discussion Phase**: The proposal is discussed by the community with technical review and feedback +3. **Voting Phase**: Network participants vote on the proposal with appropriate quorum requirements +4. **Implementation Phase**: If approved, the update is implemented across all nodes with a coordinated rollout schedule +5. **Activation Phase**: The new parameters are activated at a predetermined block height or timestamp + +**Update Coordination** +All nodes must apply network parameter updates simultaneously to maintain network consistency. The update process includes: +- **Notification Period**: Nodes are notified of upcoming updates with sufficient advance notice +- **Compatibility Checks**: Updates are validated to ensure compatibility with existing node software +- **Rollback Procedures**: Emergency rollback procedures are available if issues arise during activation +- **Monitoring**: Network-wide monitoring ensures all nodes successfully apply the updates + +**Update Validation** +Before activation, network parameter updates undergo rigorous validation: +- **Technical Review**: Updates are reviewed for technical correctness and security implications +- **Compatibility Testing**: Updates are tested in staging environments to ensure compatibility +- **Security Audit**: Security implications are assessed, especially for TEE-related changes +- **Performance Impact**: Performance implications are evaluated to ensure network stability + +**Emergency Updates** +In critical situations, emergency network parameter updates may be implemented: +- **Security Vulnerabilities**: Immediate updates to address security issues +- **Network Stability**: Updates to resolve network-wide stability problems +- **Critical Bugs**: Fixes for bugs that affect network functionality +- **Governance Override**: Emergency procedures that bypass normal governance for critical issues + +**Update Communication** +Network parameter updates are communicated through multiple channels: +- **Official Announcements**: Updates are announced through official BuilderNet channels +- **Technical Documentation**: Detailed technical documentation accompanies each update +- **Operator Notifications**: Node operators receive direct notifications of required updates +- **Community Forums**: Updates are discussed in community forums with technical details + +**Update Compliance** +All nodes must comply with network parameter updates to maintain network participation: +- **Mandatory Updates**: Critical updates that all nodes must apply to continue participating +- **Grace Period**: A grace period is provided for operators to apply non-critical updates +- **Compliance Monitoring**: Network monitoring ensures all nodes are running updated parameters +- **Enforcement**: Non-compliant nodes may be excluded from network participation until updates are applied + +### Service Components + +```python +@dataclass +class OrderflowProxy: + system_endpoint: str # Port 5542 + user_endpoint: str # Port 5543 + rbuilder_endpoint: str # Port 8645 + + def process_orderflow(self, orderflow: List[OrderflowEntry]) -> boolean: + """ + Process incoming orderflow and forward to rbuilder. + """ + # Validate orderflow + for entry in orderflow: + if not is_valid_orderflow_entry(entry): + return False + + # Forward to rbuilder via JSON-RPC + success = self.forward_to_rbuilder(orderflow) + return success + + def forward_to_rbuilder(self, orderflow: List[OrderflowEntry]) -> boolean: + """ + Forward orderflow to rbuilder via JSON-RPC on port 8645. + """ + # TODO: Implement JSON-RPC communication with rbuilder + return True +``` + +```python +@dataclass +class RBuilder: + json_rpc_endpoint: str # Port 8645 + prometheus_endpoint: str # Port 6069 + health_endpoint: str # Port 6070 + + def build_block(self, block_number: BlockNumber, + orderflow: List[OrderflowEntry]) -> Optional[Block]: + """ + Build a block using the rbuilder software. + """ + # rbuilder implements the Flat Tax Rule for refunds + # and handles block building logic + # TODO: Implement block building via rbuilder JSON-RPC + return None + + def calculate_refunds(self, block_transactions: List[OrderflowEntry], + total_mev: MevValue, proposer_payment: MevValue) -> List[RefundEntry]: + """ + Calculate refunds using the Flat Tax Rule implemented in rbuilder. + """ + # TODO: Implement refund calculation via rbuilder + return [] +``` + +```python +@dataclass +class BiddingService: + endpoint: str # Port 6148 + supported_relays: List[str] # From genesis + relay_subscriptions: Dict[str, RelaySubscription] + subscription_timeout: uint64 + + def subscribe_to_relays(self, relay_list: List[str]) -> boolean: + """ + Subscribe to all supported relays from genesis. + """ + # TODO: Implement relay subscription logic + return True + + def submit_bid(self, block_number: BlockNumber, bid_value: MevValue, + block_hash: BlockHash) -> boolean: + """ + Submit a bid for block production to all subscribed relays. + """ + # TODO: Implement bidding logic + return True +``` + +```python +@dataclass +class ConsensusClient: + rest_api_endpoint: str # Port 3500 + p2p_endpoint: str # Port 9000 + + def get_current_slot(self) -> Slot: + """ + Get the current consensus slot. + """ + # TODO: Implement slot tracking + return 0 + + def get_block_proposer(self, slot: Slot) -> Address: + """ + Get the proposer for a given slot. + """ + # TODO: Implement proposer lookup + return Address() + + def submit_block(self, block: Block) -> boolean: + """ + Submit a block to the consensus layer. + """ + # TODO: Implement block submission + return True +``` + +```python +@dataclass +class ExecutionClient: + json_rpc_endpoint: str # Port 8545 + websocket_endpoint: str # Port 8546 + engine_api_endpoint: str # Port 8551 + metrics_endpoint: str # Port 9001 + + def get_block_by_number(self, block_number: BlockNumber) -> Optional[Block]: + """ + Get block information by block number. + """ + # TODO: Implement block retrieval + return None + + def get_account_balance(self, address: Address) -> uint256: + """ + Get account balance. + """ + # TODO: Implement balance lookup + return 0 + + def estimate_gas(self, transaction: OrderflowEntry) -> uint64: + """ + Estimate gas for a transaction. + """ + # TODO: Implement gas estimation + return 0 +``` + +### Operator API Types + +```python +@dataclass +class OperatorAPI: + listen_address: str # Port 3535 + basic_auth_secret: Optional[str] + tls_enabled: boolean + tls_cert_path: str + tls_key_path: str + + def set_basic_auth(self, secret: str) -> boolean: + """ + Set the basic authentication secret. + """ + self.basic_auth_secret = secret + return True + + def get_logs(self) -> str: + """ + Get system logs. + """ + # TODO: Implement log retrieval + return "" + + def health_check(self) -> boolean: + """ + Perform health check. + """ + # TODO: Implement health check + return True + + def restart_service(self, service_name: str) -> boolean: + """ + Restart a specific service. + """ + # TODO: Implement service restart + return True + + def upload_file(self, file_type: str, file_data: Bytes) -> boolean: + """ + Upload a configuration file. + """ + # TODO: Implement file upload + return True +``` + +```python +@dataclass +class OperatorApiRequest: + endpoint: str + method: str # "GET", "POST", "PUT" + data: Optional[Bytes] + basic_auth: str + timestamp: Timestamp +``` + +```python +@dataclass +class OperatorApiResponse: + success: boolean + data: Optional[Bytes] + error: Optional[str] + timestamp: Timestamp +``` + +## Node Architecture + +### TEE Environment + +BuilderNet nodes run entirely within Trusted Execution Environments (TEEs), providing: + +1. **Confidentiality**: Orderflow data never leaves the TEE +2. **Integrity**: Code and configuration are verifiable through attestation +3. **Isolation**: Operators cannot access sensitive data + +### Service Architecture + +The node consists of several services running within the TEE: + +1. **orderflow-proxy**: Handles incoming orderflow on ports 5542/5543 +2. **rbuilder**: Core block building software with refund logic +3. **bidding-service**: Coordinates bidding for block production +4. **consensus-client**: Consensus layer client for slot tracking and block submission +5. **execution-client**: Execution layer client for blockchain data and gas estimation +6. **HAProxy**: Reverse proxy for external communication +7. **cvm-proxy**: TEE-attested communication proxy +8. **Operator API**: Admin interface for operators + +### Network Architecture + +``` +External World + ↓ (Port 443) +HAProxy → orderflow-proxy (Port 5543) → rbuilder (Port 8645) + ↓ (Port 5544) +HAProxy → orderflow-proxy (Port 5542) → rbuilder (Port 8645) + ↓ (Port 7936) +cvm-proxy → BuilderHub (secrets, config, peers) + ↓ (Port 3535) +Operator API (health, logs, management) + ↓ (Port 3500) +consensus-client → Consensus network + ↓ (Port 8545) +execution-client → Execution network +``` + +## Core Functions + +### Node Startup + +**Initialization Process** +When starting a BuilderNet node, the system first loads the BuilderNet Genesis object which contains network-wide parameters and TEE measurements. The TEE environment is initialized using the genesis measurements and the network configuration's TEE type. A TLS certificate is generated for secure communication. All core services are then initialized including the orderflow proxy, HAProxy, cvm-proxy, rbuilder, bidding service, consensus client, and execution client. + +**Relay Subscription Setup** +The bidding service subscribes to all supported relays defined in the genesis object using the network configuration's relay subscription settings. This ensures all nodes participate in the same relay network. + +**External Interface Setup** +The node establishes connections to external services using addresses from the genesis object, including BuilderHub for peer management and the relay interface for MEV-Boost integration. The Operator API is initialized using the operator configuration to provide management capabilities. + +**Node State Creation** +A new BuilderNode instance is created with the genesis object, network configuration, and operator configuration. The node's startup time is recorded and the running state is set to true. Background tasks are started to handle ongoing operations such as protocol synchronization and health monitoring. + +### Node Shutdown + +**Graceful Shutdown Process** +When shutting down a BuilderNet node, the system first checks if the node is currently running. If not, the shutdown process is skipped. The node's running state is set to false to prevent new operations from starting. + +**Service Termination** +All background tasks are stopped first, followed by the persistence of the final node state to ensure no data is lost. Each service is then stopped in sequence: orderflow proxy, HAProxy, cvm-proxy, rbuilder, bidding service, consensus client, execution client, and finally the Operator API. + +**State Persistence** +The final node state is persisted to ensure that any pending operations or important data are preserved for the next startup. + +## Orderflow Processing + +### System Guarantees + +Based on TEE integrity, the orderflow processing system provides the following guarantees: + +1. **Confidentiality**: Orderflow data is never exposed to operators or external parties +2. **Integrity**: Orderflow processing follows the exact logic defined in the attested code +3. **Best-Effort Propagation**: Orderflow is shared with other BuilderNet nodes on a best-effort basis +4. **Non-Repudiation**: All orderflow processing is cryptographically signed and verifiable + +### Orderflow Reception and Validation + +When a BuilderNet node receives an orderflow request, it follows a four-step validation process: + +**Step 1: Format Validation** +The node first validates the request format. It checks that the method is either "eth_sendBundle" or "eth_sendRawTransaction". The timestamp must not be in the future and must not be older than 60 seconds. For bundle submissions, exactly one parameter is required and it must be an object. For raw transactions, exactly one parameter is required and it must be a string. + +**Step 2: Source Authentication** +The node extracts the source identifier from the "X-BuilderNet-Source" header and looks up this peer in its local peer list from the protocol state. The peer must be known, connected, and active. The node verifies the peer's TLS certificate is valid and not expired, and that the peer's TEE attestation is recent and properly signed. + +**Step 3: Signature Verification** +The node extracts the signature from the "X-Flashbots-Signature" header, which contains the public key and signature separated by a colon. It creates a canonical message hash from the method, parameters, timestamp, and source identifier. The signature is verified using the authenticated peer's public key through TEE-attested verification. + +**Step 4: Method Processing** +If all validations pass, the node processes the request based on the method. Bundle submissions are processed by parsing the bundle structure and validating all transactions. Raw transactions are processed by validating the transaction data and creating orderflow entries. + +**Authentication Details** +BuilderNet nodes authenticate orderflow by checking peer keys stored in the protocol state. Each peer entry contains the node ID, public key, TLS certificate, and TEE attestation. The TLS certificate must be issued by a trusted certificate authority and not expired. The TEE attestation must be signed, recent (within 1 hour), and contain valid measurements matching the expected TEE environment. + +**Message Hashing** +The canonical message format includes the method, parameters, timestamp, and source identifier. This is serialized to JSON with sorted keys for deterministic hashing, then encoded as UTF-8 and hashed using Keccak256. + +### Bundle Processing + +Bundle submissions contain multiple transactions that are processed together. The node validates the bundle structure, ensuring it contains a block number and transaction list. Each transaction is validated for format and size limits. The bundle is then parsed and all transactions are converted to orderflow entries. + +### Raw Transaction Processing + +Individual raw transactions are processed similarly to bundle transactions but without the bundle wrapper. The transaction data is validated and converted to an orderflow entry. + +### Orderflow State Management + +Orderflow entries are stored in the node's state with a maximum capacity of 10,000 entries. When capacity is reached, the oldest entries are removed (FIFO). Entries are filtered by timeout and block suitability when retrieved for block building. + +### Orderflow Sharing + +**Sharing Guarantees** +The orderflow sharing system provides the following guarantees: + +1. **Confidentiality**: Orderflow data is encrypted in transit and only accessible to authorized BuilderNet nodes +2. **Best-Effort Propagation**: Orderflow sharing is attempted with all connected peers but delivery is not guaranteed +3. **Integrity**: The orderflow sharing code running in the TEE is verifiable and cannot be tampered with +4. **Non-Repudiation**: All orderflow sharing requests are cryptographically signed and verifiable +5. **Peer Authentication**: All peer communication is authenticated using TLS certificates + +**How Guarantees Are Achieved** +- **Confidentiality**: Achieved through TEE-attested TLS communication between nodes, ensuring end-to-end encryption +- **Best-Effort Propagation**: Achieved through the integrity guarantee of the TEE - the orderflow sharing code is unmodified and will attempt to share with all peers, but network-level adversaries and connectivity issues are not protected against +- **Integrity**: Achieved through TEE attestation ensuring the orderflow sharing code is verifiable and tamper-proof +- **Non-Repudiation**: Achieved through cryptographic signing of all sharing requests using TEE-attested private keys +- **Peer Authentication**: Achieved through TLS certificate verification during peer communication + +**TODO**: Add link to Flashbots forum discussion on orderflow sharing guarantees and network-level protection mechanisms. + +**Sharing Implementation** +Orderflow is shared with all connected peers on a best-effort basis. For each peer, the node creates a signed orderflow share request and sends it via HTTPS with TLS certificate verification. Successful and failed sharing attempts are logged for monitoring purposes. + +## Protocol Synchronization + +BuilderNet nodes maintain synchronization with the network by periodically fetching and updating their peer information from BuilderHub. This ensures nodes have current information about all active peers in the network. + +**Peer List Fetching** +Every 5 minutes, each node fetches the current peer list from BuilderHub. The response contains node IDs, addresses, public keys, TLS certificates, and TEE attestations for all active peers in the network. + +**Peer State Updates** +For each peer in the fetched list, the node checks if it already exists in its local peer state. If the peer exists, the node updates any changed information such as address, TLS certificate, TEE attestation, or public key. If any of these change, the node marks the peer as disconnected to force a reconnection. If the peer is new, the node creates a new peer entry. + +**Peer Removal** +The node removes any peers from its local state that are no longer present in the BuilderHub peer list, ensuring it only maintains connections to active network participants. + +**Connection Establishment** +For each peer in the updated list, the node attempts to establish a TLS connection if the peer is not already connected. Before connecting, the node verifies the peer's TLS certificate is valid and not expired, and that the peer's TEE attestation is recent and properly signed. If verification fails, the connection attempt is logged and skipped. + +**Synchronization Timing** +Protocol synchronization occurs every 5 minutes to balance network overhead with keeping peer information current. Failed synchronization attempts are logged but do not prevent the node from continuing operation with its existing peer connections. + +**Parameter Update Detection** +During protocol synchronization, nodes check for network parameter updates by querying BuilderHub for the latest genesis and network configuration versions. If updates are detected, nodes initiate the update process according to the network's update coordination procedures. + +**Update Application** +When network parameter updates are detected, nodes apply the updates in the following order: +1. **Genesis Updates**: Core network parameters are updated first to ensure network-wide consistency +2. **Configuration Updates**: Network-wide settings are applied to align with the updated parameters +3. **Service Restart**: Critical services are restarted to apply the new configuration +4. **Validation**: The node validates that all updates have been applied correctly before resuming normal operation + +## Block Building + +### Block Production Process + +**Relay Subscription Management** +The bidding service maintains active subscriptions to all supported relays defined in the genesis object. This includes establishing connections, handling subscription timeouts, and managing reconnection logic according to network configuration parameters. + +**Orderflow Retrieval** +The block production process begins by retrieving suitable orderflow entries for the target block number. The system filters orderflow by timeout and block suitability criteria. If no suitable orderflow is available, block production is skipped. + +**Block Building** +Using the rbuilder software, the node constructs a block from the available orderflow. The rbuilder implements the Flat Tax Rule for refund calculations and handles the complex logic of transaction ordering and gas optimization. + +**Bid Submission** +The bidding service calculates the optimal bid value based on the MEV available in the block and submits the bid to all subscribed MEV-Boost relays. This ensures maximum coverage of the blockspace auction market. + +**Block Submission** +The completed block is submitted to the MEV-Boost relay through the relay interface. The block includes all transactions and the calculated MEV value. The relay handles the auction process and proposer payment distribution. + +**State Recording** +Upon successful block production, the node records the block details including hash, number, and MEV value in its state. This information is used for refund calculations and performance monitoring. + +**Refund Processing** +After block production, the system calculates refunds using the Flat Tax Rule and processes them through the refund mechanism. + +### Block Submission + +**Relay Communication** +Blocks are submitted to MEV-Boost relays through a dedicated relay interface. The submission includes the complete block data, transaction list, and MEV calculations. The relay handles the auction process and determines the winning bid. + +**Auction Participation** +The relay interface manages the bidding process and handles proposer payment distribution. The node does not directly participate in the auction but provides the block content for relay evaluation. + +## Refund Processing + +### Refund Calculation + +**Flat Tax Rule Implementation** +Refund calculations are performed using the Flat Tax Rule implemented in the rbuilder software. The calculation takes into account the block's transactions, total MEV value, and proposer payment. The rbuilder handles the complex logic of determining each transaction's contribution to the overall MEV and calculating the appropriate refund amount. + +**Refund Computation** +The system extracts block details including all transactions, the total MEV value, and the proposer payment amount. These values are passed to rbuilder's refund calculation function which implements the Flat Tax Rule algorithm to determine refund amounts for each transaction contributor. + +### Refund Distribution + +**Refund Processing** +For each pending refund, the system attempts to send a refund transaction. The refund status is updated based on the success or failure of the transaction. Successful refunds are marked as processed and include the transaction hash, while failed refunds are marked as failed for retry. + +**Transaction Creation** +Refund transactions are created and sent from the official BuilderNet refund wallet address (0x62A29205f7Ff00F4233d9779c210150787638E7f). The transaction includes the calculated refund amount and is sent to the recipient address specified in the refund entry. + +**State Management** +All refund entries are added to the node's pending refunds list for tracking and monitoring purposes. This allows the system to maintain a complete record of all refund transactions and their current status. + +## Operation + +### Operator API + +The Operator API provides a basic interface for operators to interact with the BuilderNet node. It allows operators to observe the node's status, restart services, trigger a graceful reboot, and apply configuration changes. + +**Port**: 3535 (HTTPS with TLS) + +**Authentication**: HTTP Basic Auth + +**Security**: +- Designed to be used by the operator only +- Port should be firewalled to restrict public access +- Supports TLS for secure communication + +**API Endpoints** +The Operator API supports the following endpoints: +- `/api/v1/set-basic-auth` - Set basic authentication secret +- `/logs` - Retrieve system logs +- `/livez` - Health check endpoint +- `/api/v1/actions/rbuilder_restart` - Restart rbuilder service +- `/api/v1/actions/rbuilder_bidding_restart` - Restart bidding service +- `/api/v1/actions/fetch_config` - Refresh configuration +- `/api/v1/actions/ssh_stop` - Stop SSH service +- `/api/v1/actions/ssh_start` - Start SSH service +- `/api/v1/file-upload/rbuilder_blocklist` - Upload blocklist file + +**Basic Auth Management** +The operator can set a basic authentication secret for the API. This secret is used to authenticate all API requests. The secret is stored securely within the TEE and cannot be accessed by the operator. + +**Health Monitoring** +The health check endpoint returns the current status of the node. It verifies that all core services are running and responsive. A successful health check indicates the node is operational. + +**Service Management** +Operators can restart specific services through the API. Valid services include rbuilder, rbuilder_bidding, fetch_config, and ssh. Service restarts are logged and monitored for any failures. + +**Configuration Management** +Operators can upload configuration files to the node. Currently supported file types include rbuilder_blocklist. Files are validated before being applied to ensure they meet the required format and security constraints. + +**API Request Handling** +All API requests are validated for format, authentication, and authorization before processing. Requests are routed to appropriate handlers based on the endpoint. Invalid requests return error responses with specific error messages. + +### Logging and Monitoring + +**Log Delay Mechanism** +BuilderNet nodes implement a log delay mechanism to protect sensitive information. All logs are delayed by 300 seconds (5 minutes) before being made available to operators. This delay prevents operators from gaining real-time insights into orderflow processing and block building activities. + +**Log Content** +Logs contain operational information such as service status, connection events, and system metrics. Sensitive data including orderflow details, transaction contents, and MEV calculations are never logged. Log entries include timestamps, event types, and relevant identifiers without exposing confidential information. + +**Log Storage** +Logs are stored securely within the TEE environment. The log storage system implements rotation to prevent disk space issues. Old logs are automatically archived and can be retrieved through the Operator API. + +**Monitoring Metrics** +The node provides monitoring metrics through Prometheus endpoints. Metrics include system performance, network connectivity, and service health indicators. These metrics help operators monitor node performance without exposing sensitive operational details. + +**Alert System** +The node can generate alerts for critical events such as service failures, connection issues, or security violations. Alerts are sent through configured notification channels and include relevant diagnostic information while maintaining confidentiality. + +## Validation Rules + +### Node Validation + +**State and Configuration Validation** +Node validation ensures that the node's state, genesis object, network configuration, and operator configuration are consistent and valid. The system checks that the node state is properly formatted and that all configuration objects contain required parameters with valid values. + +**Genesis Validation** +The BuilderNet Genesis object is validated to ensure it contains the correct network parameters and TEE measurements. The node's TEE measurements must match those specified in the genesis object for the node to be considered valid. + +**Network Configuration Validation** +The network configuration is validated to ensure it matches the network-wide parameters defined in the genesis object. This includes verification that the node is configured to support all required relays and use the correct network-wide settings. + +**Parameter Update Validation** +When network parameter updates are received, the system validates the updates before application: +- **Version Compatibility**: Updates are checked for compatibility with the current node software version +- **Parameter Integrity**: Update signatures and hashes are verified to ensure authenticity +- **Impact Assessment**: The system evaluates the potential impact of updates on node operation +- **Rollback Capability**: Updates are validated to ensure they can be rolled back if necessary + +**Temporal Validation** +The node's startup time must not be in the future, ensuring that the node has been properly initialized. This prevents issues with time-based operations and state management. + +**TEE Environment Validation** +The TEE interface is validated to ensure it is properly initialized and functioning. This includes verification of the TEE attestation and measurement values against the genesis object to ensure the secure environment is intact. + +### Orderflow Validation + +**Transaction Parameter Validation** +Orderflow entries must have valid gas prices and gas limits greater than zero. These parameters are essential for transaction execution and must be properly set. + +**Temporal Validation** +The orderflow entry timestamp must not be in the future. This prevents processing of transactions with invalid timing that could cause issues in block building. + +**Source Validation** +The orderflow source must be one of the valid types: user, searcher, flashbots, or peer. This ensures that all orderflow comes from authorized sources and prevents processing of invalid data. + +### Block Validation + +**Block Structure Validation** +Produced blocks must have a valid block number greater than zero and contain at least one transaction. Empty blocks are not allowed in the BuilderNet system. + +**Temporal Validation** +The block timestamp must not be in the future, ensuring that blocks are produced with valid timing information. + +**MEV Validation** +The block's MEV value must be non-negative, as negative MEV values are not meaningful in the context of block building. + +**Transaction Validation** +All transactions within the block must pass orderflow validation to ensure they are properly formatted and contain valid parameters. + +### Operator API Validation + +**Request Timing Validation** +Operator API requests must have timestamps that are not in the future and not older than 5 minutes. This prevents replay attacks and ensures requests are processed in a timely manner. + +**Authentication Validation** +All Operator API requests must include basic authentication credentials. This ensures that only authorized operators can access the management interface. + +**Endpoint Validation** +Requests must target valid API endpoints. The system maintains a whitelist of allowed endpoints including authentication management, log retrieval, health checks, service management, and file uploads. Invalid endpoints are rejected to prevent unauthorized access attempts. + +## Notes + +1. **TEE Integration**: All sensitive operations are performed within TEE instances, with orderflow remaining confidential. + +2. **rbuilder Software**: The core block building logic is implemented in the open-source rbuilder software. + +3. **Flat Tax Rule**: Refunds are calculated using the Flat Tax Rule implemented in rbuilder. + +4. **Refund Wallet**: All refunds are sent from the official BuilderNet refund wallet address. + +5. **Service Architecture**: The node consists of multiple services running within the TEE environment. + +6. **Operator API**: Provides limited but useful information for operators without exposing sensitive data. + +7. **Ethereum Clients**: The specification uses generic consensus and execution layer clients, allowing for different implementations. + +8. **TEE Integrity Guarantees**: Orderflow processing is built on TEE integrity guarantees ensuring confidentiality, integrity, and isolation. + +9. **Best-Effort Propagation**: Orderflow sharing with peers is best-effort and not guaranteed to succeed. + +10. **Network vs Operator Configuration**: Network configuration contains mandatory parameters that all nodes must participate in, while operator configuration contains optional settings that operators can choose to enable or configure. + +11. **Relay Subscription**: All nodes must subscribe to the same set of relays defined in the genesis object to ensure consistent network participation. + +12. **Network Parameter Updates**: Network parameters can be updated through a governance process with coordinated rollout across all nodes to maintain network consistency. + +13. **TODO**: Implement complete rbuilder JSON-RPC integration. + +14. **TODO**: Add support for different TEE types and attestation providers. + +15. **TODO**: Implement proper refund transaction creation and submission. + +16. **TODO**: Add support for different orderflow sources and their specific handling. + +17. **TODO**: Implement proper error handling and recovery mechanisms. + +18. **TODO**: Add support for different Operator API actions and file uploads. + +19. **TODO**: Add Flashbots forum link for detailed explanation of best-effort propagation guarantees. \ No newline at end of file diff --git a/specs/Flashtestations.md b/specs/Flashtestations.md new file mode 100644 index 0000000..98364c8 --- /dev/null +++ b/specs/Flashtestations.md @@ -0,0 +1,3 @@ +# BuilderNet Flashtestations + +Need to link to Flashtestation spec and then spell out differences and or how it is used. \ No newline at end of file diff --git a/specs/p2p_interface.md b/specs/p2p_interface.md new file mode 100644 index 0000000..06bc7a4 --- /dev/null +++ b/specs/p2p_interface.md @@ -0,0 +1,356 @@ +# BuilderNet P2P Interface + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Configuration](#configuration) +- [Data Structures](#data-structures) +- [Network Architecture](#network-architecture) +- [Communication Protocols](#communication-protocols) +- [API Endpoints](#api-endpoints) +- [Validation Rules](#validation-rules) +- [Notes](#notes) + + + +## Introduction + +This document defines the P2P communication protocols for BuilderNet nodes. BuilderNet nodes communicate with each other to share orderflow confidentially and coordinate through Flashbots infrastructure. The system prioritizes confidentiality and security through TEE-based communication. + +## Configuration + +### Constants + +| Name | Value | Unit | +|------|-------|------| +| `MAX_CHUNK_SIZE` | `1024 * 1024` | bytes | +| `MAX_REQUEST_SIZE` | `1024 * 1024` | bytes | +| `MAX_RESPONSE_SIZE` | `10 * 1024 * 1024` | bytes | +| `TLS_CERT_VALIDITY` | `24 * 60 * 60` | seconds (24 hours) | + +### Network Ports + +| Port | Protocol | Service | Use | +|------|----------|---------|-----| +| `5544` | HTTPS | HAProxy | Orderflow sharing between BuilderNet nodes | +| `7936` | HTTPS/aTLS | cvm-proxy | TEE-attested TLS certificate serving | +| `9000` | TCP/UDP | Lighthouse | Consensus network peering | +| `30303` | TCP | Reth | Execution network peering | + +### Timeouts + +| Name | Value | Unit | +|------|-------|------| +| `ORDERFLOW_SHARING_TIMEOUT` | `60` | seconds | +| `BUILDERHUB_TIMEOUT` | `30` | seconds | +| `TEE_ATTESTATION_TIMEOUT` | `30` | seconds | + +## Data Structures + +### Basic Types + +```python +# Node identifier (Bytes32) +NodeId = Bytes32 + +# TLS certificate (Bytes) +TlsCertificate = Bytes + +# TEE attestation data (Bytes) +TeeAttestation = Bytes + +# Timestamp (uint64) +Timestamp = uint64 + +# Address (Bytes20) +Address = Bytes20 + +# Transaction hash (Bytes32) +TxHash = Bytes32 +``` + +### Orderflow Sharing Types + +```python +@dataclass +class OrderflowShareRequest: + source_node: NodeId + orderflow: List[OrderflowEntry] + target_block: BlockNumber + timestamp: Timestamp + signature: Bytes # Node signature +``` + +```python +@dataclass +class OrderflowShareResponse: + success: boolean + error: Optional[str] + timestamp: Timestamp +``` + +### TEE Attestation Types + +```python +@dataclass +class TeeAttestationRequest: + node_id: NodeId + tee_measurement: Bytes + ip_address: str + timestamp: Timestamp +``` + +```python +@dataclass +class TeeAttestationResponse: + node_id: NodeId + tls_certificate: TlsCertificate + tee_attestation: TeeAttestation + peer_list: List[PeerInfo] + configuration: BuilderHubConfig + timestamp: Timestamp +``` + +## Network Architecture + +### BuilderNet Node-to-Node Communication + +BuilderNet nodes communicate with each other through: + +1. **Node-to-Node HTTPS (Port 5544)**: For confidential orderflow sharing between BuilderNet nodes +2. **TEE-Attested Channel (Port 7936)**: For serving TLS certificates with TEE attestation + +### Flashbots Infrastructure Integration + +BuilderNet nodes integrate with Flashbots infrastructure through: + +1. **BuilderHub**: For secrets, configuration, and peer discovery +2. **Redistribution Archive**: For storing bid and orderflow data +3. **Identity Management**: For node identity verification +4. **Bidding Coordination**: For coordinating bids across nodes + +## Communication Protocols + +### Orderflow Sharing Protocol + +**Purpose**: Share orderflow confidentially between BuilderNet nodes. + +**Communication**: HTTPS on port 5544 + +**Request Format**: +```json +{ + "source_node": "0x...", + "orderflow": [ + { + "tx_hash": "0x...", + "gas_price": "0x...", + "gas_limit": "0x...", + "sender": "0x...", + "recipient": "0x...", + "value": "0x...", + "data": "0x...", + "timestamp": 1234567890, + "source": "peer", + "bundle_id": "0x..." + } + ], + "target_block": "0x...", + "timestamp": 1234567890, + "signature": "0x..." +} +``` + +**Response Format**: +```json +{ + "success": true, + "error": null, + "timestamp": 1234567890 +} +``` + +**Security**: +- Each node has its own TLS certificate +- Orderflow never leaves TEE instances +- No operator access to orderflow data +- Node signatures verify authenticity + +### TEE Attestation Protocol + +**Purpose**: Verify TEE environment and obtain attested TLS certificates. + +**Request**: HTTPS GET to `/cert` endpoint on port 7936 + +**Response**: TLS certificate with TEE attestation + +**Validation**: +- Verify TEE measurements match expected values +- Validate attestation signature +- Check certificate validity + +**Example**: +```bash +attested-get \ + --addr=https://direct-us.buildernet.org:7936/cert \ + --expected-measurements=https://measurements.buildernet.org \ + --out-response=builder-cert.pem +``` + +### Peer Discovery Protocol + +**Purpose**: Discover and verify other BuilderNet nodes. + +**Communication**: Via BuilderHub infrastructure + +**Process**: +1. Node A requests peer list from BuilderHub +2. BuilderHub returns list of verified BuilderNet nodes +3. Node A establishes connections with peers +4. Nodes exchange TEE attestations for verification + +## API Endpoints + +### Orderflow Sharing Endpoints + +```python +# Share orderflow with peer node +POST /orderflow/share (port 5544) +Content-Type: application/json + +{ + "source_node": "0x...", + "orderflow": [...], + "target_block": "0x...", + "timestamp": 1234567890, + "signature": "0x..." +} +``` + +### TEE Attestation Endpoints + +```python +# Get attested TLS certificate +GET /cert (port 7936) +# Returns TLS certificate with TEE attestation +``` + +## Validation Rules + +### Orderflow Sharing Validation + +```python +def is_valid_orderflow_share_request(request: OrderflowShareRequest) -> boolean: + """ + Validate an orderflow sharing request. + """ + if request.timestamp > get_current_time(): + return False + + if request.timestamp < get_current_time() - 300: # 5 minutes ago + return False + + if len(request.orderflow) == 0: + return False + + # Validate all orderflow entries + for entry in request.orderflow: + if not is_valid_orderflow_entry(entry): + return False + + # TODO: Verify node signature + # TODO: Verify source node is authorized + + return True +``` + +```python +def is_valid_orderflow_entry(entry: OrderflowEntry) -> boolean: + """ + Validate an orderflow entry. + """ + if entry.gas_price == 0: + return False + + if entry.gas_limit == 0: + return False + + if entry.timestamp > get_current_time(): + return False + + # Check source is valid for P2P sharing + if entry.source not in ["peer", "flashbots"]: + return False + + return True +``` + +### TEE Attestation Validation + +```python +def is_valid_tee_attestation(response: TeeAttestationResponse) -> boolean: + """ + Validate TEE attestation response. + """ + if response.timestamp > get_current_time(): + return False + + if len(response.tls_certificate) == 0: + return False + + if len(response.tee_attestation) == 0: + return False + + # TODO: Verify TEE attestation signature + # TODO: Validate TLS certificate against attestation + + return True +``` + +### Peer Validation + +```python +def is_valid_peer(peer: PeerInfo) -> boolean: + """ + Validate peer information. + """ + if peer.timestamp > get_current_time(): + return False + + if len(peer.tls_certificate) == 0: + return False + + if len(peer.tee_attestation) == 0: + return False + + # TODO: Verify peer TEE attestation + # TODO: Validate peer TLS certificate + + return True +``` + +## Notes + +1. **TEE Confidentiality**: All sensitive orderflow data remains within TEE instances and is never exposed to operators. + +2. **TLS Certificates**: Each BuilderNet node generates its own TLS certificate for secure communication. + +3. **Attested Communication**: The aTLS protocol provides verifiable TEE attestation for certificate validation. + +4. **Flashbots Integration**: BuilderHub provides centralized coordination while maintaining decentralization through TEE-based execution. + +5. **Node-to-Node Only**: This interface is specifically for communication between BuilderNet nodes, not for end-user interactions. + +6. **TODO**: Implement complete TEE attestation verification logic. + +7. **TODO**: Add support for different TEE types (SGX, TDX, etc.). + +8. **TODO**: Implement proper node signature verification. + +9. **TODO**: Add support for different orderflow sources and their specific validation rules. + +10. **TODO**: Implement proper error handling and retry mechanisms for network failures. \ No newline at end of file diff --git a/specs/protocol_state.md b/specs/protocol_state.md new file mode 100644 index 0000000..576f2cc --- /dev/null +++ b/specs/protocol_state.md @@ -0,0 +1,388 @@ +# BuilderNet Protocol State + +## Table of contents + + + + + +- [Introduction](#introduction) +- [Configuration](#configuration) +- [Data Structures](#data-structures) +- [State Transitions](#state-transitions) +- [Validation Rules](#validation-rules) +- [Notes](#notes) + + + +## Introduction + +This document defines the persistent state maintained by BuilderNet nodes. BuilderNet is a decentralized block building network where nodes run in Trusted Execution Environments (TEEs), share orderflow confidentially, and coordinate through Flashbots infrastructure. + +## Configuration + +### Constants + +| Name | Value | Unit | +|------|-------|------| +| `SLOTS_PER_EPOCH` | `32` | slots | +| `SECONDS_PER_SLOT` | `12` | seconds | +| `MAX_ORDERFLOW_ENTRIES` | `10000` | entries | +| `REFUND_WALLET_ADDRESS` | `0x62A29205f7Ff00F4233d9779c210150787638E7f` | address | + +### Timeouts + +| Name | Value | Unit | +|------|-------|------| +| `ORDERFLOW_TIMEOUT` | `60` | seconds | +| `BIDDING_TIMEOUT` | `10` | seconds | +| `BUILDERHUB_TIMEOUT` | `30` | seconds | + +## Data Structures + +### Basic Types + +```python +# Slot number (uint64) +Slot = uint64 + +# Block number (uint64) +BlockNumber = uint64 + +# Block hash (Bytes32) +BlockHash = Bytes32 + +# Node identifier (Bytes32) +NodeId = Bytes32 + +# Transaction hash (Bytes32) +TxHash = Bytes32 + +# MEV value in wei (uint256) +MevValue = uint256 + +# Gas price in wei (uint256) +GasPrice = uint256 + +# TEE attestation data (Bytes) +TeeAttestation = Bytes + +# TLS certificate (Bytes) +TlsCertificate = Bytes +``` + +### Orderflow Types + +```python +@dataclass +class OrderflowEntry: + tx_hash: TxHash + gas_price: GasPrice + gas_limit: uint64 + sender: Address + recipient: Address + value: uint256 + data: Bytes + timestamp: uint64 + source: OrderflowSource # "user", "searcher", "flashbots", "peer" + bundle_id: Optional[Bytes32] # For bundle transactions +``` + +```python +@dataclass +class Bundle: + transactions: List[OrderflowEntry] + bundle_hash: Bytes32 + target_block: BlockNumber + min_timestamp: uint64 + max_timestamp: uint64 + refund_recipient: Address + signer: Address +``` + +### Refund Types + +```python +@dataclass +class RefundEntry: + recipient: Address + amount: uint256 + transaction_hash: TxHash + block_number: BlockNumber + contribution: uint256 # Marginal contribution to block value + timestamp: uint64 + status: RefundStatus # "PENDING", "PROCESSED", "FAILED" +``` + +```python +class RefundStatus(Enum): + PENDING = 0 + PROCESSED = 1 + FAILED = 2 +``` + +### Network Types + +```python +@dataclass +class PeerInfo: + node_id: NodeId + address: str # IP:port + tls_certificate: TlsCertificate + tee_attestation: TeeAttestation + last_seen: uint64 + is_connected: boolean + orderflow_count: uint64 + blocks_produced: uint64 +``` + +```python +@dataclass +class BuilderHubConfig: + builder_hub_url: str + redistribution_archive_url: str + peer_discovery_url: str + identity_management_url: str + secrets_endpoint: str + configuration_endpoint: str +``` + +## State Transitions + +### BuilderNodeState + +```python +@dataclass +class BuilderNodeState: + # Current slot and block information + current_slot: Slot + head_block: BlockHash + head_block_number: BlockNumber + + # Network peers (other BuilderNet nodes) + peers: List[PeerInfo] + + # Orderflow management + pending_orderflow: List[OrderflowEntry] + processed_orderflow: List[OrderflowEntry] + orderflow_timeout: uint64 + + # Block building state + current_building_block: Optional[BlockNumber] + building_orderflow: List[OrderflowEntry] + + # Refund tracking + pending_refunds: List[RefundEntry] + processed_refunds: List[RefundEntry] + + # Node identity and configuration + node_id: NodeId + operator_address: Address + tee_attestation: TeeAttestation + tls_certificate: TlsCertificate + + # Flashbots infrastructure configuration + builder_hub_config: BuilderHubConfig + + # Statistics + total_blocks_produced: uint64 + total_mev_captured: MevValue + total_refunds_distributed: MevValue + + # Timestamps + last_update: uint64 + startup_time: uint64 +``` + +### State Update Functions + +```python +def update_slot(state: BuilderNodeState, new_slot: Slot) -> None: + """ + Update the current slot and perform slot-based state transitions. + """ + if new_slot > state.current_slot: + state.current_slot = new_slot + state.last_update = get_current_time() + + # Clear expired orderflow + current_time = get_current_time() + state.pending_orderflow = [ + entry for entry in state.pending_orderflow + if current_time - entry.timestamp < state.orderflow_timeout + ] +``` + +```python +def add_orderflow(state: BuilderNodeState, entry: OrderflowEntry) -> None: + """ + Add new orderflow to the pending queue. + """ + if len(state.pending_orderflow) < MAX_ORDERFLOW_ENTRIES: + state.pending_orderflow.append(entry) + else: + # Remove oldest entry if at capacity + state.pending_orderflow.pop(0) + state.pending_orderflow.append(entry) +``` + +```python +def share_orderflow_with_peers(state: BuilderNodeState, orderflow: List[OrderflowEntry]) -> None: + """ + Share orderflow with other BuilderNet nodes. + """ + # Orderflow is shared confidentially with other TEE instances + # via port 5544 using locally generated TLS certificates + for peer in state.peers: + if peer.is_connected: + # TODO: Implement confidential orderflow sharing + pass +``` + +```python +def record_block_production(state: BuilderNodeState, block_hash: BlockHash, + block_number: BlockNumber, mev_value: MevValue) -> None: + """ + Record successful block production and update statistics. + """ + state.head_block = block_hash + state.head_block_number = block_number + state.total_blocks_produced += 1 + state.total_mev_captured += mev_value + state.last_update = get_current_time() +``` + +```python +def calculate_refunds(state: BuilderNodeState, block_transactions: List[OrderflowEntry], + total_mev: MevValue, proposer_payment: MevValue) -> List[RefundEntry]: + """ + Calculate refunds using the Flat Tax Rule. + """ + refunds = [] + remainder = total_mev - proposer_payment + + if remainder <= 0: + return refunds + + # Group transactions by signer identity + signer_groups = group_transactions_by_signer(block_transactions) + + for signer, transactions in signer_groups.items(): + # Calculate marginal contribution + contribution = calculate_marginal_contribution(transactions, block_transactions, total_mev) + + # Calculate refund using Flat Tax Rule + refund_amount = calculate_flat_tax_refund(contribution, remainder, signer_groups) + + if refund_amount > 0: + refund_entry = RefundEntry( + recipient=signer, + amount=refund_amount, + transaction_hash=b"", # Will be set when processed + block_number=state.head_block_number, + contribution=contribution, + timestamp=get_current_time(), + status=RefundStatus.PENDING + ) + refunds.append(refund_entry) + + return refunds +``` + +## Validation Rules + +### State Validation + +```python +def is_valid_state(state: BuilderNodeState) -> boolean: + """ + Validate the BuilderNodeState structure and invariants. + """ + # Check basic type constraints + if state.current_slot < 0: + return False + + if len(state.pending_orderflow) > MAX_ORDERFLOW_ENTRIES: + return False + + # Check timestamp consistency + current_time = get_current_time() + if state.last_update > current_time: + return False + + if state.startup_time > current_time: + return False + + # Check refund wallet address + if state.builder_hub_config is None: + return False + + return True +``` + +### Orderflow Validation + +```python +def is_valid_orderflow_entry(entry: OrderflowEntry) -> boolean: + """ + Validate an orderflow entry. + """ + if entry.gas_price == 0: + return False + + if entry.gas_limit == 0: + return False + + if entry.timestamp > get_current_time(): + return False + + # Check source is valid + if entry.source not in ["user", "searcher", "flashbots", "peer"]: + return False + + return True +``` + +### Refund Validation + +```python +def is_valid_refund(refund: RefundEntry) -> boolean: + """ + Validate a refund entry. + """ + if refund.amount == 0: + return False + + if refund.block_number == 0: + return False + + if refund.timestamp > get_current_time(): + return False + + if refund.status not in [RefundStatus.PENDING, RefundStatus.PROCESSED, RefundStatus.FAILED]: + return False + + return True +``` + +## Notes + +1. **TEE Integration**: All sensitive operations are performed within TEE instances, with orderflow remaining confidential. + +2. **Orderflow Sharing**: Orderflow is shared between BuilderNet nodes via port 5544 using locally generated TLS certificates. + +3. **Flashbots Infrastructure**: BuilderHub provides secrets, configuration, peer discovery, and identity management. + +4. **Refund Mechanism**: Uses the Flat Tax Rule to calculate refunds based on marginal contributions to block value. + +5. **Refund Wallet**: All refunds are sent from the official BuilderNet refund wallet address. + +6. **TLS Certificates**: Each node generates its own TLS certificate for secure communication. + +7. **TODO**: Implement the complete Flat Tax Rule calculation with identity constraints. + +8. **TODO**: Add support for bundle-specific refund calculations. + +9. **TODO**: Implement proper TEE attestation verification. + +10. **TODO**: Add support for different orderflow sources and their specific handling. \ No newline at end of file