Getting started with Node.js and delion.io to use IOTA Tangle
Introduction
Some months passed since the first introduction of delion.io, the first Tangle-as-a-Service provider. Meanwhile we managed to stabilize and optimize the API to interact with the IOTA Tangle thanks to the valuable feedback from the community as well as startups and some corporates (which overwhelmed us a lot in a positive way!).
In our previous article we gave a rough outline on how delion.io works based on an example we call API-Splitting. We showed the role of delion.io which acts as a facilitator for app developers and consumers to leverage the potential of IOTAs Distributed Ledger called Tangle.
Today we are going to get our hands dirty and learn how to write some lines of code using Node.js to create, execute and check transactions on the Tangle using delion.io API.
Prerequisites
Installed and running latest stable version of Node.js
Code highlighting editor, we recommend using Visual Studio Code
Account on delion.io
Knowledge of Javascript + REST API + JSON
Familiarize with the developer docs of delion.io
Structure
The structure of this blog post is straightforward. We walk you through the single steps from the beginning to the end to complete a transaction.
- Signup
- Authorize
- Create Payment
- Execute Payment
- Check for Payment status
Getting started
To use the API it is necessary to have an account on delion.io, which handles all of the transaction management in the background for you. There is no need to know about Trits, Trytes, Nodes, Proof-of-Work, Addresses etc.
Signup
The signup to delion.io requires a unique email and a strong password. The password policy is as follows: minimum of 10 digits, at least 1 lower-case character, at least 1 uppercase character, at least 1 number and at least 1 symbol.
After signup, a confirmation email is sent to you. Click on the link within the email to complete the signup. If the mail does not arrive within 2 minutes, check your spam folder of your mail provider. If still no confirmation mail arrives, please let us know and send us an email to info@delion.io
Option 1: delion management console
This option refers to human centric signups, where you want to create an account for yourself or some devices for your smart home. Just go to https://console.delion.io/#/auth/register and you will see this screen.
Option 2: Via API
The API options allows to create accounts via batch or other automated processes. Below is a code example to achieve this.
Do not forget to complete the signup process by clicking on the link in the confirmation emails. Only then the account can be used.
Authenticate
After setting up the delion account properly, we can now head over to authenticate against the API to get an AuthToken which we have to use in the HTTP header of subsequent requests to the API.
Please note: The AuthToken is valid for 60 minutes only. It is therefore recommended to store the AuthToken in a database once it is newly generated and load it from there when needed. After expiration a new AuthToken must be generated.
If authentication is successful, we retreive an AuthToken which we now can use to create transactions with our account.
Create Transaction
Now having an AuthToken, there are two options to issue transactions which are described below. First, lets see how a general transaction object looks like:
A bit of explanation of every row:
3) Payment mode: currently only instant method available. The transaction will be eventually executed on the Tangle. Further payment modes are in active development :-)
4) remaining_time is the lifetime of a payment object after its creation in seconds. Set to minimum 10 seconds.
5) quick_validation: If true, the amount will be deducted from the account of the creator of this transaction. If false, the account which actually executes this payment object is debited (see Option 2b Execute a payment object)
12) transfer_type = internal means transfers to delion accounts. Transfers to external addresses are also possible. For security reasons they require an active Multi-Factor-Authorization (see delion management console -> Account Settings -> Security)
13) recipient_address: Either a delion account or a native IOTA address, depending on transfer_type (line 12)
18) Total amount of the transaction. It is the sum of lines 22 + 23
22 + 23) actual payamount and an optional fee (e.g. shipping costs/fees). The fee position is there for transparency if necessary. Otherwise we put the total amount in the payamount field.
26) description: optional, max length of 280 chars
29) two_factor_auth_code: always mandatory if transfer_type = external.
If transfer_type = internal and two_factor is activated and the amount exceeds the limits (you can set limits in the settings).
Option 1: Quick validation
This option presupposes that the recipient of a transaction is known by the payer, because it requires the recipients’ email address. Thus, the transaction can be executed immediately after creating it. In that case, the creator of the transaction is also the payer.
Please note line 33 when creating the payment object:
...
"quick_validation" : "true",
...When setting the quick_validation parameter to true, the remaining_time parameter is ignored at the same time. Instead, this transaction is executed right after submitting the API request.
Option 2a: Create a payment object
This option follows a different logic. Every account can create payment objects with predefined parameters such as total amount, remaining time to fill the transaction or a simple description.
But the execution of this payment object must be triggered separately either by a different entity or the creator of the object. In comparison to option 1 the creator of the transaction is not necessarily also the payer.
Think of it as an invoice for a service. Whoever takes that invoice and actually wants to consume the offered service can actively execute the transaction with their own account.
Example: In a checkout process for a digital service the merchant generates a payment object with all the details and returns a PAY-ID (form: PAYID-II-59FD6DBD963844B9C0ED65A63263B6B5 to the buyer. The buyer can now execute this payment object (see next chapter).
Please note: When a payment object is created, the account balance remains unchanged until the payment object is executed successfully (status = ended). We learn more about transaction status in the next chapter.
Option 2b: Execute a payment object
Now lets see how we can execute an existing payment object. The result of successfully creating a payment object is a PAYID.
Now we can share this PAYID with a different delion user, who wants to execute the transaction (see line 21).
It’s done. The transaction was submitted to the IOTA Tangle.
Check status
Last but not least we want to check the status of an executed transaction. We put the PAYID in line 18 and run the code:
The result of the API call returns the below JSON. Pay attention to the status field, which says “ended”. This means the transaction was processed successfully. Subsequent actions can now be triggered (shipping etc.)
Optional: Send notification emails
delion.io has a built-in email notification service that can be enabled if required. It triggers an email as soon as an event occurs (payment sent/received). Go to API Settings -> General -> Mail Notifications in the delion management console to adjust the settings.
Finish!
That’s it! We went through the whole process from signing up over authenticating, creating transactions and checking the status of a transaction.
From our experience and feedback the development time can be reduced significantly when prototyping an application based on IOTA Tangle using delion.io.
Try it out yourself and tell us about your experience. We’d love to hear from you. Leave a comment or get in touch with us on Twitter or Discord!
Additional remarks:
delion.io is independent from hard- and software manufacturers and thus can be implemented across different devices. That gives the flexibility of using IOTAs Distributed Ledger regardless of the platform it is running on. All it needs to run is being able to call API endpoints. You can assign a delion.io account to each of your devices and manage transactions.
For example it is possible to invoke other 3rd party APIs into the process, such as invoicing and E-Mail APIs to build powerful workflows.
We hope the code examples are clear and help you to get started with own application prototypes based on IOTA Tangle.
Thanks for reading and happy #buidling!
In case you need support, we are always happy to help. Get in touch through the below mentioned communication channels.
Support us
We hope you find our contribution to the IOTA Ecosystem valuable. As we develop delion.io in our spare time we’d like to share our IOTA donation adress with you in case you want to support us.
HMCHBKRHITLZXMAZGHGHHFHMNDI9IHSOLDLRYAXLHPPOUHFFABPLHU9XHYZUIMNEZVAUAHZJJYVYQDAOCUMCWKWSCY
Thanks!
Contact us
Helpful links
delion management console signup
delion website
delion github with code examples
delion developer docs
IOTA use cases worth spreading
Previous articles
How to connect your application to IOTA Tangle in 9 minutes
Set up IOTA payment gateway with a few lines of code
Send and receive IOTA by just using E-Mail addresses
IOTA: Tangle-as-a-Service with delion:api
Disclaimer
delion.io is not affiliated or part of the IOTA Foundation. We are focused on establishing a useful service for developers, startups and companies to help increase the adoption of IOTA Tangle as promising DLT.
