From e853c2ed1d7b9a720c1c39e822f701e9f71f13bb Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Sun, 29 Sep 2024 17:08:33 -0400 Subject: [PATCH] Update main README and Getting Started (#226) --- README.md | 78 ++++++++++++++++++++++++++------- apps/transfers/README.md | 9 +++- docs/getting_started.md | 95 ++++++++++++++++++++-------------------- 3 files changed, 115 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 484154d..6519e75 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,9 @@ thread][how_to_win_friends_thread]. _**What?**_ With Quartz, data in smart contracts can be encrypted, while computation happens privately off-chain via TEEs like SGX. Each contract can control what code runs in the -enclave, when it runs, and who is permitted to run it. +enclave, when it runs, and who is permitted to run it. Quartz provides +a library for CosmWasm and for enclave development, and a CLI tool for setting +it all up. _**How?**_ At the heart of Quartz is a light-client protocol handshake between the enclave and the smart contract which gives the smart contract control over when, how, and by who @@ -33,10 +35,6 @@ See [Future Work][future_work] WARNING: Quartz is under heavy development and is not ready for production use. The current code contains known bugs and security vulnerabilities and APIs are still liable to change. -We are making it available for devleopers to start playing with and to gather -feedback on APIs and roadmap. It can be used today on CosmWasm testnets -(testnets only, with no real funds at risk!). - --- ## Docs @@ -47,36 +45,82 @@ feedback on APIs and roadmap. It can be used today on CosmWasm testnets - [Building Applications][building_apps] - How to build Quartz applications - [Future Work][future_work] - Roadmap and future work for security, flexibility, and more -p ## This Repo -This repository contains the following components - +Quartz provides developers three main tools: -### Apps +- a smart contract library (`quartz-cw`) for building SGX-aware CosmWasm contracts +- a rust library (`quartz-tee`) for building blockchain constrained SGX enclaves +- a cli tool (`quartz`) for connecting the contract and the enclave. -Example Quartz applications, including CosmWasm smart contracts, Gramine based sidecar enclave, and demo front end +This repo contains an example, [`transfers`](/apps/transfers), which combines these +tools into a working private transfers application, complete with a Keplr-based +frontend. -Currently implemented apps - +### Smart Contract Lib -* [Transfer](/apps/transfers) - The default transfer app which allows private transfer of assets +`quartz-cw` does two main things: -### Core +- secure session management between contract and enclave +- verify remote attestations of authorized SGX enclaves -The Quartz core implementation including - +It contains the core types for session management and for interfacing with attestations +and is the only crate the smart contract dev should have to interact with. + +App devs add the `quartz-cw` message types to their contract's messages, +and call the verify handler on attested messages. While Quartz enables +securely attested private compute off-chain, app devs are still responsible +for the on-chain data model. See [Building Apps](/docs/building_apps.md) for more. + +Under the hood, attestation verification itself is performed via two separate contracts: + +- `dcap-verifier` - standalone implementation of dcap verification as a contract using + mobilecoin's Rust libs +- `tcbinfo` - public registry contract of secure sgx processor/firmware versions to + ensure attestations are only verified from up-to-date devices + +The actual types and verification logic for attestation is further encapsulated in `quartz-tee-ra`. + +### Enclave Lib + +`quartz-tee` mirrors `quartz-cw`, in that its the enclave side of what happens +on chain. Both have to manage a secure session. Where `quartz-cw` verifies +attestionations, `quartz-tee` produces them. But additionally, `quartz-tee` must +verify the state of the blockchain so that the enclave binary is restricted to +only operate authorized commands. It does this via light-client verification. +This it does the following: + +- secure session management between contract and enclave +- collect and verify light client proofs of smart contract state +- produce remote attestations + +The underlying implementation includes the following crates: * light-client-proofs: Light client and merkle proofs for CosmWasm storage * quartz-proto: protobuf message types for quartz handshake between enclave and contract -* quartz: Intel SGX remote attestation (RA) primitives and quartz handshake logic -### CosmWasm packages +### CLI Tool -CosmWasm packages for the core Quartz framework and remote attestation verification. +The core of the `quartz` command line tool is: + +- `quartz enclave build` - build the enclave binary +- `quartz enclave start` - start the enclave binary +- `quartz handshake` - create secure session between enclave and contracts + +It also has convenience commands for building and deploying a smart +contract: + +- `quartz contract build` - build the smart contract binaries +- `quartz contract deploy` - deploy the smart contracts + +And for running everything in one go (build, deploy/start, handshake): +- `quartz dev` ### Utils -Utilities for supporting Quartz development and - +The repo contains some additional utilities for supporting Quartz development and - * [cw-prover](utils/cw-prover) - Retrieve a merkle-proof for CosmWasm state * [cycles-sync](utils/cycles-sync) - Sync obligations and setoffs diff --git a/apps/transfers/README.md b/apps/transfers/README.md index ddec718..0639649 100644 --- a/apps/transfers/README.md +++ b/apps/transfers/README.md @@ -1,9 +1,14 @@ # Transfers -This is a simple Quartz demo app. It allows users to deposit funds to a -contract, transfer them around privately within the contract's encrypted state, +This is a simple Quartz demo app, complete with Keplr-based frontend. +It allows users to deposit funds to a contract, +transfer them around privately within the contract's encrypted state, and withdraw whatever funds they have. See the [getting started guide](/docs/getting_started.md) to get it quickly setup on a local testnet without SGX or on a real testnet using an Azure SGX node. + +See this [video of an early demo of the app at the Flashbots +TEE-salon](https://www.youtube.com/watch?v=3Tv6k02zvBc&t=2517s). + diff --git a/docs/getting_started.md b/docs/getting_started.md index dfccf2b..226f340 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,16 +1,5 @@ # Quartz: Getting Started Guide ---- - -WARNING: Quartz is under heavy development and is not ready for production use. -The current code contains known bugs and security vulnerabilities and APIs are still liable to change. - -We are making it available for devleopers to start playing with and to gather -feedback on APIs and roadmap. It can be used today on CosmWasm testnets -(testnets only, with no real funds at risk!). - ---- - ## Table of Contents - [Introduction](#introduction) @@ -31,12 +20,13 @@ This guide will help you get up and running with an example Quartz application. ## Quick Start -For those who want to get started quickly: +For those who want to get started quickly with the example Transfers app with +mock SGX: 1. Install dependencies (Rust, wasmd or neutrond) 2. Clone the repository: `git clone ssh://git@github.com/informalsystems/cycles-quartz` 3. Install Quartz CLI: `cargo install --path cli/` -4. Deploy the example app in one command: +4. Deploy the example app in one command (enclave, contracts, secure handshake): ```bash quartz --mock-sgx --app-dir "apps/transfers/" dev \ --unsafe-trust-latest \ @@ -45,35 +35,51 @@ For those who want to get started quickly: ``` 5. Set up the frontend (see [Frontend](#frontend)) -For more detailed instructions, continue reading the following sections. +For more detailed background and instructions, read on. ## Simple Example -Quartz includes a simple example we call the `Transfer` application. It's -located in [/apps/transfers](/apps/transfers). It's a simple demo app -designed to showcase very basic use of the Quartz framework. +Quartz includes a simple example we call the `Transfer` application, +located in [/apps/transfers](/apps/transfers), that comes with a Keplr-based +frontend. It's a simple demo app designed to showcase very basic use of the Quartz framework. It allows users to deposit funds into a contract, -transfer them privately within the contract's encrypted state, -and ultimately withdraw whatever balance they have left or have accumulated. +transfer them privately within the contract's encrypted state (updated by the +enclave),and ultimately withdraw whatever balance they have left or have accumulated. -### Key Features -- Deposit funds into a smart contract -- Transfer funds privately within the contract via encrypted transactions that are handled by Quartz (ie. processed by the enclave and remote attested to). -- Withdraw funds from the contract based on balances in the encrypted state. +Every application has a common structure: -### Application Structure - -1. **Frontend**: The user interface built with Next.js, cosmjs / graz. +1. **Frontend**: The user interface (eg. Next.js, cosmjs / graz) 2. **Contracts**: The backend application as a CosmWasm smart contract 3. **Enclave**: Code that executes off-chain and privately in an enclave +Quartz is both a library (`quartz-cw`) for building SGX-aware CosmWasm +contracts, and a cli tool (`quartz`) for managing the enclave. + +The library takes care of establishing a secure connection to the enclave (see +[How it Works](/docs/how_it_works.md), and verifying attestations from +it. The quartz tool provides commands for managing the enclave. + +This guide is primarily about using the `quartz` tool to get the example app +setup. For more on building application, see +- [Building Apps](/docs/building_apps.md) - conceptual overview +- [quartz-cw](/cosmwasm/quartz-cw) - main library. provides msgs and handlers + for the handshake and for verifying attestations +- [transfers contracts](/apps/transfers/contracts): transfer app example itself + +Onwards with the installation and running our example app! + ## Installation -Quartz is built in Rust and requires an up-to-date version with the -wasm32 target to be installed. It also expects the system to have a -CosmWasm-compatible Cosmos-SDK blockchain client installed, for instance `wasmd` -or `neutrond`. CosmWasm binaries can be built with `Go` or downloaded from their -developers. Finally, you'll need `npm` to build the frontend. +Quartz is built in Rust (+wasm32 target). It expects to interact with a CosmWasm compatible +blockchain (eg. `wasmd` or `neutrond`), built in Go (or run with Docker). And it requires `npm` for +building the frontend. Here we cover how to install Rust, Quartz, and CosmWasm +blockchains. You're responsible for installing Go and NPM. + +Pre-reqs: +- Git +- Make +- Go or Docker +- NPM ### Install Rust @@ -81,15 +87,11 @@ The minimum Rust supported version is v1.74.1. The recommended Rust version v1.79.0 since we're running against wasmd v0.45. -Install rust by executing a script from the internet (😅): - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` +Install rust [here](https://www.rust-lang.org/tools/install). Check the version with `cargo version`. -Finally add the wasm target: +Add the wasm32 target: ```bash rustup target add wasm32-unknown-unknown @@ -97,7 +99,6 @@ rustup target add wasm32-unknown-unknown And you should be good to go! - ### Install Quartz Now clone and build the repo: @@ -123,7 +124,7 @@ testnet). In either case, you can build from source in Go or use a docker container. -The docker containers come with preconfigured keys and balances. If you use the +The docker containers come with preconfigured keys and account balances. If you use the Go binaries you'll have to set up keys and balances yourself. To build from source, first make sure you have Go installed. @@ -133,7 +134,7 @@ Then for `wasmd`: ```bash git clone https://github.com/cosmwasm/wasmd/ cd wasmd -git checkout v0.44.0 +git checkout v0.45.0 go install ./cmd/wasmd ``` @@ -142,10 +143,11 @@ Or for `neutrond`: ```bash git clone -b main https://github.com/neutron-org/neutron.git cd neutron +git checkout v4.0.0 make install ``` -To use the docker images, install and set up docker. +To use the docker images instead, install and set up docker. Then for wasmd`: @@ -161,7 +163,7 @@ cd docker/neutron make start-docker-container ``` -If using docker it will pre-configure a few keys and allocate funds to them. +If using docker it will pre-configure a few keys (admin, alice, etc.) and allocate funds to them. If building from source, you'll need to initialize the accounts yourself. See the guide on [setting up a CosmWasm chain](/docs/wasmd_setup.md) and then return @@ -177,12 +179,9 @@ transfers app. Deployment involves three components: - the smart contract - the front end -Quartz provides a `dev` command to simplify building and running the enclave and smart contract in a single command. -Use of the `dev` command was shown in the [quick start](#quick-start) section -above. Here we show the individual steps and quartz commands that allow devs to -independently build and run the encalve, to build and deploy the contract, -and to perform the quartz handshake between running enclave and deployed -contract. +We can deploy the enclave and contract all at once using the `quartz dev` +convenience command (like in the [quick start](#quick-start)), but here we'll +show the individual commands. ### Enclave