# bbayazit16/l2savings architecture

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

- Interactive diagram: https://gitdiagram.com/bbayazit16/l2savings
- Repository: https://github.com/bbayazit16/l2savings

## Overview

This project is a Next.js web application focused on demonstrating Ethereum Layer 2 fee savings. Its purpose is to show how much users can save by comparing the fees paid on different L2 solutions with those that would have been incurred on Ethereum Mainnet. The project leverages React components, custom hooks, context providers, and a series of utility libraries to fetch and process blockchain data.

##### Main components
- Frontend/UI Layer: Represented by the Next.js app. This includes pages (e.g., src/app/page.tsx, src/app/faq/page.tsx) and React components (e.g., Navbar, Footer, SavingsBox, various Buttons) that build the user interface.
- State Management & Context Providers: Illustrated by the AccountProvider, ChosenL2Provider, and SavingsProvider (in src/app/providers). These components manage shared state and context for user accounts, chosen L2 chains, and savings calculations.
- Business Logic & Calculation Layer: Found in the lib directory. It includes modules that encapsulate the logic to fetch transaction data (e.g., customfetch, ethfees, gethBatchCustomReceipts) and perform the fee savings calculations. The l2 subdirectory (with different files like Arbitrum.ts, Base.ts, Optimism.ts, ZkSyncLite.ts) is key in isolating logic for each Layer 2 chain.
- Utility & Helper Functions: Other lib modules (like chainToAssetSrc.ts, constants.ts, chunk.ts, and truncateTransactionHash.ts) that support data manipulation and UI presentation.
- Styling & Configuration: Tailwind CSS and configuration files (tailwind.config.ts, postcss.config.js, next.config.js) that set up the presentation style and build environment.

##### Out the relationships and interactions
- The UI components (in src/app/components) interact directly with the context providers to obtain data such as user accounts, selected L2, and saving information.
- The providers wrap the application (as seen in src/app/providers/index.tsx) to enable state sharing, so hooks (like useAccount, useSavings, and useChosenL2) can be used by the components.
- Hooks invoke functions from the lib directory, which handle data fetching from external Ethereum and L2 RPC endpoints. These functions compute fees based on the chain-specific logic.
- External blockchain interaction occurs behind the scenes – the lib functions (especially in the l2 directory) use endpoints to query transaction receipts and fee histories.
- The custom fetch utilities and constants ensure that the calculations (for Optimism, Arbitrum, ZkSync Lite, Linea, and Base) adhere to blockchain-specific data structures and formulas.

##### Important architectural patterns
- Separation of Concerns: UI, state management, and business logic are clearly separated into distinct directories (components vs. providers vs. lib), which encourages modularity and easier maintenance.
- Context-Driven State Management: The use of providers and custom hooks demonstrates a pattern where state is centralized and shared across components.
- Chain-Specific Logic Modules: The use of separate files for each L2 (e.g., Arbitrum.ts, Base.ts) shows a plug-in-like approach that makes it easier to extend support for additional chains.
- Next.js Page Routing & Layout: The project uses Next.js conventions (with pages and app directories) to manage routing and global layouts.

##### External and internal technologies
- Frameworks/Libraries: Next.js, React, Tailwind CSS, TypeScript.
- External Services: Ethereum Mainnet and L2 (Optimism, Arbitrum, ZkSync Lite, Linea, Base) RPC endpoints used to fetch blockchain data.
- Build & Linting Tools: ESLint, Prettier, and TypeScript configurations ensure code quality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        subgraph "Pages"
            FE_Home["Home Page"]
            FE_FAQ["FAQ Page"]
        end
        FE_Components["Components"]
    end

    %% State Management & Context Providers
    subgraph "State Management & Context Providers"
        Providers["Providers"]
        Hooks["Custom Hooks"]
    end

    %% Business Logic & Calculation Layer
    subgraph "Business Logic & Calculation Layer"
        subgraph "Core Modules"
            CL_customfetch["customfetch.ts"]
            CL_ethfees["ethfees.ts"]
            CL_gethBatch["gethBatchCustomReceipts.ts"]
            CL_batchFee["batchFeeHistory.ts"]
            CL_savings["savingsdata.ts"]
        end
        subgraph "Chain Modules"
            L2_Arbitrum["Arbitrum.ts"]
            L2_Base["Base.ts"]
            L2_Linea["Linea.ts"]
            L2_Optimism["Optimism.ts"]
            L2_ZkSyncLite["ZkSyncLite.ts"]
        end
    end

    %% Utility & Helper Functions
    subgraph "Utility & Helper Functions"
        UT_chain["chainToAssetSrc.ts"]
        UT_constants["constants.ts"]
        UT_chunk["chunk.ts"]
        UT_truncate["truncateTransactionHash.ts"]
        UT_explorer["explorerUri.ts"]
        UT_account["accountMetadata.ts"]
        UT_localize["localizeChain.ts"]
        UT_provider["provider.ts"]
        UT_sort["sortBy.ts"]
    end

    %% Styling & Configuration
    subgraph "Styling & Configuration"
        SC_globals["globals.css"]
        SC_tailwind["tailwind.config.ts"]
        SC_next["next.config.js"]
        SC_postcss["postcss.config.js"]
    end

    %% External Blockchain Endpoints
    External["Ethereum Mainnet & L2 RPC Endpoints"]

    %% Connections
    FE_Components -->|"interacts"| Providers
    FE_Home -->|"navigates"| Providers
    FE_FAQ -->|"navigates"| Providers

    Providers -->|"triggers"| Hooks
    Hooks -->|"calls"| CL_customfetch

    %% Example utility usage by business logic
    CL_ethfees -->|"utilizes"| UT_constants
    CL_gethBatch -->|"utilizes"| UT_chunk

    %% Business Logic initiating external calls
    CL_savings -->|"fetches_data"| External
    L2_Optimism -->|"fetches_data"| External
    L2_Arbitrum -->|"fetches_data"| External
    L2_Linea -->|"fetches_data"| External
    L2_ZkSyncLite -->|"fetches_data"| External

    %% Click Events for Frontend/UI Layer
    click FE_Home "https://github.com/bbayazit16/l2savings/blob/master/src/app/page.tsx"
    click FE_FAQ "https://github.com/bbayazit16/l2savings/blob/master/src/app/faq/page.tsx"
    click FE_Components "https://github.com/bbayazit16/l2savings/tree/master/src/app/components"

    %% Click Events for State Management & Context Providers
    click Providers "https://github.com/bbayazit16/l2savings/tree/master/src/app/providers"
    click Hooks "https://github.com/bbayazit16/l2savings/tree/master/src/app/hooks"

    %% Click Events for Business Logic & Calculation Layer - Core Modules
    click CL_customfetch "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/customfetch.ts"
    click CL_ethfees "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/ethfees.ts"
    click CL_gethBatch "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/gethBatchCustomReceipts.ts"
    click CL_batchFee "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/batchFeeHistory.ts"
    click CL_savings "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/savingsdata.ts"

    %% Click Events for Business Logic & Calculation Layer - Chain Modules
    click L2_Arbitrum "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/l2/Arbitrum.ts"
    click L2_Base "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/l2/Base.ts"
    click L2_Linea "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/l2/Linea.ts"
    click L2_Optimism "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/l2/Optimism.ts"
    click L2_ZkSyncLite "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/l2/ZkSyncLite.ts"

    %% Click Events for Utility & Helper Functions
    click UT_chain "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/chainToAssetSrc.ts"
    click UT_constants "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/constants.ts"
    click UT_chunk "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/chunk.ts"
    click UT_truncate "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/truncateTransactionHash.ts"
    click UT_explorer "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/explorerUri.ts"
    click UT_account "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/accountMetadata.ts"
    click UT_localize "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/localizeChain.ts"
    click UT_provider "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/provider.ts"
    click UT_sort "https://github.com/bbayazit16/l2savings/blob/master/src/app/lib/sortBy.ts"

    %% Click Events for Styling & Configuration
    click SC_globals "https://github.com/bbayazit16/l2savings/blob/master/src/app/globals.css"
    click SC_tailwind "https://github.com/bbayazit16/l2savings/blob/master/tailwind.config.ts"
    click SC_next "https://github.com/bbayazit16/l2savings/blob/master/next.config.js"
    click SC_postcss "https://github.com/bbayazit16/l2savings/blob/master/postcss.config.js"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef providers fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef logic fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef config fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#C62828,stroke-width:2px;

    class FE_Home,FE_FAQ,FE_Components frontend;
    class Providers,Hooks providers;
    class CL_customfetch,CL_ethfees,CL_gethBatch,CL_batchFee,CL_savings,L2_Arbitrum,L2_Base,L2_Linea,L2_Optimism,L2_ZkSyncLite logic;
    class UT_chain,UT_constants,UT_chunk,UT_truncate,UT_explorer,UT_account,UT_localize,UT_provider,UT_sort utility;
    class SC_globals,SC_tailwind,SC_next,SC_postcss config;
    class External external;
```
