# whitechain-labs/bridge-contracts architecture

> Architecture diagram of the GitHub repository whitechain-labs/bridge-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/whitechain-labs/bridge-contracts
- Repository: https://github.com/whitechain-labs/bridge-contracts

## Overview

Whitechain Bridge is a cross-chain token and native-coin transfer system implemented by EVM smart contracts for Ethereum-compatible networks and Tron. The principal flow begins with a wallet request: a backend signs the operation, the origin-chain Bridge validates it against Mapper configuration and emits a deposit, then a backend relayer submits the target-chain withdrawal and records completion. Mapper administration supplies token/chain rules; the contracts also support lock/burn and unlock/mint handling, transfer limits, and upgradeability. The runtime contracts were not sampled, so contract-to-contract and event behavior here follows the README; backend and wallet are external systems.

Main entry points: [`ether/contracts/main/modules/bridge/Bridge.sol`](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/contracts/main/modules/bridge/Bridge.sol) (Ethereum Bridge), [`ether/scripts/modules/mapper/setup.ts`](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/mapper/setup.ts) (Ethereum mapping setup), [`tron/contracts/main/modules/bridge/Bridge.sol`](https://github.com/whitechain-labs/bridge-contracts/blob/main/tron/contracts/main/modules/bridge/Bridge.sol) (Tron Bridge), [`ether/scripts/modules/bridge/setup.ts`](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/bridge/setup.ts) (Ethereum limit setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Wallet and Services"]
  node_wallet_app["Whitechain Wallet"]
  node_bridge_backend["Bridge backend"]
  node_bridge_db[("Operation database")]
end

subgraph group_ethereum["Ethereum Contracts"]
  node_eth_bridge["Ethereum Bridge<br/>[Bridge.sol]"]
  node_eth_mapper["Ethereum Mapper<br/>[Mapper.sol]"]
end

subgraph group_tron["Tron Contracts"]
  node_tron_bridge["Tron Bridge<br/>[Bridge.sol]"]
  node_tron_mapper["Tron Mapper<br/>[Mapper.sol]"]
end

subgraph group_configuration["Mapping Administration"]
  node_mapper_admin(("Mapper administrator"))
  node_eth_mapper_setup["Ethereum mapping setup<br/>[setup.ts]"]
  node_eth_mapping_data["Ethereum mapping configuration<br/>[config.ts]"]
  node_eth_bridge_setup["Ethereum limit setup<br/>[setup.ts]"]
  node_eth_limit_data["Ethereum limit configuration<br/>[config.ts]"]
end

node_wallet(("Wallet user"))

node_wallet -->|"initiates transfer"| node_wallet_app
node_wallet_app -->|"requests signed message"| node_bridge_backend
node_bridge_backend -->|"returns signature"| node_wallet_app
node_wallet_app -->|"submits deposit"| node_eth_bridge
node_eth_bridge -->|"validates mapping"| node_eth_mapper
node_eth_bridge -->|"emits Deposit"| node_bridge_backend
node_bridge_backend -->|"stores operation"| node_bridge_db
node_bridge_backend -->|"submits withdrawal"| node_tron_bridge
node_tron_bridge -->|"emits Withdrawal"| node_bridge_backend
node_bridge_backend -->|"records completion"| node_bridge_db
node_mapper_admin -.->|"configures mappings"| node_eth_mapper_setup
node_eth_mapper_setup -->|"loads routes"| node_eth_mapping_data
node_eth_mapper_setup -->|"registers mappings"| node_eth_mapper
node_eth_bridge_setup -->|"loads limits"| node_eth_limit_data
node_eth_bridge_setup -->|"sets daily limits"| node_eth_bridge
node_mapper_admin -.->|"registers mappings"| node_tron_mapper
node_bridge_backend -.->|"submits withdrawal"| node_eth_bridge
node_eth_bridge -.->|"emits Withdrawal"| node_bridge_backend
node_bridge_backend -.->|"listens for events"| node_tron_bridge

click node_eth_bridge "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/contracts/main/modules/bridge/Bridge.sol"
click node_eth_mapper "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/contracts/main/modules/mapper/Mapper.sol"
click node_tron_bridge "https://github.com/whitechain-labs/bridge-contracts/blob/main/tron/contracts/main/modules/bridge/Bridge.sol"
click node_tron_mapper "https://github.com/whitechain-labs/bridge-contracts/blob/main/tron/contracts/main/modules/mapper/Mapper.sol"
click node_eth_mapper_setup "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/mapper/setup.ts"
click node_eth_mapping_data "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/mapper/utils/config.ts"
click node_eth_bridge_setup "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/bridge/setup.ts"
click node_eth_limit_data "https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/bridge/utils/config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wallet_app,node_bridge_backend,node_bridge_db,node_wallet toneBlue
class node_eth_bridge,node_eth_mapper toneAmber
class node_tron_bridge,node_tron_mapper toneMint
class node_mapper_admin,node_eth_mapper_setup,node_eth_mapping_data,node_eth_bridge_setup,node_eth_limit_data toneRose
```

## Components

### Wallet and Services

- **Whitechain Wallet**
- **Bridge backend**
- **Operation database**

### Ethereum Contracts

- [Ethereum Bridge](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/contracts/main/modules/bridge/Bridge.sol): `ether/contracts/main/modules/bridge/Bridge.sol`
- [Ethereum Mapper](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/contracts/main/modules/mapper/Mapper.sol): `ether/contracts/main/modules/mapper/Mapper.sol`

### Tron Contracts

- [Tron Bridge](https://github.com/whitechain-labs/bridge-contracts/blob/main/tron/contracts/main/modules/bridge/Bridge.sol): `tron/contracts/main/modules/bridge/Bridge.sol`
- [Tron Mapper](https://github.com/whitechain-labs/bridge-contracts/blob/main/tron/contracts/main/modules/mapper/Mapper.sol): `tron/contracts/main/modules/mapper/Mapper.sol`

### Mapping Administration

- **Mapper administrator**
- [Ethereum mapping setup](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/mapper/setup.ts): `ether/scripts/modules/mapper/setup.ts`
- [Ethereum mapping configuration](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/mapper/utils/config.ts): `ether/scripts/modules/mapper/utils/config.ts`
- [Ethereum limit setup](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/bridge/setup.ts): `ether/scripts/modules/bridge/setup.ts`
- [Ethereum limit configuration](https://github.com/whitechain-labs/bridge-contracts/blob/main/ether/scripts/modules/bridge/utils/config.ts): `ether/scripts/modules/bridge/utils/config.ts`

### Other components

- **Wallet user**

## Connections

- Wallet user → Whitechain Wallet: initiates transfer
- Whitechain Wallet → Bridge backend: requests signed message
- Bridge backend → Whitechain Wallet: returns signature
- Whitechain Wallet → Ethereum Bridge: submits deposit
- Ethereum Bridge → Ethereum Mapper: validates mapping
- Ethereum Bridge → Bridge backend: emits Deposit
- Bridge backend → Operation database: stores operation
- Bridge backend → Tron Bridge: submits withdrawal
- Tron Bridge → Bridge backend: emits Withdrawal
- Bridge backend → Operation database: records completion
- Mapper administrator → Ethereum mapping setup: configures mappings
- Ethereum mapping setup → Ethereum mapping configuration: loads routes (evidence: `ether/scripts/modules/mapper/setup.ts`)
- Ethereum mapping setup → Ethereum Mapper: registers mappings (evidence: `ether/scripts/modules/mapper/setup.ts`)
- Ethereum limit setup → Ethereum limit configuration: loads limits (evidence: `ether/scripts/modules/bridge/setup.ts`)
- Ethereum limit setup → Ethereum Bridge: sets daily limits (evidence: `ether/scripts/modules/bridge/setup.ts`)
- Mapper administrator → Tron Mapper: registers mappings
- Bridge backend → Ethereum Bridge: submits withdrawal
- Ethereum Bridge → Bridge backend: emits Withdrawal
- Bridge backend → Tron Bridge: listens for events
