This textbook was generated automatically from a GitHub Repo. Visit the repo for more information.

IOTA Developer Essentials Banner

IOTA Developer Essentials

Languages Covered GitHub Repo GitHub Gist Interactive Lab Complete Textbook IOTA Ecosystem

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 and NodeJs. 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.

Languages Covered

IOTA Developer Essentials are accompanied by IOTA Developer Lab and so you can play with all code snippets directly in your web browser, please see the next chapter. Feel free to experiment with the prepared code snippets and get your hands dirty. It is a best way how to get familiar quickly.

Interactive Lab

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.

GitHub Gist

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.

Interactive Lab

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:

Complete Textbook

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


Thank You

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. There is a roadmap available. Your kind donations will support the vision pushing forward. Thank you.

Donations (IOTA): DSZRO9TCIJIKZOKUPVNOJFKVAHFCKL9YMLPVZUAEVZPOFXLIUWLPRQWBMVVSFTKGMGPPHXCYE9MIZEVBXQNFYKYUA9

qr code


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. Blockchain and Tangle comparison

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. Centralized, decentralized and distributed models

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:




 

var Converter = require('../../node_modules/iota.lib.js/lib/crypto/converter/converter') //loading helping converter functions of iota.lib.js library

var Trytes = "YZJEATEQ9JKLZ" //some data encoded in Trytes
console.log(Trytes)
console.log("Number of Trytes: %s" , Trytes.length)

var Trits = Converter.trits(Trytes) //converting Trytes to Trits

console.log(Trits.join(","))
console.log("Number of trits: %s", Trits.length) //Number of trits is three times the number of trytes obviously
YZJEATEQ9JKLZ
Number of Trytes: 13
1,-1,0,-1,0,0,1,0,1,-1,-1,1,1,0,0,-1,1,-1,-1,-1,1,-1,0,-1,0,0,0,1,0,1,-1,1,1,0,1,1,-1,0,0
Number of trits: 39

IOTA 101: Basic network interactions

The tutorial is based on official IOTA libraries called PyOTA and IOTA Javascript Library - iota.lib.js. It encapsulates all official IRI API calls and it can be installed via pip in a Python environment or via npm in a NodeJS environment. Reader is also encouraged to try a ready-made environment via IOTA Developer Lab project where anyone can run a code directly in 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 implementation details slightly differ across different programming languages. Top-level details are the same regardless programming language you are going to use for your project.

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 called Deviota Field. It is a load ballancer and incentivizer that provides you an access to a pool of participanting nodes (thousands of 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.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota'); // load iota.lib.js

// # ctor initialization of the iota.lib.js library
var iota = new IOTA({
    'provider': 'https://field.deviota.com:443'
});

// basic API call to double check health conditions
iota.api.getNodeInfo(function (error, success) {
    if (error) {
        // unable to perform getNodeInfo call
        console.error(error);
    } else {
        // result is printed out
        console.log(success);
        
        // Basic check whether node is in sync or not
        // Elementary rule is that "latestMilestoneIndex" should equal to "latestSolidSubtangleMilestoneIndex" or be very close
        if (Math.abs(success['latestMilestoneIndex'] - success['latestSolidSubtangleMilestoneIndex']) > 3) {
            console.log('\r\nNode is probably not synced!');
        } else {
            console.log('\r\nNode is probably synced!');
        }
    }
});
{ appName: 'IRI',
  appVersion: '1.5.2',
  jreAvailableProcessors: 10,
  jreFreeMemory: 1607998768,
  jreVersion: '1.8.0_172',
  jreMaxMemory: 7874281472,
  jreTotalMemory: 3249537024,
  latestMilestone: 'ZETPSQANBJNDTHKUPZXOFRVPSEMXOIUEBWHFZVI9FFQHUWEGYLMYEFFQWGELAUZFWHYELAYBNTXOA9999',
  latestMilestoneIndex: 644707,
  latestSolidSubtangleMilestone: 'ZETPSQANBJNDTHKUPZXOFRVPSEMXOIUEBWHFZVI9FFQHUWEGYLMYEFFQWGELAUZFWHYELAYBNTXOA9999',
  latestSolidSubtangleMilestoneIndex: 644707,
  milestoneStartIndex: 590000,
  neighbors: 9,
  packetsQueueSize: 0,
  time: 1533050895397,
  tips: 7684,
  transactionsToRequest: 1,
  duration: 13,
  fieldPublicId: 'a92ed81c773eb6fe',
  fieldName: 'fieldtrip',
  fieldVersion: '0.1.6' }

Node is probably synced!

Please note: When using Deviota Field service then this type of check is quite useless since other API calls of yours may be served by different node that has not been checked obviously. On the other hand, the Field uses some smart techniques under the hood that should prevent you to use node that is not 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!




 

//based on https://gist.github.com/SteveFromTheOffice/c8448a09352337386f135a16bbb20d93
//modified by Petr Zizka
    
var GenerateSeed = function () {
    const length       = 81;                            // The length of the seed and int array.
    const chars        = "ABCDEFGHIJKLMNOPQRSTUVWXYZ9"; // The allowed characters in the seed.
    var result       = new Array(length);               // An empty array to store the seed characters.
    var randomValues = Buffer.alloc(length)
    
    // Generate random values and store them to array.
    crypto.randomFillSync(randomValues);
    
    var cursor = 0;                                     // A cursor is introduced to remove modulus bias.
    for (var i = 0; i < randomValues.length; i++) {     // Loop through each of the 81 random values.
        cursor += randomValues[i];                      // Add them to the cursor.
        result[i] = chars[cursor % chars.length];       // Assign a new character to the seed based on cursor mod 81.
    }
    return result.join('');                             // Merge the array into a single string and return it.
};

var NewSeed = GenerateSeed();
console.log(NewSeed);
console.log("Length: %s", NewSeed.length)
FDVZOYFGNXHGMHJOFONAWHTBFFWHTHTNONNKDLJIGASFJOU9TNUOFLIQ9AUX9NMTBJOLDWPHAZZRIMBDS
Length: 81

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.



 

// No code snippet available for the selected language: javascript

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)$$

Anatomy of IOTA address




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');

//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
var NodeURL = "https://field.deviota.com:443";

var MySeed = "WKQDUZTGFKSSLACUCHHLZRKZBHSDSCEBHKUPDLKFBQALEBKDMFRPUQGZRXAADPG9TSRTZGGBZOFRJCFMM";

var iota = new IOTA({
    'provider': NodeURL
});

//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

// Please note, it is async method - result is returned via callback function

iota.api.getNewAddress(MySeed,
    { "index": 0, "total": 3, "security": 2 },
    function (error, success) {
        if (error) {
            console.log("Error occured: %s", error);
        } else {
            console.log();
            console.log(success); //returned addresses are printed out
        }        
    });
[ 'HRLKBQUZAEB9HIVWJEWVDYQ9G9VRQXQAXR9ZWGBFQJKRPOPJYHGAT9LBEIE9RWRMUFSNLCWYHQGYAECHD',
  'XEXIDJJTANADOUBPWTCSPPRYYRTITRAHDEOZAEXWDPCYKUPTFMKVQM9KCPPLOCESFRGRVSIYZHXQZNYKC',
  'KY9DLZCHET9ATLMADPXGDVDYMPHKRKQPJZ9MB9HEIMMFCRRTNJIJIHPKGZNKKDTFMYPZRRQYAQKVAHMYX' ]

Needless to say, NodeURL is not important for this task at all. As mentioned earlier, some actions are purely done on client's side. This is one of them.

Anyway, in case of IOTA library (PyOTA or iota.lib.js) you can directly use an address generator component instead of the whole library. Outputs are equivalent in both cases.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');

var NodeURL = "https://field.deviota.com:443";
var MySeed = "WKQDUZTGFKSSLACUCHHLZRKZBHSDSCEBHKUPDLKFBQALEBKDMFRPUQGZRXAADPG9TSRTZGGBZOFRJCFMM";

var iota = new IOTA({
    'provider': NodeURL
});

//Please note, it is sync function
for (var i = 0; i < 3; i++ ) {
    var address = iota.api._newAddress(MySeed, i, 2, false);
    console.log(address);
}
HRLKBQUZAEB9HIVWJEWVDYQ9G9VRQXQAXR9ZWGBFQJKRPOPJYHGAT9LBEIE9RWRMUFSNLCWYHQGYAECHD
XEXIDJJTANADOUBPWTCSPPRYYRTITRAHDEOZAEXWDPCYKUPTFMKVQM9KCPPLOCESFRGRVSIYZHXQZNYKC
KY9DLZCHET9ATLMADPXGDVDYMPHKRKQPJZ9MB9HEIMMFCRRTNJIJIHPKGZNKKDTFMYPZRRQYAQKVAHMYX

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.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

//some IOTA address
var Adr = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW";

console.log("Original input excl. checksum address:");
console.log(Adr);
console.log("Length: %s", Adr.length)

var AdrInclCheckSum = iota.utils.addChecksum(Adr); //generate checksum
console.log("Input address including checksum:")
console.log(AdrInclCheckSum) // the last 9 trytes is the checksum
console.log("Length incl checksum: %s", AdrInclCheckSum.length)
Original input excl. checksum address:
CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW
Length: 81
Input address including checksum:
CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RWTHBIRSXTA
Length incl checksum: 90

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



 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

//address including checksum
var InputAddr = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RWTHBIRSXTA";

if (!iota.valid.isAddress(InputAddr) || InputAddr.length!=90) {
    console.log("Not valid input address given.");    
} else {
    console.log("Input address incl checksum:");
    console.log(InputAddr);

    console.log("Is it valid addr based on checksum? %s", iota.utils.isValidChecksum(InputAddr));
    console.log("Input address excl checksum:");
    console.log(iota.utils.noChecksum(InputAddr))    
}
Input address incl checksum:
CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RWTHBIRSXTA
Is it valid addr based on checksum? true
Input address excl checksum:
CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW

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 data
  • Address: It is IOTA address that is associated with the given transaction. Value indicates whether it is an address of a receiver or a sender
  • Tag: 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 approve
  • Timestamp: TX timestamp. It is actually UNIX timestamp (UTC) Creating TX in 5 steps

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.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

var MySeed = "HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA";
var TargetAddress1 = "CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9";
var TargetAddress2 = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW";

var NowIs = new Date() //get a actual date & time - just to have some meaningfull info

// preparing transactions
var pt = {
    'address': TargetAddress1, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a first message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL' //Up to 27 trytes
}

var pt2 = {
    'address': TargetAddress2, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a second message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL' //Up to 27 trytes
}

console.log("Created transaction objects - mandatory fields only:")
console.log(pt)
console.log(pt2)
Created transaction objects - mandatory fields only:
{ address: 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
  value: 0,
  message: 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBVABBEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA',
  tag: 'HRIBEK999IOTA999TUTORIAL' }
{ address: 'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
  value: 0,
  message: 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBVABBEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA',
  tag: 'HRIBEK999IOTA999TUTORIAL' }

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_index are set
  • Bundle hash is generated (Sponge function + normalization) and assigned to each transaction
  • signatureMessageFragment is bascially copy of message field in case of non-value transactions
  • PyOTA library also checks whether the data in message field 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.

$$BundleHash = fce(address, value, legacy tag, timestamp, current index, last index)$$

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.



 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

var MySeed = "HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA";
var TargetAddress1 = "CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9";
var TargetAddress2 = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW";

var NowIs = new Date(); 

var pt = {
    'address': TargetAddress1, 
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a first message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL'
};

var pt2 = {
    'address': TargetAddress2, 
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a second message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL999'
};

var bundle;

iota.api.prepareTransfers(
    MySeed,
    [pt,pt2],
    {},
    function (e, r) {
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            console.log("Generated bundle hash: %s", iota.utils.transactionObject(r[0]).bundle);
            console.log("List of all transactions in the bundle:");
            for (var i in r) {
                console.log(iota.utils.transactionObject(r[i]));
            }
            bundle=r;
        }
    }
);
Generated bundle hash: GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD
List of all transactions in the bundle:
{ hash: 'XOZAZREKXGHJKZFFGI9DFBLCAPMRRWRNER9ESCNCOFAA9GVSEDIWCUVLSJCWLUTEJDMJCIN99AAJMIUBP',
  signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  address: 'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
  value: 0,
  obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
  timestamp: 1531833342,
  currentIndex: 1,
  lastIndex: 1,
  bundle: 'GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD',
  trunkTransaction: '999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  branchTransaction: '999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  tag: 'HRIBEK999IOTA999TUTORIAL999',
  attachmentTimestamp: 0,
  attachmentTimestampLowerBound: 0,
  attachmentTimestampUpperBound: 0,
  nonce: '999999999999999999999999999' }
{ hash: 'QZBGGEATAJALRFMPUANRUSOGQJIXPFAECWTDXFMSDBAECRZEDONAONDGDHYQKQJ9GA9VUUQMCKBZNUAHD',
  signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  address: 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
  value: 0,
  obsoleteTag: 'WXIBEK999IOTA999TUTORIAL999',
  timestamp: 1531833342,
  currentIndex: 0,
  lastIndex: 1,
  bundle: 'GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD',
  trunkTransaction: '999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  branchTransaction: '999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  tag: 'HRIBEK999IOTA999TUTORIAL999',
  attachmentTimestamp: 0,
  attachmentTimestampLowerBound: 0,
  attachmentTimestampUpperBound: 0,
  nonce: '999999999999999999999999999' }

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.



 

console.log(bundle);
[ 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW999999999999999999999999999HRIBEK999IOTA999TUTORIAL999FHEKTZD99A99999999A99999999GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999HRIBEK999IOTA999TUTORIAL999999999999999999999999999999999999999999999999999999999',
  'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9999999999999999999999999999WXIBEK999IOTA999TUTORIAL999FHEKTZD99999999999A99999999GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999HRIBEK999IOTA999TUTORIAL999999999999999999999999999999999999999999999999999999999' ]

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.



 

var gta;
iota.api.getTransactionsToApprove(
    3,
    null,
    function (e, r) {
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            console.log(r);
            gta=r;
        }
    }
);
{ trunkTransaction: 'BVLJJASHPJBVREAKYZHANSZU99HUJKRNWRHD9IUHOAVLFDBJGNAZPBUNIGEOSGOCUYVYTXKCUAQXA9999',
  branchTransaction: 'TZDQHHYAELIGG9KZVGBPOFNDGTIXELQZTCNGN99ATTRAKULUXAAMLAQJAHTQJTEEJXNVCORECCHWZ9999',
  duration: 1659,
  fieldPublicId: '48fb519c27e0a687',
  fieldName: 'TingleTangleServer',
  fieldVersion: '0.1.6' }

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 nonce and transaction hash are calculated per each transaction
  • Trunk and Branch tips are correctly mapped among transactions within the bundle. Check that trunk of the first TX refers to the second TX, etc.


 

console.log("Performing POW...Wait please...");

var att;
iota.api.attachToTangle(gta['trunkTransaction'],
                        gta['branchTransaction'],
                        14,
                        bundle,
                        function (e, r) {
                            if (e) {
                                console.log("Something went wrong: %s", e);
                            }
                            else {
                                console.log(r);
                                att = r;                                    
                            }
                        }
                  );
Performing POW...Wait please...
[ 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9999999999999999999999999999WXIBEK999IOTA999TUTORIAL999FHEKTZD99999999999A99999999GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJDZUZZWZYQFHYBZIMMGYZSXYSDMB9MRKQQLLYWXPRUDXWHKJEMCWSXKERISUBWVAEWEVQUNPVHHLVOZ9999BVLJJASHPJBVREAKYZHANSZU99HUJKRNWRHD9IUHOAVLFDBJGNAZPBUNIGEOSGOCUYVYTXKCUAQXA9999HRIBEK999IOTA999TUTORIAL999CWOVCYLKE999999999MMMMMMMMMYZWWAMKZXP9KVWKNQVMEUSFHORV',
  'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW999999999999999999999999999HRIBEK999IOTA999TUTORIAL999FHEKTZD99A99999999A99999999GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJDBVLJJASHPJBVREAKYZHANSZU99HUJKRNWRHD9IUHOAVLFDBJGNAZPBUNIGEOSGOCUYVYTXKCUAQXA9999TZDQHHYAELIGG9KZVGBPOFNDGTIXELQZTCNGN99ATTRAKULUXAAMLAQJAHTQJTEEJXNVCORECCHWZ9999HRIBEK999IOTA999TUTORIAL999RDLUCYLKE999999999MMMMMMMMMBZFZLOLXIROMWKWOAPVFKVN9EPK' ]

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)
console.log("Final bundle including POW and branch/trunk transactions:");
for (var i in att) {
    console.log(iota.utils.transactionObject(att[i])) //Let's print attributes of each TX
}
Final bundle including POW and branch/trunk transactions:
{ hash: 'WSXRCNWLVGWJVOVORHVHKLQCUTMNGBSHKLWVRCVHWEFSAOSZTESATIJYPLCUTPRSEOZPORGVPKLMA9999',
  signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  address: 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
  value: 0,
  obsoleteTag: 'WXIBEK999IOTA999TUTORIAL999',
  timestamp: 1531833342,
  currentIndex: 0,
  lastIndex: 1,
  bundle: 'GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD',
  trunkTransaction: 'ZUZZWZYQFHYBZIMMGYZSXYSDMB9MRKQQLLYWXPRUDXWHKJEMCWSXKERISUBWVAEWEVQUNPVHHLVOZ9999',
  branchTransaction: 'BVLJJASHPJBVREAKYZHANSZU99HUJKRNWRHD9IUHOAVLFDBJGNAZPBUNIGEOSGOCUYVYTXKCUAQXA9999',
  tag: 'HRIBEK999IOTA999TUTORIAL999',
  attachmentTimestamp: 1531833402747,
  attachmentTimestampLowerBound: 0,
  attachmentTimestampUpperBound: 3812798742493,
  nonce: 'YZWWAMKZXP9KVWKNQVMEUSFHORV' }
{ hash: 'ZUZZWZYQFHYBZIMMGYZSXYSDMB9MRKQQLLYWXPRUDXWHKJEMCWSXKERISUBWVAEWEVQUNPVHHLVOZ9999',
  signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEACCIDTCEATBID9DEAVAABEAWAUAVABBEAVAZADBVAZADBYAWAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
  address: 'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
  value: 0,
  obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
  timestamp: 1531833342,
  currentIndex: 1,
  lastIndex: 1,
  bundle: 'GDTWCVGFQCLKTXKBTSFRYSSAYTIZLUZCBRKVGGIEBCHCBUYEGWGTGBUYJFTA9WWNKQTCGZUFEJSLQAAJD',
  trunkTransaction: 'BVLJJASHPJBVREAKYZHANSZU99HUJKRNWRHD9IUHOAVLFDBJGNAZPBUNIGEOSGOCUYVYTXKCUAQXA9999',
  branchTransaction: 'TZDQHHYAELIGG9KZVGBPOFNDGTIXELQZTCNGN99ATTRAKULUXAAMLAQJAHTQJTEEJXNVCORECCHWZ9999',
  tag: 'HRIBEK999IOTA999TUTORIAL999',
  attachmentTimestamp: 1531833400764,
  attachmentTimestampLowerBound: 0,
  attachmentTimestampUpperBound: 3812798742493,
  nonce: 'BZFZLOLXIROMWKWOAPVFKVN9EPK' }

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.



 

//broadcast and store
console.log("Broadcasting transaction...");
iota.api.storeAndBroadcast(
                           att,
                           function (e, r) {
                               if (e) {
                                   console.log("Something went wrong: %s", e);
                               }
                               else {
                                   console.log(r);
                               }
                           }
                        );
Broadcasting transaction...
{ duration: 31,
  fieldPublicId: '19d64160036f36aa',
  fieldName: 'cr4zys4m_Node3',
  fieldVersion: '0.1.6' }

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.

Different API calls

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.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

var MySeed = "HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA";
var TargetAddress1 = "CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9";
var TargetAddress2 = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW";

var NowIs = new Date(); //get a actual date & time - just to have some meaningfull info

// preparing transactions
var pt = {
    'address': TargetAddress1, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a first message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL' //Up to 27 trytes
};

var pt2 = {
    'address': TargetAddress2, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a second message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL999' //Up to 27 trytes
};


console.log("Preparing/Broadcasting... Wait please...");

// please note, it is async call
iota.api.sendTransfer(
    MySeed,              // Seed
    3,                   // Depth
    14,                  // MWM
    [pt, pt2],           // list of transactions
    function (e, r) {    // callback function
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            console.log("\nList of all transactions in the bundle:");
            console.log(r); // results if it went OK
        }
    }
);
Preparing/Broadcasting... Wait please...

List of all transactions in the bundle:
[ { hash: 'TLCTPZOCZSK9RQLUPYWYVJUSSUUEWVRSILNSN9YDYG9OSNFFRCDTYIIS99WCMDFIVLWJALIJPRGWA9999',
    signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBUAZADBUAZAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
    value: 0,
    obsoleteTag: 'ZUIBEK999IOTA999TUTORIAL999',
    timestamp: 1532099105,
    currentIndex: 0,
    lastIndex: 1,
    bundle: 'X9KUYEKYTBTDYQZXSZYTZCIBJGQVLPAQTLWXUGGKTACFYQGYNECDKSFQUEINDCSDHIPWKBQKJLLLBZZWW',
    trunkTransaction: 'JSLHDIYWYFXCEW9KCURQQWTJIUXUWRZLMNMARCLGEGNGTHMCHJXCOEQBPHCV9WTJWTRKHMWYQXMD99999',
    branchTransaction: 'DKYNISHTTTZJNATCEVRLFLETRTBFZWYS9PLNNYKDNVWLLFQVCFEKCLXYPQSSUTPA9ZJISHZF9OTAZ9999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532099116633,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'WXCAAJPERTABGGXQMXNRBVYMPSW' },
  { hash: 'JSLHDIYWYFXCEW9KCURQQWTJIUXUWRZLMNMARCLGEGNGTHMCHJXCOEQBPHCV9WTJWTRKHMWYQXMD99999',
    signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBUAZADBUAZAEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
    value: 0,
    obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
    timestamp: 1532099105,
    currentIndex: 1,
    lastIndex: 1,
    bundle: 'X9KUYEKYTBTDYQZXSZYTZCIBJGQVLPAQTLWXUGGKTACFYQGYNECDKSFQUEINDCSDHIPWKBQKJLLLBZZWW',
    trunkTransaction: 'DKYNISHTTTZJNATCEVRLFLETRTBFZWYS9PLNNYKDNVWLLFQVCFEKCLXYPQSSUTPA9ZJISHZF9OTAZ9999',
    branchTransaction: 'DKYNISHTTTZJNATCEVRLFLETRTBFZWYS9PLNNYKDNVWLLFQVCFEKCLXYPQSSUTPA9ZJISHZF9OTAZ9999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532099110026,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'BBXUTZXGTMKGIIEUOHTRHAKZKQT' } ]

And to complete the picture here is addtional code that uses prepare_transfer() and send_trytes() combo.




 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');
var NodeURL = "https://field.deviota.com:443";

var iota = new IOTA({
    'provider': NodeURL
});

var MySeed = "HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA";
var TargetAddress1 = "CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9";
var TargetAddress2 = "CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW";

var NowIs = new Date(); //get a actual date & time - just to have some meaningfull info

// preparing transactions
var pt = {
    'address': TargetAddress1, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a first message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL' //Up to 27 trytes
};

var pt2 = {
    'address': TargetAddress2, //81 trytes long address
    'value': 0,
    'message': iota.utils.toTrytes('Here comes a second message. Now is ' + NowIs),
    'tag': 'HRIBEK999IOTA999TUTORIAL999' //Up to 27 trytes
};

// Creating bundle, preparing inputs and finalizing bundle. It returns trytes of prepared TXs
var trytes;

iota.api.prepareTransfers(
    MySeed,               // Seed
    [pt, pt2],            // List of transactions
    {},                   // Options - security level / Inputs in case of value TXs, etc
    function (e, r) {     // Callback
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else { // Bundle is prepared
            trytes = r;
            console.log("Almost prepared bundle - tips and POW are still missing");
            console.log(trytes);
            console.log("Searching for tips and performing POW... Wait please...");
            iota.api.sendTrytes(
                trytes, // Trytes of prepared bundle from previous API call
                3,      // Depth
                14,     // MWM
                function (e, r) { // callback
                    if (e) {
                        console.log("Something went wrong: %s", e);
                    }
                    else { // if went OK, then it returns broadcasted TXs
                        console.log("Bundle was broadcasted.");
                        console.log("Final transactions were returned - including nonce (POW)");
                        console.log(r);
                    }
                }
            );
        }
    }
);
Almost prepared bundle - tips and POW are still missing
[ 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBWAWADBUAABEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW999999999999999999999999999HRIBEK999IOTA999TUTORIAL999DGTYUZD99A99999999A99999999GSGJVTEZNFEBIHYTYGGHBFOQPBPJRZUHT9UWI9LCIYNCRQUAJFCUZGLHPBJIQWVUXEYOCGZJHLVDTZTCW999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999HRIBEK999IOTA999TUTORIAL999999999999999999999999999999999999999999999999999999999',
  'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBWAWADBUAABEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9999999999999999999999999999ZTIBEK999IOTA999TUTORIAL999DGTYUZD99999999999A99999999GSGJVTEZNFEBIHYTYGGHBFOQPBPJRZUHT9UWI9LCIYNCRQUAJFCUZGLHPBJIQWVUXEYOCGZJHLVDTZTCW999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999HRIBEK999IOTA999TUTORIAL999999999999999999999999999999999999999999999999999999999' ]
Searching for tips and performing POW... Wait please...
Bundle was broadcasted.
Final transactions were returned - including nonce (POW)
[ { hash: 'LBOVLFUAYVYLZASJCDANPWRJMMBEHOUCTHTYHHDUKRYYVQTYGGCVKTIWBNXQLYKXLKUAOEVLMKVFA9999',
    signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAUCXCFDGDHDEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBWAWADBUAABEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
    value: 0,
    obsoleteTag: 'ZTIBEK999IOTA999TUTORIAL999',
    timestamp: 1532100127,
    currentIndex: 0,
    lastIndex: 1,
    bundle: 'GSGJVTEZNFEBIHYTYGGHBFOQPBPJRZUHT9UWI9LCIYNCRQUAJFCUZGLHPBJIQWVUXEYOCGZJHLVDTZTCW',
    trunkTransaction: 'TUAPGOKJSCBYSNGOBZKFCLNTXWAEDQYYKAKFCJGT9PHXXZSFZUQPMDEZPPYFLEGLUYDVIVLDW9MSA9999',
    branchTransaction: 'KSLXDYOXNWF9XBJ9NIDTQWDSBFUGQVCHAYQRKCHTM9PELHYDDFNVWZMGTFPH9FAGHFYEVNNJCLHQ99999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532100135187,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'IAMBQKZERMTVMQIEEEDQVNNBFBE' },
  { hash: 'TUAPGOKJSCBYSNGOBZKFCLNTXWAEDQYYKAKFCJGT9PHXXZSFZUQPMDEZPPYFLEGLUYDVIVLDW9MSA9999',
    signatureMessageFragment: 'RBTCFDTCEARCCDADTCGDEAPCEAGDTCRCCDBDSCEAADTCGDGDPCVCTCSAEAXBCDKDEAXCGDEAPBFDXCEATBID9DEAWAUAEAWAUAVABBEAVAABDBWAWADBUAABEAQBWBCCPAUAWAUAUAEAMAMBOBBCCCNA9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
    value: 0,
    obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
    timestamp: 1532100127,
    currentIndex: 1,
    lastIndex: 1,
    bundle: 'GSGJVTEZNFEBIHYTYGGHBFOQPBPJRZUHT9UWI9LCIYNCRQUAJFCUZGLHPBJIQWVUXEYOCGZJHLVDTZTCW',
    trunkTransaction: 'KSLXDYOXNWF9XBJ9NIDTQWDSBFUGQVCHAYQRKCHTM9PELHYDDFNVWZMGTFPH9FAGHFYEVNNJCLHQ99999',
    branchTransaction: 'GIGXZYNPJPSXVIYYAMEQQXUDTXGSVQHTFTIEQLUKKZGOAPBAVZTHKJGJTI9FGDZOMWIWHTPCIKTJ99999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532100130651,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'WFWBMPGEXQ9IYHSBRWFCDDDPWQL' } ]

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 value field. They usually refer to senders
  • Output TXs: those are transactions that adding (receiving) value to address(es). Those transactions have positive value field. They usually refer to recipients
  • Unspent/change TX: technically speaking it is also output transaction that adding value however it usually refers to senders and 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. Never reuse address

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:



 

// Sender's side ***********
// Sender's seed
var SeedSender = "HGW9HB9LJPYUGVHNGCPLFKKPNZAIIFHZBDHKSGMQKFMANUBASSMSV9TAJSSMPRZZU9SFZULXKJ9YLAIUA"

// Receiver's side ***********
// Recipient's seed - this is actually not needed for the exercise - it is just to have corresponding seed somewhere written
var SeedReceiver = "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)
var AddressReceiver = "BMFSMZMNBGKHAWPIZIOMJGRBXZETVSAYDSTDQCHLYTBWZMIXLNXF9XHLTMOCATFVFOMBQF9IOQGPEBPDC"

// DevNet node - Devnet Tangle that is used only for testing / dev purposes - no real tokens here: (
var DevnetNode = "https://nodes.devnet.iota.org:443"

console.log("Variables were initialized.")
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:



 

var IOTA = require('../../node_modules/iota.lib.js/lib/iota');

var iota = new IOTA({
    'provider': DevnetNode
});

console.log("Checking for total balance. This may take some time...")

var usedadr;
// now we can find out whether there are any tokens left
iota.api.getAccountData( //Get the total available balance for the given seed and all related used addresses
    SeedSender, // Sender's seed - library will do all hard work based on the seed
    {
        "start": 0, // Library will start from the address at index 0
        "security": 2 // Default security level
    },
    function (e, r) {
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            usedadr=r;
            console.log("\nPlease note, this may take some time if many addresses has been used already...");
            console.log(r);
            if (r["balance"]) {
                console.log("\nYes, there are some tokens available! hurray");
                // there are quite usefull info returned - all addresses used plus first unused address
            }
        }
    }
);
Checking for total balance. This may take some time...

Please note, this may take some time if many addresses has been used already...
{ latestAddress: 'WFKSIELWXIK9KKBOY9IDRWJPJSSMAEWTPAG9TDBLYLMKDCCRESEWXEMQKXDDYLYTGQIZEYXMYJXFBPXIW',
  addresses: 
   [ 'CXDUYK9XGHC9DTSPDMKGGGXAIARSRVAFGHJOCDDHWADLVBBOEHLICHTMGKVDOGRU9TBESJNHAXYPVJ9R9',
     'CYJV9DRIE9NCQJYLOYOJOGKQGOOELTWXVWUYGQSWCNODHJAHACADUAAHQ9ODUICCESOIVZABA9LTMM9RW',
     'UJCAVPMFHTAHMTVKGCRBKEKXYRPAFFLGHLAWHISFLWUPEXXQAWRZUSFMYPPTIUANFQMKPLTTCLAWDIUY9',
     'WMPTNPCWTVBYSEBJUCRZZIINYEUCDCTWWRVZBJPMYUPRFEEJRRDUJGXE9NYGGZMSXJUJHUISFSCWGPLJZ',
     'IFLULNLIIGWGV9OBDBZT9JHPVLITVOMRMAUOCGPGMIIEQABQANJTBQ9PLPSFRR9BTCOJGE9ZWIZAXCRAW',
     'LHPLHEZNT99XRSCPMQ9XOCIRUYOKVBLTNUVQPZCTMWOM9WHVYPFKGTFQ9MNEPSYKIV9MNPNEKLMLZONHW',
     'QDCWBZCONHEXBGNTUBXCUGM9BUEBEZODVNYKZYBJPQXUVHFHMJPMNTYLWDFFMWHH9RIKABAJVRSIE9GWD',
     'NUCUUHYYGHCHMFWYSHULQTDP9IPWNNMQTMPDRUWKPNLOTTR9LHCEJPXIBTUTEFGGVAC9L9KQKXBGWGLYW' ],
  transfers: 
   [ [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ],
     [ [Object], [Object], [Object], [Object] ] ],
  inputs: 
   [ { address: 'NUCUUHYYGHCHMFWYSHULQTDP9IPWNNMQTMPDRUWKPNLOTTR9LHCEJPXIBTUTEFGGVAC9L9KQKXBGWGLYW',
       keyIndex: 7,
       security: 2,
       balance: 940 } ],
  balance: 940 }

Yes, 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
// This step is not required in case of NodeJS library, please see result above

console.log("\nPlease note, this may take some time if many addresses have been used already...");

iota.api.getNewAddress(
    SeedSender,   // Sender's seed - library will do all hard work based on the seed
    {
        "security": 2,
        "total": null  // If null is specified, then it identifies a first non-used address
    },
    function (e, r) {
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            console.log("\nThis is the first unused address that can be used for new tokens or unspent tokens:");
            console.log(r);
        }
    }
);
Please note, this may take some time if many addresses has been used already...

This is the first unused address that can be used for new tokens or unspent tokens:
WFKSIELWXIK9KKBOY9IDRWJPJSSMAEWTPAG9TDBLYLMKDCCRESEWXEMQKXDDYLYTGQIZEYXMYJXFBPXIW

What have just happened behind the curtain?

  • The PyOTA library started to generating addresses from the index=0 of 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 balances after 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

if (usedadr['addresses'].length > 0){
    // it returns the balances as a list in the same order as the addresses were provided as input.       
       iota.api.getBalances(
           usedadr['addresses'], // list of addresses
           100, // Confirmation threshold; official docs recommend to set it to 100
           function (e, r) {
                if (e) {
                    console.log("Something went wrong: %s", e);
                }
                else {
                    console.log("\nSome positive balance identified. Individual confirmed balances per used addresses:");
                    console.log(r);
                }
            }
       )
}
else
{
    console.log("\nNo positive balance identified.");
}
Some positive balance identified. Individual confirmed balances per used addresses:
{ balances: [ '0', '0', '0', '0', '0', '0', '0', '940' ],
  references: 
   [ 'SAZUYWDRIQIRFIRAC9ZPPMULWMVFEH9FEQYWAONPBIX9WOZWMMJVTBKQPBRVHBCNVLFRKEGRMNQUKM999' ],
  milestoneIndex: 678619,
  duration: 0 }

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:



 

var tx1 = {
    'address': AddressReceiver, //81 trytes long address
    'value': 10,    
    'tag': 'HRIBEK999IOTA999TUTORIAL' //Up to 27 trytes
};

// Sending the iotas
console.log("\nSending iotas... Please wait...");

iota.api.sendTransfer(
    SeedSender, //Sender's seed
    3, //depth
    9, // MWM; in case of Devnet it is 9
    [tx1], // one transaction defined above.It is an output TX that adds tokens
    {
        "inputs": null, // you may be wondering why there is imputs = None and change_address = None.
        "address": null // It means it will be taken care by library and so make sure correct seed / security level was added while api initialization
    },
    function (e, r) {
        if (e) {
            console.log("Something went wrong: %s", e);
        }
        else {
            console.log("\nIt has been sent.Now let's see transactions that were sent:");
            console.log(r);
        }
    }
);
Sending iotas... Please wait...

It has been sent.Now let's see transactions that were sent:
[ { hash: 'KJYIXIZZDWEXR9FHPPJDFRSWXFV99LEAIZ9ETCNKXTQDBUSUJ9ADWAFQPDMCZNT9THMBVWFNGJDZJD999',
    signatureMessageFragment: '999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'BMFSMZMNBGKHAWPIZIOMJGRBXZETVSAYDSTDQCHLYTBWZMIXLNXF9XHLTMOCATFVFOMBQF9IOQGPEBPDC',
    value: 10,
    obsoleteTag: 'KVIBEK999IOTA999TUTORIAL999',
    timestamp: 1532288466,
    currentIndex: 0,
    lastIndex: 3,
    bundle: 'GYONBWHJHIWJWOLACQDHFCLBLOZLLVKLGGSABZIIBDP9NXLRSTE99YQHZIA9EUJULLPBHCDPPBFXHHIFW',
    trunkTransaction: 'MXAJYNLNECHMYRCCD9IO9B9REDAKBUHERTUWFFXOMVSZZTSKDQVBLZNCCRXYJCRSSBABTDZMNMDHPV999',
    branchTransaction: 'DOPUA9POHVEODXUOZMIKRGGXKCDPHVXFB9NEOAHSJIVHCIHLDQFTSPSYRMFWSXXBAMV9PAVVSYWVAO999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532288482035,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'VFOPUMNNV9SMBFXRQDSHMLIEJYV' },
  { hash: 'MXAJYNLNECHMYRCCD9IO9B9REDAKBUHERTUWFFXOMVSZZTSKDQVBLZNCCRXYJCRSSBABTDZMNMDHPV999',
    signatureMessageFragment: 'CA9PESLGKXJUIQRSCIE9CMSFEL9CKDYRYSPVHQDBNGIBABG9QLQJJWRQCKNQZOEIVWFRVAUTOTJEGPXKCKHBXKDELWNKLTYHEDNOEKYL9UMJD9JLQTCKTUYVZSRSBWRZDMIUOUTUMEXBMMZNJAGUVCNLCIDDO9FVU9CLMGOBNY99NVKWZONMCFCNCAWWBSGQYKGIWCMSMWZPWL9UJBMGQRFNOHILSRXOLMUMAILT9NU9UOMOYZXXYIMOJPYNPODZSWVEESYQUREHAESUK9LNYVNAPUULE9WAHFLGFFDMCHWSIRPCAKXHFVFLIPOIAHBHYDWDBORONHKTXACHTUUPHOWDQZVTFDROZPNMLQFYQNMEYIJJHD9XDKQATICNOBLKKMTCUR9ITCPNC9ENQIMECFBD9XBLXB9RACAWZGOZIBNTZKMGXXRCQYKYJVXKTMMFUFMP9NWLEUPOUOCOQZCTFGFIJOZDLJDFYDYGNYP9CDYSTTBKCJFMDCIKYLGTETTUKYLYPVUWGGGLRGENBKTDGPWSDWW9YZZGXAWNGYXBFKOUJAUQTRQOOCXPVLJMQUF9QPYMJXBXDGOG9YCGESCPEQUL9MLWZCENNLBFJQUEOKOJUNRVSUKYBHD9TRWNQIUWWWKITVMDGP9NIR9TUXSXELZSPACZCYO9YHVB9SKFSDJMXV9JHNXWIQVUMUIMFYQSYZSSTXZLDFJ9BECMXBQWEZQBWCVPTPIRVPFSKTNSD9QZGBRMBRSUWSPBHOKW9JSJEJCJRFCPUTHNDRUPDHDGLSMUPLQIOPILASXEYWNMKYWVOJVDSAMACHTNMPCFPAVEXVWBZIIQRVADCLYXRNQYIESSAZHCPINJJKHJSDWSTMLFUCZTMDSN9MZU9PYEDMMHKZGHJHPQRXOLCHOYXPDTEBXOVEKAQDAAWSJNYKMUTYI9PNZFUQZIGHVOIJZNFNOUWMAXNCWUTSGYUZUBVDXANNKWAKJJYTSMCVNHLHJCBPFOFVUT9UVBBRMMLZRFZEIWAMTYERJAFMDCXYUWCJHNWUWTPMPAARVVJLSEORWQOQKGCJEGAKPWCJYAGPQPPVKMDRTYUWOBPPQIWPSU9APDWMMLWPKQJFAYZQZWFXYIZZLHWDGOAB9XNXQWFOEABFNMBXXMDFHGOBCLZAGAOTSREUEQCVGXOARLJROMWZEKWTWIVOTZAVFJCLHJJUTRESALZLCIKBHTCFS9NFJE9RRPZQDVDBLZXCFEKHVZQWQECGRPVPVOQYCIWQLADICNAN9SLWKJMR9VXLWYSZFXRTUNAPGYPFNZSPPDVUVUYPJKLEPE9LOVQAUXGFYCRCMIERZZXFYXHQRZIBZRBNLSPNREYIUWMXBUYAJXCPJNPGBNAJGZVPQHZCTHNYQYKRSWQOITHEKGKSFFNWSEXMRRSZ9BUTJQJPDGGVMFIZUCVXMQWNDFUYPAADLCWFPVKVDNJO9WPBXRTVFNDJNNIQKXNYTJNHGIOZAKZKHIV9DAROYCIPRHYTUTRBVRHZOTNLOSCHXRAIWSCX9GHIEIFECUPATKHITFGMUQFMUVIABQDFVUMLBBGWKHKPSBWIPH9KMGRNUSOGRHDBUEBTXS9EIJ9BNWNJRIDFSSBBCBDI9ATADYJXZHWRCOHOFKZG9XINPFNIATUQHPEWABLFLUHVTZZ9QXGPLHT9VYXNQJZWQOYBGVKFPQUIGHPCERGJ9DMM9QRHBWJWEIQHTGTNKKY9KEHQGF9DOGTIVKGAGGSCTGVVMGDSOTXD9WXVLTBDDTKVWZXCWUHHGTSTCULHJCIMCKHCQIZWWFCECDNDTVFNRXNWDLS9WIUWUKXHBAAGNCXOCJVJDJXFKGSKWOQKQYWMJSLTZ9XEVPPOFCYIESCPCDVCIIDKAWQJPWVPTWJJGFSEPZTZBWYLLZRWWVQWJDDHYOQTX9ELBWTRJAYZXQ9LJRNS9YOTI9HHLBRAF9W9BTKNEPODHAXRMSAIWSLGJOGFAVYFRGXKDA9PHFUIRMIAZKHCCN9GKGQWX9OELBSALRVMAMAZVUTTDEVWXVKYJFEKYPZPLPMG9PQZJJLOBTEFJMTYHMDGSJRNOMEIIJAKBHTYHFLKDUQKKQFCBW9ILXBPSYZGPOMAQOCEACMPLROFHOFYKS9ULXKKDQQYYEHCOCISDYRFLFSIOYRIWOYFD',
    address: 'NUCUUHYYGHCHMFWYSHULQTDP9IPWNNMQTMPDRUWKPNLOTTR9LHCEJPXIBTUTEFGGVAC9L9KQKXBGWGLYW',
    value: -940,
    obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
    timestamp: 1532288478,
    currentIndex: 1,
    lastIndex: 3,
    bundle: 'GYONBWHJHIWJWOLACQDHFCLBLOZLLVKLGGSABZIIBDP9NXLRSTE99YQHZIA9EUJULLPBHCDPPBFXHHIFW',
    trunkTransaction: 'AFQGBSQLODTUM9JFGWWWIFFJSVORGV9OKSCCKWGIPSVQHXAPWDZLGIGQTDCCBWZ9INIFWPUHFCHWVM999',
    branchTransaction: 'DOPUA9POHVEODXUOZMIKRGGXKCDPHVXFB9NEOAHSJIVHCIHLDQFTSPSYRMFWSXXBAMV9PAVVSYWVAO999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532288482006,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'MSONQZMNQZZSODFEFZRRMEDNSVQ' },
  { hash: 'AFQGBSQLODTUM9JFGWWWIFFJSVORGV9OKSCCKWGIPSVQHXAPWDZLGIGQTDCCBWZ9INIFWPUHFCHWVM999',
    signatureMessageFragment: 'DKAIZXXTJTJNDNKVIYKXERREQRZJJBXMWMRHAWMAMZMYLXSKVJBMINQ9ZSRRRNFAZSVJCFSRUURVLM9MXXIUXWZY9FUKNLFX9CFMMJJUXLLZN9TNTHSKZIHHGMBQIONYMZOXFGWEQQBULSJGCZDWWDPHLXP9WIPXDCMELPJHZAWNHUTBSMJLTHHERXRZZEDSIBOGVBKONZZPENYGJEFPFUXDFX9XOCBLZGKEWYTSSFRECTQBNTAHYDBNCCXEXMVRNKXMT9GSTFPOOA9PGXJ9VCPWVVHQGHQYPPIQDOONVKRRPOZZUQBVGSUCS9XEFQXKTUPDU9KTOXICTDMPEGYVJMANOQWQ9EJCFQGAPFOIVAVTH9CDNUHMBJHMSOIPFDVFLSTZPRRGKDEHYPA9CTICDZQSTPZMAGNAAIOXPJOASA9ETPTAZIUQKYGYTQT9BDSLDZUCIGOO9FCJDYPNIOIRRAGTLTOLJSEDCNLUJWUQXBLJWHFHGOIU9QFJPLLACWHAPPJNOGZECJELEJEXE9HE9KPTFIVKDENVBMJEVNSOLXHPR9TSOIUZELXPNYOAFWQWWAEUNPIVTMRXVFUKTVOQRY9CWZNWXJG9YDIJUICI9PVMXF9CNPR9DGFFYIMBDWSAUIPVW9PBQFZDSUZQNFXALBODYQGMLAYKPAAUZGOIIARGPAHUIKPHNQVFFTAPCBXMATJRSXVPETYF9YEFJ9GISFHI9UICCZMPIEWMXUAXWZPZVQOCTWVCVFNHYSICLINERJPJRTCTKVTBXENKZEEHXHHHY9Y9GFTBPQASABDPEBMUXXVWDONMPJYCCTZBPBFIXEJWBUSKVCZCDHBKVCKJCRLXUOJUFTKFYXPVSBAQQTJFJUOM9AVOAUXJVVCMOWODJWXGDGJYAEPALAOUMTFOLRBNBWFNNIZZGF9KNAHIBYNAMKPFSHJFGRPKPISVRTPJRGBGKNDAMUTZOTFI9BYQNJNTXJZFOO9AIJLRXYUKNWCIQWMTLEXZJMTANBWC9DVPYDIOSGWNKQOGSWK9PDHQVYUVPOVHAJJVPIXJI9JTEOEZMEEZLNDZJNFKTTCKVA9OMZWJFH9KDWC9YYFWRQCUOSAOGCPUE9XBQNLJVFFYOXXIXZCPKVQZHMFLZFVSYHQLU9JSTHHPDPXRUTAZSXBUANAUDAIDXPIVQDGWZPX9GSZJUSZDFZVYLW9UPYEYSNAQNRYUMTQPYZABNUSOMVPCWVRWOABLQHPNDGPKDXNPZYWKTCZXBWWKVOAFVAFHBWVGSHSU99MHTCJXUDPYOFB9JJTUVAIJHNEPEOVMWAALWBNDBLGPAYYWGEEQWKRWSLKM9AENIVHBNKVWUFNLHQQMBRMWZKBJFUC9XNQJAQONIMERONWEGMKJKXCZYXRUBVJTFIADTFPEOKJYJRFOPBGCQIEHKPJXGR9RTQPIYCM9QKVZDXGVUYZI9XDLQMGXIOS9ADCHW9VQUWOQDPUTGTXBCJXKJAHFSEXJJRWQEYKMCHYJSFBKYQ9SSSBKVGDXNLSLZMBWYUX9UYUBIIWZKWVJXTVHJ9JNNNNJRAVJVY9LPTPQKWZVYKUCJACEFTSGTEIBWDHJNDPVWYSXWPBCTAWCPQPQDPBOGVQYKPQYMMYRVDEQKRTMYHSBTHDYWXXEHZXJHNOGHUSBVFCJGFODBQZARBQJIDCRTDFYKIIHCQEJQDYKOGZHQOYRTSGNBKQXEBVFRNGSVXBDDWDKTFXNKRAYUWFPVSZXQUHEVOTDRZWHULBHIRXMNXFMWAUCZBVBITHSADHUXNQRXOAVIXNMJQERZKHXHXGENHYEP9EVOMGKEZHILLVZYGUJNKFFMGJFFTOVKYRSZDXKICI9BKOLWUAYXSWMILGLTPGHDNTACSCLKV9FJYRSPUMN9ZKWBZJLUOEIJ9SXTFPAGTCJLHKLEWOPCZKDYXQBUKDHIYRTKPUWXDNXAZEDICTRVFXECTARTVOPUMLENTSAOOKQXZOSOAEBWFJAXSPV9GIKNINSRDN9XVPIMLXQGDAFFFEXNVDRDXPCKAAPNLLGXQPEOOZHMCVEOXXSTDGSRUALHSWLWTMEHSPLVOGVSYBOQBASSWXBKCH9MLHNCOGDXDCCGJUUSYFNQPPNKSGQVCACM9YUNQUCWNF9XRNCC9SFSYKUBNNTRJKPINLFYWXTXAW',
    address: 'NUCUUHYYGHCHMFWYSHULQTDP9IPWNNMQTMPDRUWKPNLOTTR9LHCEJPXIBTUTEFGGVAC9L9KQKXBGWGLYW',
    value: 0,
    obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
    timestamp: 1532288478,
    currentIndex: 2,
    lastIndex: 3,
    bundle: 'GYONBWHJHIWJWOLACQDHFCLBLOZLLVKLGGSABZIIBDP9NXLRSTE99YQHZIA9EUJULLPBHCDPPBFXHHIFW',
    trunkTransaction: 'GILAEUK9GRPIVROOOSNL9IQGAVTVZCTFPG9UKGHFCKKBBOOGUOEMZW9TODKMYHPSKG9ZWWJPXDKKFO999',
    branchTransaction: 'DOPUA9POHVEODXUOZMIKRGGXKCDPHVXFB9NEOAHSJIVHCIHLDQFTSPSYRMFWSXXBAMV9PAVVSYWVAO999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532288481982,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'TXP9WJCDNXEDOUCSDCXQYSNQFGH' },
  { hash: 'GILAEUK9GRPIVROOOSNL9IQGAVTVZCTFPG9UKGHFCKKBBOOGUOEMZW9TODKMYHPSKG9ZWWJPXDKKFO999',
    signatureMessageFragment: '999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999',
    address: 'QA9ZICNXBIONYSVEARJNWSTVXWDGXFPHRWTHM9DQQTOEWIOYWNUGLYT9RPQL9GRMFWNT9TZO9ZYDEOVNX',
    value: 930,
    obsoleteTag: 'HRIBEK999IOTA999TUTORIAL999',
    timestamp: 1532288481,
    currentIndex: 3,
    lastIndex: 3,
    bundle: 'GYONBWHJHIWJWOLACQDHFCLBLOZLLVKLGGSABZIIBDP9NXLRSTE99YQHZIA9EUJULLPBHCDPPBFXHHIFW',
    trunkTransaction: 'DOPUA9POHVEODXUOZMIKRGGXKCDPHVXFB9NEOAHSJIVHCIHLDQFTSPSYRMFWSXXBAMV9PAVVSYWVAO999',
    branchTransaction: 'DOPUA9POHVEODXUOZMIKRGGXKCDPHVXFB9NEOAHSJIVHCIHLDQFTSPSYRMFWSXXBAMV9PAVVSYWVAO999',
    tag: 'HRIBEK999IOTA999TUTORIAL999',
    attachmentTimestamp: 1532288481966,
    attachmentTimestampLowerBound: 0,
    attachmentTimestampUpperBound: 3812798742493,
    nonce: 'OINHWRZDGHGGBPAIBS9ZKUUHO9H' } ]

Let's review all transactions that has been prepared and sent eventually:

  • The first transaction current_index=0 is the output TX that basically adds tokens to some address
  • Transactions current_index=1 and current_index=2 are two parts of the same transaction - Input TX. This transaction deducts tokens from the address(es). You can see negative value in the transaction current_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 different security levels were discussed? There are three security levels available and the given level has the direct impact on length of the signature. Since signature_message_fragment is of the fixed size, if SL>1 then the transaction has to be split to be able to accommodate full signature.
  • The last transaction current_index=3 moves 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):