Skip to content

tools to make using IOTAs MAM more easy

License

Notifications You must be signed in to change notification settings

TangleID/mam.tools.js

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

7 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

npm

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')

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

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 <lamberti.robin@gmail.com>. Documented by jsdoc-to-markdown.

About

tools to make using IOTAs MAM more easy

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%