# byzantine-finance/vault-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/byzantine-finance/vault-sdk
- Repository: https://github.com/byzantine-finance/vault-sdk

## Overview

##### Project Type and Purpose
- This is an open-source TypeScript/JavaScript SDK (library) named “Byzantine Vault SDK.”
- Its purpose is to provide a high-level, easy-to-use interface (facade) for interacting with the Byzantine Finance Factory and vault contracts on Ethereum (and testnets).

##### File Structure Analysis
- Top-level directories:
- scripts – codegen utilities (e.g., error mapping).
- src – main library code, broken into:
· clients – façade classes and modules for vault creation (curators) and vault usage (staker).
· constants – ABI definitions and network configuration.
· types – TypeScript types and interfaces.
· utils – generic helpers (contract provider, error handling, unit conversions, network helpers).
· index.ts – root export, wiring of Byzant ineClient and helpers.
- test – end-to-end and unit tests validating all vault types, operations, metadata, roles.
- Configuration: .env example, tsconfig.json, package.json.

##### Insights from README
- The SDK wraps ethers.js provider and signer to expose four main vault-creation methods (Eigenlayer ERC20, Eigenlayer Native, Symbiotic ERC20, SuperVault ERC20).
- It also exposes two functional domains:
a. Curator functions (whitelist, fees, metadata, parameters).
b. Staker functions (deposit/withdraw, TVL, share conversion, chain-specific settings).
- Supports multiple networks (Holesky, Sepolia, soon Mainnet and Hoodi).

##### Core Components
a. User Application – the developer’s code that imports the SDK.
b. Byzantine Vault SDK – composed of:
- Entry point (index.ts) exporting ByzantineClient and getNetworkConfig.
- Clients Layer (ByzantineClient):
· Curator sub-clients (CreateVaults, AccessControl, FeeVault, LimitVault, MetadataVault, RebalanceSupervault, SharesVault, WhitelistVault).
· Staker sub-clients (DepositClient, WithdrawClient, EigenLayerClient, SymbioticClient).
- Constants (ABIs, network addresses).
- Utils (ContractProvider, error handlers, network selectors, units).
c. External Libraries – ethers.js provider and signer, dotenv, TypeScript compiler.
d. Ethereum JSON-RPC Endpoint – target network node (Infura, Alchemy, self-hosted).
e. Solidity Smart Contracts – Byzantine Factory contract and resulting vault contracts on-chain.

##### Relationships and Data Flows
- The User App calls methods on ByzantineClient.
- ByzantineClient delegates to specific sub-clients.
- Sub-clients use Utils.ContractProvider + ABIs to build and send JSON-RPC requests via ethers.js to the Ethereum node.
- The Ethereum node executes transactions on the Factory contract, instantiates vault contracts, returns receipts and events.
- ByzantineClient parses receipts, error-maps via utils, and returns high-level results (addresses, confirmations, data).
- Curator and Staker modules may read contract state (calls) or write state (transactions).

##### Architectural Patterns and Principles
- Facade Pattern: ByzantineClient offers a unified interface over multiple low-level contract operations.
- Modular Design: Clear separation between vault-creation (curator) and vault-interaction (staker) concerns.
- Single Responsibility: Each sub-client handles one aspect of the workflow (e.g., WhitelistVault, DepositClient).
- DRY via constants (ABIs) and utils (error mapping, provider).

##### Detail
- Role of ABI files in Constants for contract binding.
- Error mapping flow: raw RPC error → utils.errorCodeMapping → user-friendly exception.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    UserApp["User Application"]:::external

    %% SDK Layer
    subgraph "Byzantine Vault SDK"
        direction TB
        EntryPoint["index.ts"]:::sdkInternals

        subgraph "Facade Client"
            ByzantineClient["ByzantineClient"]:::sdkInternals
        end

        subgraph "Curator Clients"
            AccessControl["AccessControl"]:::sdkInternals
            CreateVaults["CreateVaults"]:::sdkInternals
            FeeVault["FeeVault"]:::sdkInternals
            LimitVault["LimitVault"]:::sdkInternals
            MetadataVault["MetadataVault"]:::sdkInternals
            RebalanceSupervault["RebalanceSupervault"]:::sdkInternals
            SharesVault["SharesVault"]:::sdkInternals
            WhitelistVault["WhitelistVault"]:::sdkInternals
        end

        subgraph "Staker Clients"
            DepositClient["DepositClient"]:::sdkInternals
            WithdrawClient["WithdrawClient"]:::sdkInternals
            EigenLayerClient["EigenLayerClient"]:::sdkInternals
            SymbioticClient["SymbioticClient"]:::sdkInternals
        end

        subgraph "Constants"
            AbiBurner["AbiBurner"]:::sdkInternals
            AbiByzantineFactory["AbiByzantineFactory"]:::sdkInternals
            AbiDelegator["AbiDelegator"]:::sdkInternals
            AbiEigenERC20["AbiEigenERC20"]:::sdkInternals
            AbiEigenNative["AbiEigenNative"]:::sdkInternals
            AbiSlasher["AbiSlasher"]:::sdkInternals
            AbiSuperERC20["AbiSuperERC20"]:::sdkInternals
            AbiSymERC20["AbiSymERC20"]:::sdkInternals
            AbiSymVault["AbiSymVault"]:::sdkInternals
            AbisIndex["abis.ts"]:::sdkInternals
            Networks["networks.ts"]:::sdkInternals
            ConstantsIndex["index.ts"]:::sdkInternals
        end

        subgraph "Utils"
            ContractProvider["ContractProvider"]:::sdkInternals
            ErrorHandler["contractErrorHandler"]:::sdkInternals
            ErrorCodeMapping["errorCodeMapping"]:::sdkInternals
            NetworkHelpers["network"]:::sdkInternals
            Providers["providers"]:::sdkInternals
            Units["units"]:::sdkInternals
            UtilsIndex["index.ts"]:::sdkInternals
        end
    end

    %% External Libraries
    ethersjs["ethers.js"]:::external
    dotenv["dotenv"]:::external
    tsCompiler["TypeScript Compiler"]:::external

    %% Ethereum Network
    EthereumRPC["Ethereum JSON-RPC Endpoint"]:::external

    %% On-chain Contracts
    subgraph "On-chain Contracts"
        Factory["Byzantine Finance Factory Contract"]:::onchain
        Vaults["Vault Contracts"]:::onchain
    end

    %% Connections
    UserApp -->|imports| EntryPoint
    EntryPoint -->|uses facade| ByzantineClient
    ByzantineClient -->|delegates to| AccessControl
    ByzantineClient -->|delegates to| CreateVaults
    ByzantineClient -->|delegates to| FeeVault
    ByzantineClient -->|delegates to| LimitVault
    ByzantineClient -->|delegates to| MetadataVault
    ByzantineClient -->|delegates to| RebalanceSupervault
    ByzantineClient -->|delegates to| SharesVault
    ByzantineClient -->|delegates to| WhitelistVault
    ByzantineClient -->|delegates to| DepositClient
    ByzantineClient -->|delegates to| WithdrawClient
    ByzantineClient -->|delegates to| EigenLayerClient
    ByzantineClient -->|delegates to| SymbioticClient

    AccessControl -->|reads/writes| ContractProvider
    CreateVaults -->|reads/writes| ContractProvider
    FeeVault -->|reads/writes| ContractProvider
    LimitVault -->|reads/writes| ContractProvider
    MetadataVault -->|reads/writes| ContractProvider
    RebalanceSupervault -->|reads/writes| ContractProvider
    SharesVault -->|reads/writes| ContractProvider
    WhitelistVault -->|reads/writes| ContractProvider

    DepositClient -->|reads/writes| ContractProvider
    WithdrawClient -->|reads/writes| ContractProvider
    EigenLayerClient -->|reads/writes| ContractProvider
    SymbioticClient -->|reads/writes| ContractProvider

    ContractProvider -->|uses| AbiByzantineFactory
    ContractProvider -->|uses| AbisIndex
    ContractProvider -->|uses| Networks

    ContractProvider --> ethersjs
    ethersjs --> EthereumRPC
    EthereumRPC --> Factory
    Factory --> Vaults

    Vaults -->|events/receipts| EthereumRPC
    EthereumRPC -->|responses| ethersjs
    ethersjs --> ContractProvider

    %% Click Events
    click EntryPoint "https://github.com/byzantine-finance/vault-sdk/blob/main/src/index.ts"
    click ByzantineClient "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/ByzantineClient.ts"
    click AccessControl "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/AccessControl.ts"
    click CreateVaults "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/CreateVaults.ts"
    click FeeVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/FeeVault.ts"
    click LimitVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/LimitVault.ts"
    click MetadataVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/MetadataVault.ts"
    click RebalanceSupervault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/RebalanceSupervault.ts"
    click SharesVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/SharesVault.ts"
    click WhitelistVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/curators/WhitelistVault.ts"
    click DepositClient "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/staker/DepositClient.ts"
    click WithdrawClient "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/staker/WithdrawClient.ts"
    click EigenLayerClient "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/staker/EigenLayerClient.ts"
    click SymbioticClient "https://github.com/byzantine-finance/vault-sdk/blob/main/src/clients/staker/SymbioticClient.ts"
    click AbiBurner "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiBurner.ts"
    click AbiByzantineFactory "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiByzantineFactory.ts"
    click AbiDelegator "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiDelegator.ts"
    click AbiEigenERC20 "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiEigenERC20.ts"
    click AbiEigenNative "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiEigenNative.ts"
    click AbiSlasher "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiSlasher.ts"
    click AbiSuperERC20 "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiSuperERC20.ts"
    click AbiSymERC20 "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiSymERC20.ts"
    click AbiSymVault "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/AbiSymVault.ts"
    click AbisIndex "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/abis.ts"
    click Networks "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/networks.ts"
    click ConstantsIndex "https://github.com/byzantine-finance/vault-sdk/blob/main/src/constants/index.ts"
    click ContractProvider "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/ContractProvider.ts"
    click ErrorHandler "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/contractErrorHandler.ts"
    click ErrorCodeMapping "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/errorCodeMapping.ts"
    click NetworkHelpers "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/network.ts"
    click Providers "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/providers.ts"
    click Units "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/units.ts"
    click UtilsIndex "https://github.com/byzantine-finance/vault-sdk/blob/main/src/utils/index.ts"

    %% Styles
    classDef sdkInternals fill:#e0f7fa,stroke:#006064,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:1px
    classDef onchain fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
```
