From 0bb0aa1e4b07fe3932677d4a5af3663e17b1974b Mon Sep 17 00:00:00 2001 From: Ethan Buchman Date: Tue, 1 Oct 2024 10:26:42 -0400 Subject: [PATCH] Update getting started (#229) --- README.md | 11 ++-- crates/cli/src/cli.rs | 4 +- crates/cli/src/config.rs | 2 +- docs/getting_started.md | 60 +++++++---------- docs/wasmd_setup.md | 138 +++++++++++++++++++++++++++------------ 5 files changed, 131 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 6519e75..5ff7d4e 100644 --- a/README.md +++ b/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: diff --git a/crates/cli/src/cli.rs b/crates/cli/src/cli.rs index 9075fa4..b95e789 100644 --- a/crates/cli/src/cli.rs +++ b/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 - /// Defaults to current working dir + /// Path to Quartz app directory. + /// 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")] diff --git a/crates/cli/src/config.rs b/crates/cli/src/config.rs index 422e1c4..36144f7 100644 --- a/crates/cli/src/config.rs +++ b/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, diff --git a/docs/getting_started.md b/docs/getting_started.md index 226f340..4d6020b 100644 --- a/docs/getting_started.md +++ b/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 -testnet). +For the real testnet, we use `neutrond`. -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 -Go binaries you'll have to set up keys and balances yourself. +You can also use an existing installation if you have, or you can build from +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. - -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. +The docker images come with everything. To use them install and setup 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= 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: diff --git a/docs/wasmd_setup.md b/docs/wasmd_setup.md index 83576a0..db84e4b 100644 --- a/docs/wasmd_setup.md +++ b/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 -blockchain. +Quartz expects to interact with a CosmWasm-based 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 --chain-id testing` to initialize the local wasmd -folder. +Run + +```bash +wasmd init --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 -keyring-backend = "test" -``` +```toml keyring-backend = "test" ``` Now, finally, we can create a local admin key for your wasmd. You'll use this to deploy contracts: -```bash -wasmd keys add admin +```bash +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 -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: +Now create the genesis file. -```bash -wasmd tx bank send --chain-id testing -y -``` - -If you're setting up your own local testnet, continue with the following: - -```bash -# generate a second key for the validator +```bash +# generate a second key for the validator wasmd keys add validator -# fund both accounts in genesis -wasmd genesis add-genesis-account admin 100000000000stake,100000000000ucosm +# fund both accounts in genesis +wasmd genesis add-genesis-account admin 100000000000stake,100000000000ucosm wasmd genesis add-genesis-account validator 100000000000stake,100000000000ucosm -# sign genesis tx from validator and compose genesis -wasmd genesis gentx validator 100000000stake --chain-id testing -wasmd genesis collect-gentxs +# sign genesis tx from validator and compose genesis +wasmd genesis gentx validator 100000000stake --chain-id testing +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 -[rpc] -laddr = "tcp://0.0.0.0:26657" -cors_allowed_origins = ["*"] +```toml +[rpc] +laddr = "tcp://0.0.0.0:26657" +cors_allowed_origins = ["*"] ``` And in `~/.wasmd/config/app.toml`: -```toml -[api] -enable = true -address = "tcp://0.0.0.0:1317" -enabled-unsafe-cors = true +```toml +[api] +enable = true +address = "tcp://0.0.0.0:1317" +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 +--chain-id testing -y +``` + +One your `admin` account is funded on the network, return to the [getting started guide](/docs/getting_started.md#installation)