WIP

projectglove · Aug 19, 2024 · 20517b4 · 20517b4
1 parent 09f4cda
commit 20517b4
Show file tree

Hide file tree

Showing 4 changed files with 301 additions and 38 deletions.
diff --git a/Glove Technical Design.pdf b/Glove Technical Design.pdf
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+# Glove
+
+Project Glove is a ..... You can read the technical design [here](docs/technical-design.md).
+
 **Table of Contents**
 
 - [Building Glove](#building-glove)
@@ -8,7 +12,7 @@
 - [Client CLI](#client-cli)
 - [Deployment](#deployment)
 
-# Building Glove
+## Building Glove
 
 You will need an x86-64 machine with docker installed to build Glove:
 
@@ -30,7 +34,7 @@ Enclave Image successfully created.
 }
 ```
 
-# Verifying Glove votes
+## Verifying Glove votes
 
 If you're using a Glove service and want to confirm the on-chain vote was mixed from a genuine Glove enclave, run the
 following command:
@@ -47,7 +51,7 @@ instructions on how to audit and verify the enclave code.
 > The enclave measurement for the latest build is
 > `4d132e40ed8d6db60d01d0116c34a4a92914de73d668821b6e019b72ae152b1180ef7c8a378e6c1925fe2bcb31c0ec80`.
 
-# Glove mixing
+## Glove mixing
 
 These are the rules when comes to vote requests and mixing:
 
@@ -86,7 +90,7 @@ The Glove service will initiate a mxing of the vote requests for a poll when one
 > the `--regular-mix` flag can turn this off and mix votes on a regular basis. However, this MUST NOT be enabled in 
 > production as it will leak private information of the vote requests.
 
-# Running the Glove service
+## Running the Glove service
 
 If you want to run your own Glove service, you will need to have a compatible AWS EC2 instance with AWS Nitro Enclaves
 enabled. You can follow the instructions [here](https://docs.aws.amazon.com/enclaves/latest/user/getting-started.html#launch-instance)
@@ -123,33 +127,33 @@ start the enclave in debug mode and output to the console.
 > Debug mode is not secure and will be reflected in the enclave's remote attestation and any Glove proofs created. Do
 > not enable this in production.
 
-# REST API
+## REST API
 
 The Glove service exposes a REST API for submitting votes and interacting with it.
 
-## `GET /info`
+### `GET /info`
 
 Get information about the Glove service, including the enclave. This can also act as a health check.
 
-### Request
+#### Request
 
 None
 
-### Response
+#### Response
 
 A JSON object with the following fields:
 
-#### `proxy_account`
+##### `proxy_account`
 
 The Glove proxy account address. Users will need to first assign this account as their
 [governance proxy](https://wiki.polkadot.network/docs/learn-proxies#proxy-types) before they can submit votes.
 
-#### `network_name`
+##### `network_name`
 
 The substrate-based network the Glove service is connected to. This is a [SS58](https://github.com/paritytech/ss58-registry)
 unique identifier.
 
-#### `attestation_bundle`
+##### `attestation_bundle`
 
 The attestation bundle of the enclave the service is using. This is a hex string representing the
 [`AttestationBundle`](common/src/attestation.rs#L38) struct in
@@ -158,11 +162,11 @@ The attestation bundle of the enclave the service is using. This is a hex string
 The attestation bundle is primarily used in Glove proofs when the enclave submits its mixed votes on-chain. It's
 available here for clients to verify the enclave's identity before submitting any votes.
 
-#### `version`
+##### `version`
 
 The version of the Glove service.
 
-#### Example
+##### Example
 
 ```json
 {
@@ -173,36 +177,36 @@ The version of the Glove service.
 }
 ```
 
-## `POST /vote`
+### `POST /vote`
 
 Submit a signed vote request to be included in the Glove mixing process.
 
 Multiple votes can be submitted for the same poll, but it's up to the discretion of the Glove service to accept them.
 If they are accepted they will replace the previous vote for that poll.
 
-### Request
+#### Request
 
 A JSON object with the following fields:
 
-#### `request`
+##### `request`
 
 [SCALE-encoded](https://docs.substrate.io/reference/scale-codec/) [`VoteRequest`](common/src/lib.rs#L57) as a
 hex string.
 
-#### `signature`
+##### `signature`
 
 [SCALE-encoded](https://docs.substrate.io/reference/scale-codec/)
 [`MultiSignature`](https://docs.rs/sp-runtime/latest/sp_runtime/enum.MultiSignature.html) as a hex string. The 
 signature is of the `VoteRequest` in SCALE-encoded bytes, i.e. the `request` field without the hex-encoding, signed by
 `VoteRequest.account`.
 
-#### Example
+##### Example
 
 [This example](common/test-resources/vote-request-example.mjs) shows how to create a signed vote request JSON body using
 the [Polkadot JS API](https://polkadot.js.org/docs). The request is made by the Bob dev account on the Rococo network
 for a vote of aye, on poll 185, using 2.23 ROC at 2x conviction.
 
-### Response
+#### Response
 
 If the vote request was successfully received and accepted by the service then an empty response with `200 OK` status
 code is returned. This does not mean, however, the vote was mixed and submitted on-chain; just that the Glove service
@@ -212,27 +216,27 @@ If request body is invalid then a `422 Unprocessable Entity` is returned. If the
 request itself then a `400 Bad Request` is returned with a JSON object containing the error type (`error`) and 
 description (`description`). `429 Too Many Requests` can also be returned and the request should be retried later.
 
-## `POST /remove-vote`
+### `POST /remove-vote`
 
 Submit a signed remove vote request for removing a previously submitted vote.
 
-### Request
+#### Request
 
 A JSON object with the following fields:
 
-#### `request`
+##### `request`
 
 [SCALE-encoded](https://docs.substrate.io/reference/scale-codec/) [`RemoveVoteRequest`](client-interface/src/lib.rs#L416)
 as a hex string.
 
-#### `signature`
+##### `signature`
 
 [SCALE-encoded](https://docs.substrate.io/reference/scale-codec/)
 [`MultiSignature`](https://docs.rs/sp-runtime/latest/sp_runtime/enum.MultiSignature.html) as a hex string. The 
 signature is of the `RemoveVoteRequest` in SCALE-encoded bytes, i.e. the `request` field without the hex-encoding, 
 signed by `RemoveVoteRequest.account`,
 
-### Response
+#### Response
 
 An empty response with `200 OK` status code is returned if the previous vote was successfully removed or if there was
 no matching vote.
@@ -241,19 +245,19 @@ If request body is invalid then a `422 Unprocessable Entity` is returned. If the
 request itself then a `400 Bad Request` is returned with a JSON object containing the error type (`error`) and 
 description (`description`). `429 Too Many Requests` can also be returned and the request should be retried later.
 
-## `GET /poll-info/{poll_index}`
+### `GET /poll-info/{poll_index}`
 
 Get Glove-specific information about poll with index `poll_index`.
 
-### Request
+#### Request
 
 None
 
-### Response
+#### Response
 
 A JSON object with the following fields:
 
-#### `mixing_time`
+##### `mixing_time`
 
 **Estimated** time the Glove service will mix vote requests and submit them on-chain. If the service hasn't received 
 requests for this poll then this is the time the service _would_ mix if it had. This field is only available for polls
@@ -265,7 +269,7 @@ The time is given in terms of both block number and UNIX timestamp seconds; the
 
 If the poll is not active then `400 Bad Request` is returned.
 
-#### Example
+##### Example
 
 ```json
 {
@@ -276,7 +280,7 @@ If the poll is not active then `400 Bad Request` is returned.
 }
 ```
 
-# Client CLI
+## Client CLI
 
 There is a CLI client for interacting with the Glove service from the command line. It is built alongside the Glove
 service and enclave with the `./build.sh` command (described above). To build it on a local machine:
@@ -291,13 +295,13 @@ target/release/client --help
 
 First join Glove with the `join-glove` command and then vote with `vote`.
 
-# Development
+## Development
 
-## MacOS
+### MacOS
 
 If building on MacOS, then use `cargo` directly rather than the `./build.sh` script. Only mock mode will be available.
 
-## Regenerating the Substrate metadata
+### Regenerating the Substrate metadata
 
 You first need the `subxt-cli` tool installed:
 
@@ -311,13 +315,13 @@ Then run this in the home directory of this project:
 subxt metadata --url="wss://rpc.polkadot.io:443" -f bytes > assets/polkadot-metadata.scale
 ```
 
-# Deployment
+## Deployment
 
 Additionally, to the Enclave source code the repo contain examples of the Configuration as Code scripts.
 The are located in the [devops](devops) folder.
 Cloud infrastructure is handled by Terraform/OpenTofu and VM configuration by Ansible.
 
-## Terraform/OpenTofu
+### Terraform/OpenTofu
 The scripts in the [terraform](devops/terraform) subfolder are responsible for deployment of:
 - VM with Enclave,
 - Application Load Balancer (ALB),
@@ -328,16 +332,16 @@ The scripts in the [terraform](devops/terraform) subfolder are responsible for d
 
 Please note, that in the test TLS traffic terminates on the load balancer, not VM.
 
-## Ansible
+### Ansible
 In the [Ansible](devops/ansible) folder there is the glove role and the matching playbook with an inventory file for the test deployment.
 The role gets the latest binaries from the github, release page, sets systemd service for glove API host and prepare Nitro enclave.
 
-## GitHub Actions
+### GitHub Actions
 
 The ansible playbook and the role are used in the release GHA.
 Every time a new tag is set, the action builds binaries, and then uses Ansible to update the test deployment.
 
-## Debbuging
+### Debbuging
 
 To check the status of the service run:
 ```