Update main README and Getting Started (#226)
This commit is contained in:
Ethan Buchman
GitHub
parent
66c5ef130f
commit
e853c2ed1d
3 changed files with 115 additions and 67 deletions
78
README.md
78
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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue