# aboutcircles/circles-contracts-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/aboutcircles/circles-contracts-v2
- Repository: https://github.com/aboutcircles/circles-contracts-v2

## Overview

##### Main Components

a) Core Protocol Components:
- Hub Contract (Central coordinator)
- Personal Currency System (ERC1155-based tokens)
- Trust Network Manager
- Demurrage System (7% annual)
- Migration System

b) Supporting Components:
- Name Registry
- Treasury System
- Management
- Lift System (ERC20 compatibility)
- Operators System

**[External Applications/Interfaces] ←→ [API Layer]**

**┌─────────────────────────────────────────┐**
- Hub Contract               │
- ┤
- Personal Currency │    Trust Network    │
- Management    │     Management      │
- ┘

**┌──────────┐ ┌──────────┐ ┌──────────┐**
- Groups  │ │   Lift   │ │ Treasury │
- ┘ └──────────┘ └──────────┘

**[Gnosis Chain Blockchain]**

##### Key Relationships to Highlight

- Group Management to Personal Currency system
- ERC20 Lift bridge connections

##### Special Features to Highlight

- Path-based Transactions
- Retroactive Minting (14-day window)
- Demurrage System (7% annual)
- Currency Management
- Migration Pathways

##### Technical Details

Annotations for:
- ERC1155 Implementation
- Smart Contract Interactions
- Trust Graph Structure
- Minting Policies
- Demurrage Calculations

##### Implementation Notes

- The modular nature of the system (shown in src/ directory structure)
- The separation of concerns between different components
- The upgrade paths and proxy patterns
- The interaction between personal and group currencies
- The role of operators and treasury management

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef core fill:#2b6cb0,stroke:#1a365d,color:white
    classDef support fill:#38a169,stroke:#1c4532,color:white
    classDef infra fill:#718096,stroke:#2d3748,color:white
    classDef spec fill:#d69e2e,stroke:#744210,color:white
    
    %% Layer 1 - User Interface
    subgraph Interface
        ExtApps[External Applications]
        API[API Layer]
    end

    %% Layer 2 - Protocol Core
    subgraph ProtocolCore
        Hub["Hub Contract"]:::core
        PersonalCurrency["Personal Currency System"]:::core
        TrustNetwork["Trust Network Manager"]:::core
        Demurrage["Demurrage System (7% Annual)"]:::core
    end

    %% Layer 3 - Supporting Systems
    subgraph SupportingSystems
        NameReg["Name Registry"]:::support
        Treasury["Treasury System"]:::support
        Groups["Group Management"]:::support
        Lift["Lift System (ERC20)"]:::support
        Operators["Operators System"]:::support
    end

    %% Layer 4 - Infrastructure
    subgraph Infrastructure
        GnosisChain["Gnosis Chain"]:::infra
    end

    %% Layer 5 - Specifications
    subgraph Specifications
        PathTx["Path-based Transactions"]:::spec
        GroupSpec["Group Currencies Spec"]:::spec
        TrustSpec["Trust Network Spec"]:::spec
    end

    %% Relationships
    ExtApps --> API
    API --> Hub
    Hub --> PersonalCurrency
    Hub --> TrustNetwork
    PersonalCurrency --> Demurrage
    Hub --> NameReg
    Hub --> Treasury
    Hub --> Groups
    Hub --> Lift
    Hub --> Operators
    
    %% Infrastructure Connections
    PersonalCurrency --> GnosisChain
    TrustNetwork --> GnosisChain
    Groups --> GnosisChain
    Lift --> GnosisChain
    
    %% Specification Relations
    PathTx -.-> Hub
    GroupSpec -.-> Groups
    TrustSpec -.-> TrustNetwork

    %% Click Events
    click Hub "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/hub/"
    click PersonalCurrency "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/circles/"
    click NameReg "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/names/"
    click Treasury "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/treasury/"
    click Groups "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/groups/"
    click Lift "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/lift/"
    click Operators "https://github.com/aboutcircles/circles-contracts-v2/tree/beta/src/operators/"
    click Demurrage "https://github.com/aboutcircles/circles-contracts-v2/blob/beta/specifications/TCIP009-demurrage.md"
    click TrustSpec "https://github.com/aboutcircles/circles-contracts-v2/blob/beta/specifications/TCIP002-trust-graph.md"
    click GroupSpec "https://github.com/aboutcircles/circles-contracts-v2/blob/beta/specifications/TCIP005-group-circles.md"
    click PathTx "https://github.com/aboutcircles/circles-contracts-v2/blob/beta/specifications/TCIP010-erc1155-path-transfer.md"

    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        SupportComponent["Supporting Component"]:::support
        InfraComponent["Infrastructure"]:::infra
        SpecComponent["Specification"]:::spec
    end
```
