BaseGame: Cross-Chain Bridge Event Listener Simulation

This repository contains a Python script that simulates the behavior of a validator or oracle node for a cross-chain bridge. It listens for specific events on a source blockchain, waits for transaction finality, and then simulates the corresponding action on a destination blockchain.

This project is designed as an architectural showcase, demonstrating principles of modular design, error handling, and state management in a decentralized context. It is not a production-ready bridge component but a comprehensive simulation.

Concept

A cross-chain bridge allows users to transfer assets or data from one blockchain (e.g., Ethereum) to another (e.g., Polygon). A common mechanism for this is "lock-and-mint":

1. Lock/Deposit: A user deposits tokens into a smart contract on the source chain. This action emits an event (e.g., TokensDeposited).
2. Validation: A network of off-chain nodes (listeners, validators, or oracles) listens for this event.
3. Confirmation: The nodes wait for several blocks to be mined on top of the transaction block to ensure it's final and not part of a chain reorganization (re-org).
4. Mint/Release: Once confirmed, the nodes submit a transaction to a smart contract on the destination chain, authorizing the minting or release of equivalent wrapped tokens to the user's address.

This script simulates the role of one such off-chain validator node (Step 2, 3, and 4).

Code Architecture

The script is structured into several distinct classes, each with a clear responsibility, to ensure modularity and maintainability.

• BlockchainConnector:

  • Responsibility: Manages the connection to a single blockchain via a Web3 RPC endpoint.
  • Key Methods: connect(), is_connected(), get_latest_block().
  • Purpose: Abstracts away the low-level connection logic, making it reusable for both the source and destination chains.

• CrossChainTransaction:

  • Responsibility: Acts as a data container for a single cross-chain transfer.
  • Attributes: Stores all relevant information from the deposit event, such as sender, recipient, amount, and its current status (e.g., PENDING_CONFIRMATION, COMPLETED, FAILED).
  • Purpose: Provides a structured way to manage the state of each transfer as it moves through the pipeline.

• BridgeListenerService (main class, inherits from threading.Thread):

  • Responsibility: The core orchestrator of the application.
  • Key Logic: Contains the main processing loop that:
    1. Fetches new deposit events from the source chain.
    2. Manages a queue of CrossChainTransaction objects.
    3. Processes pending transactions by checking for finality.
    4. Triggers the simulated minting process on the destination chain.
  • Purpose: Acts as the entry point and control center, tying all other components together.

How it Works

The listener operates in a continuous cycle, orchestrated by the BridgeListenerService:

1. Initialization: Upon starting, the service initializes BlockchainConnector instances for both the source and destination chains. It uses RPC URLs provided in a .env file.

2. Event Polling: In its main loop, the service uses a Web3 filter to poll the source chain's bridge contract for new TokensDeposited events. To prevent duplicate processing, it keeps track of processed transaction nonces.

3. State Management: When a new event is detected, it is encapsulated in a CrossChainTransaction object with an initial status of PENDING_CONFIRMATION. This object is added to a pending transactions dictionary.

4. Confirmation Check: For each pending transaction, the service compares the transaction's block number with the latest block number on the source chain. If the difference is greater than or equal to a configured threshold (confirmation_blocks), the transaction is considered final, and its status is updated to CONFIRMED_SOURCE.

5. Simulated Submission: Once a transaction is confirmed, the service calls the _simulate_mint_on_destination method. This method does not send a real transaction but logs the actions that a real validator would take. It includes logic to simulate network failures and retries, demonstrating resilience.

6. Lifecycle Completion: After a successful simulated submission, the transaction's status is set to COMPLETED. If it fails after multiple retries, it is marked as FAILED. Completed and failed transactions are then removed from the pending queue to free up memory.

7. Graceful Shutdown: The service can be stopped gracefully, allowing the main loop to finish its current cycle before exiting.

Usage Example

Follow these steps to run the simulation.

1. Project Setup

Clone the repository and navigate into the project directory.

git clone https://github.com/your-username/basegame.git
cd basegame

2. Create an Environment File

Create a .env file in the root of the project. This file will store your blockchain RPC URLs. You can get these from services like Infura, Alchemy, or public providers.

File: .env

# RPC URL for the source chain (e.g., Ethereum Sepolia Testnet)
SOURCE_CHAIN_RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_PROJECT_ID

# RPC URL for the destination chain (e.g., Polygon Mumbai Testnet)
DESTINATION_CHAIN_RPC_URL=https://polygon-mumbai.infura.io/v3/YOUR_INFURA_PROJECT_ID

3. Install Dependencies

Install the required Python libraries using the requirements.txt file.

pip install -r requirements.txt

4. Run the Script

Execute the main Python script from your terminal.

python bridge_listener.py

The script will start, connect to the specified chains, and begin polling for events. Since the contract addresses are placeholders, it will not find any real events. However, it will continuously log its status, demonstrating that the polling mechanism is active.

Example Output:

2023-10-27 10:30:00,123 - INFO - [MainThread] - Successfully connected to SourceChain (Sepolia) at https://rpc.sepolia.org
2023-10-27 10:30:01,456 - INFO - [MainThread] - Successfully connected to DestinationChain (Mumbai) at https://rpc-mumbai.maticvigil.com
2023-10-27 10:30:01,457 - INFO - [BridgeListenerThread] - Starting Bridge Listener Service. Polling every 15 seconds.
2023-10-27 10:30:01,457 - DEBUG - [BridgeListenerThread] - Starting new processing cycle...
2023-10-27 10:30:03,812 - DEBUG - [BridgeListenerThread] - Processing cycle finished.
2023-10-27 10:30:18,815 - DEBUG - [BridgeListenerThread] - Starting new processing cycle...
2023-10-27 10:30:20,111 - DEBUG - [BridgeListenerThread] - Processing cycle finished.
...