diff --git a/README.md b/README.md index 3b2ace0..3964cb2 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,61 @@ -# cycles-quartz +# Quartz -A Rust implementation of the cycles protocol and the Quartz app framework. +Quartz is a flexible framework for privacy-preserving computation via Trusted Execution +Environments (TEEs) organized and secured by smart contracts. + +_**Why?**_ Development of Quartz was motivated by the privacy needs of the [Cycles Protocol][cycles]. +It is designed to be more broadly useful. For background on how to think about different privacy preserving +technologies (FHE vs MPC vs ZKP vs TEE), see [How to win friends and TEE-fluence +people][how_to_win_friends_talk] and the associated [tweet +thread][how_to_win_friends_thread]. + +_**What?**_ With Quartz, data in smart contracts can be encrypted, while computation happens +privately off-chain via enclaves. Each contract can control what code runs in the +enclave, when it runs, and who is permitted to run it. + +_**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 +the enclave code is run. This significantly reduces the surface area of TEEs. +See [How it Works][how_it_works]. + +_**Where?**_ Quartz currently targets the CosmWasm smart contract environment and the Intel SGX enclave. +Other environments and TEEs remain for future work. + +_**Who?**_ Quartz is (currently) for any CosmWasm developer interested in adding privacy or secure off-chain compute to their contracts and applications. + +_**When?**_ Early, non-production versions of Quartz are available now for building +example applications. Production features and requirements are in development. +See [Future Work][future_work] + +## Docs + +- [Getting Started][getting_started] - Get a simple example app up and running in 5 minutes +- [How it Works][how_it_works] - How smart contracts and enclaves communicate securely +- [TEE Security][tees] - Resources on TEE security +- [Building Applications][building_apps] - How to build Quartz applications +- [Future Work][future_work] - Roadmap and future work for security, flexibility, and + more + +## This Repo This repository contains the following components - ### Apps -Quartz applications, each consisting of CosmWasm smart contracts, Gramine based sidecar enclaves and accompanying ZK -proofs. +Example Quartz applications, including CosmWasm smart contracts, Gramine based sidecar enclave, and demo front end Currently implemented apps - -* [MTCS](apps/mtcs) - The default app which implements Multilateral Trade Credit Set-off. +* [Transfer](apps/transfer) - The default transfer app which allows private transfer of assets ### Core The Quartz core implementation including - -* Core handlers and types for Quartz -* Intel SGX remote attestation (RA) primitives -* 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 + contract +* quartz: Intel SGX remote attestation (RA) primitives and quartz handshake logic ### CosmWasm packages @@ -40,12 +76,16 @@ Utilities for supporting Quartz development and - If you're interested in contributing, please comment on a relevant issue (if there is one) or open a new one! See [CONTRIBUTING.md](CONTRIBUTING.md). -## Resources - -* [Cycles website](https://cycles.money/) -* [Cycles Spec](docs/spec) -* [Quartz protobuf definitions](core/quartz-proto) ## License TBD + +[cycles]: https://cycles.money +[getting_started]: ./docs/getting_started.md +[how_it_works]: ./docs/how_it_works.md +[building_apps]: ./docs/building_apps.md +[tees]: ./docs/tees.md +[future_work]: ./docs/roadmap.md +[how_to_win_friends_talk]: https://www.youtube.com/watch?v=XwKIt5XYyqw +[how_to_win_friends_thread]: https://x.com/buchmanster/status/1816084691784720887 diff --git a/docs/building_apps.md b/docs/building_apps.md new file mode 100644 index 0000000..b718083 --- /dev/null +++ b/docs/building_apps.md @@ -0,0 +1,42 @@ +# Building Applications + +Quartz application developers need to write code for two kinds of environments: smart contracts and TEEs. + +For now, smart contract code is written in CosmWasm Rust and deployed on Cosmos-SDK chains that support CosmWasm. +TEE code is written in Rust and compiled via Gramine to run on Intel SGX enclaves. + +App devs need to design their smart contracts and their enclave code in tandem to work together. +Note that enclave code is not restricted to be CosmWasm as well, but can be (practically) arbitrary Rust. + +## Enclave Code + +... + +## Smart Contract Code + +The logic of a Quartz smart contract is divided roughly between the following domains: + +- public business logic - normal public business logic you would write if you weren't using Quartz, or for things that can't be done privately (eg. transfers from native non-private accounts) +- private business logic - this is business logic that executes in the TEE on data that is encrypted on-chain. +- public control logic - this is the logic that controls the enclave - who runs it, what code it runs, when it runs, etc. + +Each of these three logic written by application developers in the smart contract. + +## Public Business Logic + +Certain parts of contract logic will always remain independent of Quartz and written as normal in the given smart contract environment. +This might include certain deployment, ownership, or contract upgrade logic. +It could be certain governance or administrative logic that is intended to be public regardless. +Or it could be logic that cannot be handled via Quartz because it involves interaction with components of the blockchain that are already outside the Quartz environment. +The most common example of this is existing transparent account balances, which can only be brought into a Quartz enabled smart contract +in the first place via transparent on-chain logic. That said, these actions may trigger storage updates in the contract which are expected to be read by the enclave. + +## Private Business Logic + +This is the core business logic that must be executed privately. It comprises roughly 3 components: + +- on-chain queueing of private inputs +- off-chain execution of code in an enclave +- on-chain processing of results + +## Public Control Logic diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000..5eeec5e --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,14 @@ +# Getting Started + +Here you'll get quickly up and running with an example Quartz application. + +You can run this locally using a "mock" enclave (i.e. without real privacy or +attestations), or you can get access to a machine with Intel SGX enabled to run it securely. + +TODO sections: + +- Transfer Application - describe basic application +- Local Mock SGX - describe getting up and running locally with mock sgx (old demo instructions, updated with new quartz CLI) +- Real SGX - describe how to get setup quickly with SGX e.g. on Azure, and how to run the same example there +- Public Testnet - describe how to deploy on Neutron testnet + diff --git a/docs/how_it_works.md b/docs/how_it_works.md new file mode 100644 index 0000000..6e48027 --- /dev/null +++ b/docs/how_it_works.md @@ -0,0 +1,5 @@ +# How It Works + +Describe security model. + +Light clients, remote attestation, merkle proofs, ZKPs diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..856c854 --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,12 @@ +# Roadmap + +Quartz is being actively developed by Informal Systems as the core privacy +framework powering the Cycles Protocol. It is designed to be useful more +generally for providing private computation to smart contract platforms. + +- ORAM +- Forward Secrecy (Key Rotation) +- Managing State +- Multi-Solvers +- Solver Decentralization and Fault Tolerance +- Multi-Verifiers of TEEs and ZKPs (defense-in-depth) diff --git a/docs/tees.md b/docs/tees.md new file mode 100644 index 0000000..1839f24 --- /dev/null +++ b/docs/tees.md @@ -0,0 +1,10 @@ +# TEEs + +Resources on TEE security + +- Summarize Why TEEs + +- SGX Explained - with context +- List other resources with context +- Link to relevant talks/work (Andrew, Sylvain, Ethan, Xin, Davie, etc.) +