# spaceandtimefdn/sxt-zkpay-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/spaceandtimefdn/sxt-zkpay-contracts
- Repository: https://github.com/spaceandtimefdn/sxt-zkpay-contracts

## Overview

##### Project type and purpose
- This is a Solidity-based smart contract repository (ZKPay on Space and Time) built with Foundry.
- It provides zero-knowledge payment contracts, plus off-chain deployment and testing scripts, CI/CD checks, and security analysis configs.

##### File structure
- src/
– interfaces/ : external contract interfaces
– libraries/ : shared Solidity libraries
– (presumed) contracts/ : ZKPay core contracts (not shown but expected under src/)
- test/
– libraries/, mocks/, scenarios/ : Foundry tests, mock contracts, scenario tests
- script/
– input/config.json : parameters and verifying keys for deployment
– output/output.json : deployment metadata
- jobs/ : shell scripts for coverage measurement and deployment
- .github/workflows/ : GitHub Actions for linting, testing, and coverage
- slither*.json : static-analysis configuration
- foundry.toml, remappings.txt, soldeer.lock : Foundry build & dependency configs

##### Main components
A. On-chain layer
– ZKPay Smart Contracts (grouped into Interfaces, Libraries, Core Contracts)
– Ethereum/Space and Time network (blockchain node)
B. Off-chain tooling & pipeline
– Developer workstation (writes contracts and tests)
– Foundry toolkit (forge build/test)
– slither static analyzer
– Deployment scripts (jobs/deploy.sh, script/*)
– Test harness (jobs/check_coverage.sh)
C. CI/CD platform
– GitHub Actions (runs lint-and-test workflow)
D. External services
– Verifier or ZKP proving service (if separate)
– Config store (config.json inputs)

##### Relationships and interactions
- Developer commits → GitHub Actions
– Runs lint, slither, forge tests → generates coverage reports
- Deployment pipeline
– config.json → deploy.sh/script → publishes contract bytecode to blockchain → script/output/output.json
- Testing harness
– forge test → exercises contracts on local in-memory chain
- On-chain runtime
– EOA/User → ZKPay contracts → reads libraries & interfaces → writes to blockchain state
- Optional ZK prover
– Off-chain prover service → returns proof → submitted to verifier contract

##### Architectural patterns and design principles
- Modularity: separate Interfaces vs. Libraries vs. Core Contracts
- Layered workflow: local dev/test environment, CI pipeline, production deployment
- Single responsibility: each deployment script or test scenario does one job
- Defensible security: slither configs for both general and OZ-specific checks

##### Essential architecture without over-splitting
- Five core domains:
1. Developer & Local Test (Foundry)
2. CI/CD (GitHub Actions + Slither)
3. Deployment Scripts (jobs + script/)
4. On-Chain Contracts (Interfaces, Libraries, Core)
5. External Services (Blockchain, ZK prover)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Local Test
    subgraph "Developer & Local Test"
        Dev["Developer Workstation"]:::offchain
        Foundry["Foundry Toolkit"]:::offchain
        ConfigFile["foundry.toml"]:::offchain
        Remappings["remappings.txt"]:::offchain
        LockFile["soldeer.lock"]:::offchain
        Dev -->|"writes code & tests"| Foundry
        Foundry -->|reads| ConfigFile
        Foundry -->|reads| Remappings
        Foundry -->|reads| LockFile
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GHAction["GitHub Actions\n(lint-and-test.yml)"]:::cicd
        SlitherBase["Slither Config\n(slither.config.json)"]:::cicd
        SlitherOZ["Slither OZ Config\n(slither_openzeppelin.config.json)"]:::cicd
        GHAction -->|runs static analysis| SlitherBase
        GHAction -->|runs static analysis| SlitherOZ
        GHAction -->|runs tests & coverage| Foundry
    end

    %% Test Harness
    subgraph "Test Harness"
        LibTests["Library Tests\n(test/libraries)"]:::offchain
        MockTests["Mock Contracts\n(test/mocks)"]:::offchain
        ScenarioTests["Scenario Tests\n(test/senarios)"]:::offchain
        Foundry -->|executes| LibTests
        Foundry -->|executes| MockTests
        Foundry -->|executes| ScenarioTests
    end

    %% Off-Chain Scripts & Deployment
    subgraph "Off-Chain Scripts & Deployment"
        DeployScript["Deployment Script\n(jobs/deploy.sh)"]:::offchain
        CoverageScript["Coverage Check\n(jobs/check_coverage.sh)"]:::offchain
        InputConfig["Input Config\n(script/input/config.json)"]:::offchain
        OutputMeta["Deployment Output\n(script/output/output.json)"]:::offchain
        GHAction -->|triggers| CoverageScript
        InputConfig -->|used by| DeployScript
        DeployScript -->|publishes bytecode to| Blockchain
        DeployScript -->|produces| OutputMeta
    end

    %% On-Chain Contracts
    subgraph "On-Chain Contracts"
        Interfaces["Interfaces\n(src/interfaces)"]:::onchain
        Libraries["Libraries\n(src/libraries)"]:::onchain
        CoreContracts["Core Contracts"]:::onchain
        Interfaces -->|imported by| CoreContracts
        Libraries -->|imported by| CoreContracts
        CoreContracts -->|deployed to| Blockchain
    end

    %% External Services
    subgraph "External Services"
        Blockchain["Blockchain Network"]:::external
        ZKProver["ZK Prover Service"]:::external
        User["EOA/User"]:::external
        User -->|interacts with| CoreContracts
        ZKProver -->|provides proof to| CoreContracts
    end

    %% CI/CD triggers
    Dev -->|push commit| GHAction

    %% Mermaid Click Events
    click Interfaces "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/tree/main/src/interfaces"
    click Libraries "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/tree/main/src/libraries"
    click ConfigFile "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/foundry.toml"
    click Remappings "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/remappings.txt"
    click LockFile "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/soldeer.lock"
    click LibTests "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/tree/main/test/libraries"
    click MockTests "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/tree/main/test/mocks"
    click ScenarioTests "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/tree/main/test/scenarios"
    click DeployScript "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/jobs/deploy.sh"
    click CoverageScript "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/jobs/check_coverage.sh"
    click InputConfig "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/script/input/config.json"
    click OutputMeta "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/script/output/output.json"
    click GHAction "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/.github/workflows/lint-and-test.yml"
    click SlitherBase "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/slither.config.json"
    click SlitherOZ "https://github.com/spaceandtimefdn/sxt-zkpay-contracts/blob/main/slither_openzeppelin.config.json"

    %% Styles
    classDef onchain fill:#D6E4FF,stroke:#0047B2,color:#000
    classDef offchain fill:#E6FFFA,stroke:#00A36C,color:#000
    classDef cicd fill:#FFF7D6,stroke:#D4A017,color:#000
    classDef external fill:#F0F0F0,stroke:#888,stroke-dasharray: 5 5,color:#000
```
