docs: Quartz initial docs (#183)

Addresses, but does not close #166

Co-authored-by: Dave Kaj <davidkajpust@informal.systems>

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

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

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
+

docs/how_it_works.md

@@ -0,0 +1,5 @@
+# How It Works
+
+Describe security model.
+
+Light clients, remote attestation, merkle proofs, ZKPs

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)

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.)
+