# across-protocol/contracts architecture

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

- Interactive diagram: https://gitdiagram.com/across-protocol/contracts
- Repository: https://github.com/across-protocol/contracts

## Overview

Based on our review of the file tree and the README, this project is a multi-chain smart contract system that implements the Across Protocol. Its core purpose is to enable instant token transfers between different blockchain networks. The design is built around a central HubPool contract deployed on Ethereum (which acts as the custodian of liquidity and the cross-chain administrator) and various SpokePool contracts deployed on the destination and source chains. In addition, there are several chain-specific adapters that serve as bridges for cross-chain interactions. The project also includes multiple deployment scripts, test suites, and even programs written in Rust/Anchor for other chains or environments (for example, for SVM handling).

##### Main Components
- Central HubPool Contract – This is the anchor of the entire system. It holds the cross-chain liquidity and controls administrative actions, including upgrades to the SpokePools.
- SpokePool Contracts – Deployed on every network that participates in cross-chain token transfer. They are upgradeable using the UUPS Proxy pattern, and their upgrades are administered by the HubPool.
- Chain-Specific Adapters – For each network (e.g., Arbitrum, Optimism, Polygon, etc.), adapter contracts (and related handler contracts, such as chain-adapters, ERC1155, and other specialized ones) bridge communications between the HubPool and the member SpokePools.
- Deployment & Upgrade Scripts – Located in the “deploy” directory and various “scripts” folders, these define how contracts are deployed, how upgrades (via cross-chain upgrade commands) are managed, and how storage layout validations, proofs, and tests are carried out.
- Off-Chain Clients & Testing Infrastructure – This includes the TypeScript-based code as well as EVM and SVM test suites. They interact with the contracts through web3 interfaces and command-line scripts to simulate cross-chain message relays and token transfers.

##### Interactions & Data Flow
- Chain-specific adapter components between the HubPool and SpokePools. Label these connectors with names such as “Arbitrum Adapter”, “Optimism Adapter”, “Polygon Adapter”, etc. These adapters essentially translate or relay messages across chains.
- Token deposit requests from users at the SpokePools that communicate to the HubPool.
- Upgrade commands from the HubPool to SpokePools using the UUPS proxy mechanism.
- Cross-chain message relays (representing the relaying of execution requests and upgrades).

##### Architectural Patterns and Technologies
- UUPS Upgradeable Pattern – Clearly mark the HubPool and every SpokePool as upgradeable proxy contracts that share a fixed address while their implementations change.
- Cross-Chain Design – Emphasize that the system is built as a “hub and spoke” architecture. The HubPool is centralized on Ethereum while the spokes (SpokePools) are deployed on different networks, managed via chain adapters.
- Multi-Language & Multi-Framework Stack – Note that Solidity is used for most contracts, while Rust and Anchor are employed in the “programs” directory for some of the off-chain or non-EVM computations (such as the multicall handler or SVM-spoke functionality). Also mention the use of TypeScript (in “scripts” and “src”) for deployment and utility functions, as well as testing (EVM and SVM tests).
- Deployment and CI Pipeline – Optionally include a small section or component for the deployment pipeline, noting that the GitHub workflows, Hardhat scripts, Foundry projects, and various deployment JSON artifacts (in “deployments”) orchestrate multi-network deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contract Layer
    subgraph "Smart Contracts"
        H["Ethereum HubPool"]:::contract
        OA["Optimism Adapter"]:::contract
        AA["Arbitrum Adapter"]:::contract
        EA["Ethereum Adapter"]:::contract
        SPO["Optimism SpokePool"]:::contract
        SPA["Arbitrum SpokePool"]:::contract
        SPE["Ethereum SpokePool"]:::contract
    end

    %% Deployment & Orchestration Layer
    subgraph "Deployment & Orchestration"
        DS["Deployment & Upgrade Scripts"]:::deployment
    end

    %% Off-Chain Testing & Client Interaction Layer
    subgraph "Off-Chain Testing & Clients"
        OT["Off-Chain Clients & Testing Infrastructure"]:::testing
    end

    %% Cross-Chain Upgrade and Messaging / Interactions
    H -->|"upgrade"| SPO
    H -->|"upgrade"| SPA
    H -->|"upgrade"| SPE

    H -->|"relay"| OA
    H -->|"relay"| AA
    H -->|"relay"| EA

    OA -->|"bridge"| SPO
    AA -->|"bridge"| SPA
    EA -->|"bridge"| SPE

    SPO -->|"deposit"| H
    SPA -->|"deposit"| H
    SPE -->|"deposit"| H

    %% Off-chain deployment and testing interactions
    DS -->|"deploy"| H
    DS -->|"deploy"| OA
    DS -->|"deploy"| AA
    DS -->|"deploy"| EA
    DS -->|"deploy"| SPO
    DS -->|"deploy"| SPA
    DS -->|"deploy"| SPE

    OT -->|"simulate"| H
    OT -->|"simulate"| SPO
    OT -->|"simulate"| SPA
    OT -->|"simulate"| SPE

    %% Click Events for Components
    click H "https://github.com/across-protocol/contracts/blob/master/contracts/upgradeable & deploy/001_deploy_hubpool.ts"
    click SPO "https://github.com/across-protocol/contracts/blob/master/deploy/003_deploy_optimism_spokepool.ts"
    click SPA "https://github.com/across-protocol/contracts/blob/master/deploy/005_deploy_arbitrum_spokepool.ts"
    click SPE "https://github.com/across-protocol/contracts/blob/master/deploy/007_deploy_ethereum_spokepool.ts"
    click OA "https://github.com/across-protocol/contracts/blob/master/deploy/002_deploy_optimism_adapter.ts"
    click AA "https://github.com/across-protocol/contracts/blob/master/deploy/004_deploy_arbitrum_adapter.ts"
    click EA "https://github.com/across-protocol/contracts/blob/master/deploy/006_deploy_ethereum_adapter.ts"
    click DS "https://github.com/across-protocol/contracts/tree/master/deploy"
    click OT "https://github.com/across-protocol/contracts/tree/master/src"

    %% Styles
    classDef contract fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef deployment fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef testing fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
