diff --git a/crates/iota-sdk/src/iota_client_config.rs b/crates/iota-sdk/src/iota_client_config.rs index 2cecb9cc899..f53d58052e5 100644 --- a/crates/iota-sdk/src/iota_client_config.rs +++ b/crates/iota-sdk/src/iota_client_config.rs @@ -17,6 +17,9 @@ use crate::{ IOTA_TESTNET_GAS_URL, IOTA_TESTNET_URL, IotaClient, IotaClientBuilder, }; +/// Configuration for the IOTA client, containing a +/// [`Keystore`](iota_keys::keystore::Keystore) and potentially multiple +/// [`IotaEnv`]s. #[serde_as] #[derive(Serialize, Deserialize, Getters, MutGetters)] #[getset(get = "pub", get_mut = "pub")] @@ -28,6 +31,7 @@ pub struct IotaClientConfig { } impl IotaClientConfig { + /// Create a new [`IotaClientConfig`] with the given keystore. pub fn new(keystore: impl Into) -> Self { IotaClientConfig { keystore: keystore.into(), @@ -37,33 +41,40 @@ impl IotaClientConfig { } } + /// Set the [`IotaEnv`]s. pub fn with_envs(mut self, envs: impl IntoIterator) -> Self { self.set_envs(envs); self } + /// Set the [`IotaEnv`]s. pub fn set_envs(&mut self, envs: impl IntoIterator) { self.envs = envs.into_iter().collect(); } + /// Set the active [`IotaEnv`] by its alias. pub fn with_active_env(mut self, env: impl Into>) -> Self { self.set_active_env(env); self } + /// Set the active [`IotaEnv`] by its alias. pub fn set_active_env(&mut self, env: impl Into>) { self.active_env = env.into(); } + /// Set the active [`IotaAddress`]. pub fn with_active_address(mut self, address: impl Into>) -> Self { self.set_active_address(address); self } + /// Set the active [`IotaAddress`]. pub fn set_active_address(&mut self, address: impl Into>) { self.active_address = address.into(); } + /// Get the first [`IotaEnv`] or one by its alias. pub fn get_env(&self, alias: &Option) -> Option<&IotaEnv> { if let Some(alias) = alias { self.envs.iter().find(|env| &env.alias == alias) @@ -72,6 +83,7 @@ impl IotaClientConfig { } } + /// Get the active [`IotaEnv`]. pub fn get_active_env(&self) -> Result<&IotaEnv, anyhow::Error> { self.get_env(&self.active_env).ok_or_else(|| { anyhow!( @@ -81,6 +93,7 @@ impl IotaClientConfig { }) } + /// Add an [`IotaEnv`]. pub fn add_env(&mut self, env: IotaEnv) { if !self .envs @@ -92,6 +105,8 @@ impl IotaClientConfig { } } +/// IOTA environment configuration, containing the RPC URL, and optional +/// websocket, basic auth and faucet options. #[derive(Debug, Clone, Serialize, Deserialize, Getters, MutGetters)] #[getset(get = "pub", get_mut = "pub")] pub struct IotaEnv { @@ -105,6 +120,7 @@ pub struct IotaEnv { } impl IotaEnv { + /// Create a new [`IotaEnv`] with the given alias and RPC URL such as . pub fn new(alias: impl Into, rpc: impl Into) -> Self { Self { alias: alias.into(), @@ -115,33 +131,42 @@ impl IotaEnv { } } + /// Set a websocket URL. pub fn with_ws(mut self, ws: impl Into>) -> Self { self.set_ws(ws); self } + /// Set a websocket URL. pub fn set_ws(&mut self, ws: impl Into>) { self.ws = ws.into(); } + /// Set basic authentication information in the format of username:password. pub fn with_basic_auth(mut self, basic_auth: impl Into>) -> Self { - self.set_ws(basic_auth); + self.set_basic_auth(basic_auth); self } + /// Set basic authentication information in the format of username:password. pub fn set_basic_auth(&mut self, basic_auth: impl Into>) { self.basic_auth = basic_auth.into(); } + /// Set a faucet URL such as . pub fn with_faucet(mut self, faucet: impl Into>) -> Self { self.set_faucet(faucet); self } + /// Set a faucet URL such as . pub fn set_faucet(&mut self, faucet: impl Into>) { self.faucet = faucet.into(); } + /// Create an [`IotaClient`] with the given request timeout, max + /// concurrent requests and possible configured websocket URL and basic + /// auth. pub async fn create_rpc_client( &self, request_timeout: impl Into>, @@ -173,6 +198,7 @@ impl IotaEnv { Ok(builder.build(&self.rpc).await?) } + /// Create the env with the default devnet configuration. pub fn devnet() -> Self { Self { alias: "devnet".to_string(), @@ -182,6 +208,8 @@ impl IotaEnv { faucet: Some(IOTA_DEVNET_GAS_URL.into()), } } + + /// Create the env with the default testnet configuration. pub fn testnet() -> Self { Self { alias: "testnet".to_string(), @@ -192,6 +220,7 @@ impl IotaEnv { } } + /// Create the env with the default localnet configuration. pub fn localnet() -> Self { Self { alias: "local".to_string(), diff --git a/crates/iota-sdk/src/wallet_context.rs b/crates/iota-sdk/src/wallet_context.rs index 2fd6b140315..9be93f180a1 100644 --- a/crates/iota-sdk/src/wallet_context.rs +++ b/crates/iota-sdk/src/wallet_context.rs @@ -25,6 +25,8 @@ use tracing::warn; use crate::{IotaClient, iota_client_config::IotaClientConfig}; +/// Wallet for managing accounts, objects, and interact with client APIs. +// Mainly used in the CLI and tests. #[derive(Getters, MutGetters)] #[getset(get = "pub", get_mut = "pub")] pub struct WalletContext { @@ -35,6 +37,8 @@ pub struct WalletContext { } impl WalletContext { + /// Create a new [`WalletContext`] with the config path to an existing + /// [`IotaClientConfig`] and optional parameters for the client. pub fn new( config_path: &Path, request_timeout: impl Into>, @@ -57,10 +61,12 @@ impl WalletContext { Ok(context) } + /// Get all addresses from the keystore. pub fn get_addresses(&self) -> Vec { self.config.keystore.addresses() } + /// Get the configured [`IotaClient`]. pub async fn get_client(&self) -> Result { let read = self.client.read().await; @@ -82,6 +88,8 @@ impl WalletContext { } // TODO: Ger rid of mut + /// Get the active [`IotaAddress`]. + /// If not set, set it to the first address in the keystore. pub fn active_address(&mut self) -> Result { if self.config.keystore.addresses().is_empty() { return Err(anyhow!( @@ -157,6 +165,7 @@ impl WalletContext { Ok(values_objects) } + /// Get the address that owns the object of the provided [`ObjectID`]. pub async fn get_object_owner(&self, id: &ObjectID) -> Result { let client = self.get_client().await?; let object = client @@ -170,6 +179,7 @@ impl WalletContext { .get_owner_address()?) } + /// Get the address that owns the object, if an [`ObjectID`] is provided. pub async fn try_get_object_owner( &self, id: &Option, @@ -198,6 +208,8 @@ impl WalletContext { )) } + /// Get the [`ObjectRef`] for gas objects owned by the provided address. + /// Maximum is RPC_QUERY_MAX_RESULT_LIMIT (50 by default). pub async fn get_all_gas_objects_owned_by_address( &self, address: IotaAddress, @@ -205,6 +217,9 @@ impl WalletContext { self.get_gas_objects_owned_by_address(address, None).await } + /// Get a limited amount of [`ObjectRef`]s for gas objects owned by the + /// provided address. Max limit is RPC_QUERY_MAX_RESULT_LIMIT (50 by + /// default). pub async fn get_gas_objects_owned_by_address( &self, address: IotaAddress,