# burninggasontheblock/ebrobridge architecture

> Architecture diagram of the GitHub repository burninggasontheblock/ebrobridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/burninggasontheblock/ebrobridge
- Repository: https://github.com/burninggasontheblock/ebrobridge

## Overview

##### Project Type & Purpose
- This project is a blockchain smart contract system focused on cross-chain token transfers.
- The primary purpose is to enable users to lock ERC-20 tokens on Ethereum (using SickBridgeETH) and then mint equivalent wrapped tokens on Polygon (using WrappedToken) ensuring secure transfers via nonce tracking and ECDSA signature verification.

##### Main Components
- Ethereum Network:
- SickBridgeETH Contract: Handles token locking. It interacts with an ERC-20 token through the transferFrom function, emits a TokensLocked event (including a unique nonce and a provided signature), and manages administrative control.
- Polygon Network:
- WrappedToken Contract: Handles token minting. This contract verifies an admin signature (via ECDSA) and checks that the nonce has not been reused before minting tokens to the user.

##### Relationships & Interactions
- When tokens are locked on the Ethereum network:
- The SickBridgeETH contract receives tokens from the user.
- It increments a nonce and emits a TokensLocked event containing the lock details (user, amount, nonce, and signature).
- An off-chain process (or admin tool) then processes the event, signs a message containing the transaction’s details, and, on the Polygon network, the WrappedToken contract is called.
- The WrappedToken contract verifies the signature and nonce before minting the wrapped tokens on Polygon, emitting a TokensMinted event afterward.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Each network runs its own dedicated smart contract for its specific role (locking vs. minting).
- Event-Driven Interaction: Events (TokensLocked and TokensMinted) drive the state change between networks.
- Security: Use of nonce management prevents replay attacks while ECDSA signature validation ensures that only authorized operations are performed.
- Dependency Management: The project leverages established libraries (OpenZeppelin for secure ERC-20 handling and ECDSA operations) ensuring correctness and security.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    User["User"]:::user

    %% Ethereum Network Subgraph
    subgraph "Ethereum Network"
        SickBridgeETH["SickBridgeETH Contract"]:::ethereum
        ERC20["ERC-20 Token Contract"]:::ethereum
    end

    %% Off-chain Process
    OffChain["Off-chain Signature Process/Administrator"]:::offchain

    %% Polygon Network Subgraph
    subgraph "Polygon Network"
        WrappedToken["WrappedToken Contract"]:::polygon
    end

    %% Data/Control Flows
    User -->|"locks_tokens"| SickBridgeETH
    SickBridgeETH -->|"transferFrom"| ERC20
    SickBridgeETH -->|"TokensLocked_event"| OffChain
    OffChain -->|"submits_lock_details"| WrappedToken
    WrappedToken -->|"TokensMinted_event"| User

    %% Annotations for security and technologies
    Note1["Note: Uses nonce_tracking & ECDSA_verification"]:::note
    Note2["Tech: Solidity, OpenZeppelin libraries"]:::note
    OffChain --- Note1
    OffChain --- Note2

    %% Click Events
    click SickBridgeETH "https://github.com/burninggasontheblock/ebrobridge/blob/main/artifacts/SickBridgeETH.json"
    click WrappedToken "https://github.com/burninggasontheblock/ebrobridge/blob/main/artifacts/WrappedToken.json"

    %% Styles
    classDef ethereum fill:#aec6cf,stroke:#333,stroke-width:2px;
    classDef polygon fill:#77dd77,stroke:#333,stroke-width:2px;
    classDef offchain fill:#fdfd96,stroke:#333,stroke-width:2px;
    classDef user fill:#ffb347,stroke:#333,stroke-width:2px;
    classDef note fill:#d3d3d3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
