# mobilecoinfoundation/mobilecoin architecture

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

- Interactive diagram: https://gitdiagram.com/mobilecoinfoundation/mobilecoin
- Repository: https://github.com/mobilecoinfoundation/mobilecoin

## Overview

##### Project type and purpose
- This is a large‐scale, full‐stack, distributed blockchain network implementation (“MobileCoin”) that uses Intel SGX enclaves for byzantine‐fault‐tolerant consensus, a private “fog” layer for payment privacy, on‐chain ledger storage and distribution, plus APIs and client SDKs for wallets and monitoring.

##### Top‐level architectural components (from the file tree and README)
- Core crypto libraries (crypto/, transaction/, account-keys/, common/) – key‐management, ring CT, transaction builder/validator.
- Enclave boundary & SGX support (enclave-boundary/, sgx/) – ECALL/OCALL wrappers, edl definitions, support libraries, tooling for building enclaves.
- Consensus layer (consensus/)
– consensus/enclave: secure enclave implementation of the consensus state machine.
– consensus/service: the untrusted host process exposing gRPC APIs, interacting with enclave, running BFT protocol with peers.
- Ledger layer (ledger/)
– ledger/db: on‐disk storage of blocks and UTXOs.
– ledger/distribution: publishes the public chain snapshot to S3.
– ledger/sync: peer‐to‐peer sync service.
- Fog network (fog/)
– fog/ingest: ingest service (with enclave) for incoming transaction records.
– fog/ledger, fog/ledger-fsg: private ledger shards.
– fog/view: view service (with enclave) for clients to scan for incoming UTXOs.
– fog/distribution, fog/report: reporting and distribution services.
- API & gateway layer
– mobilecoind: combined watcher node daemon exposing JSON and gRPC APIs for wallets.
– go-grpc-gateway: a Go service that translates and proxies between REST and gRPC.
– watcher/: a standalone watcher tool for integrity checks.
- Client SDKs and CLIs (mobilecoind/clients/java, python, sample-paykit, test-client, fog‐ load-testing, etc.)
- Utilities and orchestration
– util/: build helpers, metrics, CLI tools.
– .github/, tools/, .internal-ci/, helm charts: CI pipelines, Dockerfiles, Kubernetes Helm charts for deploying consensus, fog, ledger, mobilecoind, etc.

##### Major relationships and interactions
- Wallet or SDK clients → mobilecoind or go‐grpc‐gateway (JSON/gRPC) → mobilecoind host
- mobilecoind host ↔ SGX enclave (ECALL/OCALL via enclave-boundary) → unforgeable attested enclave proof
- mobilecoind ↔ consensus peers over gRPC (peer API), each peer uses its enclave to agree on new blocks
- consensus‐service → ledger/db for block storage and UTXO indexing
- consensus‐service → ledger‐distribution → Amazon S3 for public ledger snapshots
- watcher nodes (mobilecoind in watcher mode) subscribe to consensus output to verify block signatures and maintain a local copy of the chain
- fog clients → fog/view router → SGX enclave to privately scan UTXOs, and fog/ingest to ingest key records
- fog internal services communicate via gRPC, share TLS certificates managed by Kubernetes and Helm charts

##### Important architectural patterns and design principles
- Microservices: separate Rust binaries (consensus‐service, fog‐ingest, fog‐view, ledger‐distribution, mobilecoind, watcher, test-clients) each in its own container.
- Trust boundary: clear enclave vs untrusted host separation, attested via SGX, defined in enclave-boundary and edl files.
- BFT consensus (SCP‐based) inside enclaves, untrusted network code in service layer.
- Data flow via gRPC/Protocol Buffers (proto/ directories under each api folder).
- Deployment via Docker + Helm charts (internal‐ci/helm, tools/local-network, k8s-dev) for Kubernetes.
- Zero‐knowledge ledger publishing: only UTXOs, key images, block metadata are published.
- Continuous integration: GitHub Actions building Rust and Go, publishing Docker images, running mc tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        JavaSDK["Java SDK"]:::client
        PythonSDK["Python SDK & CLI"]:::client
        SamplePayKit["Sample PayKit"]:::client
        FogLoadTest["Fog Load-Testing Client"]:::client
        MintClient["Consensus Mint Client"]:::client
        SignerCLI["Transaction Signer CLI"]:::client
    end

    %% API / Gateway Layer
    subgraph "API & Gateway Layer"
        direction TB
        GRPCGateway["Go REST↔gRPC Gateway"]:::gateway
        MobileCoinD["mobilecoind Daemon"]:::gateway
        WatcherTool["Watcher Integrity Tool"]:::gateway
    end

    %% Host Zone: Untrusted Services
    subgraph "Host Zone (Untrusted Services)"
        direction TB
        ConsensusSvc["Consensus Service (gRPC Host)"]:::service
        FogIngestSrv["Fog Ingest Server"]:::service
        FogViewSrv["Fog View Server"]:::service
        FogLedgerSrv["Fog Ledger Server"]:::service
        FogReportSrv["Fog Reporting Service"]:::service
    end

    %% Enclave Zone: SGX Enclaves
    subgraph "Enclave Zone (SGX Enclaves)"
        direction TB
        EnclaveBoundary["Enclave Boundary Wrappers"]:::enclave
        SGXSupport["SGX Support Libraries"]:::enclave
        ConsensusEnclave["Consensus Enclave"]:::enclave
        FogIngestEnclave["Fog Ingest Enclave"]:::enclave
        FogViewEnclave["Fog View Enclave"]:::enclave
        FogLedgerEnclave["Fog Ledger Enclave"]:::enclave
    end

    %% Ledger & Storage Layer
    subgraph "Ledger & Storage"
        direction TB
        LedgerDB["Ledger DB (Blocks & UTXOs)"]:::storage
        LedgerDist["Ledger Snapshot Distribution"]:::storage
        LedgerSync["Peer-to-Peer Ledger Sync"]:::storage
        S3["AWS S3 (Public Snapshots)"]:::external
    end

    %% Utilities & Orchestration
    subgraph "CI/CD & Orchestration"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        DockerBuild["Docker Build"]:::ci
        K8sDeploy["Kubernetes Deploy (Helm)"]:::ci
    end

    %% Relationships
    JavaSDK -->|"HTTP/JSON or gRPC"| MobileCoinD
    PythonSDK -->|"HTTP/JSON or gRPC"| MobileCoinD
    SamplePayKit -->|"gRPC"| GRPCGateway
    FogLoadTest -->|"gRPC"| FogIngestSrv
    MintClient -->|"gRPC"| ConsensusSvc
    SignerCLI -->|"CLI"| ConsensusSvc

    MobileCoinD -->|"ECALL/OCALL"| EnclaveBoundary
    EnclaveBoundary -->|"Attested Calls"| SGXSupport

    ConsensusSvc -->|"gRPC"| ConsensusEnclave
    ConsensusSvc -->|"Store Blocks"| LedgerDB
    ConsensusSvc -->|"Publish Snapshots"| LedgerDist
    LedgerDist -->|"Upload"| S3
    ConsensusSvc -->|"Sync Blocks"| LedgerSync

    FogIngestSrv -->|"gRPC"| FogIngestEnclave
    FogViewSrv -->|"gRPC"| FogViewEnclave
    FogLedgerSrv -->|"gRPC"| FogLedgerEnclave
    FogReportSrv -->|"HTTP API"| FogReportSrv

    GRPCGateway -->|"Proxy REST/gRPC"| MobileCoinD
    WatcherTool -->|"Subscribe Consensus"| ConsensusSvc
    WatcherTool -->|"Verify Blocks"| LedgerDB

    GitHubActions --> DockerBuild --> K8sDeploy
    K8sDeploy --> ConsensusSvc
    K8sDeploy --> FogIngestSrv
    K8sDeploy --> FogViewSrv
    K8sDeploy --> LedgerSync
    K8sDeploy --> MobileCoinD

    %% Click Events
    click crypto "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/crypto/"
    click transaction "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/transaction/"
    click account-keys "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/account-keys/"
    click common "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/common/"
    click enclave-boundary "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/enclave-boundary/"
    click sgx "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/sgx/"
    click consensus/enclave "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/consensus/enclave/"
    click consensus/service "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/consensus/service/"
    click ledger/db "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/ledger/db/"
    click ledger/distribution "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/ledger/distribution/"
    click ledger/sync "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/ledger/sync/"
    click fog/ingest/enclave "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/ingest/enclave/"
    click fog/ingest/server "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/ingest/server/"
    click fog/ingest/client "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/ingest/client/"
    click fog/ledger/enclave "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/ledger/enclave/"
    click fog/ledger/server "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/ledger/server/"
    click fog/view/enclave "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/view/enclave/"
    click fog/view/server "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/view/server/"
    click fog/distribution "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/distribution/"
    click fog/report/server "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/report/server/"
    click mobilecoind "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/mobilecoind/"
    click go-grpc-gateway "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/go-grpc-gateway/"
    click watcher "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/watcher/"
    click mobilecoind/clients/java "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/mobilecoind/clients/java/"
    click mobilecoind/clients/python "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/mobilecoind/clients/python/"
    click fog/sample-paykit "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/sample-paykit/"
    click fog/test-client "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/fog/test-client/"
    click consensus/mint-client "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/consensus/mint-client/"
    click transaction/signer "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/transaction/signer/"
    click util "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/util/"
    click .github "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/.github/"
    click .internal-ci/ "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/.internal-ci/"
    click .internal-ci/helm "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/.internal-ci/helm/"
    click tools/local-network "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/tools/local-network/"
    click tools/k8s-dev "https://github.com/mobilecoinfoundation/mobilecoin/tree/main/tools/k8s-dev/"

    %% Styles
    classDef client fill:#b3e2cd,stroke:#333,stroke-width:1px
    classDef gateway fill:#ccebc5,stroke:#333,stroke-width:1px
    classDef service fill:#80b1d3,stroke:#333,stroke-width:1px
    classDef enclave fill:#fdb462,stroke:#333,stroke-width:1px
    classDef storage fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef external fill:#b2df8a,stroke:#333,stroke-width:1px
    classDef ci fill:#fb8072,stroke:#333,stroke-width:1px
```
