MAM Tools

A library containing tools to make the use of IOTAs Masked Authenticated Messaging more easy.

Included is a lib for node.js, a js module for mocking a MAM client so that no real IOTA node is needed for the testing of MAM apps and a CLI.

CLI

You can use all functions of the MAM library with a simple CLI. The releases contain binaries for different platforms with that you can use MAM standalone from the command line:

$ mamCli-linux-x86 <command> [options]

It's also possible to run the cli directly with node/npm:

$ npm install
$ npm run cli <command> -- [options]

Note the extra '--' needed before the options.

Setting Node

The option --provider must be set in all commands. It should be set to the URL of an IOTA full node supporting POW.

Commands:

readChannel

Reads the content of a given MAM channel and printing information such as the channelRoot.

Param	Type	Default	Description
channelRoot	string		The root of the MAM channel. This is shared with others to read messages of a channel.
seed	string		The seed of the MAM channel. It's need to publish new messages to a MAM channel.
mode	string	'public'	The mode of the MAM channel. Allowed are 'public', 'private' and 'restricted'
sideKey	string	null	The sideKey needed for MAM channels in restricted mode. This is needed to read messages from this channel and to publish new ones.

Only channelRoot or seed are needed for reading a channel. The CLI will look for the channelRoot first and then for a seed. If both aren't given a random seed is generated.

Example

$ mamCli-linux-x86 readChannel --seed=THISISTHESEEDOFTHETICACCOUNTANDISHOULDNOTGIVEITTOANYBODYELSE --provider=https://your.favorite.node

publish

Publishes a new message to a specified channel.

Param	Type	Default	Description
seed	string		The seed of the MAM channel.
mode	string	'public'	The mode of the MAM channel. Allowed are 'public', 'private' and 'restricted'
sideKey	string	null	The sideKey needed for MAM channels in restricted mode.
toTrytes	boolean	true	Whether to convert the given text to trytes.
content	string		The message to publish. Remember to wrap the content in '' if it contains spaces.
readMessages	boolean	false	Whether to read the channel's content after publishing

Example

$ mamCli-linux-x86 publish --seed=THISISTHESEEDOFTHETICACCOUNTANDISHOULDNOTGIVEITTOANYBODYELSE --provider=https://your.favorite.node
    -content='Hello World' --readMessages

---

API Reference

A MAM lib for node.js

Example

const mam = require('mam.tools.js')

• mamClient
  • .changeMode ⇒ Promise.<ChangeModeState>
  • .getRoot ⇒ string
  • .getMessages ⇒ Promise.<MessageResponse>
  • .setProvider(url)
  • .getIota([url]) ⇒ IotaClass
  • .createMamFrom([params]) ⇒ Promise.<MAMClient>
  • .createMam([seed], [iota], [mode], [sideKey]) ⇒ Promise.<MAMClient>
  • .getChannelMessages(channelRoot, mamState) ⇒ Promise.<MessageResponse>
  • .generateSeed([length]) ⇒ string
  • .publish(text, mamState, iota, [toTrytes]) ⇒ Promise.<PublishResponse>

mam.changeMode ⇒ Promise.<ChangeModeState>

Changes the mode of a given mam state object. The state is initialized in a way, that the next message will be attached to the next root of the channel even if messages are already existent in the channel.

Kind: static property of mamClient
Returns: Promise.<ChangeModeState> - a Promise awaiting an object containing the mam state with changed mode and the channel root address of the channel in the new mode.

Param	Type	Default	Description
mam	Object		The mam state object whose mode should be changed.
mode	string		the mode of the MAM channel to read/write. 'public', 'restricted' and 'private' are valid.
[sideKey]	string	null	the side key when using a restricted channel.

mam.getRoot ⇒ string

Kind: static property of mamClient
Returns: string - the root address of the channels next message.

Param	Type	Description
mam	Object	the MAM state.

mam.getMessages ⇒ Promise.<MessageResponse>

Retrieves all messages starting from the given channel root using given mode and sideKey.

Kind: static property of mamClient
Returns: Promise.<MessageResponse> - a Promise awaiting an Object containing the messages retrieved from the MAM channel and the next channel root.

Param	Type	Default	Description
channelRoot	string		the root address of the first message in the channel that should be retrieved.
[mode]	string	"'public'"	the mode of the retrieved channel.
[sideKey]	string	null	the sideKey of retrieved restricted channel.

mam.setProvider(url)

Sets the node to use for all requests to the tangle. The given node must support pow.

Kind: static method of mamClient

Param	Type	Description
url	string	the url of the node to use.

mam.getIota([url]) ⇒ IotaClass

Creates an Object to handle requests to the tangle. An optional url to a node can be given, by default the url set by setProvider is used.

Kind: static method of mamClient
Returns: IotaClass - the newly created iota object.

Param	Type	Default	Description
[url]	string	"provider"	the url of the node to use. Default is the url set by setProvider.

mam.createMamFrom([params]) ⇒ Promise.<MAMClient>

Initializes a module:types.MAMClient from given parameters. The default uses a randomly generated seed with a iota using the node set by setProvider to access a public MAM channel. The state is initialized in a way, that the next message will be attached to the next root of the channel even if messages are already existent in the channel.

Kind: static method of mamClient
Returns: Promise.<MAMClient> - a Promise awaiting an object containing the MAM state object, the iota client and the root address of the channel.

Param	Type	Default	Description
[params]	Object		an Object containing seed, iota client, MAM channel mode, and a sideKey if mode is 'restricted'.
[params.seed]	string	"generateSeed()"	The seed for the MAM channels.
[params.iota]	IotaClass	getIota()	The iota client for communication with a full node.
[params.mode]	string	"'public'"	the mode of the MAM channel to read/write. 'public', 'restricted' and 'private' are valid.
[params.sideKey]	string	null	the side key when using a restricted channel.

mam.createMam([seed], [iota], [mode], [sideKey]) ⇒ Promise.<MAMClient>

Initializes a module:types.MAMClient from given parameters. The default uses a randomly generated seed with a iota using the node set by setProvider to access a public MAM channel. The state is initialized in a way, that the next message will be attached to the next root of the channel even if messages are already existent in the channel.

Kind: static method of mamClient
Returns: Promise.<MAMClient> - a Promise awaiting an object containing the MAM state object, the iota client and the root address of the channel.

Param	Type	Default	Description
[seed]	string	"generateSeed()"	The seed for the MAM channels.
[iota]	IotaClass	getIota()	The iota client for communication with a full node.
[mode]	string	"'public'"	the mode of the MAM channel to read/write. 'public', 'restricted' and 'private' are valid.
[sideKey]	string	null	the side key when using a restricted channel.

mam.getChannelMessages(channelRoot, mamState) ⇒ Promise.<MessageResponse>

Retrieves all messages starting from the given channel root using mode and sideKey given by the given mamState Object.

Kind: static method of mamClient
Returns: Promise.<MessageResponse> - a Promise awaiting an Object containing the messages retrieved from the MAM channel and the next channel root.

Param	Type	Description
channelRoot	string	the root address of the first message in the channel that should be retrieved.
mamState	Object	the initialized MAM state object.

mam.generateSeed([length]) ⇒ string

Kind: static method of mamClient
Returns: string - a randomly generated seed with the given length.

Param	Type	Default	Description
[length]	string	81	the wanted length of the generated seed.

mam.publish(text, mamState, iota, [toTrytes]) ⇒ Promise.<PublishResponse>

Publishes a given text to a MAM channel using the initialized MAM state Object.

Kind: static method of mamClient
Returns: Promise.<PublishResponse> - a Promise containing an Object conaining the root and the address of the published message and the updated MAM State Object.
Asnyc:

Param	Type	Default	Description
text	string		the text to publish to the tangle.
mamState	Object		the MAM state Object.
iota	IotaClass		the initialized iota client.
[toTrytes]	boolean	true	whether to convert the text to trytes.

---

Types

The types listed below are used by the mam tools.

• types
  • ~MAMClient : Object
  • ~ChangeModeState : Object
  • ~PublishResponse : Object
  • ~MessageResponse : Object

types~MAMClient : Object

An object containing the MAM client, root of the MAM channel and the iota client.

Kind: inner typedef of types
Properties

Name	Type	Description
iota	IotaClass	The iota client.
mam	Object	The MAM state object used by the client lib for all requests regarding the set channel (by seed and mode).
channelRoot	string	the root of the channels first message.

types~ChangeModeState : Object

An object containing the changed mamState an the root to the channels first message.

Kind: inner typedef of types
Properties

Name	Type	Description
mam	Object	The changed MAM state object used by the client lib for all requests regarding the set channel (by seed and mode).
channelRoot	string	the root of the channels first message.

types~PublishResponse : Object

An Object conaining the root and the address of the published message and the given MAM State Object.

Kind: inner typedef of types
Properties

Name	Type	Description
root	string	the root of the published message.
address	string	the address of the published message.
mamState	Object	the updated MAM state Object.

types~MessageResponse : Object

An Object containing the messages retrieved from the MAM channel and the next channel root.

Kind: inner typedef of types
Properties

Name	Type	Description
messages	Array.<string>	The messages retrieved from the MAM channel.
nextRoot	string	the root address of the next message in the mam channel.

---

© 2018 Robin Lamberti <[email protected]>. Documented by jsdoc-to-markdown.