nologies/cycles-quartz
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update main README and Getting Started (#226)

Browse source
This commit is contained in:
Ethan Buchman 2024-09-29 17:08:33 -04:00 committed by GitHub
parent 66c5ef130f
commit e853c2ed1d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 115 additions and 67 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
README.md
View file

@ -12,7 +12,9 @@ thread][how_to_win_friends_thread].
_**What?**_ With Quartz, data in smart contracts can be encrypted, while computation happens _**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 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 _**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 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. 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. 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 ## 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 - [Building Applications][building_apps] - How to build Quartz applications
- [Future Work][future_work] - Roadmap and future work for security, flexibility, and - [Future Work][future_work] - Roadmap and future work for security, flexibility, and
more more
p
## This Repo ## 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 * light-client-proofs: Light client and merkle proofs for CosmWasm storage
* quartz-proto: protobuf message types for quartz handshake between enclave and * quartz-proto: protobuf message types for quartz handshake between enclave and
contract 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 ### 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 * [cw-prover](utils/cw-prover) - Retrieve a merkle-proof for CosmWasm state
* [cycles-sync](utils/cycles-sync) - Sync obligations and setoffs * [cycles-sync](utils/cycles-sync) - Sync obligations and setoffs

9
apps/transfers/README.md
View file

@ -1,9 +1,14 @@
# Transfers # Transfers
This is a simple Quartz demo app. It allows users to deposit funds to a This is a simple Quartz demo app, complete with Keplr-based frontend.
contract, transfer them around privately within the contract's encrypted state, 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. and withdraw whatever funds they have.
See the [getting started guide](/docs/getting_started.md) to get it quickly 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 setup on a local testnet without SGX or on a real testnet using an Azure SGX
node. 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).

95
docs/getting_started.md
View file

@ -1,16 +1,5 @@
# Quartz: Getting Started Guide # 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 ## Table of Contents
- [Introduction](#introduction) - [Introduction](#introduction)
@ -31,12 +20,13 @@ This guide will help you get up and running with an example Quartz application.
## Quick Start ## 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) 1. Install dependencies (Rust, wasmd or neutrond)
2. Clone the repository: `git clone ssh://git@github.com/informalsystems/cycles-quartz` 2. Clone the repository: `git clone ssh://git@github.com/informalsystems/cycles-quartz`
3. Install Quartz CLI: `cargo install --path cli/` 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 ```bash
quartz --mock-sgx --app-dir "apps/transfers/" dev \ quartz --mock-sgx --app-dir "apps/transfers/" dev \
--unsafe-trust-latest \ --unsafe-trust-latest \
@ -45,35 +35,51 @@ For those who want to get started quickly:
``` ```
5. Set up the frontend (see [Frontend](#frontend)) 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 ## Simple Example
Quartz includes a simple example we call the `Transfer` application. It's Quartz includes a simple example we call the `Transfer` application,
located in [/apps/transfers](/apps/transfers). It's a simple demo app located in [/apps/transfers](/apps/transfers), that comes with a Keplr-based
designed to showcase very basic use of the Quartz framework. 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, It allows users to deposit funds into a contract,
transfer them privately within the contract's encrypted state, transfer them privately within the contract's encrypted state (updated by the
and ultimately withdraw whatever balance they have left or have accumulated. enclave),and ultimately withdraw whatever balance they have left or have accumulated.
### Key Features Every application has a common structure:
- 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.
### Application Structure 1. **Frontend**: The user interface (eg. Next.js, cosmjs / graz)
1. **Frontend**: The user interface built with Next.js, cosmjs / graz.
2. **Contracts**: The backend application as a CosmWasm smart contract 2. **Contracts**: The backend application as a CosmWasm smart contract
3. **Enclave**: Code that executes off-chain and privately in an enclave 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 ## Installation
Quartz is built in Rust and requires an up-to-date version with the Quartz is built in Rust (+wasm32 target). It expects to interact with a CosmWasm compatible
wasm32 target to be installed. It also expects the system to have a blockchain (eg. `wasmd` or `neutrond`), built in Go (or run with Docker). And it requires `npm` for
CosmWasm-compatible Cosmos-SDK blockchain client installed, for instance `wasmd` building the frontend. Here we cover how to install Rust, Quartz, and CosmWasm
or `neutrond`. CosmWasm binaries can be built with `Go` or downloaded from their blockchains. You're responsible for installing Go and NPM.
developers. Finally, you'll need `npm` to build the frontend.
Pre-reqs:
- Git
- Make
- Go or Docker
- NPM
### Install Rust ### 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 The recommended Rust version v1.79.0 since we're running against
wasmd v0.45. wasmd v0.45.
Install rust by executing a script from the internet (😅): Install rust [here](https://www.rust-lang.org/tools/install).
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Check the version with `cargo version`. Check the version with `cargo version`.
Finally add the wasm target: Add the wasm32 target:
```bash ```bash
rustup target add wasm32-unknown-unknown rustup target add wasm32-unknown-unknown
@ -97,7 +99,6 @@ rustup target add wasm32-unknown-unknown
And you should be good to go! And you should be good to go!
### Install Quartz ### Install Quartz
Now clone and build the repo: 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. 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. Go binaries you'll have to set up keys and balances yourself.
To build from source, first make sure you have Go installed. To build from source, first make sure you have Go installed.
@ -133,7 +134,7 @@ Then for `wasmd`:
```bash ```bash
git clone https://github.com/cosmwasm/wasmd/ git clone https://github.com/cosmwasm/wasmd/
cd wasmd cd wasmd
git checkout v0.44.0 git checkout v0.45.0
go install ./cmd/wasmd go install ./cmd/wasmd
``` ```
@ -142,10 +143,11 @@ Or for `neutrond`:
```bash ```bash
git clone -b main https://github.com/neutron-org/neutron.git git clone -b main https://github.com/neutron-org/neutron.git
cd neutron cd neutron
git checkout v4.0.0
make install 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`: Then for wasmd`:
@ -161,7 +163,7 @@ cd docker/neutron
make start-docker-container 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 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 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 smart contract
- the front end - the front end
Quartz provides a `dev` command to simplify building and running the enclave and smart contract in a single command. We can deploy the enclave and contract all at once using the `quartz dev`
Use of the `dev` command was shown in the [quick start](#quick-start) section convenience command (like in the [quick start](#quick-start)), but here we'll
above. Here we show the individual steps and quartz commands that allow devs to show the individual commands.
independently build and run the encalve, to build and deploy the contract,
and to perform the quartz handshake between running enclave and deployed
contract.
### Enclave ### Enclave