This is the README file for MobileCoin Fog.
- MobileCoin Fog is a prototype. Expect substantial changes before and after the release.
- Please see CONTRIBUTING.md for notes on contributing bug reports and code.
MobileCoin Fog is a privacy-preserving service designed to support use of the MobileCoin Payments Network on mobile devices.
MobileCoin Fog is available under open-source licenses. Look for the LICENSE file in each crate for more information.
This distribution includes cryptographic software. Your country may have restrictions on the use of encryption software. Please check your country's laws before downloading or using this software.
| Directory | Description |
|---|---|
| fog | Privacy-preserving services to support MobileCoin payments on mobile devices. |
| android-bindings | Bindings for android clients. |
| libmobilecoin | Library for use in SDKs to interact with MobileCoin payment primitives. |
| util | Miscellaneous utilities. |
| Target | Description |
|---|---|
fog-ingest-server |
Obliviously post-processes the blockchain to organize transaction outputs according to fog hints. |
fog-ledger-server |
Obliviously serves ledger materials such as rings, merkle proofs, and key images, used to verify whether a Txo was spent, or to construct new transactions. |
fog-report-server |
Provides the ingest enclave's Attestation Verification Report for transaction construction. |
fog-view-server |
Obliviously serves the post-processed Txos to clients who wish to check their balance and construct new transactions. |
The workspace can be built with cargo build and tested with cargo test. Either command will recognize the cargo --release flag to build with optimizations.
Some crates (e.g. fog-ingest-service) depend on Intel SGX, which adds additional build and runtime requirements. For detailed information about setting up a build environment, how enclaves are built, and on configuring the build, see BUILD.md.
For a quick start, you can build in the same docker image that we use for CI by using the mob tool. Note that this requires you to install Docker. You can use the mob tool with the following commands:
# From the root of the cloned repository
./mob prompt
# At the resulting docker container prompt
cargo build
To run the unittest tests locally, you need to start a local postgres instance, then run the tests. You can do this at the mob prompt:
# From the root of the cloned repository
./mob prompt
# Start postgres
service postgresql start
# Run the tests
cargo test
MobileCoin Fog is a suite of microservices designed to enable MobileCoin payments on mobile devices.
For MobileCoin payments to be practical, we cannot require the mobile device to sync the ledger or download the entire blockchain. However, a so-called "thin wallet" won't work either, because the types of queries made by a thin wallet generally reveal to the server the user's balance, when they got paid, etc. In typical thin wallet designs, the server is trusted by the user.
MobileCoin has been engineered to eliminate this sort of trust in the service is "oblivious" to the nature of the user requests, and the service operator is unable to harvest the users' data in exchange for running the service.
Because of this, off-the-shelf solutions to wallet services simply don't work. In many cases, if we naively make a database query to handle a query that a wallet would make if it had access to the ledger, it reveals significant information about e.g. whether Bob was paid or not in the last block, which payments Bob received, whether Alice paid Bob, etc., any of which would not meet our privacy goals.
Instead, Fog makes heavy use of SGX enclaves and Oblivious RAM data structures to serve such queries privately and without compromising scalability. Although such use of SGX may create potential operational challenges, the MobileCoin system has been carefully designed to navigate these challenges.
Fog works by post-processing the blockchain in an SGX-mediated way. Records are written to a database (the "recovery database") which contains the entirety of information that a user needs to recover all of their transactions privately.
Fog consists of four services:
-
The "fog-ingest" service consumes and post-processes the blockchain, writing records to the recovery database. This is an SGX service. It additionally publishes a public key to the "fog-report" service.
-
The "fog-view" service provides an API for fog users to access this database. Some of the queries that the user needs to make to the database are sensitive. To protect them, this is an SGX service and some of the queries are resolved obliviously.
-
The "fog-ledger" service provides several APIs for fog users to make queries against the MobileCoin ledger. Some of the queries that the user needs to make are sensitive; SGX also provides this service, and some of the queries are resolved obliviously.
-
The "fog-report" service. The fog report service publishes a signed fog public key which comes from the fog-ingest SGX enclave. This public key must be available to anyone who wants to send MobileCoin to a fog user, so the fog report service is expected to be publicly accessible and require no authentication (the way the others probably would). In addition to the Intel report, there is an X509 certificate chain signing the report as well. The "fog-report" service is not an SGX service.
-
Is Fog decentralized?
Fog is a scalable service that helps users find their transactions, conduct balance checks, and build new transactions. Fog does so without requiring a local copy of the blockchain and without revealing a user's activities or giving away their private keys.
Fog is intended to be run by app providers to provide their users with a private and positive mobile experience. Users need only trust the integrity of SGX, and not the service provider, for their privacy.
Fog is thus not a single, decentralized network, but can be deployed as needed by each party willing to offer this service. Fog can be treated as critical infrastructure for an app, and can be scaled to meet each party's needs.
-
What is the hint field? Can I put anything in there?
The purpose of the hint field is to send an encrypted message to a fog enclave associated to the transaction, which it finds when it post-processes the blockchain. A conforming client puts only an mc-crypto-box ciphertext of a specific size there. For non-fog transactions, a ciphertext encrypted for a random public key should be put there. Putting something in the hint field which is distinguishable from this may degrade privacy.
For troubleshooting help and other questions, please visit our community forum.
You may also open a technical support ticket via email.
Intel and the Intel logo are trademarks of Intel Corporation or its subsidiaries. MobileCoin is a registered trademark of MobileCoin Inc.