*** Update as of 10/9/19: This guide is not up to date with the latest release of Enigma’s protocol. Please read through our new (and very improved) Developer Quickstart Guide! ***

Hello to the community! With the recent launch of our public protocol testnet, we’ve had a lot of interest from developers looking to get started building secret contracts. Below is our first full “Getting Started” guide. By the time you finish it, you’ll be much better acquainted with our platform and technology — and hopefully very excited!

At Enigma, our mission is to build the first platform for scalable, privacy-preserving smart contracts, which will enable end-to-end decentralized applications. Centralized applications, acting as single points of trust and consequently single points of failure, open themselves up to data breaches, identity theft, and other manifestations of security violations. Decentralized applications work to mitigate these issues, but unfortunately can’t do so in a scalable, privacy-preserving manner. With the launch of Enigma Testnet 1.0, we had provided developers with the first taste of writing secret contracts and dApps that interact with them.

What follows is an end-to-end walkthrough guide exploring Yao’s Millionaires’ Problem. For those of you unfamiliar with this particular #firstworldproblem, it was introduced in the early 80’s by Andrew Yao, and studies the scenario where two millionaires (Alice and Bob) want to know which one of them is richer without ever revealing his or her net worth to one another. The goal of this guide is to demonstrate how you can quickly:

get the testnet set up write your first secret contract construct a simple React front-end dApp to interact with your contract

Let’s get started!

Full Demo

If you want to see how this will all look as you walk through the steps of this guide, check out the below video before or after you go through everything!

Setting up the Testnet

In this first section, I’ll walk through how you can get started using Enigma’s new Simulation Mode, which allows for development on machines without SGX hardware. (Note that this current iteration of our protocol utilizes secure hardware as its primary privacy solution, namely Intel SGX.) I recommend having a terminal window open with two separate tabs labeled dapp and network corresponding to two different repositories which you will clone shortly: enigma-template-dapp and enigma-docker-network .

In the dapp tab, clone the enigma-template-dapp repo by running: git clone https://github.com/enigmampc/enigma-template-dapp.git . Still in the dapp tab, install some NPM packages: in BOTH the root level of this repo and the client/ folder, run yarn to install the necessary packages. While you’re at it, install the darq-truffle package with the following command: npm install -g [email protected] . In the network tab, clone the enigma-docker-network (containerized environment with the Enigma protocol minimum viable testnet) by running: git clone https://github.com/enigmampc/enigma-docker-network.git .

4. If you are running MacOS, you will need to install xterm (already comes by default in Linux distributions). You can achieve this by installing XQuartz with these instructions. After installation, make sure you log out and back in, or reboot your machine.

5. Still within the network tab, launch the Enigma docker network with: ./launch.bash -s -t . The -s flag runs the Enigma network in simulation mode (SGX simulated in software instead of being run in the actual hardware) and the -t is a highly-recommended flag that spawns separate xterm shells for each service:

contract : holds business logic for Enigma network

: holds business logic for Enigma network core : responsible for core component operations that run inside SGX enclave (includes remote attestation, cryptography, and VM)

: responsible for core component operations that run inside SGX enclave (includes remote attestation, cryptography, and VM) surface : handles operations outside of SGX, bridging gap between outside world and the core component

One thing to note is this step will actually deploy the Enigma contract and Enigma Token contracts to the docker network. The contract addresses will be needed by the dapp, and thus are hosted at http://localhost:8081 and http://localhost:8082 , respectively. We’ll go over this later if this is confusing. This step will take about 10–15 minutes the very first time you run it, but will be super quick (just a matter of seconds) from there on out!

6. After the three xterm services described above launch, switch to the dapp tab. Make sure you are within the client/ folder, and run: npm run start . This should automatically launch the template dapp. If successful, you should see a page that looks like this:

If you aren’t seeing this, and instead seeing a message that tells you that the setup is still loading, try repeating the steps above to make sure nothing went wrong!

I know this page isn’t terribly exciting, but what is exciting is that you are now proficient at setting up the network for development. If you ever need to bring down the docker network, from within the network tab, bring down the services with the command ./launch.bash -q . As a heads up, you can run this command without worrying about all the stuff printing in this shell beforehand, as it’s merely outputting information from other background processes. To start things back up again, just repeat steps 5 and 6 from above. You’re all set up now to write your own secret contracts and fancy dApp to interact with them, so we are ready to move on!

Writing a Secret Contract

Secret contracts are smart contracts that execute on the decentralized network without revealing input data, ensuring data privacy. Secret contracts are written in a programming language called Solidity, and are implemented very similarly to Ethereum-based smart contracts. We recently published a walkthrough exploring a secret voting contract on Enigma.

From here on out, you will be only working with the enigma-template-dapp repo you cloned above. Although you still keep it running, you shouldn’t need to work with the enigma-docker-network repo anymore! Thus, in the enigma-template-dapp repo, inside the contracts/ folder, create a new file called MillionairesProblem.sol and paste the following contract code (comment-annotated for explanatory purposes) in there:

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

As mentioned above, the design principles and syntax (state variables, structs, constructors, functions, events, modifiers, etc.) are basically the same as smart contracts for Ethereum. The major keys to note here are the bottom two callable and callback functions.

Callable : This is a public function that runs the secret computation inside the SGX enclave. Note that it’s a pure function because it does not actually read from nor write to contract state — it computes only off of the arguments that are passed into it. We’ll go over this further later, but what’s really cool is that although you pass in encrypted values via the front end, the decryption automatically occurs within this function. The original types are inferred based on the argument types specified in the function signature. In the case of this computeRichest callable example, we pass in encrypted arguments _addresses and _netWorths , but specify types address[] and uint[] respectively. These arguments are decrypted automatically accordingly. We can now determine the index of the highest net worth and retrieve/return the decrypted address at the same index. This decrypted address is to be used as the input for the callback function.

: This is a public function that runs the secret computation inside the SGX enclave. Note that it’s a function because it does not actually read from nor write to contract state — it computes only off of the arguments that are passed into it. We’ll go over this further later, but what’s really cool is that although you pass in encrypted values via the front end, the decryption automatically occurs within this function. The original types are inferred based on the argument types specified in the function signature. In the case of this callable example, we pass in encrypted arguments and , but specify types and respectively. These arguments are decrypted automatically accordingly. We can now determine the index of the highest net worth and retrieve/return the decrypted address at the same index. This decrypted address is to be used as the input for the callback function. Callback: This is a public function automatically called by the worker (note the onlyEnigma() modifier) after the callable function is completed. It is responsible for committing the results and altering the contract state. Be sure that the input arguments for the callback directly match to the output values you’ve returned in the callable function. In this example, we input the _address we’ve obtained from the callable, store it as the richestMillionaire state variable, and emit the CallbackFinished event. This event emission is critical here, because you can set up an event watcher in your front end to react appropriately upon completion of the secure computation task.

We will also employ a contract factory design pattern so you can easily create new fresh instances of the MillionairesProblem. From the contracts/ folder you just saved the last contract in, create a new contract called MillionairesProblemFactory.sol and paste the following code:

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

At this point, you’ve written all the solidity code you need to. All you have to do is write the migration script that will deploy the MillionairesProblemFactory contract (you won’t need to deploy the MillionairesProblem because we will create new instances of this contract from the factory, as shown in the snippet above). From within the migrations/ folder, create a script called 2_deploy_millionaires_problem_factory.js and paste the following:

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

For those of you familiar with dapp development, this migration script might look a little different than you’re used to. The key idea here is that we need to pass in the address of the Enigma contract that has already been deployed when we launched the docker container. As mentioned above, that process hosts the address at http://localhost:8081 , allowing us to read this in and deploy a fresh MillionairesProblemFactory instance with this address as an argument.

Any time you create new contracts like you have in this case, or modify existing ones, make sure you redeploy to the network with the following command: darq-truffle migrate --reset --network development .

Sweet! To recap, in this section, you’ve covered writing secret contracts and what separates them from traditional smart contracts (callable and callback functions), structuring your migration scripts to pull in the Enigma contract address, and deploying your custom secret contracts. Now you’re ready to move on to the next part — building your own front end!

Creating a React Front End for your Secret DApp

As with the previous part, we’ll only be working with the enigma-template-dapp repository from here on out. We’ll be building a simple React front end for the Millionaires’ Problem. For those of you unfamiliar with React, it’s a JavaScript library for building user interfaces through a stateful component-driven approach and I highly recommend you check out a quick tutorial to get familiar with some basic concepts, such as state, props, components, JSX, etc.

As a further aside, the enigma-template-dapp repo you’ve cloned is based off of a truffle-react box variant. This boilerplate is an excellent way to rapidly build your unique dapp, with the front-end packages and logic cleanly separated from the rest of the code, located inside the client/ folder. All of the code you’ll be writing will be located within client/src . There are a couple of directories that you won’t have to touch, but since it doesn’t hurt to know what’s going on/why they’re here, I’d like to briefly point them out:

contract — symlink to the build/contracts folder at the root level of this repo (this is a side-effect of a drawback of create-react-app based projects, and is an area of active development).

— symlink to the folder at the root level of this repo (this is a side-effect of a drawback of create-react-app based projects, and is an area of active development). lib — the ABIs for the Enigma and EnigmaToken contracts are located here. We have the addresses hosted on the ports (8081 and 8082) discussed above, but in order to interact with this contract, we need the ABIs as well, and thus they are stored in this folder for convenience. The Enigma.js library is also used, which is a Javascript library to interface with the Enigma protocol.

— the ABIs for the Enigma and EnigmaToken contracts are located here. We have the addresses hosted on the ports (8081 and 8082) discussed above, but in order to interact with this contract, we need the ABIs as well, and thus they are stored in this folder for convenience. The library is also used, which is a Javascript library to interface with the Enigma protocol. test — impersonates the principal node, which will be deprecated in the next release, but is needed for now.

— impersonates the principal node, which will be deprecated in the next release, but is needed for now. utils — handles getting the proper web3 provider, truffle-wrapped contract, and an EnigmaSetup object that contains the generic, non dapp-specific requirements (web3, accounts, Enigma and EnigmaToken contracts, and enigma and principal library wrappers).

There are three files we’ll be updating/adding: App.js , MillionairesProblemWrapper.js , and AddMillionaireDialog.js . All of these files are just within the client/src directory. As a heads up, most of the code below is generic, React code that doesn’t have to do with interfacing with the Enigma secret contracts you’ve written above; I’ve made special note of the portions that are especially unique.

App.js (already exists, you will need to update this)

This is essentially the root page, which will handle:

initialization of all the EnigmaSetup object [lines 28–29] mentioned above and the top-level rendering of the app

object [lines 28–29] mentioned above and the top-level rendering of the app pulling in the contract ABIs for our custom contracts [lines 4–5] and appropriately setting the state for the current MillionairesProblem if it exists [lines 35–48]

Copy and paste the following comment-annotated code.

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

MillionairesProblemWrapper.js (you will need to create this)

This component drives the business logic for the MillionairesProblem that’s being rendered and handles:

the logic to addMillionaire (committing encrypted values for the address and net worth to the contract) [lines 51–66]

(committing encrypted values for the address and net worth to the contract) [lines 51–66] rendering the current state of the contract (number of participants, richest address) [lines 145–146]

the enigmaTask (in charge of executing the secret computation, running the callable and callback functions with the encrypted arguments necessary) [lines 68–109]

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

AddMillionaireDialog.js (you will need to create this)

This file is a material-ui-driven dialog script which handles:

inputting address and net worth [lines 48–56]

triggering the addMillionaire callback from the above file, which commits the encrypted address and net worth to the active MillionaireProblem contract [lines 58–71]

Copy/paste the following code!

*** UPDATE as of 10/9/19: Please see the New Quickstart Guide***

There you have it! That’s all for the front-end portion of the project. The vast majority of the code in this section is general, Enigma-agnostic React code. For those of you unfamiliar with React and front-end development, it’s worth spending time looking through the code in its entirety to get familiar with the concepts. For the rest of you, the really important parts of this are mostly within the MillionairesProblemWrapper.js file, where we send the encrypted addresses and net worths to the MillionaireProblem contract, retrieve complete arrays of encrypted data from the contract to be used in the computation task, and run the enigmaTask to execute the callable and callback functions of the secret contract.

The full source code for the demo app you’ve built can be found here.

Conclusion

Congratulations! In this walk-through guide, you successfully got the Enigma Testnet up and running, created your own secret contracts, and built a React-based front end to interact with the network. The Enigma framework, enabling both privacy and scalability for decentralized applications, allows for truly viable, disruptive dApp design and implementation. Now that you’ve gotten a taste of how it all works, feel free to build even more complex applications that really harness the power of the Enigma network. Then, let us know about your work on our Developers Forum! We can’t wait to see what you build.

Have any feedback on this post? Leave a comment below.

Thanks to Celeste and the Enigma Ambassadors for helping us test this guide!