Skip to content

Commit

Permalink
fix: remove parameters from doc comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@shamardy
shamardy committed Apr 1, 2024
1 parent ee8ecf3 commit 503aafb
Show file tree
Hide file tree
Showing 4 changed files with 30 additions and 225 deletions.
88 changes: 12 additions & 76 deletions mm2src/coins/hd_wallet/account_ops.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,106 +10,42 @@ use mm2_err_handle::prelude::*;
/// This allows for segregating funds into different accounts under the same seed,
/// with each account having multiple chains (often representing internal and external addresses).
///
/// Implementors of this trait provide details about such HD account like its specific derivation path, known addresses, and its index.
/// Implementors of this trait should provide details about such HD account like its specific derivation path, known addresses, and its index.
pub trait HDAccountOps {
type HDAddress: HDAddressOps + Clone + Send;

/// Creates a new `HDAccountOps` instance.
///
/// # Parameters
///
/// * `account_id`: The index of the account.
/// * `account_extended_pubkey`: The extended public key associated with this account.
/// * `account_derivation_path`: The derivation path from the master key to this account.
///
/// # Returns
///
/// A new `HDAccountOps` instance.
/// A constructor for any type that implements `HDAccountOps`.
fn new(
account_id: u32,
account_extended_pubkey: Secp256k1ExtendedPublicKey,
account_derivation_path: StandardHDPathToAccount,
) -> Self;

/// Provides the limit on the number of addresses that can be added to an account.
///
/// # Returns
///
/// A `u32` value indicating the maximum number of addresses.
/// The default is given by `DEFAULT_ADDRESS_LIMIT`.
/// Returns the limit on the number of addresses that can be added to an account.
fn address_limit(&self) -> u32;

/// Returns the number of known addresses of this account.
///
/// # Parameters
///
/// * `chain`: The `Bip44Chain` representing the BIP44 chain of the addresses.
///
/// # Returns
///
/// A result containing a `u32` that represents the number of known addresses
/// or an `InvalidBip44ChainError` if the coin doesn't support the given `chain`.
/// Returns the number of known addresses for this account for a specific chain/change
/// (internal/external) path.
fn known_addresses_number(&self, chain: Bip44Chain) -> MmResult<u32, InvalidBip44ChainError>;

/// Sets the number of known addresses of this account.
///
/// # Parameters
///
/// * `chain`: The `Bip44Chain` representing the BIP44 chain of the addresses.
/// * `new_known_addresses_number`: The new number of known addresses.
/// Sets the number of known addresses for this account for a specific chain/change
/// (internal/external) path.
fn set_known_addresses_number(&mut self, chain: Bip44Chain, new_known_addresses_number: u32);

/// Fetches the derivation path associated with this account.
///
/// # Returns
///
/// A `DerivationPath` indicating the path used to derive this account.
/// Returns the derivation path associated with this account.
fn account_derivation_path(&self) -> DerivationPath;

/// Retrieves the index of this account.
///
/// The account index is used as part of the derivation path, following the pattern `m/purpose'/coin'/account'`.
///
/// # Returns
///
/// A `u32` value indicating the account's index.
/// Returns the index of this account.
/// The account index is used as part of the derivation path,
/// following the pattern `m/purpose'/coin'/account'`.
fn account_id(&self) -> u32;

/// Checks if a specific address is activated (known) for this account at the present time.
///
/// # Parameters
///
/// * `chain`: The `Bip44Chain` representing the BIP44 chain of the address.
/// * `address_id`: The id (or index) of the address in question.
///
/// # Returns
///
/// A result containing a `bool` indicating if the address is activated,
/// or an `InvalidBip44ChainError` if the coin doesn't support the given `chain`.
///
/// # Example
///
/// ```rust
/// # use your_crate::{HDAccountOps, Bip44Chain};
/// # fn main() {
/// let account: impl HDAccountOps = /* ... */;
/// let is_activated = account.is_address_activated(Bip44Chain::External, 5).unwrap();
/// println!("Is address 5 activated? {}", is_activated);
/// # }
/// ```
fn is_address_activated(&self, chain: Bip44Chain, address_id: u32) -> MmResult<bool, InvalidBip44ChainError>;

/// Fetches the derived addresses from cache.
///
/// # Returns
///
/// A `HDAddressesCache` containing the derived addresses.
/// Fetches the derived/cached addresses.
fn derived_addresses(&self) -> &HDAddressesCache<Self::HDAddress>;

/// Fetches the extended public key associated with this account.
///
/// # Returns
///
/// A `Secp256k1ExtendedPublicKey` type representing the extended public key.
fn extended_pubkey(&self) -> &Secp256k1ExtendedPublicKey;
}
71 changes: 4 additions & 67 deletions mm2src/coins/hd_wallet/coin_ops.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,17 @@ pub struct HDAddressId {
/// This trait outlines fundamental operations like address derivation, account creation, and more.
#[async_trait]
pub trait HDWalletCoinOps {
/// The type representing the HD Wallet operations associated with this coin.
/// Any type that represents a Hierarchical Deterministic (HD) wallet.
type HDWallet: HDWalletOps + HDWalletStorageOps + Send + Sync;

/// Derives an address for the coin that implements this trait from an extended public key.
///
/// # Parameters
/// - `extended_pubkey`: The extended public key from which the address will be derived.
/// - `derivation_path`: The derivation path of the address.
///
/// # Returns
/// A result containing the derived `HDCoinHDAddress<Self>` instance or an error.
/// Derives an address for the coin that implements this trait from an extended public key and a derivation path.
fn address_from_extended_pubkey(
&self,
extended_pubkey: &Secp256k1ExtendedPublicKey,
derivation_path: DerivationPath,
) -> HDCoinHDAddress<Self>;

/// Retrieves an HD address from the cache or derives it if it hasn't been derived yet.
///
/// # Parameters
/// - `hd_account`: The HD account from which the address will be derived.
/// - `hd_addresses_cache`: The cache of derived addresses.
/// - `hd_address_id`: The unique address identifier.
///
/// # Returns
/// A result containing the derived `HDCoinHDAddress<Self>` instance or an error.
fn derive_address_with_cache(
&self,
hd_account: &HDCoinHDAccount<Self>,
Expand Down Expand Up @@ -77,14 +62,6 @@ pub trait HDWalletCoinOps {
}

/// Derives a single HD address for a given account, chain, and address identifier.
///
/// # Parameters
/// - `hd_account`: The HD account from which the address will be derived.
/// - `chain`: The Bip44 chain identifier.
/// - `address_id`: The unique address identifier.
///
/// # Returns
/// A result containing the derived `HDCoinHDAddress<Self>` instance or an error.
async fn derive_address(
&self,
hd_account: &HDCoinHDAccount<Self>,
Expand All @@ -101,13 +78,6 @@ pub trait HDWalletCoinOps {
}

/// Derives a set of HD addresses for a coin using the specified HD account and address identifiers.
///
/// # Parameters
/// - `hd_account`: The HD account associated with the addresses.
/// - `address_ids`: An iterator of `HDAddressId` items specifying which addresses to derive.
///
/// # Returns
/// A result containing a vector of derived `HDCoinHDAddress<Self>` instances or an error.
#[cfg(not(target_arch = "wasm32"))]
async fn derive_addresses<Ids>(
&self,
Expand Down Expand Up @@ -158,15 +128,8 @@ pub trait HDWalletCoinOps {
Ok(result)
}

/// Derives known HD addresses for a specific account and chain.
/// Retrieves or derives known HD addresses for a specific account and chain.
/// Essentially, this retrieves addresses that have been interacted with in the past.
///
/// # Parameters
/// - `hd_account`: The HD account from which to derive known addresses.
/// - `chain`: The Bip44 chain identifier.
///
/// # Returns
/// A result containing a vector of previously generated `HDAddress<Self::Address, Self::Pubkey>` instances or an error.
async fn derive_known_addresses(
&self,
hd_account: &HDCoinHDAccount<Self>,
Expand All @@ -180,14 +143,6 @@ pub trait HDWalletCoinOps {
}

/// Generates a new address for a coin and updates the corresponding number of used `hd_account` addresses.
///
/// # Parameters
/// - `hd_wallet`: The specified HD wallet from which the address will be derived.
/// - `hd_account`: The mutable HD account.
/// - `chain`: The Bip44 chain identifier.
///
/// # Returns
/// A result containing the generated `HDAddress<Self::Address, Self::Pubkey>` instance or an error.
async fn generate_new_address(
&self,
hd_wallet: &Self::HDWallet,
Expand All @@ -208,15 +163,6 @@ pub trait HDWalletCoinOps {
/// This method prompts the user to verify if the derived address matches
/// the hardware wallet display, ensuring security and accuracy when
/// dealing with hardware wallets.
///
/// # Parameters
/// - `hd_wallet`: The specified HD wallet.
/// - `hd_account`: The mutable HD account.
/// - `chain`: The Bip44 chain identifier.
/// - `confirm_address`: Address confirmation method.
///
/// # Returns
/// A result containing the confirmed `HDAddress<Self::Address, Self::Pubkey>` instance or an error.
async fn generate_and_confirm_new_address<ConfirmAddress>(
&self,
hd_wallet: &Self::HDWallet,
Expand Down Expand Up @@ -253,17 +199,8 @@ pub trait HDWalletCoinOps {
Ok(hd_address)
}

/// Updates the count of known addresses for a specified HD account and chain.
/// Updates the count of known addresses for a specified HD account and chain/change path.
/// This is useful for tracking the number of created addresses.
///
/// # Parameters
/// - `hd_wallet`: The specified HD wallet.
/// - `hd_account`: The mutable HD account to be updated.
/// - `chain`: The Bip44 chain identifier.
/// - `new_known_addresses_number`: The new count of known addresses.
///
/// # Returns
/// A result indicating success or an error.
async fn set_known_addresses_number(
&self,
hd_wallet: &Self::HDWallet,
Expand Down
86 changes: 13 additions & 73 deletions mm2src/coins/hd_wallet/wallet_ops.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,112 +2,52 @@ use super::{HDAccountMut, HDAccountOps, HDAccountsMap, HDAccountsMut, HDAccounts
use async_trait::async_trait;
use crypto::{Bip44Chain, StandardHDPathToCoin};

/// `HDWalletOps`: Operations that should be implemented for Structs that represent HD wallets.
/// `HDWalletOps`: Operations that should be implemented for Structs or any type that represents HD wallets.
#[async_trait]
pub trait HDWalletOps {
/// The HD account operations associated with this wallet.
/// Any type that represents a Hierarchical Deterministic (HD) wallet account.
type HDAccount: HDAccountOps + Clone + Send + Sync;

/// Returns the coin type associated with this HD Wallet.
///
/// This method can be implemented to fetch the coin type as specified in the wallet's BIP44 derivation path.
/// For example, in the derivation path `m/44'/0'/0'/0`, the coin type would be `0` (representing Bitcoin).
///
/// # Returns
///
/// A `u32` value representing the coin type from the wallet's derivation path.
/// This method should be implemented to fetch the coin type as specified in the wallet's BIP44 derivation path.
/// For example, in the derivation path `m/44'/0'/0'/0`, the coin type would be the third level `0'`
/// (representing Bitcoin).
fn coin_type(&self) -> u32;

/// Returns the derivation path associated with this HD Wallet.
///
/// This method can be implemented to fetch the derivation path as specified in the wallet's BIP44 derivation path.
///
/// # Returns
///
/// A `StandardHDPathToCoin` value representing the derivation path from the wallet's derivation path.
/// Returns the derivation path associated with this HD Wallet. This is the path used to derive the accounts.
fn derivation_path(&self) -> &StandardHDPathToCoin;

/// Fetches the gap limit associated with this HD Wallet.
///
/// # Returns
///
/// A `u32` value that specifies the gap limit.
/// Gap limit is the maximum number of consecutive unused addresses in an account
/// that should be checked before considering the wallet as having no more funds.
fn gap_limit(&self) -> u32;

/// Specifies the limit on the number of accounts that can be added to the wallet.
///
/// # Returns
///
/// A `u32` value indicating the maximum number of accounts.
/// The default is set by `DEFAULT_ACCOUNT_LIMIT`.
/// Returns the limit on the number of accounts that can be added to the wallet.
fn account_limit(&self) -> u32;

/// Specifies the default BIP44 chain for receiver addresses.
///
/// # Returns
///
/// A `Bip44Chain` value.
/// The default is set by `DEFAULT_RECEIVER_CHAIN`.
/// Returns the default BIP44 chain for receiver addresses.
fn default_receiver_chain(&self) -> Bip44Chain;

/// Provides a mutex that guards the HD accounts.
///
/// # Returns
///
/// A reference to the accounts mutex.
/// Returns a mutex that can be used to access the accounts.
fn get_accounts_mutex(&self) -> &HDAccountsMutex<Self::HDAccount>;

/// Fetches an account based on its ID. This method will return `None` if the account is not activated.
///
/// # Parameters
///
/// - `account_id`: The ID of the desired account.
///
/// # Returns
///
/// An `Option<Self::HDAccount>` which contains the account if found.
async fn get_account(&self, account_id: u32) -> Option<Self::HDAccount>;

/// Similar to `get_account`, but provides a mutable reference.
///
/// # Parameters
///
/// - `account_id`: The ID of the desired account.
///
/// # Returns
///
/// An `Option` containing a mutable reference to the account if found.
async fn get_account_mut(&self, account_id: u32) -> Option<HDAccountMut<'_, Self::HDAccount>>;

/// Gathers all the activated accounts.
///
/// # Returns
///
/// A map containing all the currently activated HD accounts.
/// Fetches all accounts in the wallet.
async fn get_accounts(&self) -> HDAccountsMap<Self::HDAccount>;

/// Similar to `get_accounts`, but provides a mutable reference to the accounts.
///
/// # Returns
///
/// A mutable reference to the map of all activated HD accounts.
async fn get_accounts_mut(&self) -> HDAccountsMut<'_, Self::HDAccount>;

/// Attempts to remove an account only if it's the last in the set.
///
/// # Parameters
///
/// - `account_id`: The ID of the account to be considered for removal.
///
/// # Returns
///
/// An `Option` containing the removed HD account if it was indeed the last one, otherwise `None`.
/// This method will return the removed account if successful or `None` otherwise.
async fn remove_account_if_last(&self, account_id: u32) -> Option<Self::HDAccount>;

/// Returns an address that's currently enabled for single-address operations, such as swaps.
///
/// # Returns
///
/// An `Option` containing the enabled address if available.
async fn get_enabled_address(&self) -> Option<<Self::HDAccount as HDAccountOps>::HDAddress>;
}
10 changes: 1 addition & 9 deletions mm2src/coins/hd_wallet/withdraw_ops.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,15 +54,7 @@ pub struct WithdrawSenderAddress<Address, Pubkey> {
#[async_trait]
pub trait HDCoinWithdrawOps: HDWalletCoinOps {
/// Fetches the sender address for a withdraw operation.
///
/// # Parameters
///
/// * `hd_wallet`: The HD wallet from which the withdraw is being made.
/// * `from`: The address id or the derivation path of the sender address.
///
/// # Returns
///
/// A struct representing the sender address or an error if the address is not activated.
/// This is the address from which the funds will be withdrawn.
async fn get_withdraw_hd_sender(
&self,
hd_wallet: &Self::HDWallet,
Expand Down

0 comments on commit 503aafb

Please sign in to comment.