Add Client fallback to local PoW option

bindings/wasm/docs/api-reference.md

@@ -4,7 +4,8 @@
 <dt><a href="#Client">Client</a></dt>
 <dd></dd>
 <dt><a href="#Config">Config</a></dt>
-<dd></dd>
+<dd><p>Options to configure a new <a href="#Client">Client</a>.</p>
+</dd>
 <dt><a href="#Credential">Credential</a></dt>
 <dd></dd>
 <dt><a href="#DID">DID</a></dt>
@@ -265,13 +266,16 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config"></a>
 
 ## Config
+Options to configure a new [Client](#Client).
+
 **Kind**: global class  
 
 * [Config](#Config)
+    * [new Config()](#new_Config_new)
     * _instance_
         * [.setNetwork(network)](#Config+setNetwork)
-        * [.setNode(url)](#Config+setNode)
         * [.setEncoding(encoding)](#Config+setEncoding)
+        * [.setNode(url)](#Config+setNode)
         * [.setPrimaryNode(url, jwt, username, password)](#Config+setPrimaryNode)
         * [.setPrimaryPoWNode(url, jwt, username, password)](#Config+setPrimaryPoWNode)
         * [.setPermanode(url, jwt, username, password)](#Config+setPermanode)
@@ -282,41 +286,55 @@ Creates a new `Client` with default settings for the given `Network`.
         * [.setQuorumSize(value)](#Config+setQuorumSize)
         * [.setQuorumThreshold(value)](#Config+setQuorumThreshold)
         * [.setLocalPoW(value)](#Config+setLocalPoW)
+        * [.setFallbackToLocalPoW(value)](#Config+setFallbackToLocalPoW)
         * [.setTipsInterval(value)](#Config+setTipsInterval)
         * [.setRequestTimeout(value)](#Config+setRequestTimeout)
     * _static_
         * [.fromNetwork(network)](#Config.fromNetwork) ⇒ [<code>Config</code>](#Config)
 
+<a name="new_Config_new"></a>
+
+### new Config()
+Creates a new `Config`.
+
 <a name="Config+setNetwork"></a>
 
 ### config.setNetwork(network)
+Sets the IOTA Tangle network.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
 | --- | --- |
 | network | [<code>Network</code>](#Network) | 
 
-<a name="Config+setNode"></a>
+<a name="Config+setEncoding"></a>
+
+### config.setEncoding(encoding)
+Sets the DID message encoding used when publishing to the Tangle.
 
-### config.setNode(url)
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
 | --- | --- |
-| url | <code>string</code> | 
+| encoding | <code>number</code> | 
 
-<a name="Config+setEncoding"></a>
+<a name="Config+setNode"></a>
+
+### config.setNode(url)
+Adds an IOTA node by its URL.
 
-### config.setEncoding(encoding)
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
 | --- | --- |
-| encoding | <code>number</code> | 
+| url | <code>string</code> | 
 
 <a name="Config+setPrimaryNode"></a>
 
 ### config.setPrimaryNode(url, jwt, username, password)
+Adds an IOTA node by its URL to be used as primary node.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -329,6 +347,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setPrimaryPoWNode"></a>
 
 ### config.setPrimaryPoWNode(url, jwt, username, password)
+Adds an IOTA node by its URL to be used as primary PoW node (for remote PoW).
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -341,6 +361,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setPermanode"></a>
 
 ### config.setPermanode(url, jwt, username, password)
+Adds a permanode by its URL.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -353,6 +375,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setNodeAuth"></a>
 
 ### config.setNodeAuth(url, jwt, username, password)
+Adds an IOTA node by its URL.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -365,6 +389,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setNodeSyncInterval"></a>
 
 ### config.setNodeSyncInterval(value)
+Sets the node sync interval.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -374,10 +400,14 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setNodeSyncDisabled"></a>
 
 ### config.setNodeSyncDisabled()
+Disables the node sync process.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 <a name="Config+setQuorum"></a>
 
 ### config.setQuorum(value)
+Enables/disables quorum.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -387,6 +417,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setQuorumSize"></a>
 
 ### config.setQuorumSize(value)
+Sets the number of nodes used for quorum.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -396,6 +428,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setQuorumThreshold"></a>
 
 ### config.setQuorumThreshold(value)
+Sets the quorum threshold.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -405,6 +439,23 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setLocalPoW"></a>
 
 ### config.setLocalPoW(value)
+Sets whether proof-of-work (PoW) is performed locally or remotely.
+
+Default: false.
+
+**Kind**: instance method of [<code>Config</code>](#Config)  
+
+| Param | Type |
+| --- | --- |
+| value | <code>boolean</code> | 
+
+<a name="Config+setFallbackToLocalPoW"></a>
+
+### config.setFallbackToLocalPoW(value)
+Sets whether the PoW should be done locally in case a node doesn't support remote PoW.
+
+Default: true.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -414,6 +465,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setTipsInterval"></a>
 
 ### config.setTipsInterval(value)
+Sets the number of seconds that new tips will be requested during PoW.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -423,6 +476,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config+setRequestTimeout"></a>
 
 ### config.setRequestTimeout(value)
+Sets the default request timeout.
+
 **Kind**: instance method of [<code>Config</code>](#Config)  
 
 | Param | Type |
@@ -432,6 +487,8 @@ Creates a new `Client` with default settings for the given `Network`.
 <a name="Config.fromNetwork"></a>
 
 ### Config.fromNetwork(network) ⇒ [<code>Config</code>](#Config)
+Creates a new `Config` for the given IOTA Tangle network.
+
 **Kind**: static method of [<code>Config</code>](#Config)  
 
 | Param | Type |

bindings/wasm/src/tangle/config.rs

@@ -1,4 +1,4 @@
-// Copyright 2020-2021 IOTA Stiftung
+// Copyright 2020-2022 IOTA Stiftung
 // SPDX-License-Identifier: Apache-2.0
 
 use identity::iota::ClientBuilder;
@@ -17,6 +17,7 @@ fn to_basic_auth<'a>(username: &'a Option<String>, password: &'a Option<String>)
   username.as_deref().zip(password.as_deref())
 }
 
+/// Options to configure a new {@link Client}.
 #[wasm_bindgen]
 #[derive(Debug)]
 pub struct Config {
@@ -25,35 +26,41 @@ pub struct Config {
 
 #[wasm_bindgen]
 impl Config {
+  /// Creates a new `Config`.
   #[wasm_bindgen(constructor)]
   pub fn new() -> Self {
     Self {
       builder: Some(ClientBuilder::new()),
     }
   }
 
+  /// Creates a new `Config` for the given IOTA Tangle network.
   #[wasm_bindgen(js_name = fromNetwork)]
   pub fn from_network(network: &WasmNetwork) -> Result<Config, JsValue> {
     let mut this: Self = Self::new();
     this.set_network(network)?;
     Ok(this)
   }
 
+  /// Sets the IOTA Tangle network.
   #[wasm_bindgen(js_name = setNetwork)]
   pub fn set_network(&mut self, network: &WasmNetwork) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.network(network.clone().into()))
   }
 
-  #[wasm_bindgen(js_name = setNode)]
-  pub fn set_node(&mut self, url: &str) -> Result<(), JsValue> {
-    self.try_with_mut(|builder| builder.node(url).map_err(wasm_error))
-  }
-
+  /// Sets the DID message encoding used when publishing to the Tangle.
   #[wasm_bindgen(js_name = setEncoding)]
   pub fn set_encoding(&mut self, encoding: WasmDIDMessageEncoding) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.encoding(encoding.into()))
   }
 
+  /// Adds an IOTA node by its URL.
+  #[wasm_bindgen(js_name = setNode)]
+  pub fn set_node(&mut self, url: &str) -> Result<(), JsValue> {
+    self.try_with_mut(|builder| builder.node(url).map_err(wasm_error))
+  }
+
+  /// Adds an IOTA node by its URL to be used as primary node.
   #[wasm_bindgen(js_name = setPrimaryNode)]
   pub fn set_primary_node(
     &mut self,
@@ -69,6 +76,7 @@ impl Config {
     })
   }
 
+  /// Adds an IOTA node by its URL to be used as primary PoW node (for remote PoW).
   #[wasm_bindgen(js_name = setPrimaryPoWNode)]
   pub fn set_primary_pow_node(
     &mut self,
@@ -84,6 +92,7 @@ impl Config {
     })
   }
 
+  /// Adds a permanode by its URL.
   #[wasm_bindgen(js_name = setPermanode)]
   pub fn set_permanode(
     &mut self,
@@ -99,6 +108,7 @@ impl Config {
     })
   }
 
+  /// Adds an IOTA node by its URL.
   #[wasm_bindgen(js_name = setNodeAuth)]
   pub fn set_node_auth(
     &mut self,
@@ -114,41 +124,59 @@ impl Config {
     })
   }
 
+  /// Sets the node sync interval.
   #[wasm_bindgen(js_name = setNodeSyncInterval)]
   pub fn set_node_sync_interval(&mut self, value: u32) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.node_sync_interval(to_duration(value)))
   }
 
+  /// Disables the node sync process.
   #[wasm_bindgen(js_name = setNodeSyncDisabled)]
   pub fn set_node_sync_disabled(&mut self) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.node_sync_disabled())
   }
 
+  /// Enables/disables quorum.
   #[wasm_bindgen(js_name = setQuorum)]
   pub fn set_quorum(&mut self, value: bool) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.quorum(value))
   }
 
+  /// Sets the number of nodes used for quorum.
   #[wasm_bindgen(js_name = setQuorumSize)]
   pub fn set_quorum_size(&mut self, value: usize) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.quorum_size(value))
   }
 
+  /// Sets the quorum threshold.
   #[wasm_bindgen(js_name = setQuorumThreshold)]
   pub fn set_quorum_threshold(&mut self, value: usize) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.quorum_threshold(value))
   }
 
+  /// Sets whether proof-of-work (PoW) is performed locally or remotely.
+  ///
+  /// Default: false.
   #[wasm_bindgen(js_name = setLocalPoW)]
   pub fn set_local_pow(&mut self, value: bool) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.local_pow(value))
   }
 
+  /// Sets whether the PoW should be done locally in case a node doesn't support remote PoW.
+  ///
+  /// Default: true.
+  #[wasm_bindgen(js_name = setFallbackToLocalPoW)]
+  pub fn set_fallback_to_local_pow(&mut self, value: bool) -> Result<(), JsValue> {
+    self.with_mut(|builder| builder.fallback_to_local_pow(value))
+  }
+
+  /// Sets the number of seconds that new tips will be requested during PoW.
   #[wasm_bindgen(js_name = setTipsInterval)]
   pub fn set_tips_interval(&mut self, value: u32) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.tips_interval(u64::from(value)))
   }
 
+  /// Sets the default request timeout.
   #[wasm_bindgen(js_name = setRequestTimeout)]
   pub fn set_request_timeout(&mut self, value: u32) -> Result<(), JsValue> {
     self.with_mut(|builder| builder.request_timeout(to_duration(value)))

identity-iota/src/tangle/client_builder.rs

@@ -131,13 +131,22 @@ impl ClientBuilder {
 
   /// Sets whether proof-of-work (PoW) is performed locally or remotely.
   ///
-  /// NOTE: the client will always fallback to local PoW if no nodes support remote PoW.
+  /// Default: false.
   #[must_use]
   pub fn local_pow(mut self, value: bool) -> Self {
     self.builder = self.builder.with_local_pow(value);
     self
   }
 
+  /// Sets whether the PoW should be done locally in case a node doesn't support remote PoW.
+  ///
+  /// Default: true.
+  #[must_use]
+  pub fn fallback_to_local_pow(mut self, value: bool) -> Self {
+    self.builder = self.builder.with_fallback_to_local_pow(value);
+    self
+  }
+
   /// Sets the number of seconds that new tips will be requested during PoW.
   #[must_use]
   pub fn tips_interval(mut self, value: u64) -> Self {