Skip to content

Latest commit

 

History

History
 
 

python

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
examples
examples
 
 
native
native
 
 
README.md
README.md
 
 

README.md

IOTA Client Python Library

Requirements

  • Rust 1.52.0+
  • Python 3.6+

Try Run w/ Local Hornet

  1. Run your local Hornet
  • $ git clone [email protected]:gohornet/hornet.git
  • checkout develop branch
  • Modify your create_snapshot_alphanet.sh, modify Line 14 to go run "..\main.go" tool snapgen alphanet1 96f9de0989e77d0e150e850a5a600e83045fa57419eaf3b20225b763d4e23813 1000000000 "snapshots\alphanet1\full_export.bin"
  • Go to hornet/alphanet
  • $ ./run_coo_bootstrap.sh

  1. 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]

  2. To use the pre-build libraries

Connecting to a MQTT broker using raw ip doesn't work with TCP. This is a limitation of rustls.

Testing

  • Install tox
    • $ pip install tox
  • Build the library
    • $ python setup.py install
  • To test install tox globally and run
    • $ tox -e py

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(
    nodes_name_password=[[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
[primary_node_jwt_name_password] list[str] undefined An array of array with node URLs and optional JWT and basic auth name and password (length 1 is only the url, length 2 is url with JWT, length 3 is url with basic auth name and password and length 4 is url with JWT and basic auth name and password)
[primary_pow_node_jwt_name_password] list[str] undefined An array of array with node URLs and optional JWT and basic auth name and password (length 1 is only the url, length 2 is url with JWT, length 3 is url with basic auth name and password and length 4 is url with JWT and basic auth name and password)
[nodes_name_password] list[]list[str] undefined An array of array with node URLs and optional JWT and basic auth name and password (length 1 is only the url, length 2 is url with JWT, length 3 is url with basic auth name and password and length 4 is url with JWT and basic auth name and password)
[permanodes_name_password] list[]list[str] undefined An array of array with node URLs and optional JWT and basic auth name and password (length 1 is only the url, length 2 is url with JWT, length 3 is url with basic auth name and password and length 4 is url with JWT and basic auth name and password)
[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
[quorum] bool false Bool to define if quorum should be used
[quorum_size] int 3 An int that defines how many nodes should be used for quorum
[quorum_threshold] int 66 Define the % of nodes that need to return the same response to accept it
[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(): NodeInfoWrapper

Gets information about the node.

Returns the NodeInfoWrapper.

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): BalanceAddressResponse

Gets the balance in the address.

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

Returns the BalanceAddressResponse.

get_address_outputs(address, options (optional)): list[UtxoInput]

Gets the UTXO outputs associated with the given address.

Param Type Default Description
[address] str undefined The address Bech32 string
[options] [AddressOutputsOptions] undefined The query filters

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.

get_receipts(): Vec

Get all receipts.

Returns the ReceiptDto.

get_receipts_migrated_at(index): Vec

Get all receipts for a given milestone index.

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

Returns the ReceiptDto.

get_treasury(): TreasuryResponse

Get the treasury amount.

Returns the TreasuryResponse.

get_included_message(): Message

Get the included message of a transaction.

Param Type Description
[index] string The id of the transaction

Returns the new Message.

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_id(payload_str): str

Get the message id from the payload string.

Param Type Default Description
payload_str str undefined The payload string from the mqtt message event

Returns The identifier of message.

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), gap_limit(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
[gap_limit] int undefined The gap limit

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.

generate_mnemonic()

Returns a random generated Bip39 mnemonic with the English word list.

Returns A String

mnemonic_to_hex_seed(mnemonic)

Returns the seed hex encoded.

Param Type Default Description
mnemonic string undefined Bip39 mnemonic with words from the English word list.

Returns A String

bech32_to_hex(bech32)

Returns a parsed hex String from bech32.

Param Type Default Description
bech32 string undefined The address Bech32 string

Returns A String

hex_to_bech32(hex, bech32_hrp (optional))

Returns a parsed bech32 String from hex.

Param Type Default Description
bech32 string undefined The address Bech32 string
bech32_hrp string undefined The Bech32 hrp string

Returns A String

is_address_valid(address): bool

Checks if a given address is valid.

Param Type Default Description
address string undefined The address Bech32 string

Returns A boolean.

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.

retry_until_included(message_id, interval (optional), max_attempts (optional)): list[(str, Message)]

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

Param Type Default Description
[message_id] str undefined The message id
interval int 5 The interval in seconds in which we retry the message.
max_attempts int 10 The maximum of attempts we retry the message.

Returns the message ids and Message of reattached messages.

consolidate_funds(seed, account_index, start_index, end_index): str

Function to consolidate all funds from a range of addresses to the address with the lowest index in that range

Param Type Description
[seed] string The seed
[account_index] int The account index.
[start_index] int The lowest address index, funds will be consolidated to this address.
[end_index] int The address index until which funds will be consolidated

Returns the address to which the funds got consolidated, if any were available.

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.

BalanceAddressResponse

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
    'dust_allowed': bool
}

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]
}

ReceiptDto

A dict with the following key/value pairs.

receiptDto = {
    'receipt': Receipt,
    'milestone_index': int,
}

TreasuryResponse

A dict with the following key/value pairs.

treasuryResponse = {
    'milestone_id': str,
    'amount': int,
}

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],
    'next_pow_score': int,
    'next_pow_score_milestone_index': 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,
    'max_reconnection_attempts': int,
}

LedgerInclusionStateDto

A dict with the following key/value pairs.

ledger_inclusion_state_dto = {
    'state': str
}

NodeInfoWrapper

A dict with the following key/value pairs.

nodeinfo_wrapper{
    url: str,
    nodeinfo: info_response,
}
info_response = {
    'name': str,
    'version': str,
    'is_healthy': bool,
    'network_id': str,
    'bech32_hrp': str,
    'min_pow_score': float,
    'messages_per_second': float,
    'referenced_messages_per_second': float,
    'referenced_rate': float,
    'latest_milestone_timestamp': u64,
    'latest_milestone_index': int,
    'confirmed_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,
}

AddressOutputsOptions

A dict with the following key/value pairs.

options = {
    'include_spent': bool,
    'output_type': string
}