# d-democrazy/btcxfactory_selfcustodial architecture

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

- Interactive diagram: https://gitdiagram.com/d-democrazy/btcxfactory_selfcustodial
- Repository: https://github.com/d-democrazy/btcxfactory_selfcustodial

## Overview

##### Main Components
- User’s Smart Contract Wallets – These are external entities that lock collateral, trigger minting, and initiate burning.
- BTCX Token Contract (BTCX.sol) – An ordinary ERC20 token (inheriting from OpenZeppelin contracts) that represents the stablecoin (BTCX) and whose supply/circulation is centrally controlled.
- CollateralManager – Representing a proxy pattern (with Implementation, Library, and Proxy files) that holds the list of allowed collateral contract addresses. This contract validates that any collateral locked is on the allowed list.
- WalletRegistry – Another proxy-based component which tracks the lock/unlock state of each user’s smart contract wallet. By performing an extcodehash check, it ensures that the wallet includes the WalletRegistry logic.
- BTCXFactory – The central ordinary contract that ties everything together. When a user requests a mint (or burn), BTCXFactory interacts with BTCX, CollateralManager, and WalletRegistry to validate that all conditions—such as collateral ratios, min/max thresholds, and available token supply—are met.
- Deployment and Support Scripts/Configurations – Foundry configuration (foundry.toml) and deployment scripts (in the “script” directory) that drive the deployment process. These are important for operational understanding but are peripheral to the core runtime architecture.

##### Relationships and Interactions
- The user’s smart contract wallet initially locks an allowed collateral (as per the CollateralManager’s list) and automatically broadcasts its “lock” state to the WalletRegistry.
- When invoking the mint function on BTCXFactory:
– BTCXFactory checks BTCX.sol for total supply and circulating supply.
– It queries CollateralManager to verify that the collateral being locked is approved.
– It validates the user’s overall collateral locking status via WalletRegistry (which also enforces minimum and maximum thresholds).
– Provided all conditions are met, BTCXFactory initiates minting (in line with the 1:100 ratio) and directs the BTCX Token Contract to mint tokens, updating the user’s wallet balance.
- For burning, the flow reverses: the wallet submits a burn request through BTCXFactory, which again consults the other contracts to ensure that burning will unlock the corresponding collateral.

##### Architectural Patterns and Design Principles
- Proxy Pattern: Notice that for each main service (CollateralManager, WalletRegistry, BTCXFactory, and BTCX), there are separate implementation and proxy contracts. This enables upgradeability while preserving state and ensuring contract logic can be updated.
- Separation of Concerns: Each contract focuses on specific responsibilities (e.g., CollateralManager for allowed addresses, WalletRegistry for state tracking), and BTCXFactory acts as the orchestrator for minting and burning.
- Data Flow Validation: BTCXFactory does not operate in isolation but always checks the state consistency across BTCX, CollateralManager, and WalletRegistry. The system design must show these validation loops clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External actor
    UserWallet("User's Smart Contract Wallets"):::external

    %% On-Chain Smart Contracts Subgraph
    subgraph "On-Chain Contracts"
        collateral("CollateralManager (Implementation + Proxy)"):::proxy
        walletreg("WalletRegistry (Implementation + Proxy)"):::proxy
        factory("BTCXFactory (Central Contract)"):::proxy
        token("BTCX Token Contract (BTCX.sol) – ERC20 Stablecoin"):::contract
    end

    %% Deployment and Support Subgraph
    subgraph "Deployment and Support"
        deploy("Deployment & Support Scripts/Configurations"):::deployment
    end

    %% Data flow arrows
    UserWallet -->|"lockCollateral"| collateral
    collateral -->|"broadcastState"| walletreg
    UserWallet -->|"mint/burnRequest"| factory
    factory -->|"mint/burnTokens"| token
    factory <-->|"validateCollateral"| collateral
    factory <-->|"validateWalletState"| walletreg

    %% Annotation for key conditions
    conditions["Note: Ratio 1:100, Min=0.01, Max=21000000 collateral, SupplyCap=2100000000 BTCX"]:::note
    factory --- conditions

    %% Click Events for Contract Components
    click token "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/src/Token"
    click token "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/script/Token"
    click collateral "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/src/Aggregators/CollateralManager"
    click collateral "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/script/CollateralManager"
    click walletreg "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/src/Aggregators/WalletRegistry"
    click walletreg "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/script/WalletRegistry"
    click factory "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/src/Factory"
    click deploy "https://github.com/d-democrazy/btcxfactory_selfcustodial/blob/main/foundry.toml"
    click deploy "https://github.com/d-democrazy/btcxfactory_selfcustodial/tree/main/script"

    %% Styles
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px
    classDef contract fill:#ccffcc,stroke:#006600,stroke-width:2px
    classDef proxy fill:#cce5ff,stroke:#00509e,stroke-width:2px
    classDef deployment fill:#ffffcc,stroke:#666600,stroke-width:2px
    classDef note fill:#e6e6fa,stroke:#663399,stroke-width:2px,stroke-dasharray: 5 5
```
