Testing your first payment

• Please see TESTNET.md for instructions on participating in the TestNet!

Sending your first payment

• Please see MAINNET.md for instructions on using MobileCoin!
• You must read and accept the Terms of Use for MobileCoins and MobileCoin Wallets to use MobileCoin Software.

Note to Developers

• Please see CONTRIBUTING.md for notes on contributing bug reports and code.

MobileCoin

MobileCoin is a privacy-preserving payments network designed for use on mobile devices.

Table of Contents

• License
• Cryptography Notice
• Repository Structure
• Build Instructions
• Overview
• FAQ
• Support

License

MobileCoin is available under open-source licenses. Look for the LICENSE file in each crate for more information.

Cryptography Notice

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.

Repository Structure

Directory	Description
attest	Remote attestation primitives.
build-info	Measurements made at compile time.
common	Items shared across MobileCoin crates.
consensus	Byzantine Fault Tolerant Consensus.
crypto	Cryptography.
enclave-boundary	Intel® SGX ECALL infrastructure.
fog	Private payments for mobile devices
ledger	Storage and synchronization for the MobileCoin blockchain.
mcbuild	Tools for building and signing enclaves.
mcconnection	Attested MobileCoin connections.
mobilecoind	Blockchain daemon and example client code.
peers	Peer-to-peer networking.
sgx	Support for Intel® Software Guard eXtensions (Intel SGX).
transaction	Private transactions.
util	Miscellaneous utilities.

Selected Binaries

Target	Description	Used by...
consensus-service	Validates new transactions for the public ledger.	Validator Nodes
ledger-distribution	Publishes the ledger to long-term storage.	Full Validator Nodes
mobilecoind	Synchronizes the ledger and provides the desktop API.	Watcher and Validator Nodes

Build Instructions

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 (for example consensus-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, 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

Overview

MobileCoin is a payment network with no central authority. The fundamental goal of the network is to safely and efficiently enable the exchange of value, represented as fractional ownership of the total value of the network. Like most cryptocurrencies, MobileCoin maintains a permanent and immutable record of all successfully completed payments in a blockchain data structure. Cryptography is used extensively to establish ownership, control transfers, and to preserve cash-like privacy for users.

Here we review a few design concepts that are essential for understanding the software.

Transactions

The MobileCoin blockchain is the source of truth for the allocation of value. It consists of an ordered collection of transaction outputs, organized into blocks. Each transaction output ("txo") has a unique corresponding construction called a key image. Every txo initially appears in the blockchain in a spendable state, as an unspent transaction output or utxo. Every successful payment consumes some utxos as inputs and creates new utxos as outputs. When a utxo is consumed, its corresponding key image is permanently added to the blockchain, ensuring that it can not be spent a second time.

The total value of the MobileCoin network is fixed by convention at a sum of 250 million mobilecoins. Each mobilecoin consists of 10¹² indivisible parts, each referred to as one picomob. Each utxo represents an integer number of picomob that can be consumed in a valid payment.

Ownership of a utxo in the MobileCoin network is equivalent to knowledge of two private keys, called the spend private key and the view private key, that provision control over discovery and transfer of value. Most users will derive these two private key values from a single underlying key we call the root entropy.

To receive a payment, a user must calculate the two public key values corresponding to their private keys to share with their counter-party. MobileCoin specifies a standard encoding scheme using a base-58 symbol library for users to safely exchange payment information.

For more information on how transactions work, and how they use CrytpoNote-style transactions to preserve privacy of both the sender and receiver, see the transaction crate.

To understand the blockchain format and storage, see the ledger_db crate.

Consensus

New transactions must be checked for attempts to counterfeit value before new key images and utxos can be added to the MobileCoin blockchain. Transactions are prepared by the user on their local computer or mobile device, and submitted to a secure enclave running on a validator node of their choice. The validator node checks the transaction and, assuming it believes the transaction is valid, shares it with other nodes in the MobileCoin network. The transaction is passed only to peer secure enclaves that can establish via remote attestation that they are running unmodified MobileCoin software on an authentic Intel processor. Each secure enclave replicates a state machine that adds valid transactions to the ledger in a deterministic order using a consensus algorithm called the MobileCoin Consensus Protocol.

The MobileCoin Consensus Protocol is a high-performance solution to the byzantine agreement problem that allows new payments to be rapidly confirmed. The consensus-service target binary uses Intel Software Guard eXtensions (Intel SGX) to provide defense-in-depth improvements to privacy and trust.

To learn how MobileCoin uses Intel SGX to provide additional integrity in Byzantine Fault Tolerant (BFT) consensus as well as forward secrecy to secure your privacy, see the consensus/enclave crate. To build and run consensus, see the consensus/service crate.

Full validator nodes additionally use the ledger-distribution target binary to publish a copy of their computed blockchain to content delivery networks (currently to Amazon S3 only). The public blockchain is a zero-knowledge data structure that consists only of utxos, key images and block metadata used to ensure consistency and to construct Merkle proofs. To build and run ledger distribution, see the ledger/distribution crate.

Watcher nodes perform an essential role in the MobileCoin network by verifying the signatures that the full validator nodes attach to each block. In this way the watcher nodes continuously monitor the integrity of the decentralized MobileCoin network. A watcher node also maintains a complete local copy of the blockchain and provides an API for wallet or exchange clients.

To run a watcher node, build and run the mobilecoind daemon.

FAQ

1. What is the impact of an Intel SGX compromise on transaction privacy?

   Secure enclaves can provide improved integrity and confidentiality while functioning as intended. Like most complex new technologies, we should anticipate that design flaws will inevitably be discovered. Several side channel attacks against secrets protected by Intel SGX have been published, and subsequently patched or otherwise mitigated. MobileCoin is designed to provide "defense in depth" in the event of an attack based on a secure enclave exploit. MobileCoin transactions use CryptoNote technology to ensure that, even in the clear, the recipient is concealed with a one-time address, the sender is concealed in a ring signature, and the amounts are concealed with Ring Confidential Transactions (RingCT).

   In the event of an Intel SGX compromise, the attacker's view of the ledger inside the enclave would still be protected by both ring signatures and one-time addresses, and amounts would remain concealed with RingCT. These privacy protection mechanisms leave open the possibility of statistical attacks that rely on tracing the inputs in ring signatures to determine probabilistic relationships between transactions. This attack is only applicable to transactions made during the time that the secure enclave exploit is known, but not patched. Once the Intel SGX vulnerability is discovered and addressed, statistical attacks are no longer possible, therefore forward secrecy is preserved.

2. Can I run a validator node without Intel SGX?

   You can run the consensus-service using Intel SGX in simulation mode, however you will not be able to participate in consensus with other validator nodes. Your software measurement will be different from hardware-enabled Intel SGX peers and remote attestation will fail.

3. Can I run a watcher node without Intel SGX?

   Yes, you can operate a watcher node and validate block signatures by running the mobilecoind daemon, which does not require Intel SGX.

4. I thought you were called MobileCoin. Where is the code for mobile devices?

   Please see fog, android-bindings, and libmobilecoin, to see how the balance checking and transaction building process works on mobile devices that don't sync the ledger.

   Please see also the MobileCoin Android and iOS SDKs, which can be integrated into your app to enable MobileCoin payments.

5. Will I need to put my keys on a remote server to scan the blockchain for incoming transactions?

   Keys will never leave your mobile device. For more details on how this works, please see the MobileCoin Fog README.

Support

For troubleshooting help and other questions, please visit our community forum.

You can also open a technical support ticket via email.

Trademarks

Intel and the Intel logo are trademarks of Intel Corporation or its subsidiaries. MobileCoin is a registered trademark of MobileCoin Inc.