# timewave-computer/valence-protocol architecture

> Architecture diagram of the GitHub repository timewave-computer/valence-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timewave-computer/valence-protocol
- Repository: https://github.com/timewave-computer/valence-protocol

## Overview

##### Main Components

a. Core Protocol Components:
- Authorization System (/contracts/authorization)
- Processor System (/contracts/processor)
- Program Registry (/contracts/program-registry)
- Program Manager (/program-manager)
- Base Account System (/contracts/accounts/base_account)

b. Library Components:
- Multiple DEX Integration Libraries (Astroport, Osmosis)
- IBC Transfer Libraries (Generic and Neutron)
- Utility Libraries (Splitter, Forwarder)

c. Cross-Chain Infrastructure:
- Domain Connectors (Cosmos, EVM)
- Bridge Systems
- IBC/ICQ Components

**[User/Developer Interface Layer]**

**[Program Management Layer]**

**[Core Protocol Layer]**

**[Library Layer]**

**[Cross-Chain Infrastructure Layer]**

**[Blockchain Networks Layer]**

##### Key Relationships to Highlight

- Bidirectional flows between Program Manager and Authorization/Processor components
- How Libraries interface with the Core Protocol
- Demonstrate cross-chain message flow through IBC/Bridge components
- How different blockchain networks connect through the infrastructure layer

##### Component Details

Core Protocol:
**┌─ Program Manager ─────┐**
- Config Management  │
- Program Migration  │
- Domain Connectors  │
- ┘

**┌─ Authorization ──────┐**
- User Actions      │
- Owner Actions     │
- Domain Management │
- ┘

**┌─ Processor ─────────┐**
- Queue Management  │
- Callbacks        │
- State Management │
- ┘

##### Implementation Notes

- Maintain clear separation between different protocol layers
- Version/status indicators for components under development
- Notes for planned future integrations (e.g., SVM support)

- Trust-minimized execution environment
- Cross-chain capabilities
- Resource model architecture
- Multi-party program support
- Domain-specific co-processor compilation

This system design should be implemented as a living document, updated as new features are added or architecture changes are made to the protocol.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#a8d1f0,stroke:#333
    classDef library fill:#90EE90,stroke:#333
    classDef infrastructure fill:#FFB347,stroke:#333
    classDef network fill:#D3D3D3,stroke:#333
    classDef interface fill:#E6E6FA,stroke:#333

    %% User/Developer Interface Layer
    subgraph Interface
        UI[User/Developer Interface]:::interface
    end

    %% Program Management Layer
    subgraph ProgramManagement
        PM["Program Manager"]:::core
        PR["Program Registry"]:::core
    end

    %% Core Protocol Layer
    subgraph CoreProtocol
        Auth["Authorization System"]:::core
        Proc["Processor System"]:::core
        BA["Base Account System"]:::core
    end

    %% Library Layer
    subgraph Libraries
        direction TB
        DEX["DEX Integration"]:::library
        IBC["IBC Transfer"]:::library
        Util["Utility Libraries"]:::library

        subgraph DEXLibs
            Astro["Astroport"]:::library
            Osmo["Osmosis"]:::library
        end

        subgraph IBCLibs
            GenIBC["Generic IBC"]:::library
            NeutIBC["Neutron IBC"]:::library
        end

        subgraph UtilLibs
            Split["Splitter"]:::library
            Forward["Forwarder"]:::library
        end
    end

    %% Cross-Chain Infrastructure Layer
    subgraph Infrastructure
        DC["Domain Connectors"]:::infrastructure
        IBCUtils["IBC Utils"]:::infrastructure
        ICQ["ICQ Components"]:::infrastructure
        Test["Testing Infrastructure"]:::infrastructure
    end

    %% Blockchain Networks Layer
    subgraph Networks
        Cosmos["Cosmos Networks"]:::network
        EVM["EVM Networks"]:::network
    end

    %% Relationships
    UI --> PM
    UI --> PR
    PM --> Auth
    PM --> Proc
    PR --> Auth
    Auth --> BA
    Proc --> BA
    BA --> DEX
    BA --> IBC
    BA --> Util
    DEX --> DC
    IBC --> DC
    DC --> IBCUtils
    DC --> ICQ
    IBCUtils --> Cosmos
    IBCUtils --> EVM
    ICQ --> Cosmos

    %% Click Events
    click Auth "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/authorization/"
    click Proc "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/processor/"
    click PR "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/program-registry/"
    click PM "https://github.com/timewave-computer/valence-protocol/tree/main/program-manager/"
    click BA "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/accounts/base_account/"
    click Astro "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/astroport-lper/"
    click Osmo "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/osmosis-cl-lper/"
    click GenIBC "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/generic-ibc-transfer/"
    click NeutIBC "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/neutron-ibc-transfer/"
    click Split "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/splitter/"
    click Forward "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/libraries/forwarder/"
    click DC "https://github.com/timewave-computer/valence-protocol/tree/main/program-manager/src/domain/"
    click IBCUtils "https://github.com/timewave-computer/valence-protocol/tree/main/packages/ibc-utils/"
    click ICQ "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/testing/test-icq-lib/"
    click Test "https://github.com/timewave-computer/valence-protocol/tree/main/contracts/testing/"
```
