This textbook was generated automatically from a GitHub Repo. Visit the repo for more information.
IOTA Developer Essentials
These notebooks provide a self-study introduction to IOTA protocol and are designed for developers and tech enthusiasts who would like to get quickly familiar with the IOTA. Technical-related information is accompanied with interactive code snippets to help you to quickly jump on the platform and be ready to build own solutions based on it.
Motto of this tutorial: "Let's start with baby steps before we can try and fly."
Main Goal
Main goal of this guide is to provide a comprehensive yet well-balanced proportion of deep-dive technical information and essentials.
Getting Started
There are several chapters available. If you are not familiar with IOTA then it is highly recommended to follow them in the particular order to understand all important IOTA concepts properly. Otherwise you may get quickly confused later.
Code Snippets
Code snippets are currently based on Python, NodeJs and C#. Since Python is very descriptive language and easy to understand, I believe the tutorial is basically understandable to anyone. Anyway, all important IOTA concepts are described in language-agnostic way and so you would be able to use any language of your choice.
Interested to see what is the overall code base coverage breaked down to a specific language? The following page provides you such an info. Needless to say, we are working hard to be sure there is no language that would be a second-class citizen.
IOTA Developer Essentials are accompanied by IOTA Developer Lab and so you can play with all code snippets directly in your web browser. Feel free to experiment with the prepared code snippets and get your hands dirty. It is a best way how to get familiar quickly.
All standalone code snippets are also maintained @ GitHub Gist. It enables you to fork them, comment them, share them, embed them and track all changes to them. See the action panel next to each code snippet.
Viewing and running
Interactive Mode
There exists a side project called IOTA Developer Lab that is built on top of IOTA Developer Essentials. The project provides infrastructure services for you to be able to get an interactive experience with all code snippets.
Static Mode
If you prefer a static experience (for printing purposes, for instance) you can reach the given notebooks as a Complete Textbook that is compiled from all source materials:
Everything is tightly linked together and so you can easily switch between different languages for instance, or you can share links to specific chapters, code snippets, etc. All links are static so feel free to share them.
Feedback and corrections
These notebooks are maintained at GitHub. Issues can be submited via issue tracker.
About
These notebooks are developed and maintained by Petr Zizka (petr@zizkovi.name). It has been supported by the EDF Grant (https://blog.iota.org/the-5th-cohort-of-iota-ecosystem-development-fund-grantees-5cbf05227525).
It is ongoing process since IOTA is still under heavy development and rapidly emerging every day. So stay tuned - the plan is to keep adding fresh content on regular basis.
Feel free to follow me at Twitter or IOTA Discord Channel (@hribek25#2683). (New to Discord? Invitation link: https://discord.gg/fNGZXvh)
Disclaimer: I am not associated with the IOTA foundation. I am IOTA supporter.
The IOTA Developer Essentials and IOTA Developer Lab are long-term projects. The main goal is to provide a comprehensive onboarding information to anybody interested in the IOTA protocol. It will cover much more chapters, more code snippets and it will also cover more languages. Your kind donations will support the vision pushing forward. Thank you.
Donations (IOTA): DSZRO9TCIJIKZOKUPVNOJFKVAHFCKL9YMLPVZUAEVZPOFXLIUWLPRQWBMVVSFTKGMGPPHXCYE9MIZEVBXQNFYKYUA9
IOTA 101: Essentials and IOTA Terminology
IOTA is an open-source Distributed Ledger Technology (DLT) with the following characteristics: permissionless, feeless and trustless. In contrary to the blockchain technology, the IOTA transactions are stored in a form of Directed Acyclic Graph (DAG) called the Tangle.
Transactions
Transactions (TXs) in the tangle can be of two types:
- Value transactions (IOTA token represents funds in case of value transactions)
- Zero-value transactions (aka meta transactions)
Every transaction is attached to a specific IOTA Address. There are no miners with IOTA protocol to validate transactions. The consensus is achieved by network participants themselves. Each participant that wants to broadcast a new transaction has to approve 2 past transactions and basically attach transaction as a children node. Transactions without children transactions (waiting to be confirmed) are called tips.
Seed, private key and address
Pair of unique IOTA address and corresponding Private Key is determistically generated from a Seed. You can generate (253 - 1) different addresses/private keys based on one Seed. Anybody can send anything to the given address however only Seed owner can send funds from IOTA address since only the Seed owner is able to generate corresponding Private Key.
IOTA protocol uses One-Time Signature (OTS) for "verifying" whether private key matches to the given address, specifically Winternitz OTS (WOTS). So Private Key (specifically Key Fragments of the private key) is the key component while signing transactions using WOTS.
That's the reason why nobody should use IOTA address that have been already funds spent from. New IOTA address (of the given seed) should be generated and used instead. Please note, it applies only to fund-spending. Receiving funds/data is totaly fine even multiple times.
To summarize the key concept here. Only Seed is needed to be stored somewhere. Everything else can be safely generated from it: private key as well as address.
IOTA nodes
The Tangle runs on a distributed network of IOTA nodes called mainnet. There are also other separate "Tangles" serving for specific purposes: Devnet, SPAMnet, etc. You can interact with the network via public nodes using collection of public API calls. You can interact with any public node of the given network since all nodes "gossiping" all TXs across the whole network. Nodes are powered by a reference piece of software called IRI (IOTA Reference Implementation) as of now.
It is also important to mention that you do not exchange any sensitive information such as Seed with a node. Every sensitive operation such as TX signing is done on client's side and node is just a "messenger" that delivers your TX to the IOTA network.
Custom node
You can even run own IOTA node and actively participate to the whole network. There is a big advantage for developers in that case. Actual implementation of IRI provides an usefull real-time information via messaging platform called ZeroMQ and so developers can leverage that.
API calls
There are ready-made libraries for major programming languages available and so you have more developer-friendly way how to interact with the IOTA network. Anyway, you can interact with IOTA network using pure API calls without any library. It is up to you.
Ternary
It is difficult to avoid mentioning Ternary numeral system while discussing IOTA at all. IOTA is based on ternary system under the hood and so you have got to be aware of some basic terminology in this respect. You are going to face this fact in any developer-related IOTA guide out there.
Ternary
Ternary has three as its base (aka base 3) as opposted to binary which is base 2. Instead of two states (0 and 1) it recognizes three states (for ex. -1, 0, 1).
Trit
One Trite is analogous to one bit. It is the smallest digit and has three states. Trit = Trinary digit.
Tryte
Tryte consists of three trits meaning 27 combinations. $$3^3=27$$
You will recognize soon that almost everything is encoded in Trytes in the IOTA world. Tryte is visually represented using [A..Z] alphabets and number 9. One character represents one tryte (here comes 27 possible characters again). Don't get mad, IOTA libraries are going to help us.
Small example:
import iota #importing PyOTA library to interact with
from pprint import pprint
TrytesAsBytes = b"YZJEATEQ9JKLZ" # some data encoded in Trytes (byte string in Python, not unicode string)
Trytes = iota.TryteString(TrytesAsBytes) # initializing TryteString type from the PyOTA library - great help while dealing with Trytes/Trits, etc.
pprint(Trytes) # getting the same data however using TryteString type of PyOTA library
pprint("Number of Trytes: %s" % len(TrytesAsBytes))
Trits = Trytes.as_trits() # converting Trytes to Trits
pprint(Trits,compact=True)
pprint("Number of trits: %s" % len(Trits)) # Number of trits is three times the number of trytes obviously
IOTA 101: Basic network interactions
The tutorial is based on IOTA libraries called PyOTA for Python, IOTA Javascript Library (@iota/core) for JavaScript and Tangle.Net for C# (.NET 4.x and .NET Standard). It encapsulates all official IRI API calls and it can be installed via pip in Python environment, via npm in JS environment and via NuGet in case of .NET environment.
Reader is also encouraged to try a ready-made environment via IOTA Developer Lab project (at lab.iota101.info) where anyone can run a code directly in a web browser. When viewing it interactively then just select a code snippet and hit ctrl + enter which executes it.
Anyway, most of the information in the tutorial is language-agnostic and so only particular interfaces slightly differ across different IOTA libraries. Top-level details are the same regardless programming language you are going to use.
A few words about specific IOTA libraries
Python
PyOTA is well maintained and understandable IOTA library that can be reached at https://github.com/iotaledger/iota.lib.py. It is very good starting point for beginners.
It can be installed via pip:
pip install pyota
JavaScipt
Official IOTA Javascript library (v1.0) is currently in beta however all main functions are working just fine, please see https://github.com/iotaledger/iota.js/. It is very modular and so you can install only components you really need.
Main component is @iota/core and can be installed via npm:
npm install @iota/core
As with everything in NodeJS, most of the tasks are asynchronous and they are chained via callbacks or promise. Snippets below leverage promise chaining.
C# (.NET)
Tangle.Net is well maintained IOTA library for .NET and can be reached at https://github.com/Felandil/tangle-.net.
It can be installed via NuGet:
nuget.exe install tangle.net
Snippets below uses synchronous functions however the library provides also asynchronous (async postfix) version.
Conneting to IOTA nodes
Before you can interact with the IOTA network you need an URL of the running IOTA node. There are dozen of directories of public nodes available, feel free to google them.
For a sake of this tutorial I use a project thetangle.org. It is a load ballancer that provides you an access to a pool of participanting nodes effortlessly.
- Advantage: you do not have to care about public nodes and whether they are running or not
- Disadvantage: you do not know in advance which specific node will process your API call. So in some respect results of API calls may differ since some API calls depend on specific node, such as GetNodeInfo().
Node is not synced
Even if a node is up and running it may not be fully prepared to process your API calls correctly. The node should be "synced", meaning should be aware of all TXs in the Tangle. It is better to avoid not fully synced nodes.
Health checking
Once you connect to an IOTA node you should be able to send API calls. However it is better to do some checks in advance in order to find out whether the given node is in good condition or not. IOTA nodes can be run by anyone and so health check is always a good practice.
Basic healthcheck can be done via GetNodeInfo() API call. It returns a basic information about the given IOTA node.
import iota #importing PyOTA library to interact with
from pprint import pprint
NodeURL = "https://nodes.thetangle.org:443"
api=iota.Iota(NodeURL) # ctor initialization of the PyOTA library
result = api.get_node_info() # basic API call to double check health conditions
pprint(result) # result is printed out
# Basic check whether node is in sync or not
# Elementary rule is that "latestMilestoneIndex" should equal to "latestSolidSubtangleMilestoneIndex" or be very close
if abs(result['latestMilestoneIndex'] - result['latestSolidSubtangleMilestoneIndex']) > 3 :
print ("\r\nNode is probably not synced!")
else:
print ("\r\nNode is probably synced!")
Please note: When using node load balancers then this type of check is quite useless since other API calls of yours may be served by different node that may have not been checked. You should be aware of it and trust that the load balancer participates only with nodes that are in a good condition.
Generating IOTA seed and IOTA address
Since the IOTA network is permissionless type of network, anybody is able to use it and interact with it. No central authority is required at any stage. So anybody is able to generate own seed and respective private key/address anytime. It is highly recommended to NOT use online generators at all.
The Seed is the only key to the given addresses. Anyone who owns the Seed owns also all funds related to respective IOTA addresses (all of them).
Seed and addresses only consists of characters [A-Z] and number 9. Length is always 81 charaters. There are usually also used additional 9 characters in IOTA addresses (so total lenght is 90 then) which is a checksum. It provides a way how to prevent typos while manipulating with IOTA addresses.
Seed
A seed generation is a process that is based on random quessing of each character in the seed. Of course, you should always use cryptographically secure pseudo-random generator!
import random
chars=u'9ABCDEFGHIJKLMNOPQRSTUVWXYZ' #27 characters - max number you can express by one Tryte - do you remember?
rndgenerator = random.SystemRandom() #cryptographically secure pseudo-random generator
NewSeed = u''.join(rndgenerator.choice(chars) for _ in range(81)) #generating 81-chars long seed. This is Python 3.6+ compatible
print(NewSeed)
print("Length: %s" % len(NewSeed))
Alternatively you can leverage also PyOTA library since it has own implementation of the pseudo-random Seed generator (Python 2.7+ compatible). Difference between both methods is very subtle. I just wanted to illustrate both ways: Fully independent and IOTA-library-dependant. Please note, IOTA Javascript library does not support a seed generation.
from iota.crypto.types import Seed #importing PyOTA library to interact with
NewSeed = Seed.random()
print(NewSeed)
print("Length: %s" % len(NewSeed))
Address
There is a deterministic function how to get an address from a seed. It is a basically an indexed collection of addresses starting with address at index 0, 1, 2, etc.
While generating addresses you should be also aware there are three different so called Security Levels (1, 2 and 3). Each security level generates totally independent pool of addresses. Addresses of Security Level 1 are totally different from addresses of Security Level 2, etc.
In a nutshell, Security Level indicates how difficult is to generate Private key from the Seed and also what is its size. The higher security level, the more secure (longer) is the given private key. Default Security Level is 2. Most of IOTA wallets uses Security Level=2 and users are usually not allowed to change it. So be carefull while designing your app.
As long as seed, address index and security level are the same, you always get the same address and corresponding private key:
$$PrivateKey/Address = fce(Seed, AddressIndex, SecurityLevel)$$General example: $$PrivateKey/Address1 = fce(Seed, 1, 2)$$ $$PrivateKey/Address2 = fce(Seed, 2, 2)$$ $$PrivateKey/Address3 = fce(Seed, 3, 2)$$
import iota
from pprint import pprint
# For this particular task the Node URL is not important as it will not be contacted at all
# However it has to be well-formatted URI
NodeURL = "https://nodes.thetangle.org:443"
MySeed = b"WKQDUZTGFKSSLACUCHHLZRKZBHSDSCEBHKUPDLKFBQALEBKDMFRPUQGZRXAADPG9TSRTZGGBZOFRJCFMM"
api=iota.Iota(NodeURL,
seed = MySeed) # if you do not specify a seed, PyOTA library randomly generates one for you under the hood
# Let's generate 3 addresses using default security level=2.
# It is deterministic function - it always generates same addresses as long as the Seed, Security Level and Index are the same
result = api.get_new_addresses(index=0,
count=3,
security_level=2)
pprint(result)
Please note, some IOTA libraries may communicate with a IOTA network while generating addresses to double check whether the given address was used or not.
So it is sometimes better to use directly an address generator component. Outputs are equivalent in both cases but the latter one usually only generates pool of addresses locally:
from iota.crypto.addresses import AddressGenerator
from pprint import pprint
MySeed = b"WKQDUZTGFKSSLACUCHHLZRKZBHSDSCEBHKUPDLKFBQALEBKDMFRPUQGZRXAADPG9TSRTZGGBZOFRJCFMM"
#security level is defined during generator init
generator = AddressGenerator(seed=MySeed,
security_level=2)
result = generator.get_addresses(0, 3) #index, count
pprint(result)
Validating IOTA address
As mentioned earlier, IOTA address consists of 81 trytes ([A..Z9] characters) or 90 trytes including checksum. Checksum is useful when you want to make sure a valid address was given (no typos, etc.) and so it is a good practise to encourage user of your app using IOTA addresses including checksums = 90 trytes.
IOTA libraries are able to help you to deal with some basic patterns such as validating addresses, generating checksums, etc.
import iota
from pprint import pprint
# some IOTA address
Adr = iota.Address(b"CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW")
pprint("Original input excl. checksum address:")
pprint(Adr)
print("Length: %s" % len(Adr))
AdrInclCheckSum = Adr.with_valid_checksum()
print("\nInput address including checksum:")
pprint(AdrInclCheckSum) # the last 9 trytes is the checksum
print("Length incl checksum: %s" % len(AdrInclCheckSum))
You should always make sure your app is dealing with valid IOTA address. Please note, you should also make sure an address is of correct length and consists only of allowed characters. IOTA libraries may slightly differ in their approaches but differences are very subtle and both libraries provide enough functions to validate IOTA address.
General steps should be:
- Checks length
- Checks valid characters
- Checks address against its checksum
import iota
import sys
from pprint import pprint
InputAddr = b"CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RWTHBIRSXTA"
if len(InputAddr)!=90:
print("Incorrect lenght of the given address. Please, use an address including checksum.")
exit(2)
try:
# address including checksum
Adr2 = iota.Address(InputAddr)
except :
print("Not valid input address given")
sys.exit(1)
pprint("Input address incl checksum:")
pprint(Adr2)
print("Is it valid addr based on checksum? %s" % (Adr2.is_checksum_valid()))
print("\nInput address excl checksum:")
pprint(Adr2[:81]) # return only first 81 characters
IOTA 101: Transactions
A transaction is a smallest piece of data that can be broadcasted to the network. Each transaction consists of fixed 2673 trytes. Transactions (TXs) are basically of two types:
- Value TXs: those transactions change ownership of IOTA tokens. Two possible states: spending TXs or receiving TXs
- Non-Value TXs: those transactions include piece of data that can be broadcasted and read from the Tangle
Transactions are broadcasted in an envelope called Bundle. Bundle may consist of multiple TXs. Bundle is processed by the Tangle as a single entity; meaning only the whole bundle is confirmed by the network (and all TXs within) or nothing. You have to prepare a bundle even if you broadcast single transaction only. Bundle is also described as atomic since every bundle includes all information needed to process it antonomously.
Each transaction includes several fields, let's name the most important ones:
Value: Value can be positive number = receiving IOTA tokens, negative number = spending IOTA tokens or zero = broadcasting only piece of dataAddress: It is IOTA address that is associated with the given transaction. Value indicates whether it is an address of a receiver or a senderTag: It is an user-defined tag that can be used for searching, etc.SignatureMessageFragment: This is the most lenghty attribute (2187 trytes) and could include: transaction signature based on private key in case it is a spending TX or piece of data (message) in case it is non-value TX. Alternatively it can be also left blank (in case of non-value TXs)TrunkTransaction/branchTransaction: Those two fields refer to some previous transactions in the Tangle (tips) that the given bundle is going to approveTimestamp: TX timestamp. It is actually UNIX timestamp (UTC)
A process of sending IOTA transaction can be summarized in 5 steps:
- To create transation(s) with the given attributes: value, address and potentially also tag or message
- To finalize a bundle that includes all transactions. Once the bundle is finalized no new transactions can be added. It basically means to generate a bundle hash
- To search for two tips in the Tangle that you are going to validate. There is not a strict rule how to search them but it is generally recommended to leave it on a tip selection algorithm implemented on node's side
- To do a Proof-of-Work for each transaction in the bundle. Result of POW is Nonce and Transaction hash stored with each transaction
- Finally you need to broadcast the whole bundle to the network
A secret of a bundle
There is a secret to be shared. You have to understand one important thing. Bundle is a top level construct that link all related transactions under one entity however the bundle itself is not broadcasted in fact. You still broadcast "only" collection of individual transactions instead. All transactions are recognized to be part of a bundle by the IOTA protocol however any data peering is based on individual transactions (in trytes).
In other words, a bundle can be reconstructed anytime from a collection of transactions via fields bundle hash, current index and last index.
Non-value transactions
Let's start with non-value transactions (meta transactions) first since they are a bit easier for starters.
Please note, the chapter is divided in two separate sections. In the first section, examples are really close to bare metal (still not too close:) to illustrate the whole process and describing implementation details wherever possible. It is also useful when you want to experiment with different settings at each step (hey "non-existing tips", looking at you).
In the second section, IOTA-facing libraries are fully levearged since they are capable to hide all implementation details behind a curtain. Needless to say, if you are not interested in such details then you would probably like to start with the second section.
Creating and broadcasting transaction in 5 steps (you want to understand the process)
Create a transaction
First of all let's create transactions (offline; in memory) and set main fields.
BTW: Timestamp field is defined automatically by the IOTA-facing libraries in the process. It is important field while creating bundle hash.
In the examples within this chapter we are going to broadcast meta transactions (data only) to two different IOTA addresses.
import iota
from datetime import datetime
from pprint import pprint
MySeed = b"HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA"
TargetAddress1 = b"CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9"
TargetAddress2 = b"CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW"
NowIs = datetime.now() # get a actual date & time - just to have some meaningfull info
# preparing transactions
pt = iota.ProposedTransaction(address = iota.Address(TargetAddress1), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a first message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
pt2 = iota.ProposedTransaction(address = iota.Address(TargetAddress2), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a second message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
# besides the given attributes, library also adds a transaction timestamp
print("Created transaction objects:\n")
pprint(vars(pt))
print("\n")
pprint(vars(pt2))
Finalizing bundle
Once all individual transactions are created it is time to prepare and finalize the bundle. While preparing the bundle you need at least to specify list of prepared transaction(s). In case of non-value transactions it is quite straightforward process. However, it is a bit more complicated in case of value transactions - please see later.
Finalizing the bundle consists of several tasks under the hood:
- Each transaction is indexed. Attributes
current_index/last_indexare set Bundle hashis generated (Sponge function + normalization) and assigned to each transactionsignatureMessageFragmentis bascially copy ofmessagefield in case of non-value transactions- PyOTA library also checks whether the data in
messagefield is larger than transaction allows (2187 trytes). If this is the case then it takes care of it and split your data into several transactions
Please note, finalizing the bundle also means you are no longer able to add new transactions to the bundle post the finalization process.
Simply put, bundle hash is a cryptographic "fingerprint" of all transactions in the bundle. It uniquely represents them and so as long as transactions are the same (incl their particular order) the bundle hash is also the same.
You may be wondering what is a difference between tag and legacy_tag. Tag includes actualy the tag that was defined during the transaction creation. Legacy_tag is also based on it however it is modified during the normalization process while bundle hashing to be sure that bundle hash is can be securely used while TX signing. That's why the bundle hash is sometimes refered as normalized bundle hash.
The bundle refers to the first transaction in collection as tail_transaction. You can perceive tail transaction as an official representative of the whole bundle while checking for confirmation status, etc. Remember, the bundle is an atomic entity and so whatever is done to bundle it applies to ALL transactions within.
# preparing bundle that consists of both transactions prepared in the previous example
pb = iota.ProposedBundle(transactions=[pt,pt2]) # list of prepared transactions is needed at least
# generate bundle hash using sponge/absorb function + normalize bundle hash + copy bundle hash into each transaction / bundle is finalized
pb.finalize()
#bundle is finalized, let's print it
print("\nGenerated bundle hash: %s" % (pb.hash))
print("\nTail Transaction in the Bundle is a transaction #%s." % (pb.tail_transaction.current_index))
print("\nList of all transactions in the bundle:\n")
for txn in pb:
pprint(vars(txn))
print("")
At this stage you can also see how does our finalized bundle look encoded in Trytes so far. It is also a proof that there is no bundle to be broadcasted itself, only list of transations matter.
Trytes = pb.as_tryte_strings() # bundle as trytes
pprint(Trytes)
Selecting two tips
As mentioned earlier you need to find two tips that you are going to validate together with your bundle for a sake of network participation. This will be outsourced to an IOTA node and so it will be for the first time we interact with the network (via API call get_transactions_to_approve).
There is a depth parameter needed. It instructs a node how many milestones it should go in the past while confirming tips. The higher value the better to network however more resources needed. Depth=3 is considered to be well-balanced compromise. Higher value than depth=10 will probably throw an exception depending on node's configuration.
It should return two selected tips as branch and trunk transactions. Those transactions will be used while broadcasting the bundle.
api = iota.Iota("https://nodes.thetangle.org:443") # selecting IOTA node
gta = api.get_transactions_to_approve(depth=3) # get tips to be approved by your bundle
pprint(gta)
Performin' POW
Proof of work is a relatively simple cryptograhic puzzle to be solved. It represents energy-based costs of your transaction. It also helps to minimize risks of some attack vectors to the network.
This task can be also outsourced to IOTA nodes. In order to perform it you need selected tips, finalized bundle (in trytes) and also Minimum Weight Magnitude parameter. This parameter defines how diffciult the given cryptographic puzzle should be to be accepted by the network. As of now, you should set at least min_weight_magnitude=14 in case of mainnet.
Please note, POW is performed per each transaction and so it can take some time. That's why it is not recommended to have more than 30 transactions in a bundle.
Once succesfully performed, the modified bundle (list of all transactions in trytes) is returned in order to be broadcasted.
Specifically:
- Fields
nonceandtransaction hashare calculated per each transaction TrunkandBranchtips are correctly mapped among transactions within the bundle. Check thattrunkof the first TX refers to the second TX, etc.
print("Performing POW... Wait please...\n")
att = api.attach_to_tangle(trunk_transaction=gta['trunkTransaction'], # first tip selected
branch_transaction=gta['branchTransaction'], # second tip selected
trytes=Trytes, # our finalized bundle in Trytes
min_weight_magnitude=14) # MWMN
pprint(att)
You can eventually also preview what specific fields have been modified using transaction objects. The bundle is ready to be broadcasted and so it also show you all fields/values that will be stored in the network.
# show what has been broadcasted - hash transaction + nonce (POW)
print("Final bundle including POW and branch/trunk transactions:\n")
for t in att['trytes']:
pprint(vars(iota.Transaction.from_tryte_string(t)))
print("")
Broadcasting
Now it is time to broadcast the given bundle to the network. List of all transations in trytes returned from the previous step is only thing needed.
Once succesfully broadcasted it returns the same input bundle as a confirmation.
print("Broadcasting transaction...")
res = api.broadcast_and_store(att['trytes'])
pprint(res)
You can check the broadcasted bundle via The Tangle Explorer at any of the receiving addresses:
Creating and broadcasting transaction in a single call (you want send a transaction quickly)
As mentioned above, IOTA-facing libraries are able to encapsulate all implementation details and so you do not need to care of them anymore. It is usually based on extended API calls that were proposed to be included by IOTA Foundation to make developer's life easier (https://github.com/iotaledger/wiki/blob/master/api-proposal.md).
Even if using extended API calls you can still slightly control a level of your involvement in the whole process. From almost no involvement and fully automatic (send_transfer()) to semi-manual approach discussed above.
There are some specifics you should consider while designing your app:
- You are loosing a bit of control of individual steps of the process and you have to rely of some predefined parameters (tip selection algo, etc.)
- If there is an exception raised during the process then you need to go back at beginning and restart the whole process again
So it is basically your call to decide what works best for you.
Now back to our exercise. Here comes a code that basically broadcasts transactions in a single call (send_transfer()) and you do not have to care of any implemenation details that are hidden under the hood.
import iota
from datetime import datetime
from pprint import pprint
MySeed = b"HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA"
TargetAddress1 = b"CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9"
TargetAddress2 = b"CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW"
NowIs = datetime.now() # get a actual date & time - just to have some meaningfull info
# preparing transactions
pt = iota.ProposedTransaction(address = iota.Address(TargetAddress1), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a first message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
pt2 = iota.ProposedTransaction(address = iota.Address(TargetAddress2), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a second message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
# besides the given attributes, library also adds a transaction timestamp
api = iota.Iota("https://nodes.thetangle.org:443")
print("Preparing/Broadcasting... Wait please...")
# the whole process initiated in a single call
FinalBundle = api.send_transfer(depth=3,
transfers=[pt,pt2],
min_weight_magnitude=14)['bundle'] # it returns a dictionary with a bundle object
#bundle is broadcasted, let's print it
print("\nGenerated bundle hash: %s" % (FinalBundle.hash))
print("\nTail Transaction in the Bundle is a transaction #%s." % (FinalBundle.tail_transaction.current_index))
print("\nList of all transactions in the bundle:\n")
for txn in FinalBundle:
pprint(vars(txn))
print("")
You can check the broadcasted bundle via The Tangle Explorer at any of the receiving addresses:
And to complete the picture here is addtional code that uses prepare_transfer() and send_trytes() combo.
import iota
from datetime import datetime
from pprint import pprint
MySeed = b"HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA"
TargetAddress1 = b"CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9"
TargetAddress2 = b"CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW"
NowIs = datetime.now() # get a actual date & time - just to have some meaningfull info
# preparing transactions
pt = iota.ProposedTransaction(address = iota.Address(TargetAddress1), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a first message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
pt2 = iota.ProposedTransaction(address = iota.Address(TargetAddress2), # 81 trytes long address
message = iota.TryteString.from_unicode('Here comes a second message. Now is %s' % (NowIs)),
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'), # Up to 27 trytes
value = 0)
# besides the given attributes, library also adds a transaction timestamp
api = iota.Iota("https://nodes.thetangle.org:443")
# Creating bundle, preparing inputs and finalizing bundle. It returns trytes of prepared TXs
Trytes = api.prepare_transfer(transfers=[pt,pt2])
print("Almost prepared bundle - tips and POW are still missing")
pprint(Trytes)
print("\nSearching for tips and performing POW... Wait please...")
Result = api.send_trytes(trytes=Trytes["trytes"],
depth=3) # Searching for tips, performing POW and broadcasting
print("Bundle was broadcasted.")
print("\nFinal transactions were returned - including nonce (POW)")
pprint(Result)
You can check the broadcasted bundle via The Tangle Explorer at any of the receiving addresses:
Value transactions
Meta transactions were discussed in the previous chapter. This chapter describes value transactions which are transactions that transfer IOTA tokens between IOTA addresses. Tokens are fully premined and so number of tokens in the network is given. So transfering tokens means changing their ownership only.
While preparing a bundle with value transations it is important to distinguish three different transaction types within a bundle:
- Input TXs: those are transactions that deducting (spending) value from address(es). Those transactions have negative
valuefield. They usually refer tosenders - Output TXs: those are transactions that adding (receiving) value to address(es). Those transactions have positive
valuefield. They usually refer torecipients - Unspent/change TX: technically speaking it is also output transaction that adding value however it usually refers to
sendersand so it is better to consider it separated from other output TXs
All three types have to be part of each bundle otherwise you are under a risk of loosing IOTA tokens. In other words, each bundle should consists of at least one input TX, one output TX and one unspent TX. Total balance of the bundle should be zero since the number of tokens is the same, just token owners have been "changed".
Example:
- Alice owns 100 tokens (input = 100)
- Alice is going to send 20 tokens to John from the address that includes 100 tokens of her (Alice -100)
- John is going to receive 20 tokens from Alice (output = 20; John +20)
- Alice still owns 80 tokens after the transaction (unspent = 80; Alice +80)
Alice's bundle should look like: \begin{align} Input - Output & = \ Unspent \\ Input - Output - Unspent & = \ 0 \\ 100 - 20 - 80 & = \ 0 \end{align}
Why Alice has to "put" all 100 tokens in the bundle while she is going to actually spend only 20 tokens? The reason is that IOTA protocol uses one-time signature scheme (OTS) for transaction signing while spending tokens. And with every signing process a half of a private key of the given address is revealed. That's why no one should ever spend tokens from the same address again.
Spending tokens
Please note: for a purpose of this chapter we are going to switch to a test network called devnet. It is the testing Tangle. Tokens are not real and everything you do have no implication to the mainnet at all. However it is stil powered by standard node software and so technicaly speaking it behaves like the mainnet. If you need more info regarding devnet please refer to the official documentation.
Everything what has been mentioned in the previous chapter focused on non-value transations is still valid also in case of value transactions however there are several additional tasks you should take care of. Needless to say, IOTA libraries (PyOTA and others) are ready to help you and are able to hide all implementation details in case you would like to. In this case I would encourage everyone to prefer a functionality that is offered by extended API calls, such as send_transfer. Experimenting with value transactions and trying to tweak them does not seem to be a good idea (on the mainnet).
Anyway, even in this chapter I am going to describe main tasks that are performed under the hood to be able to understand the whole concept.
Let's have the following setup:
import iota
from pprint import pprint
# Sender's side ***********
# Sender's seed
SeedSender = b"HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA"
# Receiver's side ***********
# Recipient's seed - this is actually not needed for the exercise - it is just to have corresponding seed somewhere written
SeedReceiver = b"NVPDKGLESTYNJEH9DTWD9DUBYWHZJDDWTBLKWEYLVZKBKKAZTIZ9CFFJMHPEKIFUWQTXRGAVRXAQZCPHL"
# This is our target address to which we are going to send tokens to (BTW: it is a first generated address based on recipient's seed)
AddressReceiver = b"BMFSMZMNBGKHAWPIZIOMJGRBXZETVSAYDSTDQCHLYTBWZMIXLNXF9XHLTMOCATFVFOMBQF9IOQGPEBPDC"
#DevNet node - Devnet Tangle that is used only for testing/dev purposes - no real tokens here:(
DevnetNode = "https://nodes.devnet.iota.org:443"
print("Variables were initialized.")
You may be wondering why only the seed for sender's side is defined. As mentioned above the reason is that the address with tokens is changing with every spending exercise and so you have to find address with tokens that left in a bucket programatically (if any tokens left:).
Let's find out. For this purpose you can use extended API call get_account_data which returns a list of used addresses and total sum of all tokens available accross all of them:
api = iota.Iota(DevnetNode,
seed=SeedSender # let's use seed of the sender and so library can do all hard work
)
print("Checking for total balance. This may take some time...")
# now we can find out whether there are any tokens left
SenderBalance = api.get_account_data(start=30, #starting from 30th address to save time
stop=None) # Get the total available balance for the given seed and all related used addresses
print("\nPlease note, this may take some time if many addresses has been used already...")
pprint(SenderBalance)
if SenderBalance['balance']>0:
print("\nYes, there are some tokens available! hurray")
Please note: API call get_account_data consider only confirmed transactions while calculating total balance. So it is better to wait until all transactions are cleared before you send additional tokens.
Are there any tokens left (value in balance field)? If yes then continue - no action is needed.
If not, then you need to obtain some. It can be done visiting IOTA faucet and entering an unused address of the given seed:
# Now let's find a first unused address that can be used as a destination address for unspent/new tokens
print("\nPlease note, this may take some time if many addresses has been used already...")
FreeAddressSender = api.get_new_addresses(index=30,
count=None, # If None is specified, then it identifies a first non-used address
security_level=2) # Let's generate an address using default security level=2.
print("\nThis is the first unused address that can be used for new tokens or unspent tokens:")
pprint(FreeAddressSender)
What have just happened behind the curtain?
- The PyOTA library started to generating addresses from the
index=0of the given seed and at the same time it also checked whether there are any transactions registered for each address - If yes, then in case we are after balances, the balance is saved. In case we are after new unused address then the given address is skipped. First address for which there are not registered transactions is returned
- That's why it may be quite time consuming. And now you also understand all issues regarding
zero balancesafter the snapshot
You may be also wondering how to get individual balances for each used address? This can be checked using the core API call get_balances which provides you with a balance for any address you specify. Let's query for used addresses from the previous exercise:
# only if there is any used addresses from the previous steps
# it returns the balances as a list in the same order as the addresses were provided as input.
if len(SenderBalance['addresses'])>0:
print("\nSome positive balance identified. Individual confirmed balances per used addresses:")
pprint(api.get_balances(addresses=SenderBalance['addresses'],
threshold=100) # Confirmation threshold; official docs recommend to set it to 100
)
else:
print("\nNo positive balance identified.")
It returns balances and you can see how the remaining tokens move to new unused address every time you spend some tokens. Needless to say, used addresses with zero balances should not be used anymore since tokens were already spent from them. So let's spend some tokens:
tx1 = iota.ProposedTransaction( address = iota.Address(AddressReceiver), # 81 trytes long address
message = None,
tag = iota.Tag(b'HRIBEK999IOTA999TUTORIAL'),
value = 10) # we are going to spend 10i
# Sending the iotas
print("\nSending iotas... Please wait...")
SentBundle = api.send_transfer(depth=3,
transfers=[tx1], # one transaction defined above. It is an output TX that adds tokens
inputs=None, # input address(es) that are used to finance the given transaction. Tokens will be deducted from them
change_address=None, # this is the adddress to which unspent amount is sent
min_weight_magnitude=9, # in case of Devnet it is 9
security_level=2) # you need to specify security level to be sure library generate compatible addresses
# you may be wondering why there is imputs=None and change_address=None.
# It means it will be taken care by library and so make sure correct seed / security level was added while api initialization
print("\nIt has been sent. Now let's see transactions that were sent:")
# let's check transactions that were sent in fact
print("Here is the bundle hash: %s" % (SentBundle['bundle'].hash))
for tx in SentBundle['bundle']:
print("\n")
pprint(vars(tx))
Let's review all transactions that has been prepared and sent eventually:
- The first transaction
current_index=0is theoutput TXthat basically adds tokens to some address - Transactions
current_index=1andcurrent_index=2are two parts of the same transaction -Input TX. This transaction deducts tokens from the address(es). You can see negativevaluein the transactioncurrent_index=1 - Why there are two parts? Since the transaction spends tokens it has to be signed in order to validate the ownership. Signature is generated from the private key and the signature can be observed in the field
signature_message_fragment. Here is the thing. Do you remember when differentsecurity levelswere discussed? There are three security levels available and the given level has the direct impact on length of the signature. Sincesignature_message_fragmentis of the fixed size, ifSL>1then the transaction has to be split to be able to accommodate full signature. - The last transaction
current_index=3moves unspent tokens to the first unused address of the given seed.
The following tasks have to be done behind the curtain in addition to the standard transaction preparation process:
- Search for address(es) with some balance until total amount of tokens available is large enough to be spent. You can use more input addresses if needed
- If there would be some unspent amount of tokens then also search for the first unused address
- Spending transactions (Input TX) has to be properly signed and split in case of
SL>1 - There is also some quick check performed whether resulting number of tokens is zero (no more tokens, no less tokens. Number of tokens has to be balanced).
So basically all steps we tried in the chapter had to be done also behind the curtain while using send_transfer extended API call. You can also see that some of those operations may be quite expensive in terms of time while being completely stateless. In real world applications it would be better to save some states (index of last address, used addresses, etc.) to avoid too many expensive operations.
You can review the given broadcasted transactions also in the tangle explorer (for devnet):