# fuellabs/fuel-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/fuellabs/fuel-bridge
- Repository: https://github.com/fuellabs/fuel-bridge

## Overview

##### Main Components

a. Layer 1 (Ethereum) Components:
- FuelMessagePortal
- FuelChainState
- ERC20Gateway
- ERC721Gateway
- Solidity Contracts Infrastructure

b. Layer 2 (Fuel) Components:
- Bridge Fungible Token Contract
- Message Predicates
- Base Asset Handler
- Contract Message Receiver

c. Bridge Infrastructure:
- Message Passing System
- Block Committer
- Verification Layer

- Ethereum     | <-> |  Bridge Layer   | <-> |    Fuel      |
- (L1)       |     |                 |     |    (L2)       |

##### Key Relationships to Highlight

a. Message Flow:
- Verification paths through the bridge layer
- Token locking/unlocking mechanisms

b. Contract Interactions:
- Related contracts with appropriate relationship lines
- Inheritance and dependency relationships
- Access control flows

##### Detailed Component Breakdown

**L1 (Ethereum) Side:**

- FuelMessagePortal      |
- Message Verification |
- State Management    |

- Gateway Contracts      |
- ERC20               |
- ERC721              |

**Bridge Layer:**

- Message Predicates     |
- Block Committer       |
- Verification Logic    |

**L2 (Fuel) Side:**

- Bridge Contracts       |
- Token Implementation |
- Message Handling    |

##### Additional Elements

Include:
- Version information for different components
- Security boundaries and trust assumptions
- Rate limiting and pause mechanism indicators
- Deployment environment distinctions (mainnet/testnet)

##### Technical Details to Note

- Relationship between fungible and non-fungible token bridges
- Message verification paths
- State synchronization mechanisms
- Upgrade proxy patterns where applicable

##### Special Focus Areas

Emphasize:
- Security checkpoints
- Cross-chain message verification
- Asset locking and unlocking mechanisms
- State consistency maintenance

##### Documentation Integration

References to:
- Architecture documentation
- Deployment configurations
- Testing infrastructure
- Monitoring systems

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph L1[Ethereum Layer 1]
        direction TB
        FMP[FuelMessagePortal]:::portal
        FCS[FuelChainState]:::state
        E20G[ERC20Gateway]:::gateway
        E721G[ERC721Gateway]:::gateway
        SC[Solidity Contracts]:::contracts
    end

    subgraph BL[Bridge Layer]
        direction TB
        MP[Message Predicates]:::bridge
        BC[Block Committer]:::bridge
        VL[Verification Layer]:::security
    end

    subgraph L2[Fuel Layer 2]
        direction TB
        BFT[Bridge Fungible Token]:::token
        BAH[Base Asset Handler]:::handler
        CMR[Contract Message Receiver]:::receiver
    end

    %% Relationships
    FMP <--> MP
    FMP <--> BC
    FCS <--> BC
    E20G <--> BFT
    E721G <--> BFT
    MP <--> CMR
    BC <--> BAH
    VL <--> BAH
    VL <--> BFT

    %% Styling
    classDef portal fill:#6495ED
    classDef state fill:#4682B4
    classDef gateway fill:#98FB98
    classDef contracts fill:#87CEEB
    classDef bridge fill:#DDA0DD
    classDef security fill:#FF6B6B
    classDef token fill:#FFD700
    classDef handler fill:#F0E68C
    classDef receiver fill:#E6E6FA

    %% Click events
    click FMP "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/solidity-contracts/contracts/fuelchain/FuelMessagePortal/"
    click E20G "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/solidity-contracts/contracts/messaging/gateway/FuelERC20Gateway"
    click E721G "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/solidity-contracts/contracts/messaging/gateway/FuelERC721Gateway"
    click BFT "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/fungible-token/bridge-fungible-token/"
    click MP "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/message-predicates/"
    click CMR "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/message-predicates/contract-message-receiver/"
    click BC "https://github.com/FuelLabs/fuel-bridge/tree/main/docker/block-committer/"
    click BAH "https://github.com/FuelLabs/fuel-bridge/tree/main/packages/base-asset/"

    %% Legend
    subgraph Legend
        L1_C[L1 Components]:::portal
        BL_C[Bridge Layer]:::bridge
        L2_C[L2 Components]:::token
        SEC[Security Components]:::security
    end
```
