diff --git a/README.md b/README.md index ba5be87..8a85075 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,15 @@ _**When?**_ Early, non-production versions of Quartz are available now for build example applications. Production features and requirements are in development. See [Future Work][future_work] +--- +WARNING: Quartz is under heavy development and is not ready for production use. +The current code contains known bugs and security vulnerabilities and APIs are still liable to change. + +We are making it available for devleopers to start playing with and to gather +feedback on APIs and roadmap. It can be used today on CosmWasm testnets +(testnets only, with no real funds at risk!). +--- + ## Docs - [Getting Started][getting_started] - Get a simple example app up and running in 5 minutes @@ -36,6 +45,7 @@ See [Future Work][future_work] - [Building Applications][building_apps] - How to build Quartz applications - [Future Work][future_work] - Roadmap and future work for security, flexibility, and more +p ## This Repo diff --git a/apps/transfers/README.md b/apps/transfers/README.md index e9d2d7e..ddec718 100644 --- a/apps/transfers/README.md +++ b/apps/transfers/README.md @@ -4,254 +4,6 @@ This is a simple Quartz demo app. It allows users to deposit funds to a contract, transfer them around privately within the contract's encrypted state, and withdraw whatever funds they have. -## Setup - -### Install Rust - -The minimum Rust supported version is v1.74.1. -The recommended Rust version v1.79.0 since we're running against -wasmd v0.45. - -Install rust by executing a script from the internet (😅): - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -Check the version with `cargo version`. - -Finally add the wasm target: - -```bash -rustup target add wasm32-unknown-unknown -``` - -And you should be good to go! - -### Install Other Tools - -You need a few other Go based tools. You should already have go. - -First add the `~/go/bin` to your path by adding this line to the end of your -`~/.bashrc`: - -```bash -export PATH="${PATH}:${HOME}/go/bin" -``` - -Then `source ~/.bashrc`. Now we can install some stuff. - -You need grpcurl: - -```bash -go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest -``` - -You need wasmd v0.45.0: - -```bash -git clone https://github.com/cosmwasm/wasmd/ -cd wasmd -git checkout v0.45.0 -go install ./cmd/wasmd -``` - -Check that both work by running `grpcurl` and `wasmd`. - -Finally, you need `websocat`: - -```bash -cargo install websocat -``` - -### Fetch the Repo - -While the repos are private you will need an ssh key registered on github in -order to fetch them. Run `ssh-keygen` and just follow the defaults. On Github, -go to Settings -> SSH and GPG Keys -> New SSH Key. Run `cat ~/.ssh/id_rsa.pub` -on the machine and copy and paste the result into Github. - -This key will now have full access to your github account so its a good idea to -remove it when you're done and re-add everytime you need to push/pull the repo. - -Now clone the repo: - -```bash -git clone ssh://git@github.com/informalsystems/cycles-quartz -cd cycles-quartz -``` - -Tada! - -### Setup Wasmd Accounts - -Run `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" -``` - -Now, finally, we can create a local admin key for your wasmd. You'll use this to -deploy contracts: - -```bash -wasmd keys add admin -``` - -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: - -```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 -wasmd keys add validator - -# 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 -``` - -Before finally starting the node, for it to work with the front end, you need to -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 = ["*"] -``` - -And in `~/.wasmd/config/app.toml`: - -```toml -[api] -enable = true -address = "tcp://0.0.0.0:1317" -enabled-unsafe-cors = true -``` - -Now, finally: - -```bash -wasmd start -``` - -And you should have a chain making blocks! - -You can also reduce the block time by lowering `timeout_commit` in -`~/.wasmd/config/config.toml`. - -Now that you have the chain running, you can start running the enclave and proxy -in other windows. - -## Run - -First set the `NODE_URL` variable to the address of the blockchain node. If it's -a local node, set it to `localhost:26657`. If it's a remote node, set it to that -node's address (eg. `export NODE_URL=143.244.186.205:26657`). - -The `scripts` dir contains some bash scripts to help run the app. These scripts -should be replaced by a new `quartz` tool. See -[issue](https://github.com/informalsystems/cycles-quartz/issues/61). - -**NOTE: If you want to run on a non-SGX machine, you must set the following -*environment variable prior to running any further commands in *all* terminals -*in which you run them:** - -```bash -export MOCK_SGX=1 -``` - -### Build the Binaries - -Build the enclave binary and the smart contract binary: - -```bash -bash scripts/build.sh -``` - -### Configure and Run Gramine - -Setup and sign the Gramine config, and then start the gramine process, which -will run the gRPC server that hosts the transfer application. The quartz port -defaults to `11090`, but you can set it deliberately with `export -QUARTZ_PORT=XXXXX`. It is best to set it everytime, since if 2 people are sshing -into the same machine to use the secure enclave, this could create undesired env -conditions where your app is talking to the wrong enclave. - -```bash -bash scripts/start.sh -``` - -The enclave binary is now running, waiting for commands. - -### Contract Setup - -With the enclave running in one window, open another window to deploy the -contract and start the listener. - -In the new window, set the `NODE_URL` env variable again (e.g. -`export NODE_URL=143.244.186.205:26657`) - -Now we can deploy the contract: - -```bash -bash scripts/deploy.sh -``` - -Note the deployed contract address and save it into the `CONTRACT` env variable. - -Now run the quartz handshake between contract and enclave: - -```bash -bash scripts/handshake.sh $CONTRACT -``` - -This should output the pubkey and nonce. - -### Run the Listener - -Finally, we're ready to listen to events from the contract and trigger execution on the enclave: - -```bash -bash scripts/listen.sh $CONTRACT -``` - -Now we can interact with the contract, and we'll see the events and contract -data come through. - -### Run the Frontend - -Now on your own machine, follow [these steps](./frontend/README.md#development). - -Make sure you have Keplr installed in your browser and you should now be able to -use the app! - -You may have to go to "Manage Chain Visibility" in Keplr settings to add the `My -Testing Chain` so you can see your balance. - -You will also need to fund any keplr account by sending funds from the CLI using -your `admin` account. - -Then you should be able to deposit, transfer, and withdraw using different Keplr -accounts. And everything will get processed automatically by the transfer.sh -script we have running on the enclave host! +See the [getting started guide](/docs/getting_started.md) to get it quickly +setup on a local testnet without SGX or on a real testnet using an Azure SGX +node. diff --git a/docs/getting_started.md b/docs/getting_started.md index 7b279d6..3dfeefe 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -1,5 +1,14 @@ # Quartz: Getting Started Guide +--- +WARNING: Quartz is under heavy development and is not ready for production use. +The current code contains known bugs and security vulnerabilities and APIs are still liable to change. + +We are making it available for devleopers to start playing with and to gather +feedback on APIs and roadmap. It can be used today on CosmWasm testnets +(testnets only, with no real funds at risk!). +--- + ## Table of Contents - [Introduction](#introduction) @@ -25,14 +34,14 @@ For those who want to get started quickly: 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. Run the development environment: +4. Deploy the example app in one command: ```bash quartz --mock-sgx --app-dir "apps/transfers/" dev \ --unsafe-trust-latest \ --contract-manifest "apps/transfers/contracts/Cargo.toml" \ --init-msg '{"denom":"ucosm"}' ``` -5. Set up the frontend (see [Building the front-end Application](#building-the-front-end-application)) +5. Set up the frontend (see [Frontend](#frontend)) For more detailed instructions, continue reading the following sections. @@ -59,32 +68,44 @@ CosmWasm-compatible Cosmos-SDK blockchain client installed, for instance `wasmd` or `neutrond`. CosmWasm binaries can be built with `Go` or downloaded from their developers. Finally, you'll need `npm` to build the frontend. +### Install Rust + +The minimum Rust supported version is v1.74.1. +The recommended Rust version v1.79.0 since we're running against +wasmd v0.45. + +Install rust by executing a script from the internet (😅): + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +Check the version with `cargo version`. + +Finally add the wasm target: + +```bash +rustup target add wasm32-unknown-unknown +``` + +And you should be good to go! + + ### Install Quartz -Install rust: - - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` -and add the wasm32 target: - - ```bash - rustup target add wasm32-unknown-unknown - ``` - Now clone and build the repo: - ```bash - git clone ssh://git@github.com/informalsystems/cycles-quartz - cd cycles-quartz - cargo install --path cli/ - ``` +```bash +git clone ssh://git@github.com/informalsystems/cycles-quartz +cd cycles-quartz +cargo install --path cli/ +``` And check that it worked: - ```bash - quartz --help - ``` +```bash +quartz --help +``` ### Install a CosmWasm Client @@ -102,36 +123,36 @@ 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.44.0 - go install ./cmd/wasmd - ``` +```bash +git clone https://github.com/cosmwasm/wasmd/ +cd wasmd +git checkout v0.44.0 +go install ./cmd/wasmd +``` Or for `neutrond`: - ```bash - git clone -b main https://github.com/neutron-org/neutron.git - cd neutron - make install - ``` +```bash +git clone -b main https://github.com/neutron-org/neutron.git +cd neutron +make install +``` To use the docker images, install and set up docker. Then for wasmd`: - ```bash - cd docker/wasmd - make run - ``` +```bash +cd docker/wasmd +make run +``` Or for `neutrond`: - ```bash - cd docker/neutron - make start-docker-container - ``` +```bash +cd docker/neutron +make start-docker-container +``` If using docker it will pre-configure a few keys and allocate funds to them. @@ -145,13 +166,20 @@ transfers app. Deployment involves three components: - the smart contract - the front end +Quartz provides a `dev` command to simplify building and running the enclave and smart contract in a single command. +Use of the `dev` command was shown in the [quick start](#quick-start) section +above. Here we show the individual steps and quartz commands that allow devs to +independently build and run the encalve, to build and deploy the contract, +and to perform the quartz handshake between running enclave and deployed +contract. + +### Enclave + 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. -### Enclave - 1. Build the enclave binary: ```bash @@ -187,9 +215,9 @@ transfers app is currently single asset only. If successful, it will print the resulting contract address. Save it to an environment variable: -``` -export CONTRACT_ADDRESS= -``` + ```bash + export CONTRACT_ADDRESS= + ``` 3. Perform the handshake: ```bash @@ -202,9 +230,9 @@ If successful, it should output a pubkey value. We'll need both the contract address and this pubkey value to configure the frontend. Save this to an environment variable: -``` -export PUBKEY= -``` + ```bash + export PUBKEY= + ``` Now the contract is ready to start processing requests to the enclave. @@ -241,24 +269,27 @@ contract and doing the handshake). Open your browser to `localhost:3000` to see the app. -You'll need to have the Keplr wallet extension installed and unlocked. +You'll need to have the Keplr wallet browser extension installed and unlocked. -Configure the chain visibility settings in Keplr so you can see your local chain -(search for the chain id, should be `testing`). +You may have to go to "Manage Chain Visibility" in Keplr settings to add the `My +Testing Chain` so you can talk to your local chain and see your balance. Create a new address in Keplr for testing purpose. You'll need to send this address some funds from the `admin` account setup with your local node. For instance, send 10M ucosm with: -``` -wasmd tx bank send admin 10000000ucosm --chain-id testing -``` + ```bash + wasmd tx bank send admin 10000000ucosm --chain-id testing + ``` You should now see the funds on your local testnet on Keplr. Now you can interact with the app by depositing funds, privately transfering them to other addresses, and finally withdrawing them. +Be sure to check the enclave window to see the logs from your interaction with +the app! + ## Real Testnet with SGX Now that we've tried the example app on a local tesnet with a mocked SGX, it's @@ -274,12 +305,12 @@ versions of SGX processors. Together they allow contracts built with quartz to securely verify remote attestations from SGX enclaves. We have already predeployed the dcap-verify and tcbinfo contracts on the Neutron -testnet at TODO. To deploy these on your own testnet, see [below][#other-testnets-with-sgx]. +testnet at TODO. To deploy these on your own testnet, see [below](#other-testnets-with-sgx). To begin, you'll need to deploy an SGX-enabled Azure instance and log in via ssh. Once logged in, clone and install Quartz like before (see -[installation][#installation] +[installation](#installation). ### Build and Deploy the Contracts