How byzantine-finance/vault-sdk works
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.