# symbioticfi/middleware-sdk architecture

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

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

## Overview

##### Project Type and Purpose
- It’s a middleware development framework for smart contracts on blockchain networks (likely Ethereum or similar).
- Its purpose is to allow developers to create custom middleware by mixing and matching core functionalities like operator management, key management, access control, timestamp capturing, and stake power calculation.
- The included examples (SimplePosMiddleware, SqrtTaskMiddleware, SelfRegister variants) demonstrate different composable setups.
- The project also emphasizes upgradeability and modular extension, as seen by the usage of initialization patterns and inheritance of multiple extensions.

##### File Structure
- Top-Level Directories:
- .github: Contains GitHub workflows (linting, testing) that govern CI/CD.
- lib: Contains external libraries such as core contracts, crypto libraries, forge-std, and OpenZeppelin contracts (both regular and upgradeable).
- src: The heart of the project. It has multiple subdirectories:
▪ examples: Contains different implementations of middleware combining various extensions.
▪ extensions: Contains modular managers (like access, keys, sig, stake-powers, etc) and operators.
▪ interfaces: Contains interface definitions for the extensions and managers.
▪ libraries, managers, and middleware: These house core logic and shared functionality.
▪ middleware directory (if present) holds the base middleware logic that integrates the managers.
- test: Contains helper scripts, test data, and tests to validate functionality.
- Other config files such as foundry.toml (for Solidity testing/building), remappings.txt, package.json and Dockerfile for containerized worker examples.
- This modular distribution (using separate directories for each “concern”) indicates a layered, component‐based architecture.

##### Elements
A. Main Components (each represented as a distinct block):
- Base Middleware Component:
- BaseMiddleware contract that “glues” together the manager capabilities.
- It integrates functionalities from VaultManager, OperatorManager, AccessManager, and KeyManager.
- Extensions Layer:
- Operator Management: Contracts from src/extensions/operators.
- Key Management: Variants like KeyManagerAddress, KeyManager256, etc. from src/extensions/managers/keys.
- Access Control: Multiple implementations from src/extensions/managers/access (e.g., OwnableAccessManager, OzAccessControl).
- Timestamp Handling: CaptureTimestamp and its implementations (EpochCapture, TimestampCapture) from src/extensions/managers/capture-timestamps.
- Signature Verification and StakePower: Blocks for ECDSASig, EdDSASig, and the stake power calculations.
- SharedVaults & Subnetwork management.
- Middleware Examples:
- Several example contracts (SimplePosMiddleware, SqrtTaskMiddleware, SelfRegister variants) as concrete case studies that inherit and combine parts of the above layers.
- Supporting Components:
- Libraries and Interfaces: Represent the shared libraries (e.g., crypto-lib) and interface definitions that abstract and standardize components.
- Test Suite/CI: Blocks that show the integration of GitHub workflows and test scripts, indicating automated testing and linting.
- External Dependencies:
- Dependencies from the lib folder, e.g., OpenZeppelin contracts, forge-std, and crypto utilities.
- Additional tooling (Docker and worker code in worker directory) that might interact with the blockchain system.

B. Relationships and Interactions:
- That the Interfaces and Libraries serve as contract boundaries or abstraction layers for the components.
- Dependency flow from lib (external libraries) into the smart contract modules.

C. Architectural Patterns and Design Principles:
- Modular and extensible design: Each extension (AccessManager, KeyManager, etc.) can be independently developed or swapped.
- Layered architecture: At the lowest level are the utility libraries and interfaces; in the middle, you have the extensible managers; at the top, the composite BaseMiddleware and its specialized examples.
- Use of inheritance and composition to decouple responsibilities, making unit testing and upgradeability (initialization ordering) a primary design element.

D. Include Relevant Technologies and Frameworks:
- Solidity smart contracts with upgradeable patterns.
- Foundry (via foundry.toml) for building/testing.
- OpenZeppelin standard implementations.
- Docker (for the worker example in SqrtTaskMiddleware).
- GitHub Actions for CI (lint.yml and test.yml).

##### Instructing the Principal Software Engineer
2. Surround it with extension components (AccessManager, KeyManager, Operators, CaptureTimestamp, Signature Verification, StakePower, SharedVaults) connecting them directly to the Base Middleware.
3. Adjacent to the middleware, document several example middleware contracts that inherit/combine these extensions.
5. At the periphery, indicate development infrastructure: CI workflows and Dockerized worker components.
- Inheritance/composition (from BaseMiddleware to extensions, and from extensions to examples).
- Data flow (e.g., request flows, signature verification paths).
- Dependencies (e.g., tests and CI feeding back to the main system).
- Modularity: Each component should have a clear boundary, and connections should be drawn to show interaction points (e.g., initialization order, data passing among contracts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Supporting Components
    subgraph "Supporting Components"
        ED["External Dependencies"]:::external
        LIB["Libraries & Shared Functionality"]:::support
        INT["Interfaces"]:::support
        ML["Manager Logic & Storage"]:::support
    end

    %% Core Middleware and Extensions
    subgraph "Core Middleware"
        BM["BaseMiddleware"]:::core
        OM["Operator Management"]:::extension
        KM["Key Management"]:::extension
        AC["Access Control"]:::extension
        TS["Timestamp Handling"]:::extension
        SV["Signature Verification"]:::extension
        SP["Stake Power Calculation"]:::extension
    end

    %% Middleware Examples
    subgraph "Middleware Examples"
        ME["Middleware Examples"]:::example
    end

    %% Deployment & Testing Infrastructure
    subgraph "Deployment & Testing"
        CI["CI/CD & Testing"]:::ci
        DW["Dockerized Worker"]:::ci
    end

    %% Relationships: Supporting Components -> Core Middleware
    ED --> BM
    LIB --> BM
    INT --> BM
    ML --> BM

    %% Relationships: Core Middleware -> Extensions
    BM --> OM
    BM --> KM
    BM --> AC
    BM --> TS
    BM --> SV
    BM --> SP

    %% Relationships: Examples inherit from BaseMiddleware
    ME -->|"inherits"| BM

    %% Relationships: Deployment & Testing interactions
    CI --> BM
    DW --> ME

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef extension fill:#bbf,stroke:#333,stroke-width:2px;
    classDef support fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#fed,stroke:#333,stroke-width:2px;
    classDef example fill:#fbd,stroke:#333,stroke-width:2px;
    classDef ci fill:#ffc,stroke:#333,stroke-width:2px;

    %% Click Events
    click BM "https://github.com/symbioticfi/middleware-sdk/tree/main/src/middleware"
    click OM "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/operators"
    click KM "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/managers/keys"
    click AC "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/managers/access"
    click TS "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/managers/capture-timestamps"
    click SV "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/managers/sigs"
    click SP "https://github.com/symbioticfi/middleware-sdk/tree/main/src/extensions/managers/stake-powers"
    click ME "https://github.com/symbioticfi/middleware-sdk/tree/main/src/examples"
    click INT "https://github.com/symbioticfi/middleware-sdk/tree/main/src/interfaces"
    click LIB "https://github.com/symbioticfi/middleware-sdk/tree/main/src/libraries"
    click ML "https://github.com/symbioticfi/middleware-sdk/tree/main/src/managers"
    click ED "https://github.com/symbioticfi/middleware-sdk/tree/main/lib"
    click CI "https://github.com/symbioticfi/middleware-sdk/tree/main/.github/workflows"
    click DW "https://github.com/symbioticfi/middleware-sdk/tree/main/src/examples/sqrt-task-network/worker"
```
