nologies/cycles-quartz
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update READMEs and getting started

Browse source
This commit is contained in:
Ethan Buchman 2024-09-29 01:24:39 -04:00
parent cb42873410
commit 6a768df643
3 changed files with 100 additions and 307 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
README.md
View file

@ -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

254
apps/transfers/README.md
View file

@ -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 <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
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 <sender key name> <recipient address> <amount ucosm> --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.

143
docs/getting_started.md
View file

@ -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=<CONTRACT_ADDRESS>
```
```bash
export CONTRACT_ADDRESS=<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=<PUBKEY>
```
```bash
export PUBKEY=<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 <KEPLR ADDRESS> 10000000ucosm --chain-id testing
```
```bash
wasmd tx bank send admin <KEPLR ADDRESS> 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