README.md

IOTA Client Python Library

Requirements

• Rust 1.45.0+
• Python 3.6+

Try Run w/ Local Hornet

1. Run your local Hornet

• $ git clone [email protected]:gohornet/hornet.git
• checkout chrysalis-pt2 branch
• Modify your create_snapshot_alphanet.sh, modify Line 14 to go run ../main.go tool snapgen alphanet1 96f9de0989e77d0e150e850a5a600e83045fa57419eaf3b20225b763d4e23813 snapshots/alphanet1/full_export.bin
• $ ./run_coo_bootstrap.sh

2. To Build the iota_client python library by yourself, there are two ways.

   • By using the cargo
     • Go to bindings/python/native
     • $ cargo build --release
     • The built library is located in target/release/
     • On MacOS, rename libiota_client.dylib to iota_client.so, on Windows, rename iota_client.dll to iota_client.pyd, and on Linux libiota_client.so to iota_client.so.
     • Copy your renamed library to bindings/python/examples/
     • Go to bindings/python/examples
     • $ python example.py
   • By using maturin
     • Go to bindings/python/native
     • $ pip3 install maturin
     • $ maturin develop
     • $ maturin build --manylinux off
     • The wheel file is now created in bindings/python/native/target/wheels
     • $ pip3 install [THE_BUILT_WHEEL_FILE]

3. To Use the pre-build libraries

   • To use the pre-built libraries for linux/macos/windows, please check the Artifacts files generated by the Github Action in the last commit. For example, there are the following 12 wheels in https://github.com/iotaledger/iota.rs/actions/runs/596639195. Please download the one which matches your os and python version.
     • linux-iota-client-py3.6-wheel
     • linux-iota-client-py3.7-wheel
     • linux-iota-client-py3.8-wheel
     • linux-iota-client-py3.9-wheel
     • osx-iota-client-py3.6-wheel
     • osx-iota-client-py3.7-wheel
     • osx-iota-client-py3.8-wheel
     • osx-iota-client-py3.9-wheel
     • windows-iota-client-py3.6-wheels
     • windows-iota-client-py3.7-wheels
     • windows-iota-client-py3.8-wheels
     • windows-iota-client-py3.9-wheels
   • $ pip3 install [THE_DOWNLOADED_WHEEL_FILE]

Python Example

import iota_client
import os
LOCAL_NODE_URL = "http://0.0.0.0:14265"

# NOTE! Load the seed from your env path instead
# NEVER assign the seed directly in your codes!
# DO NOT USE THIS!!:
# SEED = "256a818b2aac458941f7274985a410e57fb750f3a3a67969ece5bd9ae7eef5b2"

# USE THIS INSTEAD
SEED = os.getenv('MY_IOTA_SEED')

EMPTY_ADDRESS = "atoi1qzt0nhsf38nh6rs4p6zs5knqp6psgha9wsv74uajqgjmwc75ugupx3y7x0r"
client = iota_client.Client(
    node=LOCAL_NODE_URL, node_sync_disabled=True)


def main():
    print('get_health()')
    print(f'health: {client.get_health()}')

    print('get_info()')
    print(f'node_info: {client.get_info()}')

    print('get_tips()')
    print(f'tips: {client.get_tips()}')

    print('get_addresses')
    address_changed_list = client.get_addresses(
        seed=SEED, account_index=0, input_range_begin=0, input_range_end=10, get_all=True)
    print(f'address_changed list: {address_changed_list}')

    # Get the (address, changed ) for the first found address
    address, changed = address_changed_list[0]
    print(f'get_address_balance() for address {address}')
    print(f'balance: {client.get_address_balance(address)}')

    print(f'get_address_balance() for address {EMPTY_ADDRESS}')
    print(f'balance: {client.get_address_balance(EMPTY_ADDRESS)}')

    print(f'get_address_outputs() for address {EMPTY_ADDRESS}')
    print(f'outputs(): {client.get_address_outputs(EMPTY_ADDRESS)}')

    print(f'message() 100 tokens to address {EMPTY_ADDRESS}')
    message_id = client.message(
        seed=SEED, outputs=[{'address': EMPTY_ADDRESS, 'amount': 100}])['message_id']
    print(f'Token sent with message_id: {message_id}')
    print(f'Please check http://127.0.0.1:14265/api/v1/messages/{message_id}')

    print(f'get_message_metadata() for message_id {message_id}')
    message_metadata = client.get_message_metadata(message_id)
    print(f'message_metadata: {message_metadata}')

    print(f'get_message_data() for message_id {message_id}')
    message_data = client.get_message_data(message_id)
    print(f'message_data: {message_data}')

    print(f'get_message_raw() for message_id {message_id}')
    message_raw = client.get_message_raw(message_id)
    print(f"raw_data = {message_raw.encode('utf-8')}")
    print(
        f"Note the raw data is exactly the same from http://127.0.0.1:14265/api/v1/messages/{message_id}/raw")
    print(', which is not utf-8 format. The utf-8 format here is just for ease of demonstration')

    print(f'get_message_children() for message_id {message_id}')
    children = client.get_message_children(message_id)
    print(f"children: {children}")

    print(f'message() Indexation')
    message_id_indexation = client.message(
        index="Hello", data=[84, 97, 110, 103, 108, 101])
    print(f'Indexation sent with message_id: {message_id_indexation}')
    print(
        f'Please check http://127.0.0.1:14265/api/v1/messages/{message_id_indexation}')

    # Note that in rust we need to specify the parameter type explicitly, so if the user wants
    # to use the utf-8 string as the data, then the `data_str` field can be used.
    print(f'message() Indexation')
    message_id_indexation = client.message(
        index="Hi", data_str="Tangle")
    print(f'Indexation sent with message_id: {message_id_indexation}')
    print(
        f'Please check http://127.0.0.1:14265/api/v1/messages/{message_id_indexation}')

    print(f"get_message_index() for index 'Hello'")
    message_id_indexation_queried = client.get_message_index("Hello")
    print(f'Indexation: {message_id_indexation_queried}')

    print(f"find_messages() for indexation_keys = ['Hello']")
    messages = client.find_messages(indexation_keys=["Hello"])
    print(f'Messages: {messages}')

    print(f"get_unspent_address()")
    unspent_addresses = client.get_unspent_address(seed=SEED)
    print(f'(unspent_address, index): {unspent_addresses}')

    print(f"get_balance()")
    balance = client.get_balance(seed=SEED)
    print(f'balance: {balance}')

    addresses = []
    for address, _changed in address_changed_list:
        addresses.append(address)
    print(f"get_address_balances() for {addresses}")
    balances = client.get_address_balances(addresses)
    print(f'balances: {balance}')


if __name__ == "__main__":
    main()

API Reference

Note that in the following APIs, the corresponding exception will be returned if an error occurs. Also for all the optional values, the default values are the same as the ones in the Rust version.

Client

constructor(network (optional), storage (optional), password (optional), polling_interval (optional)): AccountManager

Creates a new instance of the Client.

Param	Type	Default	Description
[network]	str	undefined	The network
[node]	str	undefined	A node URL
[nodes]	list[str]	undefined	An array of node URLs
[node_sync_interval]	int	undefined	The interval for the node syncing process
[node_sync_disabled]	bool	undefined	Disables the node syncing process. Every node will be considered healthy and ready to use
[node_pool_urls]	str	undefined	An array of node pool URLs
[request_timeout]	int	undefined	Sets the default HTTP request timeout
[api_timeout]	dict	undefined	The API to set the request timeout. Key: 'GetHealth', 'GetInfo', 'GetPeers', 'GetTips', 'PostMessage', 'GetOutput', 'GetMilestone' Value: timeout in milliseconds
[local_pow]	bool	undefined	Flag determining if PoW should be done locally or remotely
[tips_interval]	int	undefined	Time between requests for new tips during PoW
[mqtt_broker_options]	BrokerOptions	undefined	Sets the options for the MQTT connection with the node

Returns The constructed Client.

Full Node APIs

get_health(): bool

Gets the node health status.

Returns whether the node is healthy.

get_info(): InfoResponse

Gets information about the node.

Returns the InfoResponse.

get_peers(): list[PeerDto]

Gets peers of the node.

Returns the list of PeerDto.

get_tips(): list[str]

Gets non-lazy tips.

Returns two non-lazy tips' message ids in list.

post_message(msg): str

Submits a message.

Param	Type	Default	Description
[msg]	Message	undefined	The message to submit

Returns the message id of the submitted message.

get_output(output_id): OutputResponse

Gets the UTXO outputs associated with the given output id.

Param	Type	Default	Description
[output_id]	str	undefined	The id of the output to search

Returns the OutputResponse[#outputresponse].

get_address_balance(address): BalanceForAddressResponse

Gets the balance in the address.

Param	Type	Default	Description
[address]	list[str]	undefined	The address Bech32 string

Returns the BalanceForAddressResponse.

get_address_outputs(address): list[UTXOInput]

Gets the UTXO outputs associated with the given address.

Param	Type	Default	Description
[address]	str	undefined	The address Bech32 string

Returns the list of UTXOInput.

find_outputs(output_ids (optional), addresses (optional)): list[OutputResponse]

Gets the UTXO outputs associated with the given output ids and addresses.

Param	Type	Default	Description
[output_ids]	list[str]	undefined	The list of addresses to search
[addresses]	list[str]	undefined	The list of output ids to search

Returns the list of OutputResponse.

get_milestone(index): MilestoneDto

Gets the milestone by the given index.

Param	Type	Default	Description
[index]	int	undefined	The index of the milestone

Returns the MilestoneDto.

get_milestone_utxo_changes(index): MilestoneUTXOChanges

Gets the utxo changes by the given milestone index.

Param	Type	Default	Description
[index]	int	undefined	The index of the milestone

Returns the MilestoneUTXOChanges.

High-Level APIs

message(seed (optional), account_index (optional), initial_address_index (optional), inputs (optional), input_range_begin (optional), input_range_end (optional), outputs (optional), dust_allowance_outputs (optional), index (optional), index_raw (optional), data (optional), data_str (optional), parents (optional)): Message

Build a message.

Param	Type	Default	Description
[seed]	str	undefined	The hex-encoded seed of the account to spend
[account_index]	int	undefined	The account index
[initial_address_index]	int	undefined	The initial address index
[inputs]	list[Input]	undefined	Inputs
[input_range_begin]	int	undefined	The begin index of the input
[input_range_end]	int	undefined	The end index of the input
[outputs]	list[Output]	undefined	Outputs
[dust_allowance_outputs]	list[Output]	undefined	Dust allowance output to the transaction
[index]	str	undefined	The indexation string
[index_raw]	list[int]	undefined	The indexation byte array
[data]	list[int]	undefined	The data in bytes
[data_str]	str	undefined	The data string
[parents]	list[str]	undefined	The message ids of the parents

Returns the built Message.

get_message_metadata(message_id): MessageMetadataResponse

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the MessageMetadataResponse.

get_message_data(message_id): Message

Gets the message data from the message id.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the Message.

get_message_raw(message_id): str

Gets the raw message string from the message id.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the raw message string.

get_message_children(message_id): list[str]

Gets the children of the given message.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the list of children strings.

get_message_index(index): list[str]

Gets the list of message indices from the message_id.

Param	Type	Default	Description
[index]	str	undefined	The identifier of message

Returns the list of message ids.

find_messages(indexation_keys (optional), message_ids (optional)): list[Message]

Finds all messages associated with the given indexation keys and message ids.

Param	Type	Default	Description
[indexation_keys]	list[str]	undefined	The list of indexations keys too search
[message_ids]	list[str]	undefined	The list of message ids to search

Returns the list of the found messages.

get_unspent_address(seed, account_index (optional), initial_address_index(optional)): (str, int)

Gets a valid unspent address.

Param	Type	Default	Description
[seed]	str	undefined	The hex-encoded seed to search
[account_index]	int	undefined	The account index
[initial_address_index]	int	undefined	The initial address index

Returns a tuple with type of (str, int) as the address and corresponding index in the account.

get_addresses(seed, account_index (optional), input_range_begin (optional), input_range_end (optional) get_all (optional)): list[(str, bool (optional))]

Finds addresses from the seed regardless of their validity.

Param	Type	Default	Description
[seed]	str	undefined	The hex-encoded seed to search
[account_index]	int	undefined	The account index
[input_range_begin]	int	undefined	The begin of the address range
[input_range_end]	int	undefined	The end of the address range
[get_all]	bool	undefined	Get all addresses

Returns a list of tuples with type of (str, int) as the address and corresponding index in the account.

get_balance(seed, account_index (optional), initial_address_index(optional)): int

Get balance on a given seed and its wallet account index.

Param	Type	Default	Description
[seed]	str	undefined	The hex-encoded seed to search
[account_index]	int	undefined	The account index
[initial_address_index]	int	undefined	The initial address index

Returns the amount of balance.

get_address_balances(addresses): list[AddressBalancePair]

Get the balance in iotas for the given addresses.

Param	Type	Default	Description
[addresses]	list[str]	undefined	The list of addresses to search

Returns the list of AddressBalancePair.

retry(message_id): (str, Message)

Retries (promotes or reattaches) the message associated with the given id.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the message id and the retried Message.

reattach(message_id): (str, Message)

Reattaches the message associated with the given id.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the message id and the reattached Message.

promote(message_id): (str, Message)

Promotes the message associated with the given id.

Param	Type	Default	Description
[message_id]	str	undefined	The message id

Returns the message id and the promoted Message.

MQTT APIs

subscribe_topic(topic, callback): void

Subscribe a topic and assign the associated callback.

Param	Type	Default	Description
[topic]	str	undefined	The MQTT topic
[callback]	function	undefined	The callback function

subscribe_topics(topics, callback): void

Subscribe topics and assign the associated callbacks, respectively.

Param	Type	Default	Description
[topics]	list[str]	undefined	The MQTT topics
[callback]	function	undefined	The callback functions

unsubscribe(): void

Unsubscribe all topics.

disconnect(): void

Disconnect the mqtt broker.

WalletAddress

A dict with the following key/value pairs.

message_metadata_response = {
    'message_id': str,
    'parent_message_ids': list[str],
    'is_solid': bool,
    'referenced_by_milestone_index': int, # (optional)
    'milestone_index': int,  # (optional)
    'ledger_inclusion_state': LedgerInclusionStateDto,  # (optional)
    'conflict_reason': int,  # (optional)
    'should_promote:' bool  # (optional)
    'should_reattach': bool  # (optional)
}

Please refer to LedgerInclusionStateDto for the details of this type.

BalanceForAddressResponse

A dict with the following key/value pairs.

balance_for_address_response = {
    'address_type': int,
    'address': str,
    'balance': int
}

AddressBalancePair

A dict with the following key/value pairs.

address_balance_pair = {
    'address': str,
    'balance': int
}

MilestoneDto

A dict with the following key/value pairs.

milestoned_to = {
    'index': int,
    'timestamp': int,
    'message_id':  str
}

MilestoneUTXOChanges

A dict with the following key/value pairs.

milestone_utxo_changes = {
    'index': int,
    'created_outputs': list[str],
    'consumed_outputs': list[str]
}

UTXOInput

A dict with the following key/value pairs.

utxo_input = {
    'transaction_id': list[int],
    'index': int
}

OutputResponse

A dict with the following key/value pairs.

output_response = {
    'message_id': str,
    'transaction_id': str,
    'output_index': int,
    'is_spent': bool,
    'output': OutputDto
}

Please refer to OutputDto for the details of this type.

OutputDto

A dict with the following key/value pairs.

output_dto = {
    'treasury': TreasuryOutputDto, # (opitonal)
    'signature_locked_single': SignatureLockedSingleOutputDto, # (opitonal)
    'signature_locked_dust_allowance': SignatureLockedDustAllowanceOutputDto # (opitonal)
}

Please refer to TreasuryOutputDto, SignatureLockedSingleOutputDto, and SignatureLockedDustAllowanceOutputDto for the details of these types.

SignatureLockedSingleOutputDto

A dict with the following key/value pairs.

signature_locked_single_output_dto = {
    'kind': int,
    'address': AddressDto,
    'amount': int
}

Please refer to AddressDto for the details of this type.

SignatureLockedDustAllowanceOutputDto

A dict with the following key/value pairs.

signature_locked_dust_allowance_output_dto = {
    'kind': int,
    'address': AddressDto,
    'amount': int
}

Please refer to AddressDto for the details of this type.

pub struct TreasuryOutputDto {

A dict with the following key/value pairs.

treasury_output_dto = {
    'kind': int,
    'amount':int
}

AddressDto

A dict with the following key/value pairs.

address_dto = {
    'ed25519': Ed25519AddressDto
}

Please refer to Ed25519AddressDto for the details of this type.

Ed25519AddressDto

A dict with the following key/value pairs.

ed25519_address_dto = {
    'kind': int,
    'address': str
}

Message

A dict with the following key/value pairs.

message = {
    'message_id': str,
    'network_id': int,
    'parents': list[str],
    'payload': Payload, # (optional)
    'nonce': int
}

Please refer to Payload for the details of this type.

Payload

A dict with the following key/value pairs.

payload = {
    'transaction': list[Transaction], # (optional)
    'milestone': list[Milestone], # (optional)
    'indexation': list[Indexation], # (optional)
}

Please refer to Transaction, Milestone, and Indexation for the details of these types.

Transaction

A dict with the following key/value pairs.

transaction = {
    'essence': RegularEssence,
    'unlock_blocks': list[UnlockBlock]
}

Please refer to RegularEssence, and UnlockBlock for the details of these types.

Milestone

A dict with the following key/value pairs.

milestone = {
    'essence': MilestonePayloadEssence,
    'signatures': list[list[int]]
}

Please refer to MilestonePayloadEssence for the details of this type.

MilestonePayloadEssence

A dict with the following key/value pairs.

milestone_payload_essence = {
    'index': int,
    'timestamp': int,
    'parents': list[str],
    'merkle_proof': list[int],
    'public_keys': list[list[int]]
}

Indexation

A dict with the following key/value pairs.

indexation = {
    'index': str,
    'data': list[int]
}

RegularEssence

A dict with the following key/value pairs.

regular_essence = {
    'inputs': list[Input],
    'outputs': list[Output],
    'payload': list[Payload]
}

Please refer to Input, Output, and Payload for the details of these types.

Output

A dict with the following key/value pairs.

output = {
    'address': str,
    'amount': int
}

Input

A dict with the following key/value pairs.

input = {
    'transaction_id': str,
    'index': int
}

UnlockBlock

A dict with the following key/value pairs.

unlock_block = {
    'signature': Ed25519Signature, # (optional)
    'reference': int # (optional)
}

Please refer to Ed25519Signature for the details of this type.

Ed25519Signature

A dict with the following key/value pairs.

ed25519_signature = {
    'public_key': list[int],
    'signature': list[int]
}

BrokerOptions

A dict with the following key/value pairs.

broker_options = {
    'automatic_disconnect': bool,
    'timeout': int,
    'use_ws': bool
}

LedgerInclusionStateDto

A dict with the following key/value pairs.

ledger_inclusion_state_dto = {
    'state': str
}

InfoResponse

A dict with the following key/value pairs.

info_response = {
    'name': str,
    'version': str,
    'is_healthy': bool,
    'network_id': str,
    'bech32_hrp': str,
    'latest_milestone_index': int,
    'solid_milestone_index': int,
    'pruning_index': int,
    'features': list[str],
    'min_pow_score': float,
}

NetworkInfo

A dict with the following key/value pairs.

network_info = {
    'network': str,
    'network_id': int,
    'bech32_hrp': str,
    'min_pow_score': float,
    'local_pow': bool,
    'tips_interval': int,
}

PeerDto

A dict with the following key/value pairs.

peer_dto = {
    'id': str,
    'multi_addresses': list[str],
    'alias': str, # (optional)
    'relation': RelationDto,
    'connected': bool,
    'gossip': GossipDto, # (optional)
}

Please refer to RelationDto and GossipDto for the details of these types.

RelationDto

A dict with the following key/value pairs.

relation_dto = {
    'relation': str
}

GossipDto

A dict with the following key/value pairs.

gossip_dto = {
    'heartbeat': HeartbeatDto,
    'metrics': MetricsDto
}

Please refer to HeartbeatDto and MetricsDto for the details of these types.

HeartbeatDto

A dict with the following key/value pairs.

heart_beat_dto = {
    'solid_milestone_index': int,
    'pruned_milestone_index': int,
    'latest_milestone_index': int,
    'connected_neighbors': int,
    'synced_neighbors': int
}

MetricsDto

A dict with the following key/value pairs.

metrics_dto = {
    'received_messages': int,
    'known_messages': int,
    'received_message_requests': int,
    'received_milestone_requests': int,
    'received_heartbeats': int,
    'sent_messages': int,
    'sent_message_requests': int,
    'sent_milestone_requests': int,
    'sent_heartbeats': int,
    'dropped_packets': int,
}