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.