Doc comments 1 (#837)

* doc comments * update app_id docs * signature clarifications * undo a misleading comment * typo Co-authored-by: Federico Giacon <[email protected]> * further clarify eip-712 Co-authored-by: Federico Giacon <[email protected]> Co-authored-by: Federico Giacon <[email protected]>
cowprotocol · Nov 29, 2022 · ed35294 · ed35294
1 parent 8b875ed
commit ed35294
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 1 deletion.
diff --git a/crates/model/src/app_id.rs b/crates/model/src/app_id.rs
@@ -6,6 +6,9 @@ use std::{
     str::FromStr,
 };
 
+/// This allows arbitrary user data to be associated with an order. This type holds the
+/// hash of the data, while the data itself is uploaded to IPFS. The hash is signed along with the
+/// order.
 #[derive(Clone, Copy, Default, Eq, Hash, PartialEq)]
 pub struct AppId(pub [u8; 32]);
 

diff --git a/crates/model/src/auction.rs b/crates/model/src/auction.rs
@@ -34,7 +34,8 @@ pub struct Auction {
     /// valid on this block.
     pub block: u64,
 
-    /// The latest block on which a settlement has been processed.
+    /// The latest block on which a settlement has been processed. This field is used to tell which
+    /// orders are still in-flight. See [`InFlightOrders`].
     ///
     /// Note that under certain conditions it is possible for a settlement to
     /// have been mined as part of [`block`] but not have yet been processed.

diff --git a/crates/model/src/order.rs b/crates/model/src/order.rs
@@ -274,6 +274,9 @@ impl OrderData {
     pub const BALANCE_INTERNAL: [u8; 32] =
         hex!("4ac99ace14ee0a5ef932dc609df0943ab7ac16b7583634612f8dc35a4289a6ce");
 
+    /// Returns the value of hashStruct() over the order data as defined by EIP-712.
+    ///
+    /// https://eips.ethereum.org/EIPS/eip-712#definition-of-hashstruct
     pub fn hash_struct(&self) -> [u8; 32] {
         let mut hash_data = [0u8; 416];
         hash_data[0..32].copy_from_slice(&Self::TYPE_HASH);

diff --git a/crates/model/src/signature.rs b/crates/model/src/signature.rs
@@ -11,6 +11,7 @@ use web3::{
     types::Recovery,
 };
 
+/// See [`Signature`].
 #[derive(Eq, PartialEq, Clone, Copy, Debug, Default, Deserialize, Serialize, Hash)]
 #[serde(rename_all = "lowercase")]
 pub enum SigningScheme {
@@ -32,12 +33,29 @@ impl From<QuoteSigningScheme> for SigningScheme {
     }
 }
 
+/// Signature over the order data.
+/// All variants rely on the EIP-712 hash of the order data, referred to as the order hash.
 #[derive(Eq, PartialEq, Clone, Deserialize, Serialize, Hash)]
 #[serde(into = "JsonSignature", try_from = "JsonSignature")]
 pub enum Signature {
+    /// The order struct is signed according to EIP-712.
+    ///
+    /// https://eips.ethereum.org/EIPS/eip-712
     Eip712(EcdsaSignature),
+    /// The order hash is signed according to EIP-191's personal_sign signature format.
+    ///
+    /// https://eips.ethereum.org/EIPS/eip-191
     EthSign(EcdsaSignature),
+    /// Signature verified according to EIP-1271, which facilitates a way for contracts to
+    /// verify signatures using an arbitrary method. This allows smart contracts to sign and
+    /// place orders. The order hash is passed to the verification method, along with this
+    /// signature.
+    ///
+    /// https://eips.ethereum.org/EIPS/eip-1271
     Eip1271(Vec<u8>),
+    /// For these signatures, the user broadcasts a transaction onchain. This transaction contains
+    /// a signature of the order hash. Because this onchain transaction is also signed, it proves
+    /// that the user indeed signed the order.
     PreSign,
 }
 
@@ -261,6 +279,7 @@ fn hashed_ethsign_message(domain_separator: &DomainSeparator, struct_hash: &[u8;
     signing::keccak256(&message)
 }
 
+/// Orders are always hashed into 32 bytes according to EIP-712.
 fn hashed_signing_message(
     signing_scheme: EcdsaSigningScheme,
     domain_separator: &DomainSeparator,