Skip to main content

API Reference

Contents

The API is spread out across three categories:

Author

Main user implementation of a Channel. Generates the channel, processes subscriptions and manages them. It can also send and fetch messages.

new(seed, options, channel_type): Author

Generates an Author instance

ParamTypeDescription
seedstringUnique user seed
optionsSendOptionsOptions for Client
implementationChannelTypeChannel Type

Returns: An Author instance for administrating a channel.

from_client(client, seed, implementation): Author

Create an Author instance from a client

ParamTypeDescription
clientClientA Client Instance
seedstringUnique user seed
implementationChannelTypeChannel Type

Returns: An Author instance for administrating a channel.

import(client, bytes, password): Author

Import an Author instance from an encrypted binary array

ParamTypeDescription
clientClientA Client Instance
bytesUint8ArrayExported binary of author
passwordstringKey to decrypt binary

Returns: A recovered Author instance for administrating a channel.

export(password): Uint8Array

Export an Author instance as an encrypted array using a given password

ParamTypeDescription
passwordstringKey to encrypt

Returns: Binary array representing an encrypted state of the author.

recover(seed, ann_address, implementation, options): Author

Recover an Author instance from scratch using the known startup configurations

ParamTypeDescription
seedstringUnique user seed
ann_addressAddressAnnouncement message address for validation
implementationChannelTypeChannel Type
optionsSendOptionsOptions for Client

Returns: A recovered Author instance for administrating a channel.

clone(): Author

Generate a copy of the Author instance for consumption by asynchronous functions

ParamTypeDescription

Returns: A consumable Author instance for functions.

channel_address(): string

Return the channel address of the channel instance.

ParamTypeDescription

Returns: Channel Address for user generated channel.

Return the announcement link of the channel instance.

ParamTypeDescription

Returns: Announcement Address for user generated channel.

is_multi_branching(): bool

Check if a channel type is single branching or multi branching.

ParamTypeDescription

Returns: Boolean representing the channel type: false=single branch, true=multi branch.

get_public_key(): string

Retrieve the Author public key.

ParamTypeDescription

Returns: The Author public key in hex representation.

fetch_state(): Array<UserState>

Retrieve the currently known publisher states for the channel.

ParamTypeDescription

Returns: An array of user state objects representing the currently known state of all publishers in the channel.

info

The following functions require author.clone() to use, as they consume the instance

async - send_announce(): UserResponse

Send an announcement message, initialising the channel

ParamTypeDescription

Returns: A User Response wrapper around the announcement message.

Send a keyload message for all subscribed participants in the channel, linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to

Returns: A User Response wrapper around the keyload message.

Send a keyload message for specified subscribers and pre shared keys in the channel, linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to
psk_idsPskIdsPskIds instance
sig_pksPublicKeysPublicKeys instance

Returns: A User Response wrapper around the keyload message.

Send a tagged packet message linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to
public_payloadUint8ArrayByte array of public payload for message
masked_payloadUint8ArrayByte array of masked payload for message

Returns: A User Response wrapper around the tagged packet message.

Send a signed packet message linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to
public_payloadUint8ArrayByte array of public payload for message
masked_payloadUint8ArrayByte array of masked payload for message

Returns: A User Response wrapper around the signed packet message.

Process a subscription message by its link.

ParamTypeDescription
linkaddressAddress of subscription message

Process an unsubscription message by its link.

ParamTypeDescription
linkaddressAddress of unsubscription message

Receive a tagged packet by its link.

ParamTypeDescription
linkaddressAddress of tagged packet message

Returns: A User Response wrapper around the tagged packet message.

Receive a signed packet by its link.

ParamTypeDescription
linkaddressAddress of signed packet message

Returns: A User Response wrapper around the signed packet message.

Receive a sequence message by its link, and return the address of the sequenced message.

ParamTypeDescription
linkaddressAddress of tagged packet message

Returns: The address link of the sequenced message.

Receive a message generically without knowing its type.

ParamTypeDescription
linkaddressAddress of the message to be fetched

Returns: A User Response wrapper around the retrieved message.

Receive a message by its msg number in an anchored single depth channel.

ParamTypeDescription
anchor_linkaddressAnchor message link for the channel
msg_numnumberNumber of the message being retrieved

Returns: A User Response wrapper around the retrieved message.

async - sync_state()

Synchronise a publishers state prior to sending another message. Retrieves any other messages from the channel to ensure the user state matches all other publishers.

ParamTypeDescription

async - fetch_next_msgs(): Array<UserResponse>

Fetch all the next messages pending to be received by the user (empty array if none are present).

ParamTypeDescription

Returns: An array of User Response wrappers around the retrieved messages.

Fetch the previous message sent before the provided message link.

ParamTypeDescription
linkaddressAddress off message to begin fetching from

Returns: A User Response wrapper around the retrieved message.

Fetch a defined number of previous messages in a channel.

ParamTypeDescription
linkaddressAddress off message to begin fetching from
maxnumberMax number of messages to fetch

Returns: An array of User Response wrappers around the retrieved messages.

store_psk(psk): String

Store a Pre Shared Key (Psk) and retrieve the Pre Shared Key Id (PskId) for use in keyload messages | Param | Type | Description | | --------------- | ----------------------------- | ----------------------------------- | | psk | String | Pre shared key in string format |

Returns: A PskId String representing the Psk in store.

remove_psk(pskid)

Removes a Pre Shared Key (Psk) from the Author instance using a Pre Shared Key Id (PskId)

ParamTypeDescription
pskidStringPskId string representing the Psk in store

store_new_subscriber(pk)

Store the ed25519 Public Key identifier of a predefined subscriber into the Author instance

ParamTypeDescription
pkStringPublic Key string of Subscriber

auth_remove_subscriber(pk)

Removes a Subscriber from the Author instance using their ed25519 Public Key

ParamTypeDescription
pkStringPublic Key string of Subscriber

reset_state()

Reset the mapping of known publisher states for the channel for retrieval of messages from scratch.

ParamTypeDescription

Subscriber

Additional user implementations of a Channel. Can publish and read from public branches, and branches that have been restricted by keyload messages that contain their public key.

new(seed, options): Subscriber

Generates a Subscriber instance

ParamTypeDescription
seedstringUnique user seed
optionsSendOptionsOptions for Client

Returns: A Subscriber instance.

from_client(client, seed): Subscriber

Create a Subscriber instance from a client

ParamTypeDescription
clientClientA Client Instance
seedstringUnique user seed

Returns: A Subscriber instance.

import(client, bytes, password): Subscriber

Import a Subscriber instance from an encrypted binary array

ParamTypeDescription
clientClientA Client Instance
bytesUint8ArrayExported binary of author
passwordstringKey to decrypt binary

Returns: A recovered Subscriber instance.

export(password): Uint8Array

Export a Subscriber instance as an encrypted array using a given password

ParamTypeDescription
passwordstringKey to encrypt

Returns: Binary array representing an encrypted state of the subscriber.

clone(): Subscriber

Generate a copy of the Subscriber instance for consumption by asynchronous functions

ParamTypeDescription

Returns: A consumable Subscriber instance for functions.

channel_address(): string

Return the channel address of the channel instance.

ParamTypeDescription

Returns: Channel Address for user generated channel.

Return the announcement link of the channel instance.

ParamTypeDescription

Returns: Announcement Address for user generated channel.

is_multi_branching(): bool

Check if a channel type is single branching or multi branching.

ParamTypeDescription

Returns: Boolean representing the channel type: false=single branch, true=multi branch.

get_public_key(): string

Retrieve the Subscriber public key.

ParamTypeDescription

Returns: The Subscriber public key in hex representation.

author_public_key(): string

Retrieve the Author public key. Errors if no channel is registered.

ParamTypeDescription

Returns: The Subscriber public key in hex representation.

is_registered(): bool

Check if the subscriber instance has processed a channel announcement.

ParamTypeDescription

Returns: Boolean representing if the subscriber instance has processed a channel announcement correctly.

unregister()

Unregister a subscriber instance from a channel.

ParamTypeDescription

fetch_state(): Array<UserState>

Retrieve the currently known publisher states for the channel.

ParamTypeDescription

Returns: An array of user state objects representing the currently known state of all publishers in the channel.

info

The following functions require subscriber.clone() to use, as they consume the instance

Send a subscription message attached to an announcement message link.

ParamTypeDescription
linkaddressAddress of announcement message

Returns: A User Response wrapper around the subscribe message.

Send an unsubscription message attached to the user subscription message link.

ParamTypeDescription
linkaddressAddress of subscription message

Returns: A User Response wrapper around the unsubscribe message.

Send a tagged packet message linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to
public_payloadUint8ArrayByte array of public payload for message
masked_payloadUint8ArrayByte array of masked payload for message

Returns: A User Response wrapper around the tagged packet message.

Send a signed packet message linked to a previous message (usually the announcement in a multi branch).

ParamTypeDescription
linkaddressAddress of message being linked to
public_payloadUint8ArrayByte array of public payload for message
masked_payloadUint8ArrayByte array of masked payload for message

Returns: A User Response wrapper around the signed packet message.

Process an announcement message and register the channel.

ParamTypeDescription
linkaddressAddress of the announcement message

Receive a keyload by its link and return whether the subscriber has access beyond it or not.

ParamTypeDescription
linkaddressAddress of tagged packet message

Returns: Boolean representing access to the branch.

Receive a tagged packet by its link.

ParamTypeDescription
linkaddressAddress of tagged packet message

Returns: A User Response wrapper around the tagged packet message.

Receive a signed packet by its link.

ParamTypeDescription
linkaddressAddress of signed packet message

Returns: A User Response wrapper around the signed packet message.

Receive a sequence message by its link, and return the address of the sequenced message.

ParamTypeDescription
linkaddressAddress of tagged packet message

Returns: The address link of the sequenced message.

Receive a message generically without knowing its type.

ParamTypeDescription
linkaddressAddress of the message to be fetched

Returns: A User Response wrapper around the retrieved message.

Receive a message by its msg number in an anchored single depth channel.

ParamTypeDescription
anchor_linkaddressAnchor message link for the channel
msg_numnumberNumber of the message being retrieved

Returns: A User Response wrapper around the retrieved message.

async - sync_state()

Synchronise a publishers state prior to sending another message. Retrieves any other messages from the channel to ensure the user state matches all other publishers.

ParamTypeDescription

async - fetch_next_msgs(): Array<UserResponse>

Fetch all the next messages pending to be received by the user (empty array if none are present).

ParamTypeDescription

Returns: An array of User Response wrappers around the retrieved messages.

Fetch the previous message sent before the provided message link.

ParamTypeDescription
linkaddressAddress off message to begin fetching from

Returns: A User Response wrapper around the retrieved message.

Fetch a defined number of previous messages in a channel.

ParamTypeDescription
linkaddressAddress off message to begin fetching from
maxnumberMax number of messages to fetch

Returns: An array of User Response wrappers around the retrieved messages.

store_psk(psk): String

Store a Pre Shared Key (Psk) and retrieve the Pre Shared Key Id (PskId) for use in keyload messages | Param | Type | Description | | --------------- | ----------------------------- | ----------------------------------- | | psk | String | Pre shared key in string format |

Returns: A PskId String representing the Psk in store.

remove_psk(pskid)

Removes a Pre Shared Key (Psk) from the Author instance using a Pre Shared Key Id (PskId)

ParamTypeDescription
pskidStringPskId string representing the Psk in store

reset_state()

Reset the mapping of known publisher states for the channel for retrieval of messages from scratch.

ParamTypeDescription

Types

Generic Types and Primitives used in Wasm API:

Client

Transport client for interacting with an Iota node.

new(node, options): Client

ParamTypeDescription
nodestringA node URL
optionsSendOptionsOptions for Client

Returns: A client instance.

SendOptions

Options for a transport client

new(url, depth, local_pow, threads): SendOptions

Create a new set of Send Options for the client

ParamTypeDescription
urlstringA node URL
local_powboolPerform pow locally

Returns: Send Options for a client instance.

UserResponse

Response structure containing the details of a sent or retrieved message

Create a new User Response from the return of the rust api for sending and receiving messages.

ParamTypeDescription
linkAddressAddress link of message
seq_linkAddressSequence Address Link (can be undefined)
messageMessageSent or retrieved message (can be undefined)

Returns: User Response containing links and message.

Create a new User Response from the return of the rust api for sending and receiving messages, using strings for the link and seq_link inputs.

ParamTypeDescription
linkstringAddress string of message
seq_linkstringSequence Address string (can be undefined)
messageMessageSent or retrieved message (can be undefined)

Returns: User Response containing links and message.

copy(): UserResponse

Create a copy of the User Response

ParamTypeDescription

Returns: A copy of the User Response.

Fetch the sequence link of the retrieved or sent message (Default if there is none).

ParamTypeDescription

Returns: The link for the retrieved or sent message.

get_message(): Message

Fetch the retrieved or sent message (Default if there is none).

ParamTypeDescription

Returns: The retrieved or sent message.

Address

Streams Address containing the Application Instance and Message Id

set_addr_id(addr_id)

ParamTypeDescription
addr_idstringApplication instance of the channel

addr_id(): string

ParamTypeDescription

Returns: The Channel Identifier/Application Instance of the Address

set_msg_id(msg_id)

ParamTypeDescription
msg_idstringMessage Identifier of the message itself

msg_id(): string

ParamTypeDescription

Returns: The Message Identifier of the Address

from_string(address): Address

Make an Address object from a string representation

ParamTypeDescription
addressstringString representation of an Address

Returns: An Address object

to_string(): string

Return a string representation of an Address object

ParamTypeDescription

Returns: String representation of an Address

Message

A wrapper for a Rust Streams Message

default(): Message

Generate a default message object

ParamTypeDescription

Returns: A default Message object

new(pk, public_payload, masked_payload): Message

Make a Message object from the optional pk and the public and masked payloads

ParamTypeDescription
pkstring / undefinedOptional public key for message
public_payloadUint8ArrayPublic payload bytes
masked_payloadUint8ArrayMasked payload bytes

Returns: A Message wrapper object

get_public_key(): string

Fetch the public key of the Message sender (default if none is presented)

ParamTypeDescription

Returns: Public key in hex representation of the sender of the message

get_public_payload(): Uint8Array

Fetch the public payload of the Message sender

ParamTypeDescription

Returns: Public payload byte array

get_masked_payload(): Uint8Array

Fetch the masked payload of the Message sender

ParamTypeDescription

Returns: Masked payload byte array

NextMsgId

A wrapper for a Rust NextMsgId structure

new(identifier, msgid): NextMsgId

Make a NextMsgId object from the identifier and expected next message address

ParamTypeDescription
identifierstringIdentifier for expected message
msgidAddressAddress of expected next message

Returns: A NextMsgId wrapper object

get_identifier(): string

Fetch the identifier of the Message sender

ParamTypeDescription

Returns: Identifier in hex representation of the sender of the message

PskIds

An array of PskIds representing the Pre Shared Keys that are used in keyload messages.

new(): PskIds

Generate a new array of PskIds

ParamTypeDescription

Returns: Empty array for PskIds to be added to

add(pskid)

Add a pskid

ParamTypeDescription
pskidstringPskId string representation [must be 32 bytes]

get_ids(): Array<string>

Fetch PskIds in string formatting

ParamTypeDescription

Returns: Array of PskIds in string formatting

PublicKeys

An array of PublicKeys representing a set of users.

new(): PublicKeys

Generate a new array of PublicKeys

ParamTypeDescription

Returns: Empty array for PublicKeys to be added to

add(pk)

Add a public key string

ParamTypeDescription
pkstringPublic Key string representation

get_pks(): Array<string>

Fetch Public Keys in string formatting

ParamTypeDescription

Returns: Array of Public Keys in string formatting

Cursor

The publishing state of a particular publisher (The latest sequenced message known for that publisher). This includes:

  • The latest published message link
  • The sequence state number of the publisher
  • A branch number for that latest posted message

UserState

A wrapper around a publisher state. Includes the identifier and cursor of the publisher

get_identifier()

Get the public key of the user from the state

ParamTypeDescription

Returns: Identifier of publisher in hex formatting

Get the link from the internal cursor object

ParamTypeDescription

Returns: The latest published message link

get_seq_no()

Get the sequence state number from the internal cursor object

ParamTypeDescription

Returns: The latest sequence state number of the publisher

get_branch_no()

Get the branch state number from the internal cursor object

ParamTypeDescription

Returns: The latest branch state number of the publisher