# defindex-io/stellar-contracts architecture

> Architecture diagram of the GitHub repository defindex-io/stellar-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/defindex-io/stellar-contracts
- Repository: https://github.com/defindex-io/stellar-contracts

## Overview

DeFindex is a Soroban contract suite for creating and operating tokenized vaults that allocate assets to yield strategies. The principal workflow is to deploy a factory and strategies, create a vault, then deposit, invest, report gains, and withdraw. TypeScript scripts configure networks, deploy contracts, and maintain address books; on-chain Rust contracts implement vault, factory, and strategy behavior. Edges follow excerpts and the README; unsampled strategy and vault internals are represented at their exact source paths, with only evidenced relationships shown.

Main entry points: [`vault/src/lib.rs`](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/lib.rs) (Vault contract), [`vault/src/strategies.rs`](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/strategies.rs) (Strategy management), [`src/utils/vault.ts`](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/vault.ts) (Vault operations), [`src/strategies/deploy_blend.ts`](https://github.com/defindex-io/stellar-contracts/blob/main/src/strategies/deploy_blend.ts) (Blend deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deploy["Deployment tooling"]
  node_env["Network config<br/>[env_config.ts]"]
  node_addressbook["Address book<br/>[address_book.ts]"]
  node_tx["Transaction helpers<br/>[tx.ts]"]
  node_contracttools["Contract deployment<br/>[contract.ts]"]
  node_factorydeploy["Factory deployment<br/>[deploy_factory.ts]"]
  node_strategydeploy["Strategy deployment"]
  node_blenddeploy["Blend deployment<br/>[deploy_blend.ts]"]
  node_vaultdeploy["Vault deployment<br/>[deploy_vault.ts]"]
  node_vaultclient["Vault operations<br/>[vault.ts]"]
end

subgraph group_vault["Vault contracts"]
  node_vaultcore["Vault contract<br/>[lib.rs]"]
  node_vaultdeposit["Deposits and shares<br/>[deposit.rs]"]
  node_vaultfunds["Funds management<br/>[funds.rs]"]
  node_vaultinvest["Investment routing<br/>[investment.rs]"]
  node_vaultreport["Strategy reporting<br/>[report.rs]"]
  node_vaultstrategy["Strategy management<br/>[strategies.rs]"]
  node_vaultaccess["Roles and access<br/>[access.rs]"]
  node_vaultstorage[("Vault state<br/>[storage.rs]")]
end

subgraph group_strategies["Yield strategies"]
  node_blend["Blend strategy<br/>[lib.rs]"]
  node_blendreserves["Blend reserves<br/>[reserves.rs]"]
  node_blendstorage[("Blend state<br/>[storage.rs]")]
  node_fixed["Fixed APR strategy<br/>[lib.rs]"]
  node_hodl["Hodl strategy<br/>[lib.rs]"]
  node_soroswap["Soroswap strategy<br/>[lib.rs]"]
  node_xycloans["Xycloans strategy<br/>[lib.rs]"]
  node_unsafehodl["Unsafe Hodl strategy<br/>[lib.rs]"]
end

subgraph group_factory["Factory contract"]
  node_factory["Vault factory<br/>[lib.rs]"]
  node_factorystorage[("Factory state<br/>[storage.rs]")]
end

subgraph group_shared["Shared contract types"]
  node_strategycore["Strategy core<br/>[lib.rs]"]
  node_commonmodels["Shared models<br/>[models.rs]"]
end

node_operator(("Deployer"))
node_network{{"Stellar network"}}

node_operator -->|"runs deployment"| node_factorydeploy
node_operator -->|"runs deployment"| node_strategydeploy
node_operator -->|"runs deployment"| node_vaultdeploy
node_factorydeploy -.->|"loads settings"| node_env
node_strategydeploy -->|"dispatches"| node_blenddeploy
node_blenddeploy -->|"loads settings"| node_env
node_blenddeploy -->|"reads addresses"| node_addressbook
node_blenddeploy -->|"deploys contracts"| node_contracttools
node_contracttools -->|"updates entries"| node_addressbook
node_contracttools -->|"submits transactions"| node_tx
node_vaultdeploy -->|"reads addresses"| node_addressbook
node_vaultdeploy -->|"creates vault"| node_factory
node_vaultclient -->|"invokes contracts"| node_contracttools
node_vaultclient -->|"uses addresses"| node_addressbook
node_vaultclient -->|"calls factory"| node_factory
node_vaultclient -->|"calls vault"| node_vaultcore
node_factory -->|"reads and writes"| node_factorystorage
node_factory -.->|"deploys vault"| node_vaultcore
node_vaultcore -->|"processes deposits"| node_vaultdeposit
node_vaultcore -.->|"manages funds"| node_vaultfunds
node_vaultcore -.->|"routes investments"| node_vaultinvest
node_vaultcore -->|"fetches reports"| node_vaultreport
node_vaultcore -.->|"manages strategies"| node_vaultstrategy
node_vaultcore -.->|"checks roles"| node_vaultaccess
node_vaultcore -.->|"reads and writes"| node_vaultstorage
node_blend -->|"uses reserves"| node_blendreserves
node_blend -->|"reads and writes"| node_blendstorage
node_vaultstrategy -.->|"dispatches to"| node_blend
node_vaultstrategy -.->|"dispatches to"| node_fixed
node_vaultstrategy -.->|"dispatches to"| node_hodl
node_vaultstrategy -.->|"dispatches to"| node_soroswap
node_vaultstrategy -.->|"dispatches to"| node_xycloans
node_vaultstrategy -.->|"dispatches to"| node_unsafehodl
node_blend -->|"uses shared core"| node_strategycore
node_vaultcore -.->|"uses shared models"| node_commonmodels

click node_env "https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/env_config.ts"
click node_addressbook "https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/address_book.ts"
click node_tx "https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/tx.ts"
click node_contracttools "https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/contract.ts"
click node_factorydeploy "https://github.com/defindex-io/stellar-contracts/blob/main/src/deploy_factory.ts"
click node_strategydeploy "https://github.com/defindex-io/stellar-contracts/blob/main/src/strategies/deploy_strategies.ts"
click node_blenddeploy "https://github.com/defindex-io/stellar-contracts/blob/main/src/strategies/deploy_blend.ts"
click node_vaultdeploy "https://github.com/defindex-io/stellar-contracts/blob/main/src/deploy_vault.ts"
click node_vaultclient "https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/vault.ts"
click node_factory "https://github.com/defindex-io/stellar-contracts/blob/main/factory/src/lib.rs"
click node_factorystorage "https://github.com/defindex-io/stellar-contracts/blob/main/factory/src/storage.rs"
click node_vaultcore "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/lib.rs"
click node_vaultdeposit "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/deposit.rs"
click node_vaultfunds "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/funds.rs"
click node_vaultinvest "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/investment.rs"
click node_vaultreport "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/report.rs"
click node_vaultstrategy "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/strategies.rs"
click node_vaultaccess "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/access.rs"
click node_vaultstorage "https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/storage.rs"
click node_blend "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/lib.rs"
click node_blendreserves "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/reserves.rs"
click node_blendstorage "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/storage.rs"
click node_fixed "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/fixed_apr/src/lib.rs"
click node_hodl "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/hodl/src/lib.rs"
click node_soroswap "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/soroswap/src/lib.rs"
click node_xycloans "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/xycloans/src/lib.rs"
click node_unsafehodl "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/unsafe_hodl/src/lib.rs"
click node_strategycore "https://github.com/defindex-io/stellar-contracts/blob/main/strategies/core/src/lib.rs"
click node_commonmodels "https://github.com/defindex-io/stellar-contracts/blob/main/common/src/models.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_env,node_addressbook,node_tx,node_contracttools,node_factorydeploy,node_strategydeploy,node_blenddeploy,node_vaultdeploy,node_vaultclient toneBlue
class node_vaultcore,node_vaultdeposit,node_vaultfunds,node_vaultinvest,node_vaultreport,node_vaultstrategy,node_vaultaccess,node_vaultstorage toneAmber
class node_blend,node_blendreserves,node_blendstorage,node_fixed,node_hodl,node_soroswap,node_xycloans,node_unsafehodl toneMint
class node_factory,node_factorystorage toneRose
class node_strategycore,node_commonmodels,node_operator,node_network toneIndigo
```

## Components

### Deployment tooling

- [Network config](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/env_config.ts): `src/utils/env_config.ts`
- [Address book](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/address_book.ts): `src/utils/address_book.ts`
- [Transaction helpers](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/tx.ts): `src/utils/tx.ts`
- [Contract deployment](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/contract.ts): `src/utils/contract.ts`
- [Factory deployment](https://github.com/defindex-io/stellar-contracts/blob/main/src/deploy_factory.ts): `src/deploy_factory.ts`
- [Strategy deployment](https://github.com/defindex-io/stellar-contracts/blob/main/src/strategies/deploy_strategies.ts): `src/strategies/deploy_strategies.ts`
- [Blend deployment](https://github.com/defindex-io/stellar-contracts/blob/main/src/strategies/deploy_blend.ts): `src/strategies/deploy_blend.ts`
- [Vault deployment](https://github.com/defindex-io/stellar-contracts/blob/main/src/deploy_vault.ts): `src/deploy_vault.ts`
- [Vault operations](https://github.com/defindex-io/stellar-contracts/blob/main/src/utils/vault.ts): `src/utils/vault.ts`

### Vault contracts

- [Vault contract](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/lib.rs): `vault/src/lib.rs`
- [Deposits and shares](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/deposit.rs): `vault/src/deposit.rs`
- [Funds management](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/funds.rs): `vault/src/funds.rs`
- [Investment routing](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/investment.rs): `vault/src/investment.rs`
- [Strategy reporting](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/report.rs): `vault/src/report.rs`
- [Strategy management](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/strategies.rs): `vault/src/strategies.rs`
- [Roles and access](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/access.rs): `vault/src/access.rs`
- [Vault state](https://github.com/defindex-io/stellar-contracts/blob/main/vault/src/storage.rs): `vault/src/storage.rs`

### Yield strategies

- [Blend strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/lib.rs): `strategies/blend/src/lib.rs`
- [Blend reserves](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/reserves.rs): `strategies/blend/src/reserves.rs`
- [Blend state](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/blend/src/storage.rs): `strategies/blend/src/storage.rs`
- [Fixed APR strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/fixed_apr/src/lib.rs): `strategies/fixed_apr/src/lib.rs`
- [Hodl strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/hodl/src/lib.rs): `strategies/hodl/src/lib.rs`
- [Soroswap strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/soroswap/src/lib.rs): `strategies/soroswap/src/lib.rs`
- [Xycloans strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/xycloans/src/lib.rs): `strategies/xycloans/src/lib.rs`
- [Unsafe Hodl strategy](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/unsafe_hodl/src/lib.rs): `strategies/unsafe_hodl/src/lib.rs`

### Factory contract

- [Vault factory](https://github.com/defindex-io/stellar-contracts/blob/main/factory/src/lib.rs): `factory/src/lib.rs`
- [Factory state](https://github.com/defindex-io/stellar-contracts/blob/main/factory/src/storage.rs): `factory/src/storage.rs`

### Shared contract types

- [Strategy core](https://github.com/defindex-io/stellar-contracts/blob/main/strategies/core/src/lib.rs): `strategies/core/src/lib.rs`
- [Shared models](https://github.com/defindex-io/stellar-contracts/blob/main/common/src/models.rs): `common/src/models.rs`

### Other components

- **Deployer**
- **Stellar network**

## Connections

- Deployer → Factory deployment: runs deployment
- Deployer → Strategy deployment: runs deployment
- Deployer → Vault deployment: runs deployment
- Factory deployment → Network config: loads settings
- Strategy deployment → Blend deployment: dispatches
- Blend deployment → Network config: loads settings (evidence: `src/strategies/deploy_blend.ts`)
- Blend deployment → Address book: reads addresses (evidence: `src/strategies/deploy_blend.ts`)
- Blend deployment → Contract deployment: deploys contracts (evidence: `src/strategies/deploy_blend.ts`)
- Contract deployment → Address book: updates entries (evidence: `src/utils/contract.ts`)
- Contract deployment → Transaction helpers: submits transactions (evidence: `src/utils/contract.ts`)
- Vault deployment → Address book: reads addresses
- Vault deployment → Vault factory: creates vault
- Vault operations → Contract deployment: invokes contracts (evidence: `src/utils/vault.ts`)
- Vault operations → Address book: uses addresses (evidence: `src/utils/vault.ts`)
- Vault operations → Vault factory: calls factory (evidence: `src/utils/vault.ts`)
- Vault operations → Vault contract: calls vault (evidence: `src/utils/vault.ts`)
- Vault factory → Factory state: reads and writes (evidence: `factory/src/lib.rs`)
- Vault factory → Vault contract: deploys vault
- Vault contract → Deposits and shares: processes deposits (evidence: `vault/src/lib.rs`)
- Vault contract → Funds management: manages funds (evidence: `vault/src/lib.rs`)
- Vault contract → Investment routing: routes investments (evidence: `vault/src/lib.rs`)
- Vault contract → Strategy reporting: fetches reports (evidence: `vault/src/lib.rs`)
- Vault contract → Strategy management: manages strategies (evidence: `vault/src/lib.rs`)
- Vault contract → Roles and access: checks roles (evidence: `vault/src/lib.rs`)
- Vault contract → Vault state: reads and writes (evidence: `vault/src/lib.rs`)
- Blend strategy → Blend reserves: uses reserves (evidence: `strategies/blend/src/lib.rs`)
- Blend strategy → Blend state: reads and writes (evidence: `strategies/blend/src/lib.rs`)
- Strategy management → Blend strategy: dispatches to
- Strategy management → Fixed APR strategy: dispatches to
- Strategy management → Hodl strategy: dispatches to
- Strategy management → Soroswap strategy: dispatches to
- Strategy management → Xycloans strategy: dispatches to
- Strategy management → Unsafe Hodl strategy: dispatches to
- Blend strategy → Strategy core: uses shared core (evidence: `strategies/blend/src/lib.rs`)
- Vault contract → Shared models: uses shared models
