docs: how it works and building apps (#213)

README.md

@@ -83,10 +83,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 TBD
 
 [cycles]: https://cycles.money
-[getting_started]: ./docs/getting_started.md
+[getting_started]: /docs/getting_started.md
-[how_it_works]: ./docs/how_it_works.md
+[how_it_works]: /docs/how_it_works.md
-[building_apps]: ./docs/building_apps.md
+[building_apps]: /docs/building_apps.md
-[tees]: ./docs/tees.md
+[tees]: /docs/tees.md
-[future_work]: ./docs/roadmap.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

@@ -1,6 +1,24 @@
 # Building Applications
 
-Quartz application developers need to write code for two kinds of environments: smart contracts and TEEs. 
+Quartz is a framework for building private applications using TEEs. 
+It allows app devs to establish secure communication with TEEs
+and to manage what codes run on what data, and when. 
+
+---
+WARNING:
+
+Quartz provides utilities for secure communication with TEEs,
+but it DOES NOT specify a data model for applications. This gives application
+devs great power and flexibility, but with this power comes great
+responsibility. App devs must remain dilligent to ensure their data model does
+not leak private information (or leaks only what they are comfortable with). 
+
+The Quartz framework intends to provide better tools and patterns for securely
+working with private data, for instance via ORAM.
+
+---
+
+With Quartz, app devs 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.
@@ -8,35 +26,74 @@ TEE code is written in Rust and compiled via Gramine to run on Intel SGX enclave
 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, but can be (practically) arbitrary Rust.
 
-## Enclave Code
+See the [transfers app][transfers_app] for a very simplistic example of a quartz
+application.
 
-... 
+For background on basic TEE components and how Quartz works, see [How it
+Works][how_it_works].
 
 ## Smart Contract Code
 
-The logic of a Quartz smart contract is divided roughly between the following domains:
+A Quartz smart contract must specify:
 
-- 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)
+- how private requests are queued for TEE execution 
-- private business logic - this is business logic that executes in the TEE on data that is encrypted on-chain.
+- how private state is managed
-- public control logic - this is the logic that controls the enclave - who runs it, what code it runs, when it runs, etc.
+- how TEE responses (both public and private) are executed 
+- how TEE operators are managed and authorized
 
-Each of these three logic written by application developers in the smart contract.
+Private requests should be encrypted to authorized TEE keys and queued for
+execution at some frequency by the TEE.
 
-## Public Business Logic
+Private state should be managed in such a way that accessing/updating it does
+not unecessarily leak private information.
 
-Certain parts of contract logic will always remain independent of Quartz and written as normal in the given smart contract environment. 
+Public responses can be executed directly on-chain (e.g. public balance
-This might include certain deployment, ownership, or contract upgrade logic. 
+changes), while private responses can be executed by verifying remote
-It could be certain governance or administrative logic that is intended to be public regardless. 
+attestations and zero-knowledge proofs generated by the TEE. App devs must take
-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.
+care that execution of responses does not accidentally leak more information
-The most common example of this is existing transparent account balances, which can only be brought into a Quartz enabled smart contract 
+than they desire.
-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
+TEE operators and the code they run should be managed via some registration procedure.
 
-This is the core business logic that must be executed privately. It comprises roughly 3 components:
+Like any CosmWasm application, a Quartz application defines a set of messages
+and handlers for them.
 
-- on-chain queueing of private inputs
+Quartz provides message types and handlers for the handshake messages to
-- off-chain execution of code in an enclave
+abstract them away from developers. It also provides types to specify that
-- on-chain processing of results
+certain messages should include a remote attestation (RA) that must be verified.
 
-## Public Control Logic
+As noted in [How it Works][how_it_works], RA depends on info about the Trusted Computing
+Base (TCB). This is implemented as a separate TCBInfo contract. The TCBInfo
+contract is a public good that can be used by many different instances of
+Quartz, and a production version is best instantiated and maintained on a
+central coordination blockchain (e.g. the Cosmos Hub).
+
+DCAP verification is also implemented as its own independent contract, to reduce
+contract code size. Verification is thus performed by calling the DCAP contract.
+
+## Enclave Code
+
+A Quartz enclave must listen for events from the blockchain to act upon. Quartz
+provides a websocket handler for doing so. App devs can define what events to
+listen for and how to respond to them (this must be coordinated with the events
+emitted by their smart contract).
+
+The enclave code must then specify what data is to be fetched from the
+blockchain for execution. This data must be verified via light client proofs.
+It is the app dev's responsibility to ensure these proofs are correctly fetched and
+verified. This ensures the enclave has permission from the contract to execute specific data. It can also ensure
+that the enclave operates on a full set of data (ie. no requests were
+excluded), providing censorship resistance.
+
+The enclave code can then decrypt data and execute according to
+app-specific logic. 
+
+Enclaves can maintain their own local private state through SGX sealed files
+(TODO).
+
+The enclave code can then produce a remote attestation of the result, and
+optionally a zero-knowledge proof (ZKP) of execution.
+
+
+[transfers_app]: /apps/transfers
+[how_it_works]: /docs/how_it_works.md

docs/how_it_works.md

@@ -1,5 +1,91 @@
 # How It Works
 
-Describe security model.
+Quartz establishes a secure light-client based session between a smart
+contract and a TEE via a handshake protocol. This registers the TEE with the
+contract and the contract with the TEE. Data can then be encrypted to the TEE and 
+submitted to the contract, and the contract can control when the TEE runs and on
+what data. All communication with the TEE is done via 
+a light-client based round-trip with the blockchain. 
 
-Light clients, remote attestation, merkle proofs, ZKPs
+The main goal is to prevent grinding or replay attacks on the TEE - the ability
+for an operator to re-run execution many times on the same data, in an effort to
+leak information. The basic idea is that all execution on the
+TEE is gated by verifying light client proofs from the blockchain that give the
+enclave permission to execute.
+
+To do this, the contract must be able to verify that specific code is running on the TEE,
+that a specific TEE instance is running (with that code), and that that TEE instance
+generated a specific decryption key. This is all achieved by the Quartz
+Handshake. 
+
+Following the handshake, app-specific execution can proceed in the enclave in a
+controlled manner.
+
+First, some basic concepts.
+
+## Basic Concepts
+
+In SGX land, the hash of the code that will run on the enclave is called
+`mr_enclave` (for enclave "measurement")
+
+Verifying that the code with a given `mr_encalve` executed on an SGX device is
+called `remote attestation` (RA).
+
+Intel's latest standard for remote attestation is called DCAP (Data Center
+Attestation Primitives)
+
+DCAP verification is basically verification of an x509 certificate
+chain of signatures from Intel and from the given SGX device.
+
+Secure DCAP verification depends on an up-to-date index of SGX versions (microcode and software)
+and their security status (i.e. whether they are out-dated or need a security
+update). This index is called the Trusted Computing Base (TCB). A valid DCAP signature must be generated by 
+an SGX version that is up-to-date according to the TCB info.
+
+To establish a secure session between a smart contract and a TEE, Quartz
+performs a handshake where the smart contract
+verifies remote attestations from the TEE, and the TEE verifies light client proofs from the smart contract.
+
+## Handshake
+
+The goal of the handshake is to establish:
+
+- specific code is running on the TEE (given by an `mr_enclave`)
+- a specific TEE is running (given by a `nonce`)
+- the TEE has a speciifc decryption key (given by a `pubkey`)
+
+This is done in three corresponding steps:
+
+- Instantiate
+- SessionCreate
+- SessionSetPubKey
+
+In `Instantiate`, the smart contract is configured with a given `mr_enclave` and with the
+light client parameters for verification (ie. weak subjectivity initialization).
+This is a trusted initialization phase that requires off chain social consensus
+to align on valid code to run and on legitimate light client initialization. The
+`mr_enclave` should correspond to audited code with reproducible builds.
+
+In SessionCreate, a nonce is generated on the TEE and remote attests to it. The smart
+contract verifies the RA and that it was produced from the correct `mr_encalve`,
+and stores the nonce.
+
+In SessionPubKey, the TEE verifies a light client proof that the nonce was
+stored in the contract, generates an encryption key pair, and remote attests to
+the nonce and pubkey. The smart contract verifies the RA and that the nonce is the same and stores the pubkey.
+
+The TEE is now ready to process requests encrpyted to the pubkey.
+
+## Execution
+
+After the handshake, encrypted requests can be submitted to the smart contract,
+encrypted to the TEE's now registered pubkey. At whatever cadence defined by the
+contract, the TEE can fetch the encrypted requests, verify a light client proof of the requests and
+the contracts authorization for the TEE to process them, decrypt the requests, and perform
+some computation. 
+
+The TEE can then remote attest to the results, and optionally produce a
+zero-knowledge proof (ZKP) of the whole execution.
+
+The smart contract can then verify the RA and the ZKP. The ZKP provides
+additional guarantees of the correctness of the execution performed by the TEE.