Updated README with Glove servive REST API doc

This includes a Polkadot JS sample which creates a valid payload for the `/vote` endpoint. This endpoint
was also updated to return a JSON object if the request was bad with the error information.
Also added some documentation to the public Rust structs

.gitignore

@@ -2,13 +2,9 @@
 # will have compiled files and executables
 debug/
 target/
-
 # These are backup files generated by rustfmt
 **/*.rs.bk
-
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
-
 .DS_Store
-
 .idea/

README.md

@@ -14,9 +14,8 @@ Enclave Image successfully created.
 {
   "Measurements": {
     "HashAlgorithm": "Sha384 { ... }",
-    "PCR0": "77af85a8afd3a38d4f1bcce280d886eac18b60bb8c2365906b88676fe3739458f7854c5fd8eb27d5eb4858269f6686cb",
-    "PCR1": "4b4d5b3661b3efc12920900c80e126e4ce783c522de6c02a2a5bf7af3a2b9327b86776f188e4be1c1c404a129dbda493",
-    "PCR2": "d97a4d6458988da4bae2cde519b75bde177fea4454d356921abc339840b28164af049e1bc68ef29fcc9dac9578f3101c"
+    "PCR0": "d68be77c357668869010a6c56a7d2248e47128eb4aa19f4063bd3edafc075826873661a8dc0ce86321a3eb32274d093a",
+...
   }
 }
 ```
@@ -27,7 +26,7 @@ running a Glove enclave on genuine AWS Nitro hardware.
 
 > [!NOTE]
 > The enclave image measurement for the latest build is
-> `77af85a8afd3a38d4f1bcce280d886eac18b60bb8c2365906b88676fe3739458f7854c5fd8eb27d5eb4858269f6686cb`.
+> `d68be77c357668869010a6c56a7d2248e47128eb4aa19f4063bd3edafc075826873661a8dc0ce86321a3eb32274d093a`.
 
 # Running Glove
 
@@ -59,6 +58,95 @@ start the enclave in debug mode and output to the console.
 > [!WARNING]
 > Debug mode is not secure and will be reflected in the enclave's remote attestation. Do not enable this in production.
 
+# REST API
+
+The Glove service exposes a REST API for submitting votes and interacting with it.
+
+## `GET /info`
+
+Get information about the Glove service, including the enclave. This can also act as a health check.
+
+### Request
+
+None
+
+### Response
+
+A JSON object with the following fields:
+
+#### `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`
+
+The substrate-based network the Glove service is connected to.
+
+#### `node_endpoint`
+
+The [node endpoint](https://wiki.polkadot.network/docs/maintain-endpoints) URL the service is using to interact with the
+network. This is only provided as a convenience for Glove clients, otherwise they can use any node endpoint as long as
+it points to the same network.
+
+#### `attestation_bundle`
+
+The attestation bundle of the enclave the service is using. This is a hex-encoded string (without the `0x` prefix),
+representing the [`AttestationBundle`](common/src/attestation.rs#L43) struct in
+[SCALE](https://docs.substrate.io/reference/scale-codec/) encoding. 
+
+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.
+
+#### Example
+
+```json
+{
+  "proxy_account": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+  "network_name": "rococo",
+  "node_endpoint": "wss://rococo-rpc.polkadot.io",
+  "attestation_bundle": "6408de7737c59c238890533af25896a2c20608d8b380bb01029acb3927..."
+}
+```
+
+## `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 discrection of the Glove service to accept them.
+If they are accepted they will replace the previous vote for that poll.
+
+### Request
+
+A JSON object with the following fields:
+
+#### `request`
+
+[SCALE-encoded](https://docs.substrate.io/reference/scale-codec/) [`VoteRequest`](common/src/lib.rs#L36) struct as a 
+hex string (without the `0x` prefix).
+
+#### `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 (without the
+`0x` prefix). Signed by`VoteRequest.account`, the signature is of the `VoteRequest` in SCALE-encoded bytes, i.e. the
+`request` field without the hex-encoding.
+
+#### 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
+
+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
+will do so at the appropriate time.
+
+If there was something wrong with the vote request then a `400 Bad Request` is returned with a JSON object containing 
+the error type (`error`) and description (`description`).
+
 # Client CLI
 
 There is a CLI client for interacting with the Glove service from the command line. It is built alonside the Glove

client-interface/src/lib.rs

@@ -349,7 +349,8 @@ pub fn account_to_subxt_multi_address(account: AccountId32) -> SubxtMultiAddress
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct ServiceInfo {
     pub proxy_account: AccountId32,
-    pub network_url: String,
+    pub network_name: String,
+    pub node_endpoint: String,
     #[serde(with = "common::serde_over_hex_scale")]
     pub attestation_bundle: AttestationBundle
 }
@@ -380,7 +381,8 @@ mod tests {
     fn service_info_json() {
         let service_info = ServiceInfo {
             proxy_account: dev::alice().public_key().0.into(),
-            network_url: "wss://polkadot.api.onfinality.io/public-ws".to_string(),
+            network_name: "polkadot".to_string(),
+            node_endpoint: "wss://polkadot.api.onfinality.io/public-ws".to_string(),
             attestation_bundle: AttestationBundle {
                 attested_data: AttestedData {
                     genesis_hash: random::<[u8; 32]>().into(),
@@ -397,7 +399,8 @@ mod tests {
             serde_json::from_str::<Value>(&json).unwrap(),
             json!({
                 "proxy_account": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
-                "network_url": "wss://polkadot.api.onfinality.io/public-ws",
+                "network_name": "polkadot",
+                "node_endpoint": "wss://polkadot.api.onfinality.io/public-ws",
                 "attestation_bundle": hex::encode(&service_info.attestation_bundle.encode())
             })
         );

client/src/main.rs

@@ -38,7 +38,7 @@ async fn main() -> Result<SuccessOutput> {
         .json::<ServiceInfo>().await?;
 
     let network = SubstrateNetwork::connect(
-        service_info.network_url.clone(),
+        service_info.node_endpoint.clone(),
         args.secret_phrase
     ).await?;
 
@@ -224,10 +224,10 @@ fn info(service_info: &ServiceInfo) -> Result<SuccessOutput> {
         Err(attestation_error) => &format!("Error verifying attestation: {}", attestation_error)
     };
 
-    println!("Glove proxy account:   {}", service_info.proxy_account);
-    println!("Enclave:               {}", enclave_info);
-    println!("Substrate network URL: {}", service_info.network_url);
-    println!("Genesis hash:          {}", hex::encode(ab.attested_data.genesis_hash));
+    println!("Glove proxy account: {}", service_info.proxy_account);
+    println!("Enclave:             {}", enclave_info);
+    println!("Substrate Network:   {}", service_info.network_name);
+    println!("Genesis hash:        {}", hex::encode(ab.attested_data.genesis_hash));
 
     Ok(SuccessOutput::None)
 }

common/Cargo.toml

@@ -23,4 +23,5 @@ hex.workspace = true
 
 [dev-dependencies]
 serde_json.workspace = true
+subxt-signer.workspace = true
 # TODO client-interface and enclave-interface should be merged into common but behind feature flags

common/src/attestation.rs

@@ -11,6 +11,8 @@ use sp_core::{ed25519, H256, Pair};
 
 use crate::{ExtrinsicLocation, nitro, SignedGloveResult};
 
+/// Represents a Glove proof of the mixing result done by a secure enclave. The votes on-chain
+/// must be compared to the result in the proof to ensure the mixing was done correctly.
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub struct GloveProof {
     pub signed_result: SignedGloveResult,
@@ -40,6 +42,10 @@ impl GloveProof {
     }
 }
 
+/// An attestation bundle is a combination of [AttestedData] and [Attestation].
+///
+/// [verify] must be called to ensure the attestation is valid and comes from a genuine secure
+/// enclave and to confirm the [AttestedData] matches the attestation.
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub struct AttestationBundle {
     pub attested_data: AttestedData,
@@ -52,7 +58,10 @@ pub struct AttestationBundle {
 pub const ATTESTATION_BUNDLE_ENCODING_VERSION: u8 = 1;
 
 impl AttestationBundle {
+    /// Verify the attesation and prove the enclave is secure and the attested data came from it.
     ///
+    /// Note, this does not prove the attestation is for a enclave running Glove. For that the
+    /// [EnclaveInfo] that's returned must be checked.
     pub fn verify(&self) -> Result<EnclaveInfo, Error> {
         match &self.attestation {
             Attestation::Nitro(nitro_attestation) => {
@@ -95,18 +104,26 @@ impl AttestationBundle {
     }
 }
 
+/// The attested data that is signed by the enclave.
 #[derive(Debug, Clone, PartialEq, Encode, Decode, MaxEncodedLen)]
 pub struct AttestedData {
+    /// The genesis hash of the chain the enclave is working on.
     pub genesis_hash: H256,
+    /// The signing key the enclave is using to sign Glove proofs.
     pub signing_key: ed25519::Public
 }
 
+/// Enum of the various attestation types.
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub enum Attestation {
+    /// AWS Nitro Enclaves attestation
     Nitro(nitro::Attestation),
+    /// Marker for a mock enclave. There is no hardware security in a mock enclave and is therefore
+    /// only suitable for testing.
     Mock
 }
 
+/// The information about the enclave that produced the attestation.
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub enum EnclaveInfo {
     Nitro(nitro::EnclaveInfo)

common/src/lib.rs

@@ -34,17 +34,28 @@ impl SignedVoteRequest {
 
 #[derive(Debug, Clone, PartialEq, Encode, Decode, MaxEncodedLen)]
 pub struct VoteRequest {
+    /// The account on whose behalf the Glove proxy will vote for.
     pub account: AccountId32,
+    /// The genesis hash of the substrate chain where the poll is taking place. This is necessary
+    /// to ensure the vote is not replayed on a different chain.
     pub genesis_hash: H256,
+    /// The index of the poll/referendum.
     #[codec(compact)]
     pub poll_index: u32,
-    /// Nonce value to prevent replay attacks. Only needs to be unique for the same poll.
+    /// Nonce value to prevent replay attacks. Needs to be unique for the same poll.
     pub nonce: u32,
+    /// `true` for aye, `false` for nay.
     pub aye: bool,
+    /// The amount of tokens to vote with. The units are in
+    /// [Planck](https://wiki.polkadot.network/docs/learn-DOT#the-planck-unit).
     pub balance: u128,
     pub conviction: Conviction,
 }
 
+/// Conviction voting multiplier.
+///
+/// See [here](https://wiki.polkadot.network/docs/learn-polkadot-opengov#voluntary-locking-conviction-voting)
+/// for more details.
 #[derive(Debug, Copy, Clone, PartialEq, Encode, Decode, MaxEncodedLen)]
 pub enum Conviction {
     None,
@@ -69,9 +80,12 @@ impl VoteRequest {
     }
 }
 
+/// Signed Glove result from an enclave. The signature can be verified using `signing_key` from
+/// the [`attestation::AttestedData`].
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub struct SignedGloveResult {
     pub result: GloveResult,
+    /// Signature of `result` in SCALE endoding.
     pub signature: ed25519::Signature
 }
 
@@ -162,6 +176,7 @@ mod tests {
     use rand::random;
     use serde_json::{json, Value};
     use sp_core::{Pair, sr25519};
+    use subxt_signer::sr25519::dev;
 
     use Conviction::{Locked3x, Locked6x};
 
@@ -200,6 +215,27 @@ mod tests {
         assert_eq!(deserialized_signed_request, signed_request);
     }
 
+    #[test]
+    fn signed_vote_request_json_using_polkadot_js() {
+        // Produced from test-resources/vote-request-example.mjs
+        let json = r#"
+{
+  "request": "8eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a486408de7737c59c238890533af25896a2c20608d8b380bb01029acb392781063ee502f5c1912301009c5b3607020000000000000000000002",
+  "signature": "01ea13f59165bc295d1e99629622dc0c13a1c7163017359178606f0e36d1d2c246c021190cf0508b0d60d292a00ba06ed396d5559fe7334c78c95bf289e84ebc81"
+}
+"#;
+
+        let signed_request = serde_json::from_str::<SignedVoteRequest>(json).unwrap();
+        assert!(signed_request.verify());
+        let request = signed_request.request;
+        assert_eq!(request.account, dev::bob().public_key().0.into());
+        assert_eq!(request.poll_index, 185);
+        assert_eq!(request.genesis_hash, H256::from_str("6408de7737c59c238890533af25896a2c20608d8b380bb01029acb392781063e").unwrap());
+        assert_eq!(request.balance, 2230000000000);
+        assert_eq!(request.aye, true);
+        assert_eq!(request.conviction, Conviction::Locked2x);
+    }
+
     #[test]
     fn different_signer_to_vote_request_account() {
         let (pair1, _) = sr25519::Pair::generate();

common/src/nitro.rs

@@ -14,10 +14,15 @@ static ROOT_CA_BYTES: &[u8] = include_bytes!("../../assets/aws-nitro-root.pem");
 
 #[derive(Debug, Clone, PartialEq, Encode, Decode)]
 pub struct EnclaveInfo {
+    /// The enclave image measurement (`PCR0`). This value must be checked against known
+    /// measurements of Glove enclaves.
     pub image_measurement: Vec<u8>,
-    // TODO Image signer
 }
 
+/// Attestation document from AWS Nitro Enclaves.
+///
+/// The enclave itself by either be running in secure mode or debug mode. This can be determined by
+/// calling [crate::attestation::AttestationBundle::verify].
 #[derive(Debug, Clone)]
 pub struct Attestation(CoseSign1);