# superform-xyz/v2-core-public-cantina architecture

> Architecture diagram of the GitHub repository superform-xyz/v2-core-public-cantina, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/superform-xyz/v2-core-public-cantina
- Repository: https://github.com/superform-xyz/v2-core-public-cantina

## Overview

##### Project type and purpose
- This is a blockchain-based, modular DeFi protocol (“Superform v2”) for yield abstraction.
- It provides on-chain smart-contract modules (hooks, executors, validators, accounting) and an off-chain bundler (SuperBundler) to batch, sign, and relay user operations (ERC-7579 / ERC-4337).

##### File structure
- src/core/: the on-chain “Core Components” broken down into layers:
- accounting/ (SuperLedger, oracles)
- adapters/ (bridge adapters)
- executors/ (SuperExecutor, SuperDestinationExecutor)
- hooks/ (bridges, claim, loan, stake, swappers, tokens, vaults…)
- interfaces/, libraries/, paymaster/, validators/
- lib/: external submodules (OpenZeppelin, Solady, Pendle, etc.)
- test/ mirrors the core structure for unit/integration testing
- audits/, foundry.toml, Makefile: build, test, audit artifacts

##### README for architecture insights
- Core components: SmartAccount layer, Execution layer, Validation layer, Accounting layer
- Cross-chain infrastructure: bridge adapters + destination executors/validators
- Off-chain: SuperBundler generates Merkle trees, collects signatures, batches UserOps

##### Detail without over-fragmentation
- Smart-contract layers (executors, validators, paymaster, registry)
- Enumerate major hook categories (bridges, claim, stake, swap, token, vault modules)
- External dependencies (EntryPoint, oracles, off-chain merkle-js)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Off-chain Layer"
    direction TB
    User["User"]:::frontend
    Frontend["DApp Frontend"]:::frontend
    Bundler["SuperBundler\n(Merkle Tree Generator)"]:::frontend
  end

  subgraph "On-chain Source Chain"
    direction TB
    EntryPoint["ERC-4337 EntryPoint"]:::external
    subgraph "Core Components"
      direction TB
      subgraph "Execution Layer"
        direction TB
        SuperExecutor["SuperExecutor"]:::core
        Hooks["Hooks Modules"]:::core
      end
      subgraph "Validation Layer"
        SuperMerkleValidator["SuperMerkleValidator"]:::core
      end
      subgraph "Paymaster & Registry"
        direction TB
        SuperNativePaymaster["SuperNativePaymaster"]:::core
        SuperRegistry["SuperRegistry"]:::core
      end
      subgraph "Accounting Layer"
        direction TB
        SuperLedger["SuperLedger"]:::ledger
        YieldSourceOracles["YieldSourceOracles"]:::ledger
      end
    end
  end

  subgraph "Cross-chain Infrastructure"
    direction TB
    BridgeAdapters["Bridge Adapters"]:::crosschain
  end

  subgraph "On-chain Destination Chain"
    direction TB
    subgraph "Core Components"
      direction TB
      subgraph "Execution Layer"
        SuperDestinationExecutor["SuperDestinationExecutor"]:::crosschain
      end
      subgraph "Validation Layer"
        SuperDestinationValidator["SuperDestinationValidator"]:::crosschain
      end
      subgraph "Accounting Layer"
        DestLedger["Destination Ledger"]:::ledger
      end
    end
  end

  User --> Frontend
  Frontend --> Bundler
  Bundler -->|"Batch UserOps & Merkle Proof"| EntryPoint
  EntryPoint -->|"UserOp"| SuperMerkleValidator
  SuperMerkleValidator -->|"validated"| SuperExecutor
  SuperExecutor -->|"executes hooks"| Hooks
  Hooks -->|"update"| SuperLedger
  Hooks -->|"query oracles"| YieldSourceOracles
  SuperExecutor -->|"calls cross-chain if needed"| BridgeAdapters
  BridgeAdapters -->|"relay to dest chain"| SuperDestinationExecutor
  SuperDestinationExecutor -->|"validated"| SuperDestinationValidator
  SuperDestinationExecutor -->|"update"| DestLedger
  Bundler -->|"sponsors gas"| SuperNativePaymaster
  SuperNativePaymaster -.-> EntryPoint
  SuperRegistry -->|"module config"| SuperExecutor

  click SuperExecutor "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/executors/SuperExecutor.sol"
  click SuperDestinationExecutor "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/executors/SuperDestinationExecutor.sol"
  click SuperMerkleValidator "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/validators/SuperMerkleValidator.sol"
  click SuperDestinationValidator "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/validators/SuperDestinationValidator.sol"
  click SuperNativePaymaster "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/paymaster/SuperNativePaymaster.sol"
  click SuperRegistry "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/interfaces/SuperRegistry.sol"
  click SuperLedger "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/accounting/SuperLedger.sol"
  click YieldSourceOracles "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/src/core/accounting/oracles/YieldSourceOracles.sol"
  click BridgeAdapters "https://github.com/superform-xyz/v2-core-public-cantina/tree/main/src/core/adapters/"
  click Hooks "https://github.com/superform-xyz/v2-core-public-cantina/tree/main/src/core/hooks/"
  click Bundler "https://github.com/superform-xyz/v2-core-public-cantina/blob/main/test/utils/merkle/merkle-js/build-hook-merkle-trees.js"

  classDef frontend fill:#a8f0c6,stroke:#2d6a4f,color:#0b3d91
  classDef core fill:#a0c4ff,stroke:#4361ee,color:#001233
  classDef crosschain fill:#ffd6a5,stroke:#fb8b24,color:#6d6875
  classDef ledger fill:#e0e0e0,stroke:#8d99ae,color:#2b2d42
  classDef external fill:#ffffff,stroke:#adb5bd,color:#495057
```
