iota_sdk/
iota_client_config.rs

1// Copyright (c) Mysten Labs, Inc.
2// Modifications Copyright (c) 2024 IOTA Stiftung
3// SPDX-License-Identifier: Apache-2.0
4
5use std::fmt::{Display, Formatter, Write};
6
7use anyhow::{anyhow, bail};
8use getset::{Getters, MutGetters};
9use iota_config::Config;
10use iota_keys::keystore::{AccountKeystore, Keystore};
11use iota_types::base_types::*;
12use serde::{Deserialize, Serialize};
13use serde_with::serde_as;
14
15use crate::{
16    IOTA_DEVNET_GAS_URL, IOTA_DEVNET_GRAPHQL_URL, IOTA_DEVNET_URL, IOTA_LOCAL_NETWORK_GAS_URL,
17    IOTA_LOCAL_NETWORK_GRAPHQL_URL, IOTA_LOCAL_NETWORK_URL, IOTA_MAINNET_GRAPHQL_URL,
18    IOTA_MAINNET_URL, IOTA_TESTNET_GAS_URL, IOTA_TESTNET_GRAPHQL_URL, IOTA_TESTNET_URL, IotaClient,
19    IotaClientBuilder,
20};
21
22/// Configuration for the IOTA client, containing a
23/// [`Keystore`](iota_keys::keystore::Keystore) and potentially multiple
24/// [`IotaEnv`]s.
25#[serde_as]
26#[derive(Serialize, Deserialize, Getters, MutGetters)]
27#[getset(get = "pub", get_mut = "pub")]
28pub struct IotaClientConfig {
29    pub(crate) keystore: Keystore,
30    pub(crate) envs: Vec<IotaEnv>,
31    pub(crate) active_env: Option<String>,
32    pub(crate) active_address: Option<IotaAddress>,
33}
34
35impl IotaClientConfig {
36    /// Create a new [`IotaClientConfig`] with the given keystore.
37    pub fn new(keystore: impl Into<Keystore>) -> Self {
38        let keystore = keystore.into();
39        IotaClientConfig {
40            envs: Default::default(),
41            active_env: None,
42            active_address: keystore.addresses().first().copied(),
43            keystore,
44        }
45    }
46
47    /// Set the default [`IotaEnv`]s for mainnet, devnet, testnet, and localnet.
48    pub fn with_default_envs(mut self) -> Self {
49        // We don't want to set any particular one of the default networks as active.
50        self.envs = vec![
51            IotaEnv::mainnet(),
52            IotaEnv::devnet(),
53            IotaEnv::testnet(),
54            IotaEnv::localnet(),
55        ];
56        self
57    }
58
59    /// Set the [`IotaEnv`]s.
60    pub fn with_envs(mut self, envs: impl IntoIterator<Item = IotaEnv>) -> Self {
61        self.set_envs(envs);
62        self
63    }
64
65    /// Set the [`IotaEnv`]s. Also sets the active env to the first in the list.
66    pub fn set_envs(&mut self, envs: impl IntoIterator<Item = IotaEnv>) {
67        self.envs = envs.into_iter().collect();
68        if let Some(env) = self.envs.first() {
69            self.set_active_env(env.alias().clone());
70        }
71    }
72
73    /// Set the active [`IotaEnv`] by its alias.
74    pub fn with_active_env(mut self, env: impl Into<Option<String>>) -> Self {
75        self.set_active_env(env);
76        self
77    }
78
79    /// Set the active [`IotaEnv`] by its alias.
80    pub fn set_active_env(&mut self, env: impl Into<Option<String>>) {
81        self.active_env = env.into();
82    }
83
84    /// Set the active [`IotaAddress`].
85    pub fn with_active_address(mut self, address: impl Into<Option<IotaAddress>>) -> Self {
86        self.set_active_address(address);
87        self
88    }
89
90    /// Set the active [`IotaAddress`].
91    pub fn set_active_address(&mut self, address: impl Into<Option<IotaAddress>>) {
92        self.active_address = address.into();
93    }
94
95    /// Get an [`IotaEnv`] by its alias.
96    pub fn get_env(&self, alias: &str) -> Option<&IotaEnv> {
97        self.envs.iter().find(|env| env.alias == alias)
98    }
99
100    /// Get the active [`IotaEnv`].
101    pub fn get_active_env(&self) -> Result<&IotaEnv, anyhow::Error> {
102        self.active_env
103            .as_ref()
104            .and_then(|alias| self.get_env(alias))
105            .ok_or_else(|| {
106                anyhow!(
107                    "Environment configuration not found for env [{}]",
108                    self.active_env.as_deref().unwrap_or("None")
109                )
110            })
111    }
112
113    /// Add an [`IotaEnv`] if there's no env with the same alias already.
114    pub fn add_env(&mut self, env: IotaEnv) {
115        if self.get_env(&env.alias).is_none() {
116            if self
117                .active_env
118                .as_ref()
119                .and_then(|env| self.get_env(env))
120                .is_none()
121            {
122                self.set_active_env(env.alias.clone());
123            }
124            self.envs.push(env);
125        }
126    }
127
128    /// Set an [`IotaEnv`]. Replaces any existing env with the same alias.
129    pub fn set_env(&mut self, env: IotaEnv) {
130        self.envs.retain(|e| e.alias != env.alias);
131        self.add_env(env);
132    }
133}
134
135/// IOTA environment configuration, containing the RPC URL, and optional
136/// websocket, basic auth and faucet options.
137#[derive(Debug, Clone, Serialize, Deserialize, Getters, MutGetters)]
138#[getset(get = "pub", get_mut = "pub")]
139pub struct IotaEnv {
140    pub(crate) alias: String,
141    pub(crate) rpc: String,
142    pub(crate) graphql: Option<String>,
143    pub(crate) ws: Option<String>,
144    /// Basic HTTP access authentication in the format of username:password, if
145    /// needed.
146    pub(crate) basic_auth: Option<String>,
147    pub(crate) faucet: Option<String>,
148}
149
150impl IotaEnv {
151    /// Create a new [`IotaEnv`] with the given alias and RPC URL such as <https://api.testnet.iota.cafe>.
152    pub fn new(alias: impl Into<String>, rpc: impl Into<String>) -> Self {
153        Self {
154            alias: alias.into(),
155            rpc: rpc.into(),
156            graphql: None,
157            ws: None,
158            basic_auth: None,
159            faucet: None,
160        }
161    }
162
163    /// Set a graphql URL.
164    pub fn with_graphql(mut self, graphql: impl Into<Option<String>>) -> Self {
165        self.set_graphql(graphql);
166        self
167    }
168
169    /// Set a graphql URL.
170    pub fn set_graphql(&mut self, graphql: impl Into<Option<String>>) {
171        self.graphql = graphql.into();
172    }
173
174    /// Set a websocket URL.
175    pub fn with_ws(mut self, ws: impl Into<Option<String>>) -> Self {
176        self.set_ws(ws);
177        self
178    }
179
180    /// Set a websocket URL.
181    pub fn set_ws(&mut self, ws: impl Into<Option<String>>) {
182        self.ws = ws.into();
183    }
184
185    /// Set basic authentication information in the format of username:password.
186    pub fn with_basic_auth(mut self, basic_auth: impl Into<Option<String>>) -> Self {
187        self.set_basic_auth(basic_auth);
188        self
189    }
190
191    /// Set basic authentication information in the format of username:password.
192    pub fn set_basic_auth(&mut self, basic_auth: impl Into<Option<String>>) {
193        self.basic_auth = basic_auth.into();
194    }
195
196    /// Set a faucet URL such as <https://faucet.testnet.iota.cafe/v1/gas>.
197    pub fn with_faucet(mut self, faucet: impl Into<Option<String>>) -> Self {
198        self.set_faucet(faucet);
199        self
200    }
201
202    /// Set a faucet URL such as <https://faucet.testnet.iota.cafe/v1/gas>.
203    pub fn set_faucet(&mut self, faucet: impl Into<Option<String>>) {
204        self.faucet = faucet.into();
205    }
206
207    /// Create an [`IotaClient`] with the given request timeout, max
208    /// concurrent requests and possible configured websocket URL and basic
209    /// auth.
210    pub async fn create_rpc_client(
211        &self,
212        request_timeout: impl Into<Option<std::time::Duration>>,
213        max_concurrent_requests: impl Into<Option<u64>>,
214    ) -> Result<IotaClient, anyhow::Error> {
215        let request_timeout = request_timeout.into();
216        let max_concurrent_requests = max_concurrent_requests.into();
217        let mut builder = IotaClientBuilder::default();
218
219        if let Some(request_timeout) = request_timeout {
220            builder = builder.request_timeout(request_timeout);
221        }
222        if let Some(ws_url) = &self.ws {
223            builder = builder.ws_url(ws_url);
224        }
225        if let Some(basic_auth) = &self.basic_auth {
226            let fields: Vec<_> = basic_auth.split(':').collect();
227            if fields.len() != 2 {
228                bail!("Basic auth should be in the format `username:password`");
229            }
230            builder = builder.basic_auth(fields[0], fields[1]);
231        }
232
233        if let Some(max_concurrent_requests) = max_concurrent_requests {
234            builder = builder.max_concurrent_requests(max_concurrent_requests as usize);
235        }
236        Ok(builder.build(&self.rpc).await?)
237    }
238
239    /// Create the env with the default mainnet configuration.
240    pub fn mainnet() -> Self {
241        Self {
242            alias: "mainnet".to_string(),
243            rpc: IOTA_MAINNET_URL.into(),
244            graphql: Some(IOTA_MAINNET_GRAPHQL_URL.into()),
245            ws: None,
246            basic_auth: None,
247            faucet: None,
248        }
249    }
250
251    /// Create the env with the default devnet configuration.
252    pub fn devnet() -> Self {
253        Self {
254            alias: "devnet".to_string(),
255            rpc: IOTA_DEVNET_URL.into(),
256            graphql: Some(IOTA_DEVNET_GRAPHQL_URL.into()),
257            ws: None,
258            basic_auth: None,
259            faucet: Some(IOTA_DEVNET_GAS_URL.into()),
260        }
261    }
262
263    /// Create the env with the default testnet configuration.
264    pub fn testnet() -> Self {
265        Self {
266            alias: "testnet".to_string(),
267            rpc: IOTA_TESTNET_URL.into(),
268            graphql: Some(IOTA_TESTNET_GRAPHQL_URL.into()),
269            ws: None,
270            basic_auth: None,
271            faucet: Some(IOTA_TESTNET_GAS_URL.into()),
272        }
273    }
274
275    /// Create the env with the default localnet configuration.
276    pub fn localnet() -> Self {
277        Self {
278            alias: "localnet".to_string(),
279            rpc: IOTA_LOCAL_NETWORK_URL.into(),
280            graphql: Some(IOTA_LOCAL_NETWORK_GRAPHQL_URL.into()),
281            ws: None,
282            basic_auth: None,
283            faucet: Some(IOTA_LOCAL_NETWORK_GAS_URL.into()),
284        }
285    }
286}
287
288impl Display for IotaEnv {
289    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
290        let mut writer = String::new();
291        writeln!(writer, "Active environment: {}", self.alias)?;
292        write!(writer, "RPC URL: {}", self.rpc)?;
293        if let Some(graphql) = &self.graphql {
294            writeln!(writer)?;
295            write!(writer, "GraphQL URL: {graphql}")?;
296        }
297        if let Some(ws) = &self.ws {
298            writeln!(writer)?;
299            write!(writer, "Websocket URL: {ws}")?;
300        }
301        if let Some(basic_auth) = &self.basic_auth {
302            writeln!(writer)?;
303            write!(writer, "Basic Auth: {basic_auth}")?;
304        }
305        if let Some(faucet) = &self.faucet {
306            writeln!(writer)?;
307            write!(writer, "Faucet URL: {faucet}")?;
308        }
309        write!(f, "{writer}")
310    }
311}
312
313impl Config for IotaClientConfig {}
314
315impl Display for IotaClientConfig {
316    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
317        let mut writer = String::new();
318
319        writeln!(
320            writer,
321            "Managed addresses: {}",
322            self.keystore.addresses().len()
323        )?;
324        write!(writer, "Active address: ")?;
325        match self.active_address {
326            Some(r) => writeln!(writer, "{r}")?,
327            None => writeln!(writer, "None")?,
328        };
329        writeln!(writer, "{}", self.keystore)?;
330        if let Ok(env) = self.get_active_env() {
331            write!(writer, "{env}")?;
332        }
333        write!(f, "{writer}")
334    }
335}
iota_sdk/iota_client_config.rs

iota_sdk/
iota_client_config.rs
