Basic Concepts

Before diving into the API, it’s important to understand the fundamental data types of IOTA.

The official IOTA documentation site gives a good and in-depth explanation of the concepts used in IOTA. PyOTA documentation will try to give references to the official site wherever possible.

Ternary

IOTA uses the ternary numerical system to represent data. The smallest unit of information is a trit, that can have a value of -1, 0 or 1 in a balanced ternary system. A combination of 3 trits equals one tryte, therefore a tryte can have 3 * 3 * 3 = 27 different values.

To represent a tryte, IOTA encodes these 27 values into characters based on the tryte alphabet.

In PyOTA, trits are represented as a sequence of numerical values (List[int]) while trytes have their own class called TryteString.

IOTA token

The IOTA token is a unit of value that can be transferred over an IOTA network through transfer bundles.

The IOTA token was launched on the Mainnet in June 2017. At this point, the nodes in the network were hard-coded with a total supply of 2,779,530,283 277,761. This large supply allows each of the billions of devices, which are expected to be a part of the Internet of Things, to have its own wallet and transact micropayments with other devices.

Seed

Seed in IOTA is your unique password. It is the digital key that unlocks your safe that holds your tokens, or proves the ownership of messages.

Seeds in PyOTA are always 81 trytes long and may only contain characters from the tryte alphabet.

Warning

Treat your seed(s) the same as you would the password for any other financial service. Never share your seed with anyone, and never use online generators to create a seed. The library can help you to create your own locally and it does not require internet connection: iota.crypto.Seed.random().

For PyOTA-specific implementation details on seeds, see crypto.Seed.

Address

To send or receive any transaction (let them be zero-value or value transacitons) in IOTA, you will need to specify an address. An address is like a physical mailbox on your entrance door: anyone can drop things in your mailbox (send you messages or tokens), but only you can empty it (withdraw tokens).

Warning

Addresses should not be re-used once they are spent from. You can receive as many transactions to an address as you wish, but only spend from that address once.

Addresses are generated from your seed through cryptographic functions. There are 9⁵⁷ different addresses that one might generate from a seed, which is quite a lot. Given your seed, the index and security level parameters specify which address will be generated from it. The process is deterministic, meaning that same input paramteres always generate the same address.

Addresses are 81 trytes long and may contain extra 9 trytes for checksum. The checksum may be used to verify that an address is in fact a valid IOTA address.

For-PyOTA specific implementation details on addresses, see Address.

Transaction

A transaction is a single transfer instruction that can either withdraw IOTA tokens from an address, deposit them into an address, or have zero-value (contain data, a message, or a signature). If you want to send anything to an IOTA network, you must send it to a node as a transaction.

—from the official IOTA documentation site

Transactions are always 2673 trytes long and their structure is defined by the protocol. They can be classified into three categories:

• Input transaction: A transaction that withdraws tokens from an address.

• Output transaction: A transaction that deposits tokens to an address.

• Zero-value transaction: A transaction that has 0 value and might carry messages or signatures.

Depending on the type of the transaction, different fields are required to be filled.

A transaction’s unique identifier in IOTA is the TransactionHash, that is generated from the trytes of the transaction. If any trytes change in the transaction, the returning transaction hash would alter. This way, transaction hashes ensure the immutability of the Tangle.

To become accepted by the network, a transaction has to be attached to the Tangle. The attachment process means that the transaction should reference two unconfirmed transactions (tips) in the Tangle and do a small proof-of-work. This process might be performed by a node, or by using the local proof-of-work feature of the client libraries.

For PyOTA-specific implementation details on transactions, see Transaction and ProposedTransaction.

Bundle

A bundle is a group of transactions that rely on each other’s validity. For example, a transaction that deposits IOTA tokens into an address relies on another transaction to withdraw those IOTA tokens from another address. Therefore, those transactions must be in the same bundle.

—from the official IOTA documentation site

In other words, a bundle is collection of transactions, treated as an atomic unit when attached to the Tangle.

Note

Unlike a block in a blockchain, bundles are not first-class citizens in IOTA; only transactions get stored in the Tangle.

Instead, bundles must be inferred by following linked transactions with the same bundle hash.

Transactions in the bundle are linked together through their trunkTransaction fields, furthermore they are indexed within the bundle and contain a bundleHash field that is a unique identifier for the bundle.

Structure of a bundle with four transactions. Numbers in brackets denote (currentIndex, lastIndex) fields. Head of the bundle has index 3, while tail has index 0.

Read more about how bundles are structured.

Bundles can be classified into two categories:

• Transfer bundles: Bundles that contain input and output transactions. A bundle always has to be balanced, meaning that input transaction values should equal to output transaction values.

• Zero-value bundles: Bundles that contain only zero-value transactions.

For PyOTA-specific implementation details on bundles, see Bundle and ProposedBundle.

Now that you are familiar with some basic IOTA concepts, it is time to explore how PyOTA implements these and how you can work with them.