# symbioticfi/core architecture

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

- Interactive diagram: https://gitdiagram.com/symbioticfi/core
- Repository: https://github.com/symbioticfi/core

## Overview

##### Project Type and Purpose
- The project is a decentralized security protocol implemented in Solidity. It manages custom multi-asset restaking, allowing decentralized networks to manage collateral assets without locking funds.
- Core functions are described in the README as managing Collateral, Vaults (delegation and restaking management), Operators (infrastructure providers), and Resolvers (slashing incident management). There is also a broader ecosystem (Networks) that the protocol supports.

##### File Structure
- Top-Level Directories:
- src – contains the Solidity smart contracts grouped by domain (common, delegator, libraries, service, slasher, vault). This is the core blockchain/contract implementation.
- interfaces – holds Solidity interfaces that define how components communicate with one another.
- tests – houses unit and integration tests which help validate the smart contract logic.
- audits – includes security audit reports which emphasize a focus on security and compliance.
- lib – external libraries are integrated here (e.g., OpenZeppelin contracts and Forge Standard libraries) which suggests reliance on battle-tested code.
- script – deployment and integration scripts indicate how the system is deployed and interconnected.
- Build and Configuration Files:
- foundry.toml, package.json, .env.example and remappings.txt show the configuration for building, testing, and deploying the contracts.
- GitHub workflows and other CI/CD configurations imply automated testing and linting are part of the development process.

##### Key Components and Their Roles
- Collateral: Not explicitly mapped to a single directory but likely defined within core contracts (potentially under "src/contracts/common" or as documented in the specs collateral.md). This is a critical asset management module.
- Vaults: Located under "src/contracts/vault". This module will handle the delegation, restaking management, and reward distribution.
- Delegator: Found under "src/contracts/delegator"; this may handle the delegation mechanisms that power the vault functionality.
- Slasher: Under "src/contracts/slasher", this component likely deals with penalizing (slashing) misbehaving operators.
- Service and operator components: “src/contracts/service” and possibly parts of "src/interfaces/service" signal the modular interaction with external infrastructure.
- Libraries: Modules in "src/contracts/libraries" consolidate common logic and shared routines.
- Interfaces: The "src/interfaces" directory provides formal contracts between modules to ensure proper interactions and abstraction.

a. Main Components:
- Smart Contract Layer: Represent all deployed contract modules (Collateral, Vaults, Delegator, Slasher, Service, and Libraries). Each should be encapsulated as distinct blocks.
- External Dependencies: A block for external libraries (OpenZeppelin, forge-std) and any external audit integrations.
- Deployment/Test Automation: A section for scripts, CI/CD (GitHub Workflows), and test environments.

b. Relationships and Interactions:
- Vaults contract calls Delegator and Slasher for management and penalty functions.
- Operator actions (possibly via the Service module) that interact with Contracts.
- Interfaces mediating data exchange between the network’s external components and the on-chain contracts.
- Where external libraries (e.g., OpenZeppelin) augment the security and functionality of contract code.

c. Architectural Patterns:
- Modular architecture: Each domain (Collateral, Vault, etc.) is encapsulated, following separation of concerns.
- Interface-based design: Contracts interact through clearly defined interfaces for flexibility and testing.
- Use of established libraries (OpenZeppelin) to ensure security and upgradeability.

d. Relevant Technologies and Frameworks:
- Solidity for smart contracts, Foundry/Toml configuration for building and testing.
- Integration with OpenZeppelin contracts for secure, standardized code.
- GitHub workflows to manage linting and testing, highlighting CI/CD as part of the operational model.

##### Execution
- Drill down each major module to show internal relationships within the on-chain layer.

## Diagram (Mermaid)

```mermaid
graph TD
    %% On-chain Smart Contract Layer
    subgraph "On-chain Smart Contract Layer"
        Collateral["Collateral Module\n(Manages collateral assets)"]:::core
        Vault["Vault Module\n(Handles delegation & rewards)"]:::core
        Delegator["Delegator Module\n(Manages delegation logic)"]:::core
        Slasher["Slasher Module\n(Manages penalization)"]:::core
        Service["Service/Operator Component\n(Handles operator interactions)"]:::core
        Libraries["Libraries\n(Shared routines & utilities)"]:::core
    end

    %% Interface Contracts
    subgraph "Interface Contracts"
        InterfaceLayer["Interface Layer\n(Defines contract interactions)"]:::interface
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ExternalLibs["External Libraries\n(OpenZeppelin & Forge)"]:::external
        AuditReports["Audit Reports\n(Security audits)"]:::external
    end

    %% Deployment/Testing Infrastructure
    subgraph "Deployment & Testing Infrastructure"
        Deployment["Deployment Scripts & CI/CD\n(Foundry, GitHub workflows, tests)"]:::deployment
    end

    %% Relationships within On-chain Smart Contract Layer
    Vault -->|"calls"| Delegator
    Vault -->|"calls"| Slasher
    Delegator -->|"communicates"| Service
    Collateral ---|"shares-logic"| Libraries

    %% Interactions between Layers
    InterfaceLayer -->|"mediates"| Vault
    InterfaceLayer -->|"mediates"| Collateral
    InterfaceLayer -->|"mediates"| Delegator
    InterfaceLayer -->|"mediates"| Slasher
    InterfaceLayer -->|"mediates"| Service

    ExternalLibs -->|"augments"| Collateral
    ExternalLibs -->|"augments"| Vault
    ExternalLibs -->|"augments"| Delegator
    ExternalLibs -->|"augments"| Slasher
    ExternalLibs -->|"augments"| Service

    Deployment -->|"deploys/tests"| Vault
    Deployment -->|"deploys/tests"| Collateral
    Deployment -->|"deploys/tests"| Delegator
    Deployment -->|"deploys/tests"| Slasher
    Deployment -->|"deploys/tests"| Service

    %% Apply classes
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef interface fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef deployment fill:#f8d7da,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mappings
    click Collateral "https://github.com/symbioticfi/core/blob/main/specs/Collateral.md"
    click Collateral "https://github.com/symbioticfi/core/tree/main/src/contracts/common"
    click Vault "https://github.com/symbioticfi/core/tree/main/src/contracts/vault"
    click Vault "https://github.com/symbioticfi/core/blob/main/specs/Vault.md"
    click Delegator "https://github.com/symbioticfi/core/tree/main/src/contracts/delegator"
    click Delegator "https://github.com/symbioticfi/core/blob/main/specs/Operator.md"
    click Slasher "https://github.com/symbioticfi/core/tree/main/src/contracts/slasher"
    click Service "https://github.com/symbioticfi/core/tree/main/src/contracts/service"
    click Service "https://github.com/symbioticfi/core/tree/main/src/interfaces/service"
    click Libraries "https://github.com/symbioticfi/core/tree/main/src/contracts/libraries"
    click InterfaceLayer "https://github.com/symbioticfi/core/tree/main/src/interfaces"
```
