# codefox-inc/sparkn-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/codefox-inc/sparkn-contracts
- Repository: https://github.com/codefox-inc/sparkn-contracts

## Overview

##### Main Components
- Smart Contracts:
- ProxyFactory.sol – the central entry point for creating new contest proxies and controlling fund distribution.
- Distributor.sol – the logic implementation contract used to handle prize distribution via delegatecall.
- Proxy.sol – a minimal proxy contract deployed per contest, forwarding calls to the Distributor.
- External Roles:
- Organizer – creates contests and, using the factory, deploys proxies and distributes prizes.
- Sponsor – funds the contest by sending whitelisted ERC20 tokens to the anticipated proxy address.
- Supporter – participants who help solve problems, with winners eventually receiving prize funds.
- Owner – the protocol administrator who can execute critical functions (including rescue operations).
- Off-Chain Components:
- Web2 integrations or interfaces (as indicated by hybrid design notes), deployment scripts (Makefile, script folder), and CI/CD workflows (GitHub Action workflows) that support the development, testing, and deployment processes.

##### Relationships and Interactions
- The central orchestrator is the ProxyFactory which:
- Configures contests via setContest().
- Offers a function to pre-calculate proxy contract addresses (getProxyAddress()).
- Deploys Proxy contracts which then perform a delegatecall to the Distributor for distributing funds.
- Proxy contracts themselves are lightweight containers that rely on the logic housed in the Distributor contract.
- Roles interact with the system through these contracts:
- For example, organizers and sponsors send funds to the Proxy contract address prior to deployment.
- Depending on the contest lifecycle, the functions deployProxyAndDistribute(), deployProxyAndDistributeBySignature(), or deployProxyAndDistributeByOwner() are invoked.

##### Architectural Patterns and Design Principles
- Proxy Pattern: To minimize gas costs by deploying minimal proxy contracts for each contest while sharing the distribution logic from a single Distributor instance.
- Delegation via delegatecall: Allows Proxy contracts to execute Distributor functions in their own context, preserving storage and efficiency.
- Use of Immutable Variables: The design makes heavy use of immutability to prevent state variable collisions.
- Meta Transaction and EIP712: To support off-chain signing and safe on-chain operations.
- Separation of Concerns: Clear distinction between contest orchestration (factory), contract logic (distributor), and the minimal proxy layer.

##### Technology Stack and Supporting Elements
- Solidity smart contracts under the src/ directory.
- Testing with Foundry (evident from Makefile, foundry.toml, test folder with fuzz, integration, unit tests).
- Use of libraries from OpenZeppelin (for access control and signature verification).
- GitHub CI/CD integration (GitHub workflows) for automated testing.
- External ABI files and deployment scripts assist with integration in various EVM networks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Roles
    subgraph "External Roles"
        OR["Organizer"]:::role
        SP["Sponsor"]:::role
        SU["Supporter"]:::role
        OW["Owner"]:::role
    end

    %% Smart Contract System
    subgraph "On-Chain Smart Contracts"
        PF["ProxyFactory Contract"]:::contract
        PR["Proxy Contract"]:::contract
        DT["Distributor Contract"]:::contract
    end

    %% Off-Chain Components
    subgraph "Off-Chain Components"
        DS["Deployment & Scripting Tools"]:::offchain
        TS["Testing Suite"]:::offchain
        CI["CI/CD Workflows"]:::offchain
    end

    %% Roles interacting with ProxyFactory
    OR -->|"setContest()"| PF
    SP -->|"Pre-fund Proxy"| PF
    OW -->|"RescueOperations"| PF

    %% ProxyFactory creates Proxy contracts
    PF -->|"deployProxyAndDistribute()"| PR
    PF -->|"getProxyAddress()"| PR

    %% Proxy delegates to Distributor
    PR -->|"delegatecall distribute()"| DT

    %% Off-Chain integration with Smart Contracts
    DS -->|"Deploy/Script"| PF
    DS -->|"Deploy/Script"| PR
    DS -->|"Deploy/Script"| DT

    TS -->|"Testing"| PF
    TS -->|"Testing"| PR
    TS -->|"Testing"| DT

    CI -->|"AutomateDeploy&Test"| PF
    CI -->|"AutomateDeploy&Test"| PR
    CI -->|"AutomateDeploy&Test"| DT

    %% Click Events
    click PF "https://github.com/codefox-inc/sparkn-contracts/blob/main/abi/proxyFactory.json"
    click DT "https://github.com/codefox-inc/sparkn-contracts/blob/main/abi/Distributor.json"
    click PR "https://github.com/codefox-inc/sparkn-contracts/tree/main/src"
    click DS "https://github.com/codefox-inc/sparkn-contracts/tree/main/Makefile"
    click TS "https://github.com/codefox-inc/sparkn-contracts/tree/main/test/"
    click CI "https://github.com/codefox-inc/sparkn-contracts/tree/main/.github/workflows/"

    %% Styles
    classDef contract fill:#FEF5E7,stroke:#D35400,stroke-width:2px;
    classDef role fill:#D6EAF8,stroke:#1F618D,stroke-width:2px;
    classDef offchain fill:#E8F8F5,stroke:#17A589,stroke-width:2px;
```
