Skip to content

Latest commit

 

History

History
870 lines (691 loc) · 56.1 KB

api.md

File metadata and controls

870 lines (691 loc) · 56.1 KB
Raw

API Reference

Classes

RAAM ⇐ RAAMReader

This class is used to publish messages in a RAAM channel. It also provides the methods of RAAMReader.

RAAMReader

This class is used to read messages from a RAAM channel. Any instance stores read messages by this instance for later use. This way, queries to a node are minimized.

Typedefs

Leaf : object

An object containing public and private key for one-time signing a message.

Node : object

An object representing a node of a merkle tree with a hash, and the position of the node by height and index.

MessageTransfers : object

An object representing a message as transfers for a iota transaction bundle.

Message : object

An object representing the compiled RAAM message with all neccessary information to create its transfers.

ProgressCallback : function

Callback function that is called after a given timeout to report the progress in channel creation.

ReadCallback : function

Callback function that is called after each message request.

Subscription : object

An object containing information about the created subscription, including the function to end the subscription.

SingleSubscription : object

An object containing information about the created subscription, including the function to end the subscription.

SingleSubscription : object

An object containing information about the created subscription, including the function to end the subscription.

SingleResult : object

Container class for the result of a single fetched message.

FetchResult : object

Conainer class for the result of a fetch request.

RAAM ⇐ RAAMReader

This class is used to publish messages in a RAAM channel. It also provides the methods of RAAMReader.

Kind: global class Extends: RAAMReader

new RAAM(leafs, hashes, height, [options])

Throws:

  • Error if tree is incomplete.
Param Type Description
leafs Array.<Leaf> The leafs of the merkle tree which will be used as the signing keys of the messages.
hashes Array.<Node> The nodes of the merkle tree which will be used for the authentication path of the messages.
height number A number between 1 and 26 representing the height of the merkle tree used for this channel.
[options] object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node providing POW.
[options.channelPassword] Trytes The optional password for the channel as trytes.

raam.createPublicMessageTransfers(message, [options]) ⇒ MessageTransfers

Compiles the authentication path and a signature using the correct signing key. Converts the encrypted payload of the message into transaction transfers. This message can be decoded by only using its address.

Kind: instance method of RAAM Throws:

    • if message isn't formatted as trytes.
  • if index is not between zero and the maximal index of the channel.
  • if a message was already found at this index.
  • if channel password is set.
Param Type Default Description
message Trytes The message to attach to the channel as trytes.
[options] object Optional parameters.
[options.index] number this.cursor The index of the message in the channel.
[options.tag] Trytes 'RAAM' Tag
[options.nextRoot] Int8Array The root of another channel, used for branching or when channel is exausted.

raam.createMessageTransfers(message, [options]) ⇒ MessageTransfers

Compiles the authentication path and a signature using the correct signing key. Converts the encrypted payload of the message into transaction transfers.

Kind: instance method of RAAM Throws:

    • if message isn't formatted as trytes.
  • if index is not between zero and the maximal index of the channel.
  • if a message was already found at this index.
Param Type Default Description
message Trytes The message to attach to the channel as trytes.
[options] object Optional parameters.
[options.index] number this.cursor The index of the message in the channel.
[options.tag] Trytes 'RAAM' Tag
[options.messagePassword] Trytes The password to encrypt this message with.
[options.nextRoot] Int8Array The root of another channel, used for branching or when channel is exausted.

raam.publishMessageTransfers(transfers, [options]) ⇒ Promise

Takes transaction transfers and converts them into a transaction bundle, which is then attached to the tangle. POW is done remotely. Increases the cursor, so that it points to the next index where a message can be attached. Message is stored locally after publishing.

Kind: instance method of RAAM Fulfil: Transaction[] - The bundle of the attached message. Reject: Error

  • if message is too long
Param Type Default Description
transfers Array.<Transfer> The array of transfers forming the transactions of a IOTA bundle.
[options] object Optional parameters.
[options.message] Message The compiled RAAM message with all neccessary information to create its transfers. If it's passed message will be stored locally after publishing.
[options.depth] number 3 Depth
[options.mwm] number 14 Min weight magnitude
[options.iota] API this.iota A composed IOTA API for communication with a full node providing POW.

raam.publishPublic(message, [options]) ⇒ Promise

Compiles the authentication path and a signature using the correct signing key. Converts the encrypted payload of the message into a transaction bundle, which is then attached to the tangle. POW is done remotely. Increases the cursor, so that it points to the next index where a message can be attached. Message is stored locally after publishing. This message can be decoded by only using its address.

Kind: instance method of RAAM Fulfil: Transaction[] - The bundle of the attached message. Reject: Error

  • if message is too long
  • if message isn't formatted as trytes.
  • if index is not between zero and the maximal index of the channel.
  • if a message was already found at this index.
  • if channel password is set.
Param Type Default Description
message Trytes The message to attach to the channel as trytes.
[options] object Optional parameters.
[options.index] number this.cursor The index of the message in the channel.
[options.tag] Trytes 'RAAM' Tag
[options.depth] number 3 Depth
[options.mwm] number 14 Min weight magnitude
[options.iota] API this.iota A composed IOTA API for communication with a full node providing POW.
[options.nextRoot] Int8Array The root of another channel, used for branching or when channel is exausted.

raam.publish(message, [options]) ⇒ Promise

Compiles the authentication path and a signature using the correct signing key. Converts the encrypted payload of the message into a transaction bundle, which is then attached to the tangle. POW is done remotely. Increases the cursor, so that it points to the next index where a message can be attached. Message is stored locally after publishing.

Kind: instance method of RAAM Fulfil: Transaction[] - The bundle of the attached message. Reject: Error

  • if message is too long
  • if message isn't formatted as trytes.
  • if index is not between zero and the maximal index of the channel.
  • if a message was already found at this index.
Param Type Default Description
message Trytes The message to attach to the channel as trytes.
[options] object Optional parameters.
[options.index] number this.cursor The index of the message in the channel.
[options.tag] Trytes 'RAAM' Tag
[options.depth] number 3 Depth
[options.mwm] number 14 Min weight magnitude
[options.iota] API this.iota A composed IOTA API for communication with a full node providing POW.
[options.messagePassword] Trytes The password to encrypt this message with.
[options.nextRoot] Int8Array The root of another channel, used for branching or when channel is exausted.

raam.syncChannel([options]) ⇒ Promise

Reads messages from the channel until the index where no message is found. Alle found messages will be stored locally and be returned. Sets the cursor to the first index where no message was found.

Kind: instance method of RAAM Overrides: syncChannel Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raam.fetch([options]) ⇒ Promise

Reads a single message with given index or an amount of messages by giving start and index from the channel. Only indexes where no message is already stored locally are queried from the given full node, since they are immutable. Returns all found messages in an array. Indexes where no message was found will be left empty. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned per index as arrays.

Kind: instance method of RAAM Overrides: fetch Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.index] number The index in the channel of the message to fetch. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to fetch. If start and index aren't set start is 0.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raam.fetchPublic([options]) ⇒ Promise

Reads a single public message with given index or an amount of public messages by giving start and index from the channel. Only indexes where no message is already stored locally are queried from the given full node, since they are immutable. Returns all found messages in an array. Indexes where no message was found will be left empty. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned per index as arrays.

Kind: instance method of RAAM Overrides: fetchPublic Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.index] number The index in the channel of the message to fetch. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to fetch. If start and index aren't set start is 0.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.callback] ReadCallback Callback function that is called after each message request.

raam.subscribe(callback, [options]) ⇒ Subscription

Subscribes to a given set of messages in the channel. A callback will be called when a message arrives. Subscriptions to messages already present locally are omitted and a callback is not called for them. The arriving messages are stored locally.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: instance method of RAAM Overrides: subscribe Returns: Subscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.index] number The index in the channel of the message to subscribe to. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to subscribe to. If start and index aren't set start is the first index where no message is present locally.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed, if it's not already present locally and not yet subscribed.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raam.subscribePublic(callback, [options]) ⇒ Subscription

Subscribes to a given set of public messages in the channel. A callback will be called when a message arrives. Subscriptions to public messages already present locally are omitted and a callback is not called for them. The arriving messages are stored locally.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: instance method of RAAM Overrides: subscribePublic Returns: Subscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.index] number The index in the channel of the message to subscribe to. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to subscribe to. If start and index aren't set start is the first index where no message is present locally.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed, if it's not already present locally and not yet subscribed.

RAAM.fromSeed(seed, [options]) ⇒ Promise

Creates a RAAM channel from a seed. For that a merkle tree is created consisting of all one-time signing keys that sign the messages of the channel. For bigger values of height/amount this can take a while. After creation a RAAM instance for read/write operations of the channel is returned. It's possible to save the merkle tree to a file, which can be used to fastly reinitialize the channel. This file needs to be stored in save place, as everybody who accesses it can publishes messages to this channel. Feedback in the creation process is provided by an optional callback.

Kind: static method of RAAM Fulfil: RAAM

Param Type Default Description
seed Trytes The seed from which the signing keys are created.
[options] object Optional parameters.
[options.amount] number The maximum amount of messages that can be published in this channel.
[options.height] number Math.ceil(Math.log2(amount)) A number between 1 and 26 representing the height of the merkle tree used for this channel.
[options.iota] API this.iota A composed IOTA API for communication with a full node providing POW.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.security] number 2 The security of the signing and encryption keys as a number between 1 and 4.
[options.offset] number 0 The starting index used for building the subroots from which the keys are created.
[options.saveToFile] boolean false whether to save the created merkle tree to a file, which can be used for fast reinitializing the channel.
[options.fileName] string "channelKeys.json" The filename of the file where the merkle tree is saved.
[options.progressCallback] ProgressCallback A callback function called after the given timeout reporting the progress of the channel creation.
[options.timeout] number 5000 The timeout after the progressCallback is triggered.

RAAM.fromFile(fileName, [options]) ⇒ RAAM

Initializes a RAAM channel from a file containing the signing keys for this channel.

Kind: static method of RAAM

Param Type Default Description
fileName string The name of the file to load.
[options] object Optional parameters.
[options.iota] API this.iota A composed IOTA API for communication with a full node providing POW.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.amount] number The maximum amount of messages that can be published in this channel.
[options.height] number Math.ceil(Math.log2(amount)) A number between 1 and 26 representing the height of the merkle tree used for this channel.
[options.seed] Trytes The seed from which the signing keys are created.
[options.offset] number 0 The starting index used for building the subroots from which the keys are created.
[options.progressCallback] ProgressCallback A callback function called after the given timeout reporting the progress of the channel creation.
[options.timeout] number 5000 The timeout after the progressCallback is triggered.

RAAMReader

This class is used to read messages from a RAAM channel. Any instance stores read messages by this instance for later use. This way, queries to a node are minimized.

Kind: global class

new RAAMReader(channelRoot, [options])

Param Type Description
channelRoot Int8Array The channel root by that the channel is identified as trits.
[options] object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.amount] number The maximum amount of messages in this channel. From this the height of the channel can be calculated. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

raamReader.syncChannel([options]) ⇒ Promise

Reads messages from the channel until the index where no message is found. Alle found messages will be stored locally and be returned. Sets the cursor to the first index where no message was found.

Kind: instance method of RAAMReader Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raamReader.fetch([options]) ⇒ Promise

Reads a single message with given index or an amount of messages by giving start and index from the channel. Only indexes where no message is already stored locally are queried from the given full node, since they are immutable. Returns all found messages in an array. Indexes where no message was found will be left empty. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned per index as arrays.

Kind: instance method of RAAMReader Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.index] number The index in the channel of the message to fetch. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to fetch. If start and index aren't set start is 0.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raamReader.fetchPublic([options]) ⇒ Promise

Reads a single public message with given index or an amount of public messages by giving start and index from the channel. Only indexes where no message is already stored locally are queried from the given full node, since they are immutable. Returns all found messages in an array. Indexes where no message was found will be left empty. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned per index as arrays.

Kind: instance method of RAAMReader Fulfil: FetchResult

Param Type Description
[options] Object Optional parameters.
[options.iota] API A composed IOTA API for communication with a full node.
[options.index] number The index in the channel of the message to fetch. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to fetch. If start and index aren't set start is 0.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.callback] ReadCallback Callback function that is called after each message request.

raamReader.subscribe(callback, [options]) ⇒ Subscription

Subscribes to a given set of messages in the channel. A callback will be called when a message arrives. Subscriptions to messages already present locally are omitted and a callback is not called for them. The arriving messages are stored locally.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: instance method of RAAMReader Returns: Subscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.index] number The index in the channel of the message to subscribe to. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to subscribe to. If start and index aren't set start is the first index where no message is present locally.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed, if it's not already present locally and not yet subscribed.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.

raamReader.subscribePublic(callback, [options]) ⇒ Subscription

Subscribes to a given set of public messages in the channel. A callback will be called when a message arrives. Subscriptions to public messages already present locally are omitted and a callback is not called for them. The arriving messages are stored locally.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: instance method of RAAMReader Returns: Subscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.index] number The index in the channel of the message to subscribe to. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to subscribe to. If start and index aren't set start is the first index where no message is present locally.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed, if it's not already present locally and not yet subscribed.

RAAMReader.fetchPublicMessages(iota, address, [options]) ⇒ Promise

Reads one or more messages located by their addresses. Returns all found messages in a Map mapping addresses to SingleResult objects. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned in the SingleResults.

Kind: static method of RAAMReader Fulfil: Map.<Trytes, SingleResult>

Param Type Description
iota API A composed IOTA API for communication with a full node.
address Array.<Trytes> An array of IOTA addresses used to locate the messages.
[options] Object Optional parameters.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.channelRoot] Int8Array The channel root by that the channel is identified as trits. This is parameter is only used as an extra verification information.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

RAAMReader.fetchMessages(iota, channelRoot, [options]) ⇒ Promise

Reads a single message with given index or an amount of messages by giving start and index from the channel with the given channel root. Returns all found messages in an array. Indexes where no message was found will be left empty. Also skipped bundles at the queried addresses, channel roots of provided branches and errors are returned per index as arrays.

Kind: static method of RAAMReader Fulfil: FetchResult

Param Type Description
iota API A composed IOTA API for communication with a full node.
channelRoot Int8Array The channel root by that the channel is identified as trits.
[options] Object Optional parameters.
[options.index] number The index in the channel of the message to fetch. If start is set too, index is not used.
[options.start] number The start index in the channel of the messages to fetch. If start and index aren't set start is 0.
[options.end] number The end index in the channel of the messages to fetch. If end is undefined messages will be fetched until an index where no message is found is reached.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.callback] ReadCallback Callback function that is called after each message request.
[options.messagePassword] Trytes The default message password which will be used to decrypt all found messages.
[options.messagePasswords] Array.<Trytes> An array containing different message passwords for different messages. The ith element is the password for the ith message in the channel.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

RAAMReader.fetchSingle(iota, channelRoot, index, [options]) ⇒ Promise

Reads a single message with given index from the channel with the given channel root. Returns the found message iff any, the index, skipped bundles at the queried address and errors.

Kind: static method of RAAMReader Fulfil: SingleResult

Param Type Description
iota API A composed IOTA API for communication with a full node.
channelRoot Int8Array The channel root by that the channel is identified as trits.
index number The index in the channel of the message to fetch. If start is set too index is not used.
[options] Object Optional parameters.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.messagePassword] Trytes The message password which will be used to decrypt the found message.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

RAAMReader.fetchPublic(iota, address, [options]) ⇒ Promise

Reads a single public message from the given address. Returns the found message iff any, the index, skipped bundles at the queried address and errors.

Kind: static method of RAAMReader Fulfil: SingleResult

Param Type Description
iota API A composed IOTA API for communication with a full node.
address Trytes An IOTA address used to locate the message.
[options] Object Optional parameters.
[options.index] number The index in the channel of the message to fetch. Not used for locating message. This is parameter is only used as an extra verification information.
[options.channelRoot] Int8Array The channel root by that the channel is identified as trits. This is parameter is only used as an extra verification information.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

RAAMReader.subscribeIndex(channelRoot, index, callback, [options]) ⇒ SingleSubscription

Subscribes to a given index in a RAAM channel. A callback will be called when a message arrives.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: static method of RAAMReader Returns: SingleSubscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
channelRoot Int8Array The channel root by that the channel is identified as trits.
index number The index in the channel of the message to subscribe to.
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed.
[options.channelPassword] Trytes The optional password for the channel as trytes.
[options.messagePassword] Trytes The message password which will be used to decrypt the found message.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

RAAMReader.subscribePublic(address, callback, [options]) ⇒ SingleSubscription

Subscribes to public RAAM messages on a given address. A callback will be called when a message arrives.

For reacting to new arriving messages a ZMQ stream of an IOTA full node is listened. The URL to it can be passed. If it's not passed the last one is used. There can be only a connection to one ZMQ stream at a time. The connection is established if the first subscription is created and closed when all subscriptions have been cancelled.

Kind: static method of RAAMReader Returns: SingleSubscription - An object containing information about the created subscription, including the function to end the subscription. Throws:

  • Error if the serverURL is not passed and hasn't been set already.
Param Type Description
address Trytes An IOTA address used to locate the message.
callback ReadCallback The callback that is called if a subscribed message arrives.
[options] Object Optional parameters.
[options.serverURL] String The URL for the ZMQ stream of an IOTA full node. Is used iff not connected to another ZMQ stream already. The URL needs to be passed at least once, because there is no default.
[options.subscribeFollowing] boolean if set to true, when a subscribed message arrives, the next message will be subscribed.
[options.index] number The index in the channel of the message to subscribe to. This is parameter is only used as an extra verification information.
[options.channelRoot] Int8Array The channel root by that the channel is identified as trits. This is parameter is only used as an extra verification information.
[options.security] number The security of the signing and encryption keys as a number between 1 and 4. This is parameter is only used as an extra verification information.
[options.height] number The height as a number between 1 and 26 of the channel yielding the maximum amount of messages of the channel. This is parameter is only used as an extra verification information.

Leaf : object

An object containing public and private key for one-time signing a message.

Kind: global typedef Properties

Name Type Description
public Int8Array The verifying key as trits.
private Int8Array The signing key as trits.
index number The index in the merkle tree at leaf level, representing which message is signed with this key.
height number The level in the merkle tree, which is always 0.

Node : object

An object representing a node of a merkle tree with a hash, and the position of the node by height and index.

Kind: global typedef Properties

Name Type Description
hash Int8Array The hash of the direct children of this node in the merkle tree as trits.
index number The index in the level of the merkle tree from left to right.
height number The level of the node in the merkle tree.

MessageTransfers : object

An object representing a message as transfers for a iota transaction bundle.

Kind: global typedef Properties

Name Type Description
transfers Array.<Transfer> The array of transfers forming the transactions of a IOTA bundle.
message Message The compiled RAAM message with all neccessary information to create its transfers.

Message : object

An object representing the compiled RAAM message with all neccessary information to create its transfers.

Kind: global typedef Properties

Name Type Description
index number The index of the message in the channel.
height number A number between 1 and 26 representing the height of the merkle tree used for this channel.
security number The security of the signing and encryption keys as a number between 1 and 4.
message Trytes The message to attach to the channel as trytes.
signature Int8Array The signature created from the message digest with signing key from the merkle tree.
verifyingKey Int8Array The key to verify the signature and to verify its membership of the merkle tree.
authPathHashes Array.<Int8Array> The other merkle tree nodes to rebuild the merkle root.
nextRoot Int8Array The root of another channel, used for branching or when channel is exausted.

ProgressCallback : function

Callback function that is called after a given timeout to report the progress in channel creation.

Kind: global typedef

Param Type Description
leafs Array.<Leaf> an array containing all leafs created since the last callback.
hashes Array.<Node> an array containing all hashes in the merkle tree created since the last callback.

ReadCallback : function

Callback function that is called after each message request.

Kind: global typedef

Param Type Description
error Error Error that occured while getting the message iff any.
index number The index of the message.
message Trytes The fetched message if the request was successful.
skipped Array.<object> An array containing skipped bundles that were found at the same address that the message has. Elements {bundle, error} contain the bundle hash and the error causing the skipping.
nextRoot Int8Array The nextRoot of the message iff any.
channelRoot Int8Array The channelRoot of the message.

Subscription : object

An object containing information about the created subscription, including the function to end the subscription.

Kind: global typedef Properties

Name Type Description
start number The start index in the channel of the subscribed messages.
end number The end index in the channel of the subscribed messages.
subscribeFollowing boolean whether the following index will be subscribed when a message arrives and is not yet present locally or subscribed.
callback ReadCallback The callback that is called if a subscribed message arrives.
unsubscribe function When called the subscription to all specified indexes will be ended.

SingleSubscription : object

An object containing information about the created subscription, including the function to end the subscription.

Kind: global typedef Properties

Name Type Description
index number The index of the currently subscribed message.
channelRoot Int8Array The channel root by that the channel is identified as trits.
subscribeFollowing boolean whether the following index will be subscribed when a message arrives.
callback ReadCallback The callback that is called if a subscribed message arrives.
unsubscribe function When called the current subscription will be ended.

SingleSubscription : object

An object containing information about the created subscription, including the function to end the subscription.

Kind: global typedef Properties

Name Type Description
index number The index of the currently subscribed message.
channelRoot Int8Array The channel root by that the channel is identified as trits.
subscribeFollowing boolean whether the following index will be subscribed when a message arrives.
callback ReadCallback The callback that is called if a subscribed message arrives.
unsubscribe function When called the current subscription will be ended.

SingleResult : object

Container class for the result of a single fetched message.

Kind: global typedef Properties

Name Type Description
message Trytes The fetched message, iff any.
index number The index of the fetched message.
nextRoot Int8Array The nextRoot, iff any, provided by the message.
skipped Array.<object> An array containing skipped bundles that were found at the same address that the message has. Elements {bundle, error} contain the bundle hash and the error causing the skipping.
channelRoot Int8Array The channelRoot of the message.

FetchResult : object

Conainer class for the result of a fetch request.

Kind: global typedef Properties

Name Type Description
messages Array.<Trytes> Array of found messages, where the message at start index is the first message in the array. Elements where no message was found will be left empty.
errors Array.<Error> Array of errors that occured while fetching messages.
skipped Array.<Array.<object>> An array containing skipped bundles that were found at the same addresses that the messages have. Elements are arrays containing objects {bundle, error} consisting of the bundle hash and the error causing the skipping. If no bundles where skipped for a message the array element is empty.
branches Array.<Int8Array> The nextRoot, iff any, provided by a certain message.

Documented by jsdoc-to-markdown.