# automata-network/unifi-tdx-prover architecture

> Architecture diagram of the GitHub repository automata-network/unifi-tdx-prover, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/automata-network/unifi-tdx-prover
- Repository: https://github.com/automata-network/unifi-tdx-prover

## Overview

##### Project Type and Purpose
- This is a Rust‐based, microservice/open‐source tool (“Unifi TDX Prover”) designed to run inside an Intel TDX Trusted Execution Environment (TEE).
- Its primary responsibility is to generate and sign rollup validity proofs (PoE) for Unifi’s atomicWithdrawal by executing blocks, building proofs of block execution (PoB), and providing attestation reports and ephemeral key–signed proofs to an on‐chain ProverRegistry contract.

##### File Structure Analysis
- Top-level binaries:
- bin/multi-prover: the long-running Actix-Web Prover service
- bin/guest-input-to-proof-request: a CLI tool to convert raw GuestInput JSON → ProofRequest JSON
- crates/: modular libraries
- base/: core types and helpers (base64, Ethereum RPC, keypairs, thread management, on‐chain ProverRegistry interactions)
- executor/: block execution engine (chain state, memdb) and proof‐of‐block (PoB) logic
- prover/: orchestrates PoB → PoE signing and exposes an internal Prover API
- tee/: interfaces with TDX (mock or real attestation report generation, IMA, TDX builders, agent service)
- config/: JSON configs for different environments (holesky/testnet/mainnet vs. localhost_mock)
- testdata/: sample GuestInput and expected ProofRequest JSON files

##### Architecture Overview from README
- Sequence:
1. TDX Prover initializes, generates ephemeral key, calls ProverRegistry contract to register the instance (attestation report + userData)
2. On each new block, an external “ProofBuilder API” (multi-prover) calls requestProof(ProofInput)
3. The prover → executor executes block (PoB), signs PoE with ephemeral key inside TEE, returns ProofResponse
4. ProofBuilder then calls ProverRegistry.verifyProofs([...]) on-chain

##### Components
a. Front-end / Client Tools:
- CLI: guest-input-to-proof-request
- ProofBuilder API (could be an external service or UI that calls multi-prover)
b. Prover Service (multi-prover):
- Actix-Web HTTP Server listening on configurable port (20300)
- Prover API layer (crates/prover/src/api.rs)
- Executor module (crates/executor) for PoB
- TEE interface module (crates/tee) for attestation & signing PoE
- Base module (crates/base) for on-chain interactions & key management
c. External Systems:
- Ethereum JSON-RPC node (for sending register & verify transactions)
- ProverRegistry Solidity contract (on Unifi’s layer1)
- AttestationVerifier Solidity contract
d. Data Stores / Config:
- In-memory DB (memdb) for chain state in executor
- Local config files (config/*.json)

##### Relationships & Data Flow
- CLI → Prover Service (submit GuestInput JSON)
- Prover Service → Executor (PoB generation)
- Executor → Prover Service (PobResult)
- Prover Service → TEE module (attach attestation & sign PoE)
- Prover Service → Ethereum RPC (register instance, verify proofs)
- Ethereum RPC → On-chain contracts (ProverRegistry & AttestationVerifier) → events back to Prover Service

##### Architectural Patterns & Principles
- Modular crates correspond to bounded contexts (Separation of concerns)
- Single Long-Running Service (multi-prover) + Lightweight CLI
- TEE enclave abstraction (mock vs. real) behind a unified API (agent_service.rs)
- On-chain registration & verification as an external dependency

##### Technologies & Frameworks
- Rust + Cargo workspaces
- Actix-Web for HTTP server
- Intel TDX APIs (via crates/tee)
- Ethereum JSON-RPC (ethers-rs or custom base::eth module)
- JSON config & serde for serialization
- CLI via cargo run --bin

##### Final Recommendations
- Configuration injection (config/*.json) at service startup
- Ephemeral key lifecycle: generated on startup in TEE, used per-block, rotated via on-chain event

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Lane: Client Tools
    subgraph "Client Tools" 
        direction TB
        CLI["CLI: guest-input-to-proof-request"]:::cli
        PBAPI["ProofBuilder API"]:::external
    end

    CLI -->|"GuestInput JSON"| PBAPI
    PBAPI -->|"ProofRequest JSON"| PS

    %% Middle Lane: Prover Service
    subgraph "Prover Service (multi-prover)" 
        direction TB
        PS["Actix-Web HTTP Server\n(listen port 20300)"]:::service
        CFG["Config Files\n(config/*.json)"]:::config
        PS --> CFG
        PS --> API
        API["Prover API Layer"]:::module
        API --> EXEC
        EXEC["Proof-of-Block Logic\n(crates/executor)"]:::module
        subgraph ExecutorDeps
            direction TB
            CHAIN["Chain State\n(crates/executor/src/chain.rs)"]:::db
            MEMDB["In-Memory DB\n(crates/executor/src/memdb.rs)"]:::db
        end
        EXEC --> CHAIN
        EXEC --> MEMDB
        API --> TEEIF
        TEEIF["TEE Interface\n(agent_service)"]:::tee
        API --> BASE
        BASE["Base Utilities & Ethereum RPC"]:::module
    end

    %% Bottom Lane: TEE Enclave & External Systems
    subgraph "TEE Enclave Modules"
        direction TB
        ATT["Attestation Report\n(attestation_report)"]:::tee
        MOCK["Mock TEE Builder\n(mock_builder)"]:::tee
        REAL["Real TDX Builder\n(tdx_builder)"]:::tee
        IMA["IMA Measurement\n(ima)"]:::tee
    end

    subgraph "External Systems"
        direction TB
        ETHRPC["Ethereum JSON-RPC Node"]:::external
        SC["Smart Contracts:\nProverRegistry & AttestationVerifier"]:::contract
    end

    TEEIF --> ATT
    TEEIF --> MOCK
    TEEIF --> REAL
    TEEIF --> IMA

    BASE -->|"eth RPC calls"| ETHRPC
    ETHRPC --> SC
    SC -->|"events & tx receipts"| PS

    %% Click Events
    click CLI "https://github.com/automata-network/unifi-tdx-prover/blob/main/bin/guest-input-to-proof-request/src/main.rs"
    click PS "https://github.com/automata-network/unifi-tdx-prover/blob/main/bin/multi-prover/src/main.rs"
    click API "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/prover/src/api.rs"
    click EXEC "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/executor/src/block_executor.rs"
    click CHAIN "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/executor/src/chain.rs"
    click MEMDB "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/executor/src/memdb.rs"
    click ATT "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/tee/src/attestation_report.rs"
    click MOCK "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/tee/src/mock_builder.rs"
    click REAL "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/tee/src/tdx_builder.rs"
    click IMA "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/tee/src/ima.rs"
    click TEEIF "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/tee/src/agent_service.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/eth.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/prover_registry.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/keypair.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/thread.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/base64.rs"
    click BASE "https://github.com/automata-network/unifi-tdx-prover/blob/main/crates/base/src/error.rs"
    click CFG "https://github.com/automata-network/unifi-tdx-prover/blob/main/config/holesky.json"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef service fill:#afa,stroke:#333,stroke-width:1px
    classDef module fill:#dfd,stroke:#333,stroke-width:1px
    classDef tee fill:#fc9,stroke:#333,stroke-width:1px
    classDef db fill:#ffd,stroke:#333,stroke-width:1px
    classDef contract fill:#eef,stroke:#333,stroke-width:1px
    classDef config fill:#ccc,stroke:#333,stroke-width:1px
```
