From 164ea7ce3c00344b474a5c2c42ab195d9700e259 Mon Sep 17 00:00:00 2001 From: Dimitri Date: Wed, 18 Sep 2024 11:29:01 +0700 Subject: [PATCH] AI generated doc comments --- packages/relayer/src/chain.rs | 171 ++++++++++++++++++ packages/relayer/src/core.rs | 9 + packages/relayer/src/database.rs | 24 +++ packages/relayer/src/modules/dkim.rs | 43 +++++ packages/relayer/src/modules/mail.rs | 37 ++++ .../relayer/src/modules/web_server/mod.rs | 2 + .../src/modules/web_server/rest_api.rs | 64 ++++++- .../relayer/src/modules/web_server/server.rs | 5 + 8 files changed, 354 insertions(+), 1 deletion(-) diff --git a/packages/relayer/src/chain.rs b/packages/relayer/src/chain.rs index 0cffe7f..d3df1e6 100644 --- a/packages/relayer/src/chain.rs +++ b/packages/relayer/src/chain.rs @@ -16,6 +16,11 @@ pub struct ChainClient { } impl ChainClient { + /// Sets up a new ChainClient. + /// + /// # Returns + /// + /// A `Result` containing the new `ChainClient` if successful, or an error if not. pub async fn setup() -> Result { let wallet: LocalWallet = PRIVATE_KEY.get().unwrap().parse()?; let provider = Provider::::try_from(CHAIN_RPC_PROVIDER.get().unwrap())?; @@ -28,6 +33,19 @@ impl ChainClient { Ok(Self { client }) } + /// Sets the DKIM public key hash. + /// + /// # Arguments + /// + /// * `selector` - The selector string. + /// * `domain_name` - The domain name. + /// * `public_key_hash` - The public key hash as a 32-byte array. + /// * `signature` - The signature as Bytes. + /// * `dkim` - The ECDSA Owned DKIM Registry. + /// + /// # Returns + /// + /// A `Result` containing the transaction hash as a String if successful, or an error if not. pub async fn set_dkim_public_key_hash( &self, selector: String, @@ -52,6 +70,17 @@ impl ChainClient { Ok(tx_hash) } + /// Checks if a DKIM public key hash is valid. + /// + /// # Arguments + /// + /// * `domain_name` - The domain name. + /// * `public_key_hash` - The public key hash as a 32-byte array. + /// * `dkim` - The ECDSA Owned DKIM Registry. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the hash is valid. pub async fn check_if_dkim_public_key_hash_valid( &self, domain_name: ::std::string::String, @@ -65,6 +94,15 @@ impl ChainClient { Ok(is_valid) } + /// Gets the DKIM from a wallet. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// + /// # Returns + /// + /// A `Result` containing the ECDSA Owned DKIM Registry if successful, or an error if not. pub async fn get_dkim_from_wallet( &self, controller_eth_addr: &str, @@ -75,6 +113,15 @@ impl ChainClient { Ok(ECDSAOwnedDKIMRegistry::new(dkim, self.client.clone())) } + /// Gets the DKIM from an email auth address. + /// + /// # Arguments + /// + /// * `email_auth_addr` - The email auth address as a string. + /// + /// # Returns + /// + /// A `Result` containing the ECDSA Owned DKIM Registry if successful, or an error if not. pub async fn get_dkim_from_email_auth( &self, email_auth_addr: &str, @@ -86,6 +133,17 @@ impl ChainClient { Ok(ECDSAOwnedDKIMRegistry::new(dkim, self.client.clone())) } + /// Gets the email auth address from a wallet. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `wallet_addr` - The wallet address as a string. + /// * `account_salt` - The account salt as a string. + /// + /// # Returns + /// + /// A `Result` containing the email auth address as H160 if successful, or an error if not. pub async fn get_email_auth_addr_from_wallet( &self, controller_eth_addr: &str, @@ -108,6 +166,15 @@ impl ChainClient { Ok(email_auth_addr) } + /// Checks if a wallet is deployed. + /// + /// # Arguments + /// + /// * `wallet_addr_str` - The wallet address as a string. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the wallet is deployed. pub async fn is_wallet_deployed(&self, wallet_addr_str: &str) -> Result { let wallet_addr: H160 = wallet_addr_str.parse().map_err(ChainError::HexError)?; match self.client.get_code(wallet_addr, None).await { @@ -122,6 +189,16 @@ impl ChainClient { } } + /// Gets the acceptance command templates. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing a vector of acceptance command templates. pub async fn get_acceptance_command_templates( &self, controller_eth_addr: &str, @@ -140,6 +217,16 @@ impl ChainClient { Ok(templates[template_idx as usize].clone()) } + /// Gets the recovery command templates. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing a vector of recovery command templates. pub async fn get_recovery_command_templates( &self, controller_eth_addr: &str, @@ -158,6 +245,17 @@ impl ChainClient { Ok(templates[template_idx as usize].clone()) } + /// Completes the recovery process. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `account_eth_addr` - The account Ethereum address as a string. + /// * `complete_calldata` - The complete calldata as a string. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the recovery was successful. pub async fn complete_recovery( &self, controller_eth_addr: &str, @@ -207,6 +305,17 @@ impl ChainClient { .unwrap_or(false)) } + /// Handles the acceptance process. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `email_auth_msg` - The email authentication message. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the acceptance was successful. pub async fn handle_acceptance( &self, controller_eth_addr: &str, @@ -238,6 +347,17 @@ impl ChainClient { .unwrap_or(false)) } + /// Handles the recovery process. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `email_auth_msg` - The email authentication message. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the recovery was successful. pub async fn handle_recovery( &self, controller_eth_addr: &str, @@ -266,6 +386,15 @@ impl ChainClient { .unwrap_or(false)) } + /// Gets the bytecode of a wallet. + /// + /// # Arguments + /// + /// * `wallet_addr` - The wallet address as a string. + /// + /// # Returns + /// + /// A `Result` containing the bytecode as Bytes. pub async fn get_bytecode(&self, wallet_addr: &str) -> std::result::Result { let wallet_address: H160 = wallet_addr.parse().map_err(ChainError::HexError)?; let client_code = self @@ -276,6 +405,16 @@ impl ChainClient { Ok(client_code) } + /// Gets the storage at a specific slot for a wallet. + /// + /// # Arguments + /// + /// * `wallet_addr` - The wallet address as a string. + /// * `slot` - The storage slot. + /// + /// # Returns + /// + /// A `Result` containing the storage value as H256. pub async fn get_storage_at( &self, wallet_addr: &str, @@ -288,6 +427,17 @@ impl ChainClient { .await?) } + /// Gets the recovered account from an acceptance command. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `command_params` - The command parameters. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing the recovered account address as H160. pub async fn get_recovered_account_from_acceptance_command( &self, controller_eth_addr: &str, @@ -320,6 +470,17 @@ impl ChainClient { Ok(recovered_account) } + /// Gets the recovered account from a recovery command. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `command_params` - The command parameters. + /// * `template_idx` - The template index. + /// + /// # Returns + /// + /// A `Result` containing the recovered account address as H160. pub async fn get_recovered_account_from_recovery_command( &self, controller_eth_addr: &str, @@ -353,6 +514,16 @@ impl ChainClient { Ok(recovered_account) } + /// Checks if an account is activated. + /// + /// # Arguments + /// + /// * `controller_eth_addr` - The controller Ethereum address as a string. + /// * `account_eth_addr` - The account Ethereum address as a string. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating if the account is activated. pub async fn get_is_activated( &self, controller_eth_addr: &str, diff --git a/packages/relayer/src/core.rs b/packages/relayer/src/core.rs index fd4e16a..43986c6 100644 --- a/packages/relayer/src/core.rs +++ b/packages/relayer/src/core.rs @@ -19,6 +19,15 @@ const DOMAIN_FIELDS: usize = 9; const COMMAND_FIELDS: usize = 20; const EMAIL_ADDR_FIELDS: usize = 9; +/// Handles an incoming email for authentication or recovery. +/// +/// # Arguments +/// +/// * `email` - The raw email string to be processed. +/// +/// # Returns +/// +/// A `Result` containing an `EmailAuthEvent` on success, or an `EmailError` on failure. pub async fn handle_email(email: String) -> Result { let parsed_email = ParsedEmail::new_from_raw_email(&email).await?; trace!(LOG, "email: {}", email); diff --git a/packages/relayer/src/database.rs b/packages/relayer/src/database.rs index 1af6a22..5998413 100644 --- a/packages/relayer/src/database.rs +++ b/packages/relayer/src/database.rs @@ -30,6 +30,15 @@ pub struct Database { } impl Database { + /// Opens a new database connection. + /// + /// # Arguments + /// + /// * `path` - The connection string for the database. + /// + /// # Returns + /// + /// A `Result` containing the `Database` struct if successful, or an error if the connection fails. pub async fn open(path: &str) -> Result { let res = Self { db: PgPool::connect(path) @@ -42,6 +51,11 @@ impl Database { Ok(res) } + /// Sets up the database by creating necessary tables if they don't exist. + /// + /// # Returns + /// + /// A `Result` indicating success or failure of the setup process. pub async fn setup_database(&self) -> Result<()> { sqlx::query( "CREATE TABLE IF NOT EXISTS credentials ( @@ -208,6 +222,16 @@ impl Database { Ok(()) } + /// Checks if a guardian is set for a given account and email address. + /// + /// # Arguments + /// + /// * `account_eth_addr` - The Ethereum address of the account. + /// * `guardian_email_addr` - The email address of the guardian. + /// + /// # Returns + /// + /// A `Result` containing a boolean indicating whether the guardian is set. pub async fn is_guardian_set( &self, account_eth_addr: &str, diff --git a/packages/relayer/src/modules/dkim.rs b/packages/relayer/src/modules/dkim.rs index b1d29c2..21ae7d3 100644 --- a/packages/relayer/src/modules/dkim.rs +++ b/packages/relayer/src/modules/dkim.rs @@ -30,6 +30,16 @@ pub struct SignedDkimPublicKey { } impl<'a> DkimOracleClient<'a> { + /// Generates an agent for the DKIM Oracle Client. + /// + /// # Arguments + /// + /// * `pem_path` - The path to the PEM file. + /// * `replica_url` - The URL of the replica. + /// + /// # Returns + /// + /// An `anyhow::Result`. pub fn gen_agent(pem_path: &str, replica_url: &str) -> anyhow::Result { let identity = Secp256k1Identity::from_pem_file(pem_path)?; let transport = ReqwestTransport::create(replica_url)?; @@ -40,6 +50,16 @@ impl<'a> DkimOracleClient<'a> { Ok(agent) } + /// Creates a new DkimOracleClient. + /// + /// # Arguments + /// + /// * `canister_id` - The ID of the canister. + /// * `agent` - The agent to use for communication. + /// + /// # Returns + /// + /// An `anyhow::Result`. pub fn new(canister_id: &str, agent: &'a Agent) -> anyhow::Result { let canister = CanisterBuilder::new() .with_canister_id(canister_id) @@ -48,6 +68,16 @@ impl<'a> DkimOracleClient<'a> { Ok(Self { canister }) } + /// Requests a signature for a DKIM public key. + /// + /// # Arguments + /// + /// * `selector` - The selector for the DKIM key. + /// * `domain` - The domain for the DKIM key. + /// + /// # Returns + /// + /// An `anyhow::Result`. pub async fn request_signature( &self, selector: &str, @@ -67,6 +97,19 @@ impl<'a> DkimOracleClient<'a> { } } +/// Checks and updates the DKIM for a given email. +/// +/// # Arguments +/// +/// * `email` - The email address. +/// * `parsed_email` - The parsed email data. +/// * `controller_eth_addr` - The Ethereum address of the controller. +/// * `wallet_addr` - The address of the wallet. +/// * `account_salt` - The salt for the account. +/// +/// # Returns +/// +/// A `Result<()>`. pub async fn check_and_update_dkim( email: &str, parsed_email: &ParsedEmail, diff --git a/packages/relayer/src/modules/mail.rs b/packages/relayer/src/modules/mail.rs index ffc15d8..c90b6d8 100644 --- a/packages/relayer/src/modules/mail.rs +++ b/packages/relayer/src/modules/mail.rs @@ -80,6 +80,15 @@ pub struct EmailAttachment { pub contents: Vec, } +/// Handles all possible email events and requests. +/// +/// # Arguments +/// +/// * `event` - The `EmailAuthEvent` to be handled. +/// +/// # Returns +/// +/// A `Result` indicating success or an `EmailError`. pub async fn handle_email_event(event: EmailAuthEvent) -> Result<(), EmailError> { match event { EmailAuthEvent::AcceptanceRequest { @@ -378,6 +387,16 @@ pub async fn handle_email_event(event: EmailAuthEvent) -> Result<(), EmailError> Ok(()) } +/// Renders an HTML template with the given data. +/// +/// # Arguments +/// +/// * `template_name` - The name of the template file. +/// * `render_data` - The data to be used in rendering the template. +/// +/// # Returns +/// +/// A `Result` containing the rendered HTML string or an `EmailError`. pub async fn render_html(template_name: &str, render_data: Value) -> Result { let email_template_filename = PathBuf::new() .join(EMAIL_TEMPLATES.get().unwrap()) @@ -397,6 +416,15 @@ pub async fn render_html(template_name: &str, render_data: Value) -> Result` with the parsed error message. pub fn parse_error(error: String) -> Result> { let mut error = error; if error.contains("Contract call reverted with data: ") { @@ -420,6 +448,15 @@ pub fn parse_error(error: String) -> Result> { } } +/// Sends an email using the configured SMTP server. +/// +/// # Arguments +/// +/// * `email` - The `EmailMessage` to be sent. +/// +/// # Returns +/// +/// A `Result` indicating success or an `EmailError`. pub async fn send_email(email: EmailMessage) -> Result<(), EmailError> { let smtp_server = SMTP_SERVER.get().unwrap(); diff --git a/packages/relayer/src/modules/web_server/mod.rs b/packages/relayer/src/modules/web_server/mod.rs index 35ed632..3a48beb 100644 --- a/packages/relayer/src/modules/web_server/mod.rs +++ b/packages/relayer/src/modules/web_server/mod.rs @@ -1,3 +1,5 @@ +//! This module contains the axum web server and its routes and custom errors. + pub mod relayer_errors; pub mod rest_api; pub mod server; diff --git a/packages/relayer/src/modules/web_server/rest_api.rs b/packages/relayer/src/modules/web_server/rest_api.rs index 1f520ce..df9bce3 100644 --- a/packages/relayer/src/modules/web_server/rest_api.rs +++ b/packages/relayer/src/modules/web_server/rest_api.rs @@ -7,7 +7,15 @@ use relayer_utils::{calculate_account_salt, extract_template_vals, TemplateValue use serde::{Deserialize, Serialize}; use std::str; -// Create request status API +/// Retrieves the status of a request. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the request ID. +/// +/// # Returns +/// +/// A `Result` containing a JSON `RequestStatusResponse` or an `ApiError`. pub async fn request_status_api( Json(payload): Json, ) -> Result, ApiError> { @@ -33,6 +41,15 @@ pub async fn request_status_api( })) } +/// Handles an acceptance request for a wallet. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the acceptance request details. +/// +/// # Returns +/// +/// A `Result` containing a JSON `AcceptanceResponse` or an `ApiError`. pub async fn handle_acceptance_request( Json(payload): Json, ) -> Result, ApiError> { @@ -193,6 +210,15 @@ pub async fn handle_acceptance_request( })) } +/// Handles a recovery request for a wallet. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the recovery request details. +/// +/// # Returns +/// +/// A `Result` containing a JSON `RecoveryResponse` or an `ApiError`. pub async fn handle_recovery_request( Json(payload): Json, ) -> Result, ApiError> { @@ -386,6 +412,15 @@ pub async fn handle_recovery_request( })) } +/// Handles the completion of a recovery request. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the complete recovery request details. +/// +/// # Returns +/// +/// A `Result` containing a `String` message or an `ApiError`. pub async fn handle_complete_recovery_request( Json(payload): Json, ) -> Result { @@ -425,6 +460,15 @@ pub async fn handle_complete_recovery_request( } } +/// Retrieves the account salt for a given email address and account code. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the email address and account code. +/// +/// # Returns +/// +/// A `Result` containing the account salt as a `String` or an `ApiError`. pub async fn get_account_salt( Json(payload): Json, ) -> Result { @@ -433,6 +477,15 @@ pub async fn get_account_salt( Ok(account_salt) } +/// Marks a guardian as inactive for a given wallet. +/// +/// # Arguments +/// +/// * `payload` - A JSON payload containing the account and controller Ethereum addresses. +/// +/// # Returns +/// +/// A `Result` containing a `String` message or an `ApiError`. pub async fn inactive_guardian( Json(payload): Json, ) -> Result { @@ -472,6 +525,15 @@ fn parse_error_message(error_data: String) -> String { format!("Failed to parse contract error: {}", error_data) } +/// Receives and processes an email. +/// +/// # Arguments +/// +/// * `email` - The raw email as a `String`. +/// +/// # Returns +/// +/// A `Result` containing `()` or an `ApiError`. pub async fn receive_email_api_fn(email: String) -> Result<(), ApiError> { println!("receive_email_api_fn"); let parsed_email = ParsedEmail::new_from_raw_email(&email).await?; diff --git a/packages/relayer/src/modules/web_server/server.rs b/packages/relayer/src/modules/web_server/server.rs index f96afb1..594ee4c 100644 --- a/packages/relayer/src/modules/web_server/server.rs +++ b/packages/relayer/src/modules/web_server/server.rs @@ -3,6 +3,11 @@ use axum::{routing::post, Router}; use relayer_utils::LOG; use tower_http::cors::{AllowHeaders, AllowMethods, Any, CorsLayer}; +/// Runs the server and sets up the API routes. +/// +/// # Returns +/// +/// A `Result` indicating success or failure. pub async fn run_server() -> Result<()> { let addr = WEB_SERVER_ADDRESS.get().unwrap();