Skip to main content

Examples

This section will guide you through several examples using the python binding of the wallet.rs library. You can also find the code for the examples in the /bindings/python/examples folder in the official GitHub repository.

All the examples in this section expect you to set your custom password in the .env file:

SH_PASSWORD="here is your super secure password"

Account Manager and Individual Accounts#

You can initialize (open) a secure storage for individual accounts. The storage is backed up by Stronghold by default, using an AccountManager instance.

The following example creates a new database and account:

{@include ../../../bindings/python/examples/1a_create_account_manager.py}
  • Storage is initialized under the given path (./alice-database)
  • The password is set based on your password in .env file ( manager.setStrongholdPassword(process.env.SH_PASSWORD) )
  • When you initialize the new database, a Stronghold mnemonic (seed) is automatically generated and stored by default ( manager.storeMnemonic(SignerType.Stronghold) ).
  • The seed should be set only for the first time. In order to open already initialized database, you can simply use your password.

The storage is encrypted at rest, so you need a strong password and location where to place your storage.

warning

We highly recommended that you to store your Stronghold password encrypted on rest and separated from Stronghold snapshots.

Deal with the password with utmost care.

The storage comprises two things:

  • A single file called wallet.stronghold , which contains seed and is secured by Stronghold and encrypted at rest. The generated seed (mnemonic) serves as a cryptographic key from which all accounts and related addresses are generated.
  • Other data used by library that is stored under the db sub-directory. The includes account information, generated addresses, fetched messages, etc. This data is used to speed up some operations, such as account creation, address generation, etc.

One of the key principles behind Stronghold based storage is that no one can extract a seed from the storage. You deal with all accounts purely via an AccountManager instance. All complexities are hidden under the hood and dealt with securely.

If you also want to store a seed somewhere else, you can use the AccountManager.generateMnemonic() method. This method will generate a random seed, and it can be used before the actual account initialization.

You can find detailed information about seed generation at Developer Guide to Chrysalis.

Accounts#

The wallet.rs library uses a model of individual accounts to separate individual users and clients from each other. It is possible to generate multiple addresses for each account deterministically.

Each account is related to a specific IOTA network (mainnet or testnet), which is referenced by node properties such as node url. In this example, the Chrysalis testnet balancer.

For more information about client_options , please refer to Wallet Python API Reference.

{@include ../../../bindings/python/examples/1b_create_account.py}

Alias should be unique, and it can be any string that you see fit. The alias is usually used to identify the account later on. Each account is also represented by an index which is incremented by 1 every time new account is created. Any account can be then referred to by its index , alias or one of its generated addresses .

Once an account has been created, you retrieve an instance of it using the following methods:

  • get_account(account_id: str)
  • get_accounts() .

You can get an overview of all available accounts by running the following snippet:

for acc in account_manager.get_accounts():
print(f"Account alias: {acc.alias()}; network: {acc.bech32_hrp()}")

You can get and instance of a specific account using the account_manager.get_account("ALIAS"), replacing "ALIAS" for the given alias:

account = account_manager.get_account("Alice")

Several API calls can be performed via an account instance.

info

It is a good practice to sync the given account with the Tangle every time you work with an account instance to retrieve the latest information available. You can do this using the account.sync() method. By default, account.sync() is performed automatically on send , retry , reattach and promote API calls.

The most common methods of account instance are:

  • account.alias() : returns an alias of the given account.
  • account.addresses() : returns list of addresses related to the account.
  • account.get_unused_address() : returns a first unused address.
  • account.is_latest_address_unused() : queries the Tangle and returns a bool whether latest address was already used.
  • account.generate_address() : generates a new address for the address index incremented by 1.
  • account.balance() : returns the balance for the given account.
  • account.sync() : syncs the account information with the tangle.

Generating Address(es)#

Each account can have multiple addresses . Addresses are generated deterministically based on the account and address index. This means that the combination of account and index uniquely identifies the given address.

There are two types of addresses, internal and public (external), and each set of addresses is independent of each other and has independent index id.

  • Public addresses are created by account.generateAddress() and are indicated as internal=false (public)
  • Internal addresses are also called change addresses. Internal addresses are used to store the excess funds and are indicated as internal=true.

This approach is also known as a BIP32 Hierarchical Deterministic wallet (HD Wallet).

info

The IOTA 1.5 (Chrysalis) network supports reusing addresses multiple times.

You can use the following example to generate a new address via an instance of account which was retrieved using an account_manager instance:

{@include ../../../bindings/python/examples/2_generate_address.py}

Example output:

[{
'address': {
'inner': 'atoi1qzy79ew8x4hn4dsr0t3j8ce8hdwdrh8xzx85x2gkse6k0fx2jkyaqdgd2rn'
},
'balance': 0,
'key_index': 0,
'internal': False,
'outputs': []
},
{
'address': {
'inner': 'atoi1qzht4m2jt0q50lhlqa786pcx6vardm4xj8za72fezde6tj39acatq5zh2cg'
},
'balance': 0,
'key_index': 1,
'internal': False,
'outputs': []
}
]

There are two human-readable prefixes in IOTA 1.5 network: iota (mainnet) and atoi (testnet). If you take a close look at the addresses in the output, you will be able to notice that both of them start with atoi , and are therefore testnet addresses.

You can find detailed information about generating addresses at the Developer Guide to Chrysalis.

Checking the Balance#

Before we continue further, please visit the IOTA testnet faucet service and send some tokens to your testnet addresses.

IOTA Faucet Service

You can use the following example to sync your accounts and retrieve their balances.

{@include ../../../bindings/python/examples/3_check_balance.py}

Example output:

Total balance:
{
'total': 10000000,
'available': 10000000,
'incoming': 10000000,
'outgoing': 0
}
Balance per individual addresses:
[{
'address': {
'inner': 'atoi1qzy79ew8x4hn4dsr0t3j8ce8hdwdrh8xzx85x2gkse6k0fx2jkyaqdgd2rn'
},
'balance': 0,
'key_index': 0,
'internal': False,
'outputs': []
},
{
'address': {
'inner': 'atoi1qzht4m2jt0q50lhlqa786pcx6vardm4xj8za72fezde6tj39acatq5zh2cg'
},
'balance': 10000000,
'key_index': 1,
'internal': False,
'outputs': [{
'transaction_id': '1c88c91fe0a8eed074b5ccdfdad52403d7908d157b231ae1ef28b0e20ba14e8e',
'message_id': 'f1575f984f7fda6e9b3e23e96ef3304fcd0ba4ce323af3920856a427fabe1abe',
'index': 0,
'amount': 10000000,
'is_spent': False,
'address': {
'inner': 'atoi1qzht4m2jt0q50lhlqa786pcx6vardm4xj8za72fezde6tj39acatq5zh2cg'
}
}]
},
{
'address': {
'inner': 'atoi1qpvnsgygzal4vkxhlc0ew7c6c6csnjr72x5rgn3txqswrsa2xfrec8v04f7'
},
'balance': 0,
'key_index': 2,
'internal': False,
'outputs': []
}
]

In the detailed view per individual addresses, there is also outputs section. The outputs shows all the transactions (also known as wallet message(s) ), which are related to that address, and therefore account for the balance.

You can also check the balance using the Tangle Explorer.

info

IOTA is based on Unspent Transaction Output model. You can find a detailed explanation in the Developer Guide to Chrysalis.

Sending Tokens#

The process of sending tokens via wallet.rs can be described as follows:

  1. Create instance of iota_wallet.Transfer() class with the following mandatory arguments: amount, address and remainder_value_strategy . The remainder_value_strategy argument can be either:
    • ReuseAddress
    • ChangeAddress
  2. Once you have created an instance of iota_wallet.Transfer() , you can send the tokens using the transfer() function of the Account instance.
info

We highly recommend that you sync the account information with the Tangle by running the account.sync().execute() method before doing anything with the account. This way you can ensure that you rely on the latest available information.

{@include ../../../bindings/python/examples/4_send.py}

The previous snippet should have a similar output to the following JSON object:

{
'id': '9d3c401d59b0a87f6fbaa58582bb71e1858d63336421ccbae834821d9be113d3',
'version': 1,
'parents': ['66009ff08637c3e74340fb9e09e30e3c4453728c857fd425df2d2e0587af6426',
'6da392ac35f73594bf5509fb5c3304e972b36313ce98f2cc63def7cde2054b53',
'9157b29cbffcd5c9669cf22004fbc557354e5ade7268f5bfe25fbc75ab29e3b1',
'bfe860e09350cd3b8db90611e78e03fdda654139a4b34e68e4b1bb07528b2bef'
],
'payload_length': 233,
'payload': {
'transaction': [{
'essence': {
'regular': {
'inputs': [{
'transaction_id': '692d6660084dd3b6341ef4f761bc8b8bb27ac35bb0b352bfb030f2c80753815b',
'index': 0,
'metadata': {
'transaction_id': '692d6660084dd3b6341ef4f761bc8b8bb27ac35bb0b352bfb030f2c80753815b',
'message_id': 'c6284e0cc2a6383474782d4e6b6cfaf16c1831c8875cca262982782758a248c0',
'index': 0,
'amount': 10000000,
'is_spent': False,
'address': {
'inner': 'atoi1qq24vlx53qdskyfw6940xa2vg55ma5egzyqv6glq23udx3e0zkmmg97cwze'
}
}
}],
'outputs': [{
'address': 'atoi1qq24vlx53qdskyfw6940xa2vg55ma5egzyqv6glq23udx3e0zkmmg97cwze',
'amount': 9000000
},
{
'address': 'atoi1qpvnsgygzal4vkxhlc0ew7c6c6csnjr72x5rgn3txqswrsa2xfrec8v04f7',
'amount': 1000000
}
],
'payload': None
}
},
'unlock_blocks': [{
'signature': {
'public_key': [15... < TRIMMED > ...],
'signature': [210... < TRIMMED > ...]
},
'reference': None
}]
}],
'milestone': None,
'indexation': None
},
'timestamp': 1615132552,
'nonce': 274654,
'confirmed': None,
'broadcasted': True,
'incoming': False,
'value': 1000000,
'remainder_value': 9000000
}}

This is a wallet message that fully describes the given transaction.

To understand all aspects of messages, you will need to get familiar with concept of UTXO . You can find detailed information in the UTXO section in the Developer Guide to Chrysalis.

You can double-check the message using Tangle Explorer using its node_response['id']. Please make sure you select the right network.

If you have used the ChangeAddress remainder_value_strategy, the message will transfer tokens to the target address as well as new internal address within the given account (internal=True).

You can find detailed information about messages and payloads in the Developer Guide to Chrysalis.

Reattachments#

If you need to reattach a message, you should use the iota_wallet.promote(account_id, message_id) or iota_wallet.reattach(account_id, message_id) methods, sending your account_id and message_id as arguments.

List of Messages (transactions)#

You can query for a list of all particular messages (transactions) related to the given account using account.list_messages() method, and the related account.message_count() method.

You can use those methods to check whether a message is confirmed, broadcast, etc. You should always Sync the account with the Tangle before checking confirmation status.

You can use the following example to sync an account , and list all the messages related to the account .

{@include ../../../bindings/python/examples/4b_list_messages.py}

Dust Protection#

The network uses a dust protection protocol to prevent malicious actors from spamming the network while also keeping track of the unspent amount ( UTXO ).

info

โ€œ... micro-transaction below 1Mi of IOTA tokens can be sent to another address if there is already at least 1Mi on that address. That's why we sent 1Mi in the last example to comply with the protection.โ€

Dust protection also means you can't leave less than 1Mi on a spent address (leave a dust behind).

Backup Database#

Due to security practices that are incorporated in the Stronghold's DNA, there's no way to retrieve a seed, as seeds are encrypted at rest. Therefore, if you're using the default options, backing up the seed storage is a very important task.

The following example will guide you in backing up your data in secure files. You can move this file to another app or device, and restore it.

{@include ../../../bindings/python/examples/5_backup.py}

Output:

Backup path: ./backup/2021-03-07T18-24-06-iota-wallet-backup-wallet.stronghold

Alternatively, you can create a copy of the wallet.stronghold file and use it as seed backup. This can be achieved by a daily cronjob, rsync or scp with a datetime suffix for example.

Restore a Database#

To restore a database via wallet.rs, you will need to:

  1. Create new empty database with a password (without mnemonic seed)
  2. Import all accounts from the file that has been backed up earlier

The following example restores a secured backup file:

{@include ../../../bindings/python/examples/6_restore.py}

Since the backup file is just a copy of the original database it can be also be renamed to wallet.stronghold and opened in a standard way.

account_manager = iw.AccountManager(
storage_path='./alice-database'
)
account_manager.set_stronghold_password("password")

Listening to Events#

wallet.rs library is able to listen to several supported event. As soon as the event occurs, a provided callback will be triggered.

You can add any of the following event listeners:

  • on_balance_change(callback): id
  • on_new_transaction(callback): id
  • on_confirmation_state_change(callback): id
  • on_reattachment(callback): id
  • on_broadcast(callback): id
  • on_error(callback): id
  • on_stronghold_status_change(callback): id

Once you have registered an event listener using, the function will return an id for the listener as a list[Bytes].
You can later use this id to remove a listener by using the corresponding method described below:

  • remove_balance_change_listener(id)
  • remove_new_transaction_listener(id)
  • remove_confirmation_state_change_listener(id)
  • remove_reattachment_listener(id)
  • remove_broadcast_listener(id)
  • remove_error_listener(id)
  • remove_stronghold_status_change_listener(id)

The following example set's up a listener for the on_balance_change event using an event-based pattern:

{@include ../../../bindings/python/examples/7b_event_simple_event.py}

Expected output:

Account: Alice
Syncing...
Address: {'inner': 'atoi1qquszp0hzfsrgx4vx58dfg4v6eh20d2k3ddfgg9dt5778c2egc9uyw7g457'}
Fill your address with the Faucet: https://faucet.testnet.chrysalis2.com/
Waiting for external event (on_balance_changed)...
On balanced changed: {"indexationId":"c3a7a1ab8ba78460954223a704693d088ddd0388681ac6cc1dd964a388d1a619","accountId":"wallet-account://e51a6285ea2d8cbdf5b6da2b85a8344f619d798d869ef4fb88c5fac0e653d6cc","address":"atoi1qquszp0hzfsrgx4vx58dfg4v6eh20d2k3ddfgg9dt5778c2egc9uyw7g457","balanceChange":{"spent":0,"received":10000000}}
Done.

Alternatively, events can be consumed via queue-base pattern as shown in the following example:

{@include ../../../bindings/python/examples/7_event_queue.py}