Skip to content
/ iota_lightnode.js Public

A high-level wrapper for the IOTA Javascript Library iota.lib.js

License

MIT license
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

DaMarkov/iota_lightnode.js

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

10 Commits
bin
bin
 
 
deb
deb
 
 
dist
dist
 
 
examples
examples
 
 
proxy-server
proxy-server
 
 
src
src
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 

Repository files navigation

IOTA Lightnode: a wrapper for the IOTA Javascript Library

iota_lightnode.js wraps the IOTA Javascript Library iota.lib.js and overs the following high-level features

  • Generate transaction list of bundles
  • Discovery of confirmed/rejected/pending bundles
  • Reconnect to next node after timeout
  • Proxy server with caching for faster syncing
  • Sign transactions offline (cold storage)
  • Supports ccurl and curl.js to do the proof of work locally
  • Detects if the node can perform the proof of work
  • Promotes transactions, detects if the sub-tangle is inconsistent and reattaches the bundle automatically if necessary
  • Supports pre-bundles for easier construction of complicated bundles

Installation

git clone https://github.com/DaMarkov/iota_lightnode.js.git
cd iota_lightnode.js
npm install

Getting Started

<script type="text/javascript" src="dist/iota_lightnode.browser.js"></script>
<script type="text/javascript" src="deb/curl.min.js"></script>

<script>

var lightnode = window.iota_lightnode.initializeIOTA();//initialize iota lightnode
lightnode.setCurlLibrary(window.curl);//Connect lightnode with curl to do the proof of work in the browser

var seed = lightnode.generateSeedInsecurely();//Generate seed (Seeds generated by this function are NOT cryptographically safe!)

lightnode.calculateFirstAddress(seed, function(error, new_address)//Generate the first address of this seed
{
    //Attach address to tangle
    var transfer = [{//Transfer to be attached to the tangle
        'address': new_address,//Recipient address (our own)
        'value': parseInt(0),//Number of IOTA to be transacted
    }];

    lightnode.sendTransfer(seed, transfer, function(error, attached_bundle)//Prepare bundle, do tip selection, perform proof of work and attach to tangle
    {
        if (error)//Either invalid transfer or node is down
        {
            console.error(error);
            console.log( "Error! Could not submit transaction! The node you are connecting to might be down." );
        }
        else//Success
        {
            console.log( "Successfully attached your transaction to the tangle with bundle", attached_bundle);
            console.log( "The transaction hash is: ", attached_bundle[0].hash );
        }
    });
});

</script>

The folder examples/ contains additional examples.

Structure

  1. bin/ contains the compiled version of ccurl for Windows/Mac/Linux 64-bit.
  2. deb/ contains dependencies used in examples. Most noticeable curl.min.js which is used to perform the proof of work in browser.
  3. dist/ iota_lightnode browser and node.js version as well as mnemonic.js to convert seeds in a readable format
  4. examples/ example files
  5. proxy-server/ proxy server using node.js. This server connects to a node and acts as a cache.
  6. src/ additional source code of iota_lightnode.js

Definition of objects

address

A address represents an address that has been generated by the seed. The address list can be retrieved by calling getAddresses.

var addressList = iota_lightnode.getAddresses();
addressList[0].address;//The public address of this address object as a string of 81 trytes (without checksum)
addressList[0].balance;//The balance is the confirmed balance if all currently pending transaction were confirmed.
addressList[0].confirmedBalance;//The balance of this address as returned by an getBalances API call. This is the balance in IOTA that has been deposited on this address.
addressList[0].used;//True if this address has been used as least ones, i.e. there exists a transaction were this address is used either as an input or output. False if not used in any transaction.
addressList[0].usedAsSent;//True if this address has been used to spent IOTA. Otherwise false. Note that after spending from an address a part of the private key of that address is published on the tangle. Is this field is true and the balance is positive the funds of this address are at risk! The funds should be transfered to an address which has the usedAsSent set to false immediately!
addressList[0].updating;//True if bundles of this address are currently being downloaded from the node. Otherwise false. See also isSyncing() to check for any updating addresses.

transfer

Represents the smallest object in IOTA. A transfer changes the balance of one address. A transfer can also contain data like signature. For a simple transaction of 1 IOTA from address A to B to transfer objects are required. One transfer object for address A with value -1 to reduce A' balance and one transfer object for address B with value 1 to increase B's balance by 1 IOTA. Both of these transfers will be in one bundle and therefore will be processed by the network in unison.

var bundleList = iota_lightnode.getBundles();
var bundle   = bundleList[0];
var transfer = bundle[0];
transfer.address;//Address of this transfer as a string of 81 trytes (no checksum)
transfer.attachmentTimestamp;//UNIX timestamp in ms when the transaction was attached (more precisely when the proof of work was performed)
transfer.attachmentTimestampLowerBound;//Unused so far
transfer.attachmentTimestampUpperBound;//Unused so far
transfer.branchTransaction;//Hash of one of the transfers that this transfer validates
transfer.bundle;//Bundle hash. This determines which bundle this transfer belongs to
transfer.currentIndex;//Index of this transfer in the bundle. This number is between 0 and lastIndex
transfer.hash;//Hash of the essential part of this transfer
transfer.lastIndex;//Last index in the bundle. This can be used to determine how many transfers are in a bundle
transfer.nonce;//Nonce of this transfer. The nonce is determined be the proof of work and chosen such that the hash of this transfer has a specified number of 9's at the end
transfer.obsoleteTag;//Obsolete. Do not use. Will be removed.
transfer.signatureMessageFragment;//2187 tryte long message. This field will hold the signature (or part of the signature) of the private address that spents IOTA. If the signature is longer than 2187 tryte multiple transfer objects will be used (and the therefore there will be more transfer objects in one bundle)
transfer.tag;//Tag, a string of 27 trytes. Transfers can be searched by their tag
transfer.timestamp;//UNIX timestamp in s when the transaction was created (more precisely when the transfer was signed)
transfer.trunkTransaction;//Hash of one of the transfers that this transfer validates
transfer.value;//Value of this transfer as a integer (can be positive and negative). When this transfer is confirmed the balance of transfer.address will be oldBalance(address) +

bundle

A bundle is the atomic structure of IOTA. It contains of a number of transfers. If a bundle is confirmed all transfers in the bundle are confirmed. If a bundle is pending all transfers in the bundle are pending. The first transfer in a bundle contains the field confirmationStatus. This field has one of the following values: Unkown: the confirmation status is not known. iota_lightnode has not yet asked the node about the confirmation status of this bundle. Use checkConfirmations to invoke iota_lightnode to request the confirmation status 2. Pending: the bundle has not yet been confirmed by the network 3. Confirmed: the bundle has been confirmed by the network 4. Reattachment Confirmed: the bundle did not get confirmed. However, a reattachment of the bundle did get confirmed 5. Rejected: the bundle did get rejected by the network. The bundle might be invalid or an invalid transaction might reference one transfer of this bundle. In any case the bundle belong to an inconsistent subtangle. In order to get this bundle to confirm it has the be reattached by calling reattachBundle.

var bundleList = iota_lightnode.getBundles();
var bundle     = bundleList[0];

bundle[0];//first transfer object
bundle[1];//second transfer object

bundle[0].confirmationStatus;//Only the first transfer object contains this field!

transaction

A transaction is higher level object and contains information about multiple bundles with the same bundle hash.

var transactionList = iota_lightnode.getTransactions();
var transaction     = transactionList[0];

transaction.attachmentTimestamp;////UNIX timestamp in ms when the transaction was attached to the tangle
transaction.bundle;//array containing all bundles of this transaction
transaction.bundles;//array of bundle hashes
transaction.transaction.confirmationStatus;//Only the first transfer object contains this field!
transaction.hashes;//array of the tail transaction hashes of each bundle
transaction.inbound;//true if one of the receiving addresses of the transaction belongs is in the address list, otherwise false
transaction.outbound;//true if one of the spending addresses of the transaction belongs is in the address list, otherwise false
transaction.tag;//tag of the first transfer with a positive value
transaction.timestamp;//UNIX timestamp in s when the transaction was signed
transaction.totalValueTransfered;//Total amount of IOTA transfered in the transaction
transaction.value;//Amount of IOTA transfered only involving addresses that are in the address list

Reference

calculateAddress

Generates addresses for a given seed.

Input

window.iota_lightnode.calculateAddress(seed, index, total, checksum, security, callback(error, addresses))
  1. seed: 81-trytes seed used to generate the address.
  2. index: integer index of the (first) address to be generated. Set to 0 to obtain the first address of the seed, 1 to obtain the second, etc. Default: 0.
  3. total: integer number of addresses to be generated. Default: 1.
  4. checksum: bool Set to true to generate address with a checksum (90 trytes long). If set to false, addresses generated will lack a checksum. Default: false.
  5. security: integer security parameter that is used for the addresses. Default: The default was set when initializeIOTA() was called.
  6. callback: function This function will be called total number of times. The first parameter contains any error(s), the second an array of the addresses that have (so far) been generated.

Return Value

None

Example

var seed  = 'OFMEOSBNBTAXQTGBHLVRRPAMPYUXZAFBAIHMJQHCSVPUELJMHNCNMSTX9DWZH9INOU9OJAUTPOYOTRZKY';
var total = 10;

window.iota_lightnode.calculateAddress(seed, 0, total, true, 3, function(error, addresses) {
	console.log(addresses.length, "have been generated so far:", addresses);
});

calculateFirstAddress

Similar to calculateAddress. This function calculates the first address (including checksum) of a given seed. The security parameter of the generated address is the same when initializeIOTA() was called.

Input

window.iota_lightnode.calculateFirstAddress(seed, callback(error, addresses))
  1. seed: 81-trytes seed used to generate the address.
  2. callback: function This function will be called when the address has ben generated. The first parameter contains any error(s), the second a string with the generated address including the checksum (90 trytes).

Return Value

None

Example

var seed  = 'OFMEOSBNBTAXQTGBHLVRRPAMPYUXZAFBAIHMJQHCSVPUELJMHNCNMSTX9DWZH9INOU9OJAUTPOYOTRZKY';
var total = 10;

window.iota_lightnode.calculateFirstAddress(seed, function(error, addresses) {
    console.log("First address is:", addresses);
});

checkConfirmations

This function updates the confirmation status of the bundles iota_lightnode is aware of. I.e. checkConfirmations goes trough the bundle list returned by getBundles and updates the confirmation status of pending transactions. After calling checkConfirmations the function isCheckingConfirmations will return true as long as the API calls are being made. When all bundles have been updated isCheckingConfirmations will return false. Note that the bundle list can be filled up by calling getAccountData of sendTransfer.

Input

window.iota_lightnode.checkConfirmations()

Return Value

None

Example

window.iota_lightnode.checkConfirmations();
console.log("Checking confirmation status of transactions...");
while (window.iota_lightnode.isCheckingConfirmations())
    ;//Do something else
console.log("Confirmation status updated!");

[createPreBundle]

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

enableLocalProofOfWork

This function enables or disable the local proof of work.

Input

window.iota_lightnode.enableLocalProofOfWork(enable)
  1. enable: bool Set to true to enable local proof of work. Set to false to disable local proof of work

Return Value

None

Example

window.iota_lightnode.isRemoteProofOfWorkAvailable(function(available) {//Check if the node we are connected to can perform the proof of work
    if (available)//The node can to the proof of work
        window.iota_lightnode.enableLocalProofOfWork(false);//OK, we don't have to do anything, let the node do the hard stuff
    else//Node does not perform the proof of work
        window.iota_lightnode.enableLocalProofOfWork(true);//We have to do the proof of work ourself
});

ensureBundleGetsConfirmed

This functions ensures that a bundle get confirmed by promoting it. Here is a brief summary of the algorithm used: The function attaches transactions to the tangle which validate the bundle. After every attachment the functions sleeps for a few seconds in order to use not to many resources. After 1 minute an API call is made to check if the bundle is still consistent. If the bundle is inconsistent, a reattachment is performed and the reattached bundle starts getting promoted. After about 10 minutes a reattachment is performed in any case.

Input

window.iota_lightnode.ensureBundleGetsConfirmed(bundle, callback(success))
  1. bundle: object a bundle as for example returned by sendTransfer. This is the bundle that will get promoted / reattached
  2. callback: function callback function which takes on parameter success. success will be true when the bundle or a reattachment of the bundle got confirmed by the network. If success is false an error occurred. This might be the case when the connection to the node got disconnected. Note that if success is false does NOT imply that the bundle did not get confirmed. It merely means that iota_lightnode could not determine the confirmation status of the bundle.

Return Value

None

Example

window.iota_lightnode.sendTransfer(seed, transfer, function(error, attached_bundle) {
    if (error)
        console.error(error);
    else
    {
        //Make sure the transaction gets confirmed
        window.iota_lightnode.ensureBundleGetsConfirmed(attached_bundle, function(success) {
            if (success)
                console.log( "Your transaction has been confirmed by the network!" );
            else
                console.log( "Error! Properly lost connection to the node!" );
        });
    }
});

findBundle

Searches the bundle list of iota_lightnode for a bundle with the bundle hash that is specified. If there are multiple bundles with the same bundle hash in the list (as may be the case when a reattachment occurred), the first item in the list is returned.

Input

window.iota_lightnode.findBundle(bundleHash)
  1. bundleHash: string of 81 trytes. The bundle hash that is being searched for.

Return Value

If a bundle with the specified bundle hash could be found, the bundle is returned as an object. If no bundle with the specified bundle hash could be found, undefined is returned.

Example

window.iota_lightnode.sendTransfer(seed, transfer, function(error, attached_bundle) {//Execute transactions
    if (!error)
    {
        var bundle_hash = attached_bundle[0].bundle;//Get the bundle hash of the transaction which has been attached

        //Find the bundle in the list
        var bundleFound = window.iota_lightnode.findBundle(bundle_hash);

        if (typeof bundleFound === 'undefined')
            console.log( "Bundle could not be found!" );
        else
            console.log( "Found bundle", bundleFound );
    }
});

[fromTrytes]

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

generateSeedInsecurely

Generates a seed (81 trytes). This functions is NOT cryptographic cryptographically secure! Do NOT use the function to generates seeds to create wallets and store a lot of IOTA on them!

Input

None.

Return Value

  1. string - returns a string of length 81 which contains only the characters A-Z and 9.

Example

var seed = window.iota_lightnode.generateSeedInsecurely();
    console.log("New seed:", seed);
});

[getAccountData]

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

[getAddresses]

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getBalance

Returns the total balance (sum of all addresses). getAccountData should have been called before calling getBalance in order to obtain the addresses / bundles / balances / transactions of a given seed. Balance is defined as the confirmed balance including all pending transactions. For example if there are no pending transactions balance and confirmed balance are the same. If there are pending transactions getBalance returns the balance if all the pending transactions were actually confirmed.

Input

None.

Return Value

  1. integer - returns the sum of the balances of all addresses in IOTA

Example

window.iota_lightnode.getAccountData(seed);
//Wait until account data is loaded
//Assume that there are no pending transactions and there are exactly two addresses connected with this seed
//Address 0 has 100i, Address 1 has 50i
window.iota_lightnode.getBalance();//150 is returned
window.iota_lightnode.getconfirmedBalance();//150 is returned
//Spent all 100i of address 0 by sending it to some third-party address
window.iota_lightnode.getBalance();//50 is returned, since this will be the total balance if the pending transaction were to be confirmed
window.iota_lightnode.getconfirmedBalance();//150 is returned, since the transaction has not been confirmed yet
//After confirmation, address 0 has 0i, address 1 has 50i
window.iota_lightnode.getBalance();//50 is returned
window.iota_lightnode.getconfirmedBalance();//50 is returned, since the transaction got confirmed
});

getBundles

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getBundlesOfAddress

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getBundlesOfAddressIndex

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getConfirmedBalance

Returns the total confirmed balance (sum of the confirmed balance of all addresses). getAccountData should have been called before calling getBalance in order to obtain the addresses / bundles / balances / transactions of a given seed.

Input

None.

Return Value

  1. integer - returns the sum of the confirmed balances of all addresses in IOTA

Example

window.iota_lightnode.getAccountData(seed);
//Wait until account data is loaded
//Assume that there are no pending transactions and there are exactly two addresses connected with this seed
//Address 0 has 100i, Address 1 has 50i
window.iota_lightnode.getBalance();//150 is returned
window.iota_lightnode.getconfirmedBalance();//150 is returned
//Spent all 100i of address 0 by sending it to some third-party address
window.iota_lightnode.getBalance();//50 is returned, since this will be the total balance if the pending transaction were to be confirmed
window.iota_lightnode.getconfirmedBalance();//150 is returned, since the transaction has not been confirmed yet
//After confirmation, address 0 has 0i, address 1 has 50i
window.iota_lightnode.getBalance();//50 is returned
window.iota_lightnode.getconfirmedBalance();//50 is returned, since the transaction got confirmed
});

getIOTA

Returns the IOTA object of iota.lib.js.

Input

None.

Return Value

  1. Object - returns the IOTA object of iota.lib.js.

Example

window.iota_lightnode.getIOTA().getNewAddress(seed, {'index': index, 'checksum': true, 'security': 2}, function(error, new_address) {
    console.log(new_address, "generated with iota.lib.js within iota_lightnode");
});

getProvider

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getTransactions

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getTransactionsOfAddress

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

getTransactionsOfAddressIndex

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

initializeIOTA

Initializes iota_lightnode.js and iota.lib.js. This function has to be called before any other function of iota_lightnode.js can be called.

Input

window.iota_lightnode.initializeIOTA(security, depth, minWeightMagnitude)
  1. security: integer security parameter that should be used for address generation if no additional security parameter is supplied. Default: 2.
  2. depth: integer depth parameter for iota.lib.js. Used in the tip selection algorithm. Default: 3.
  3. minWeightMagnitude: integer minimum weight parameter used for the proof of work. The difficult of the proof of work increases with this parameter. Currently, only transactions with weight magnitude >= 14 will be accepted by the network (of main net). Default: 14

Return Value

  1. Object - returns the iota_lightnode object.

Example

var lightnode = window.iota_lightnode.initializeIOTA();

isCheckingConfirmations

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isInAddressList

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isInputAddress

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isPerformingTransfers

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isPerformingProofOfWork

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isProofOfWorkLocal

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isRemoteProofOfWorkAvailable

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isSyncing

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

isOutputAddress

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

reattachBundle

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

reattachTransaction

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

sendPreBundle

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

sendSignedBundle

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

sendTransfer

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

setCurlLibrary

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

setProvider

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

signPreBundle

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

toTrytes

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

updateAddress

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

updateAddressesOneByOne

TODO

Input

TODO

TODO

Return Value

TODO

Example

TODO

About

A high-level wrapper for the IOTA Javascript Library iota.lib.js

Topics

javascript wrapper iota tangle balanced-ternary iota-javascript-library iota-library

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages