Connecting to Node(s)

You can access all the features of the iota.rs library using an instance of the Client class. The Client class provides high-level abstraction to all interactions over IOTA network (Tangle). You have to instantiate this class before you start any interactions with the library, or more precisely with the IOTA nodes that power IOTA network.

The library is designed to automatically choose a starting IOTA node based on the network type you would like to participate in: devnet or mainnet.

Password Storage

It is not recommended to store passwords or seeds on a host's environment variables or in the source code in a production setup. Please follow our backup and security recommendations for production use.

Java

bindings/java/examples/java-app/src/main/java/org/iota/client/example/ExampleApp.java

loading...

See full example on GitHub

Output example of the getInfo() function of the Client instance:

The most common ones are:

• .withNetwork(string): Can be either devnet or mainnet. It instructs the library whether to automatically select devnet nodes or mainnet nodes.
• .withNode(string): Specify address of actual running IOTA node that should be used to communicate with in the format https://node:port). For example: https://api.lb-0.h.chrysalis-devnet.iota.cafe:443.
• .withNodePoolUrls(String[]): The library also supports managing a pool of nodes. You can provide a list of nodes and the library manages the access to them automatically by selecting them based on their sync status. If you provide .withNodePoolUrls(String[]), then the library periodically will periodically check whether node is in sync or not by calling .withNodeSyncInterval(float).
• .withLocalPow(boolean): If .localPow (True) a Proof-of-work will be done locally and not remotely.
• .withNodeSyncDisabled(): When called, the library will use nodes that are not in sync with network. This parameter is usually useful if you would like to interact with a local test node that is not fully synced. This parameter should not be used in production.

Nodejs

bindings/nodejs/examples/01_get_info.js

loading...

See full example on GitHub

Output example of the getInfo() function of the Client instance:

The most common ones are:

• .network(str): Can be either devnet or mainnet. It instructs the library whether to automatically select devnet nodes or mainnet nodes.
• .node(url): Specify address of actual running IOTA node that should be used to communicate with in the format https://node:port). For example: https://api.lb-0.h.chrysalis-devnet.iota.cafe:443.
• .nodePoolUrls(urls): The library also supports managing a pool of nodes. You can provide a list of nodes and the library manages the access to them automatically by selecting them based on their sync status. If you provide .nodePoolUrls(urls), then the library periodically will periodically check whether node is in sync or not by calling .nodeSyncInterval(interval).
• .localPow(bool): If .localPow (True) a Proof-of-work will be done locally and not remotely.
• .disableNodeSync(): When called, the library will use nodes that are not in sync with network. This parameter is usually useful if you would like to interact with a local test node that is not fully synced. This parameter should not be used in production.

The following example uses additional initialization chaining calls, such as leveraging a custom node:

bindings/nodejs/examples/01b_get_info.js

loading...

See full example on GitHub

Python

bindings/python/examples/01_get_info.py

loading...

See full example on GitHub

Output example of the get_info() function of the Client class:

The Client class constructor provides several parameters via which the process can be closely managed.

The most common ones are:

• network: Can be either devnet or mainnet. It instructs the library whether to automatically select devnet nodes or mainnet nodes.
• node: Specify address of actual running IOTA node that should be used to communicate with in the format https://node:port). For example: https://api.lb-0.h.chrysalis-devnet.iota.cafe:443.
• node_pool_urls: The library also supports managing a pool of nodes. You can provide a list of nodes and the library manages the access to them automatically by selecting them based on their sync status. If you provide node_pool_urls, then the library periodically will periodically check whether node is in sync or not by calling .node_sync_interval.
• local_pow: If local_pow==True (default value) a Proof-of-work will be done locally and not remotely.
• node_sync_disabled: When called, the library will use nodes that are not in sync with network. This parameter is usually useful if you would like to interact with a local test node that is not fully synced. This parameter should not be used in production.

Rust

examples/01_get_info.rs

loading...

See full example on GitHub

Output example of the get_info() function of the Client instance:

{
  "nodeinfo": {
    "name": "HORNET",
    "version": "0.6.0-alpha",
    "is_healthy": true,
    "network_id": "migration",
    "bech32_hrp": "atoi",
    "min_pow_score": 100,
    "messages_per_second": 4.2,
    "referenced_messages_per_second": 4.1,
    "referenced_rate": 97.61904761904762,
    "latest_milestone_timestamp": 1618139001,
    "latest_milestone_index": 7092,
    "confirmed_milestone_index": 7092,
    "pruning_index": 0,
    "features": ["PoW"]
  },
  "url": "https://api.lb-0.h.chrysalis-devnet.iota.cafe"
}

The most important properties are:

• is_healthy: Indicates whether the given node is in sync with the network and therefore safe to use. Even if a node is up and running, it may not be fully prepared to process your API calls properly. The node should be "synced", meaning that it should be aware of all transactions in the Tangle. It is better to avoid interacting with nodes which are not fully synced.
• bech32_hrp: Indicates whether the given node is a part of devnet (atoi) or mainnet (iota). You can find more info regarding the IOTA address format in the official Chrysalis documentation.

Load Balancers & Health Checks

If you use node load balancers then the health check may be useless as the follow-up API calls may be served by a different node behind the load balancer that may not have been checked. You should be aware of this fact and trust that the load balancer participates only with nodes that are in healthy state. The iota.rs library additionally supports a management of internal node pool, so you can mimic a load-balancer-like behavior using this feature locally.

You can instantiate the Client, and optionally configure it, by chaining calls to the ClientBuilder helper class. The ClientBuilder helper class provides several chaining calls through which the process can be closely managed.

The most common ones are:

• .with_network(self, network: &str): Can be either devnet or mainnet. It instructs the library whether to automatically select devnet nodes or mainnet nodes.
• .with_node.(self, url: &str): Specify address of actual running IOTA node that should be used to communicate with in the format https://node:port). For example: https://api.lb-0.h.chrysalis-devnet.iota.cafe:443.
• .with_node_pool_urls(self, node_pool_urls: &[String]) : The library also supports managing a pool of nodes. You can provide a list of nodes and the library manages the access to them automatically by selecting them based on their sync status. If you provide .node_pool_urls(urls), then the library periodically will periodically check whether node is in sync or not by calling .with_node_sync_interval(self, node_sync_interval: Duration).
• .with_local_pow(self, local: bool): If .with_local_pow(True) a Proof-of-work will be done locally and not remotely.
• . with_node_sync_disabled(self): When called, the library will use nodes that are not in sync with network. This parameter is usually useful if you would like to interact with a local test node that is not fully synced. This parameter should not be used in production.

Wasm

bindings/wasm/examples/01_get_info.js

loading...

See full example on GitHub

Output example of the getInfo() function of the Client instance:

{
  "nodeinfo": {
    "name": "HORNET",
    "version": "0.6.0-alpha",
    "isHealthy": true,
    "networkId": "migration",
    "bech32HRP": "atoi",
    "minPoWScore": 100,
    "messagesPerSecond": 4.2,
    "referencedMessagesPerSecond": 4.1,
    "referencedRate": 97.61904761904762,
    "latestMilestoneTimestamp": 1618139001,
    "latestMilestoneIndex": 7092,
    "confirmedMilestoneIndex": 7092,
    "pruningIndex": 0,
    "features": ["PoW"]
  },
  "url": "https://api.lb-0.h.chrysalis-devnet.iota.cafe"
}

The most important properties are:

• isHealthy: Indicates whether the given node is in sync with the network and therefore safe to use. Even if a node is up and running, it may not be fully prepared to process your API calls properly. The node should be "synced", meaning that it should be aware of all transactions in the Tangle. It is better to avoid interacting with nodes which are not fully synced.
• bech32HRP: Indicates whether the given node is a part of devnet (atoi) or mainnet (iota). You can find more info regarding the IOTA address format in the official Chrysalis documentation.

Load Balancers & Health Checks

If you use node load balancers then the health check may be useless as the follow-up API calls may be served by a different node behind the load balancer that may not have been checked. You should be aware of this fact and trust that the load balancer participates only with nodes that are in healthy state. The iota.rs library additionally supports a management of internal node pool, so you can mimic a load-balancer-like behavior using this feature locally.

You can instantiate the Client, and optionally configure it, by chaining calls to the ClientBuilder helper class. The ClientBuilder helper class provides several chaining calls through which the process can be closely managed.

The most common ones are:

• .network(str): Can be either devnet or mainnet. It instructs the library whether to automatically select devnet nodes or mainnet nodes.
• .node(url): Specify address of actual running IOTA node that should be used to communicate with in the format https://node:port). For example: https://api.lb-0.h.chrysalis-devnet.iota.cafe:443.
• .nodePoolUrls(urls): The library also supports managing a pool of nodes. You can provide a list of nodes and the library manages the access to them automatically by selecting them based on their sync status. If you provide .nodePoolUrls(urls), then the library periodically will periodically check whether node is in sync or not by calling .nodeSyncInterval(interval).
• .localPow(bool): If .localPow (True) a Proof-of-work will be done locally and not remotely.
• .disableNodeSync(): When called, the library will use nodes that are not in sync with network. This parameter is usually useful if you would like to interact with a local test node that is not fully synced. This parameter should not be used in production.

The following example uses additional initialization chaining calls, such as leveraging a custom node:

bindings/wasm/examples/01b_get_info.js

loading...

See full example on GitHub