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

Update getting started (#229)

Browse source
This commit is contained in:
Ethan Buchman 2024-10-01 10:26:42 -04:00 committed by GitHub
parent 3e62031528
commit 0bb0aa1e4b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 131 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
README.md
View file

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

4
crates/cli/src/cli.rs
View file

@ -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")]

2
crates/cli/src/config.rs
View file

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

60
docs/getting_started.md
View file

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

138
docs/wasmd_setup.md
View file

@ -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 <your name> --chain-id testing` to initialize the local wasmd
folder.
Run
```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
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 <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
```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 <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)