How mobilecoinfoundation/mobilecoin works
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.