Update getting started (#229)

README.md

@@ -51,7 +51,7 @@ The current code contains known bugs and security vulnerabilities and APIs are s
 Quartz provides developers three main tools:
 
 - a smart contract library (`quartz-cw`) for building SGX-aware CosmWasm contracts
-- a rust library (`quartz-tee`) for building blockchain constrained SGX enclaves
+- a rust library (`quartz-enclave`) for building blockchain constrained SGX enclaves
 - a cli tool (`quartz`) for connecting the contract and the enclave.
 
 This repo contains an example, [`transfers`](/apps/transfers), which combines these
@@ -84,12 +84,12 @@ The actual types and verification logic for attestation is further encapsulated
 
 ### Enclave Lib
 
-`quartz-tee` mirrors `quartz-cw`, in that its the enclave side of what happens
+`quartz-enclave` 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
+attestionations, `quartz-enclave` produces them. But additionally, `quartz-enclave` 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:
+`quartz-enclave` does the following:
 
 - secure session management between contract and enclave
 - collect and verify light client proofs of smart contract state
@@ -109,6 +109,9 @@ The core of the `quartz` command line tool is:
 - `quartz enclave start` - start the enclave binary
 - `quartz handshake` -  create secure session between enclave and contracts
 
+All commands support a `--mock-sgx` flag for dev/testing purposes without using
+a real SGX.
+
 It also has convenience commands for building and deploying a smart
 contract:
 

crates/cli/src/cli.rs

@@ -39,8 +39,8 @@ pub struct Cli {
     #[serde(skip_serializing_if = "is_false")]
     pub mock_sgx: bool,
 
-    /// Path to Quartz app directory
+    /// Path to Quartz app directory.
-    /// Defaults to current working dir
+    /// Defaults to current working dir.
     /// For quartz init, root serves as the parent directory of the directory in which the quartz app is generated
     #[arg(long)]
     #[serde(skip_serializing_if = "Option::is_none")]

crates/cli/src/config.rs

@@ -30,7 +30,7 @@ pub struct Config {
     #[serde(default = "default_port")]
     pub enclave_rpc_port: u16,
 
-    /// Path to Quartz app directory
+    /// Path to Quartz app directory.
     /// Defaults to current working dir
     #[serde(default = "default_app_dir", skip_serializing)]
     pub app_dir: PathBuf,

docs/getting_started.md

@@ -26,9 +26,10 @@ 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. Navigate to the example app: `cd apps/transfers`
 4. Deploy the example app in one command (enclave, contracts, secure handshake):
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" dev \
+   quartz --mock-sgx dev \
    --unsafe-trust-latest \
    --contract-manifest "apps/transfers/contracts/Cargo.toml" \
    --init-msg '{"denom":"ucosm"}'
@@ -117,37 +118,16 @@ quartz --help
 
 ### Install a CosmWasm Client
 
-For the local testnet, its simplest to use `wasmd`. 
+For the local testnet, we use `wasmd`. 
 
-For the real testnet, `neutrond` is required (the guide is for Neutron's
+For the real testnet, we use `neutrond`.
-testnet).
 
-In either case, you can build from source in Go or use a docker container.
+We quickest start, we provide docker images for both.
 
-The docker containers come with preconfigured keys and account balances. If you use the
+You can also use an existing installation if you have, or you can build from
-Go binaries you'll have to set up keys and balances yourself.
+source in Go. If so, you'll have to setup accounts that can pay gas. See [wasmd setup instructions](/docs/wasmd_setup.md)
 
-To build from source, first make sure you have Go installed.
+The docker images come with everything. To use them install and setup docker.
-
-Then for `wasmd`:
-
-```bash
-git clone https://github.com/cosmwasm/wasmd/
-cd wasmd
-git checkout v0.45.0
-go install ./cmd/wasmd
-```
-
-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 instead, install and set up docker.
 
 Then for wasmd`:
 
@@ -163,13 +143,13 @@ cd docker/neutron
 make start-docker-container
 ```
 
-If using docker it will pre-configure a few keys (admin, alice, etc.) and allocate funds to them. 
+If will pre-configure a few keys (admin, alice, etc.) and allocate funds to them. 
+The default sending account for quartz txs is `admin`. 
 
 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
 back here.
 
-
 ## Local Testnet Without SGX
 
 From the root of the `cycles-quartz` repo, we can now deploy our example
@@ -188,17 +168,20 @@ show the individual commands.
 First we build and run the enclave code. 
 Quartz provides a `--mock-sgx` flag so we can deploy locally for testing and
 development purposes without needing access to an SGX core.
-We use `--app-dir` to specify where the app code is located.
 
+We can run everything from within the `apps/transfers` dir in this repo. To run
+from elsewhere by specify a path, eg. from the root of the repo with `--app-dir apps/transfers`.
+
+Now, from `apps/transfers`:
 
 1. Build the enclave binary:
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" enclave build
+   quartz --mock-sgx enclave build
    ```
 
 2. Start the enclave:
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" enclave start
+   quartz --mock-sgx enclave start
    ```
 
 The enclave is a long running process. You'll have to open another window to
@@ -208,12 +191,12 @@ continue.
 
 1. Build the contract binary:
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" contract build --contract-manifest "apps/transfers/contracts/Cargo.toml"
+   quartz --mock-sgx contract build --contract-manifest "contracts/Cargo.toml"
    ```
 
 2. Deploy the contract:
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" contract deploy \
+   quartz --mock-sgx contract deploy \
    --contract-manifest "apps/transfers/contracts/Cargo.toml" \
    --init-msg '{"denom":"ucosm"}'
    ```
@@ -231,7 +214,7 @@ export CONTRACT_ADDRESS=<CONTRACT_ADDRESS>
 
 3. Perform the handshake:
    ```bash
-   quartz --mock-sgx --app-dir "apps/transfers/" handshake --contract $CONTRACT_ADDRESS
+   quartz --mock-sgx handshake --contract $CONTRACT_ADDRESS
    ```
 
 This will setup a secure connection between the contract and the enclave.
@@ -324,7 +307,10 @@ Once logged in, clone and install Quartz like before (see
 
 ### Build and Deploy the Contracts
 
-TODO: make this about deploying to neutron.
+TODO: 
+- make this about deploying to neutron.
+- do it from apps/transfers to avoid specifying `--app-dir`
+
 
 To build both the contract binaries, use the build command:
 

docs/wasmd_setup.md

@@ -1,80 +1,112 @@
-## CosmWasm Node Setup
+# CosmWasm Binaries: Install and Configure
 
-Here we describe how to initialize accounts and balances on a CosmWasm
+Quartz expects to interact with a CosmWasm-based blockchain. 
-blockchain.
+The default/archetypal binary is `wasmd`. We also use `neutrond` for the
+testnet.
+
+Here we describe how to get setup from scratch or how to use an existing wasmd
+binary/network you have access to.
+
+- [Install](#install)
+- [Configure from scratch](#configure-from-scratch)
+- [Configure existing](#configure-existing)
+
+## Install
+
+To build from source, first make sure you have Go installed.
+
+Then for `wasmd`:
+
+```bash
+git clone https://github.com/cosmwasm/wasmd/
+cd wasmd
+git checkout v0.45.0
+go install ./cmd/wasmd
+```
+
+Or for `neutrond`:
+
+```bash
+git clone -b main https://github.com/neutron-org/neutron.git
+cd neutron
+git checkout v4.0.0
+make install
+```
+
+## Configure From Scratch
+
+We have to initialize a new chain and load it with some accounts.
 
 We'll assume you're using `wasmd` but it could be `neutrond` or any other.
 
-We'll also assume your chain ID is `testing`.
+We also have to give the chain a chain ID. We'll use `testing`.
 
-Run `wasmd init <your name> --chain-id testing` to initialize the local wasmd
+Run 
-folder.
+
+```bash
+wasmd init <your name> --chain-id testing
+```
+
+to initialize the local wasmd folder.
 
 Now open the file `~/.wasmd/config/client.toml` and change the field
 `keyring-backend` from `os` to `test`:
 
-```toml
+```toml keyring-backend = "test" ```
-keyring-backend = "test"
-```
 
 Now, finally, we can create a local admin key for your wasmd. You'll use this to
 deploy contracts:
 
-```bash
+```bash 
-wasmd keys add admin
+wasmd keys add admin 
 ```
 
-This should output a wasm address.
+This should output a wasm address. 
 
-Now either you will setup a local testnet or use an existing testnet. If its an
+Now create the genesis file.
-existing testnet, you need to fund this account. Send this address to someone
-who has access to the admin account for your testnet. If you have access
-yourself you can send funds yourself:
 
-```bash
+```bash 
-wasmd tx bank send <sender key name> <recipient address> <amount ucosm> --chain-id testing -y
+# generate a second key for the validator 
-```
-
-If you're setting up your own local testnet, continue with the following:
-
-```bash
-# generate a second key for the validator
 wasmd keys add validator
 
-# fund both accounts in genesis
+# fund both accounts in genesis 
-wasmd genesis add-genesis-account admin 100000000000stake,100000000000ucosm
+wasmd genesis add-genesis-account admin 100000000000stake,100000000000ucosm 
 wasmd genesis add-genesis-account validator 100000000000stake,100000000000ucosm
 
-# sign genesis tx from validator and compose genesis
+# sign genesis tx from validator and compose genesis 
-wasmd genesis gentx validator 100000000stake --chain-id testing
+wasmd genesis gentx validator 100000000stake --chain-id testing 
-wasmd genesis collect-gentxs
+wasmd genesis collect-gentxs 
 ```
 
 Before finally starting the node, for it to work with the front end, you need to
 configure CORS.
 
+### Configure CORS
+
 In `~/.wasmd/config/config.toml`, you'll need to make sure the listen address
 binds to the public IP (0.0.0.0) and the CORS allows all origins:
 
-```toml
+```toml 
-[rpc]
+[rpc] 
-laddr = "tcp://0.0.0.0:26657"
+laddr = "tcp://0.0.0.0:26657" 
-cors_allowed_origins = ["*"]
+cors_allowed_origins = ["*"] 
 ```
 
 And in `~/.wasmd/config/app.toml`:
 
-```toml
+```toml 
-[api]
+[api] 
-enable = true
+enable = true 
-address = "tcp://0.0.0.0:1317"
+address = "tcp://0.0.0.0:1317" 
-enabled-unsafe-cors = true
+enabled-unsafe-cors = true 
 ```
 
 Now, finally:
 
-```bash
+## wasmd start
-wasmd start
+
+```bash 
+wasmd start 
 ```
 
 And you should have a chain making blocks!
@@ -84,3 +116,29 @@ You can also reduce the block time by lowering `timeout_commit` in
 
 Now that you have the chain running, you can start running the enclave and proxy
 in other windows.
+
+Return to the [getting started guide](/docs/getting_started.md#installation)
+
+## Configure Existing
+
+If you want to join an existing testnet you either need to setup a node and 
+sync that testnet or find a node to use.
+
+You'll also need to setup an account and get it funded.
+
+Assuming you're using the Neutron testnet, create a new account called `admin`:
+
+```bash
+neutron keys add admin
+```
+
+Now use a faucet or send this address to someone who can give you funds on the tesnet. 
+
+If you have funds yourself you can simply transfer them:
+
+```bash 
+neutrond tx bank send <sender key name> <recipient address> <amount>
+--chain-id testing -y 
+```
+
+One your `admin` account is funded on the network, return to the [getting started guide](/docs/getting_started.md#installation)