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.
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.
The option --provider
must be set in all commands. It should be set to the URL of an IOTA full node supporting POW.
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
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
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>
- .changeMode ⇒
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. |
Kind: static property of mamClient
Returns: string
- the root address of the channels next message.
Param | Type | Description |
---|---|---|
mam | Object |
the MAM state. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
The types listed below are used by the mam tools.
- types
- ~MAMClient :
Object
- ~ChangeModeState :
Object
- ~PublishResponse :
Object
- ~MessageResponse :
Object
- ~MAMClient :
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. |
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. |
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. |
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.