Skip to main content

iota_sdk.client.client

ClientError Objects​

class ClientError(Exception)

Represents a client error.

Client Objects​

class Client(NodeCoreAPI, NodeIndexerAPI, HighLevelAPI, ClientUtils)

Represents an IOTA client.

Attributes:

  • handle - The handle to the inner client object.

__init__​

def __init__(nodes: Optional[Union[str, List[str]]] = None,
             primary_node: Optional[str] = None,
             primary_pow_node: Optional[str] = None,
             permanode: Optional[str] = None,
             ignore_node_health: Optional[bool] = None,
             api_timeout: Optional[timedelta] = None,
             node_sync_interval: Optional[timedelta] = None,
             remote_pow_timeout: Optional[timedelta] = None,
             tips_interval: Optional[int] = None,
             quorum: Optional[bool] = None,
             min_quorum_size: Optional[int] = None,
             quorum_threshold: Optional[int] = None,
             user_agent: Optional[str] = None,
             local_pow: Optional[bool] = None,
             fallback_to_local_pow: Optional[bool] = None,
             pow_worker_count: Optional[int] = None,
             client_handle=None)

Initialize the IOTA Client.

Arguments

  • nodes:
    A single Node URL or an array of URLs.
  • primary_node:
    Node which will be tried first for all requests.
  • primary_pow_node:
    Node which will be tried first when using remote PoW, even before the primary_node.
  • permanode:
    Permanode URL.
  • ignore_node_health:
    If the node health should be ignored.
  • api_timeout:
    Timeout for API requests.
  • node_sync_interval:
    Interval in which nodes will be checked for their sync status and the NetworkInfo gets updated.
  • remote_pow_timeout:
    Timeout when sending a block that requires remote proof of work.
  • tips_interval:
    Tips request interval during PoW in seconds.
  • quorum:
    If node quorum is enabled. Will compare the responses from multiple nodes and only returns the response if 'quorum_threshold'% of the nodes return the same one.
  • min_quorum_size:
    Minimum amount of nodes required for request when quorum is enabled.
  • quorum_threshold:
    % of nodes that have to return the same response so it gets accepted.
  • user_agent:
    The User-Agent header for requests.
  • local_pow:
    Local proof of work.
  • fallback_to_local_pow:
    Fallback to local proof of work if the node doesn't support remote PoW.
  • pow_worker_count:
    The amount of threads to be used for proof of work.
  • client_handle:
    An instance of a node client.

get_handle​

def get_handle()

Get the client handle.

Returns:

The inner client object.

build_alias_output​

def build_alias_output(
        alias_id: HexStr,
        unlock_conditions: List[UnlockCondition],
        amount: Optional[int] = None,
        native_tokens: Optional[List[NativeToken]] = None,
        state_index: Optional[int] = None,
        state_metadata: Optional[str] = None,
        foundry_counter: Optional[int] = None,
        features: Optional[List[Feature]] = None,
        immutable_features: Optional[List[Feature]] = None) -> AliasOutput

Build an AliasOutput.

Arguments:

  • alias_id - A unique ID for the new alias.
  • unlock_conditions - The unlock conditions for the new output.
  • amount - The amount of base coins in the new output.
  • native_tokens - Native tokens added to the new output.
  • state_index - A counter that must increase by 1 every time the alias is state transitioned.
  • state_metadata - Metadata that can only be changed by the state controller.
  • foundry_counter - A counter that denotes the number of foundries created by this alias account.
  • features - A list of features.
  • immutable_features - A list of immutable features.

Returns:

The alias output as dict.

build_basic_output​

def build_basic_output(
        unlock_conditions: List[UnlockCondition],
        amount: Optional[int] = None,
        native_tokens: Optional[List[NativeToken]] = None,
        features: Optional[List[Feature]] = None) -> BasicOutput

Build a BasicOutput.

Arguments:

  • unlock_conditions - The unlock conditions for the new output.
  • amount - The amount of base coins in the new output.
  • native_tokens - Native tokens added to the new output.
  • features - Features that add utility to the output but do not impose unlocking conditions.

Returns:

The basic output as dict.

build_foundry_output​

def build_foundry_output(
        serial_number: int,
        token_scheme: SimpleTokenScheme,
        unlock_conditions: List[UnlockCondition],
        amount: Optional[int] = None,
        native_tokens: Optional[List[NativeToken]] = None,
        features: Optional[List[Feature]] = None,
        immutable_features: Optional[List[Feature]] = None) -> FoundryOutput

Build a FoundryOutput.

Arguments:

  • serial_number - The serial number of the foundry with respect to the controlling alias.
  • token_scheme - Defines the supply control scheme of the tokens controlled by the foundry. Currently only a simple scheme is supported.
  • unlock_conditions - The unlock conditions for the new output.
  • amount - The amount of base coins in the new output.
  • native_tokens - Native tokens added to the new output.
  • features - Features that add utility to the output but do not impose unlocking conditions.
  • immutable_features - Features that add utility to the output but do not impose unlocking conditions. These features need to be kept in future transitions of the UTXO state machine.

Returns:

The foundry output as dict.

build_nft_output​

def build_nft_output(
        nft_id: HexStr,
        unlock_conditions: List[UnlockCondition],
        amount: Optional[int] = None,
        native_tokens: Optional[List[NativeToken]] = None,
        features: Optional[List[Feature]] = None,
        immutable_features: Optional[List[Feature]] = None) -> NftOutput

Build an NftOutput.

Arguments:

  • nft_id - A unique ID for the new NFT.
  • unlock_conditions - The unlock conditions for the new output.
  • amount - The amount of base coins in the new output.
  • native_tokens - Native tokens added to the new output.
  • features - Features that add utility to the output but do not impose unlocking conditions.
  • immutable_features - Features that add utility to the output but do not impose unlocking conditions. These features need to be kept in future transitions of the UTXO state machine.

Returns:

The NFT output as dict.

build_and_post_block​

def build_and_post_block(
        secret_manager: Optional[Union[LedgerNanoSecretManager,
                                       MnemonicSecretManager,
                                       SeedSecretManager,
                                       StrongholdSecretManager]] = None,
        account_index: Optional[int] = None,
        coin_type: Optional[int] = None,
        custom_remainder_address: Optional[str] = None,
        data: Optional[HexStr] = None,
        initial_address_index: Optional[int] = None,
        input_range_start: Optional[int] = None,
        input_range_end: Optional[int] = None,
        inputs: Optional[List[Dict[str, Any]]] = None,
        output: Optional[AddressAndAmount] = None,
        outputs: Optional[List[Any]] = None,
        tag: Optional[HexStr] = None) -> List[Union[HexStr, Block]]

Build and post a block.

Arguments

  • account_index: The account index to issue the block with.
  • coin_type: The type of base coin.
  • custom_remainder_address: Address to send the remainder funds to.
  • data: Hex encoded data.
  • initial_address_index: Initial address index.
  • input_range_start: Start of the input range.
  • input_range_end: End of the input range.
  • inputs: Inputs to use.
  • output: Address and amount to send to.
  • outputs: Outputs to use.
  • tag: Hex encoded tag.

Returns:

The created block as dict.

get_node​

def get_node() -> Dict[str, Any]

Get a node candidate from the healthy node pool.

get_network_info​

def get_network_info() -> NetworkInfo

Gets the network related information such as network_id and min_pow_score.

get_network_id​

def get_network_id() -> int

Gets the network id of the node we're connecting to.

get_bech32_hrp​

def get_bech32_hrp() -> str

Returns the bech32_hrp.

get_min_pow_score​

def get_min_pow_score() -> int

Returns the min pow score.

get_tips_interval​

def get_tips_interval() -> int

Returns the tips interval.

get_local_pow​

def get_local_pow() -> bool

Returns if local pow should be used or not.

get_fallback_to_local_pow​

def get_fallback_to_local_pow() -> bool

Get fallback to local proof of work timeout.

unhealthy_nodes​

def unhealthy_nodes() -> List[Dict[str, Any]]

Returns the unhealthy nodes.

prepare_transaction​

def prepare_transaction(
        secret_manager: Optional[Union[LedgerNanoSecretManager,
                                       MnemonicSecretManager,
                                       SeedSecretManager,
                                       StrongholdSecretManager]] = None,
        options=None)

Prepare a transaction for signing.

Arguments:

  • secret_manager - One of the supported secret managers.
  • options - the transaction options.

sign_transaction​

def sign_transaction(
        secret_manager: Union[LedgerNanoSecretManager, MnemonicSecretManager,
                              SeedSecretManager, StrongholdSecretManager],
        prepared_transaction_data: PreparedTransactionData
) -> TransactionPayload

Sign a transaction.

Arguments:

  • secret_manager - One of the supported secret managers.
  • prepared_transaction_data - a prepared transaction to sign.

submit_payload​

def submit_payload(payload: Payload) -> List[Union[HexStr, Block]]

Submit a payload in a block.

Arguments:

payload : The payload to submit.

Returns:

List of HexStr or Block.

listen_mqtt​

def listen_mqtt(topics: List[str], handler)

Listen to MQTT events.

Arguments:

  • topics - The topics to listen to.
  • handler - A callback function for MQTT events.

clear_mqtt_listeners​

def clear_mqtt_listeners(topics: List[str])

Removes all listeners for the provided MQTT topics.

Arguments:

  • topics - The topics to stop listening to.