Skip to main content

Class: StreamrClient

The main API used to interact with Streamr.

Constructors

constructor

new StreamrClient(config?)

Parameters

NameType
configStreamrClientConfig

Properties

id

Readonly id: string


generateEthereumAccount

Static Readonly generateEthereumAccount: () => { address: string ; privateKey: string } = _generateEthereumAccount

Type declaration

▸ (): Object

Returns

Object

NameType
addressstring
privateKeystring

Important Methods

createStream

createStream(propsOrStreamIdOrPath): Promise\<Stream>

Creates a new stream.

Parameters

NameTypeDescription
propsOrStreamIdOrPathstring | Partial\<StreamMetadata> & { id: string }the stream id to be used for the new stream, and optionally, any associated metadata

Returns

Promise\<Stream>

Remarks

when creating a stream with an ENS domain, the returned promise can take several minutes to settle


getOrCreateStream

getOrCreateStream(props): Promise\<Stream>

Gets a stream, creating one if it does not exist.

Parameters

NameTypeDescription
propsObjectthe stream id to get or create. Field partitions is only used if creating the stream.
props.idstring-
props.partitions?number-

Returns

Promise\<Stream>

Remarks

when creating a stream with an ENS domain, the returned promise can take several minutes to settle


getStream

getStream(streamIdOrPath): Promise\<Stream>

Gets a stream.

Parameters

NameType
streamIdOrPathstring

Returns

Promise\<Stream>

rejects if the stream is not found


getSubscriptions

getSubscriptions(streamDefinition?): Promise\<Subscription[]>

Returns a list of subscriptions matching the given criteria.

Parameters

NameTypeDescription
streamDefinition?StreamDefinitionleave as undefined to get all subscriptions

Returns

Promise\<Subscription[]>


publish

publish(streamDefinition, content, metadata?): Promise\<Message>

Publishes a message to a stream partition in the network.

Parameters

NameTypeDescription
streamDefinitionStreamDefinitionthe stream or stream partition to publish the message to
contentunknownthe content (the payload) of the message (must be JSON serializable)
metadata?PublishMetadataprovide additional metadata to be included in the message or to control the publishing process

Returns

Promise\<Message>

the published message (note: the field content is encrypted if the stream is private)


resend

resend(streamDefinition, options, onMessage?): Promise\<MessageStream>

Performs a resend of stored historical data.

Parameters

NameTypeDescription
streamDefinitionStreamDefinitionthe stream partition for which data should be resent
optionsResendOptionsdefines the kind of resend that should be performed
onMessage?MessageListenercallback will be invoked for each message retrieved

Returns

Promise\<MessageStream>

a MessageStream that provides an alternative way of iterating messages. Rejects if the stream is not stored (i.e. is not assigned to a storage node).


subscribe

subscribe(options, onMessage?): Promise\<Subscription>

Subscribes to a stream partition in the network.

Parameters

NameTypeDescription
optionsSubscribeOptionsthe stream or stream partition to subscribe to, additionally a resend can be performed by providing resend options
onMessage?MessageListenercallback will be invoked for each message received in subscription

Returns

Promise\<Subscription>

a Subscription that can be used to manage the subscription etc.


unsubscribe

unsubscribe(streamDefinitionOrSubscription?): Promise\<unknown>

Unsubscribes from streams or stream partitions in the network.

Parameters

NameTypeDescription
streamDefinitionOrSubscription?StreamDefinition | Subscriptionleave as undefined to unsubscribe from all existing subscriptions.

Returns

Promise\<unknown>

Remarks

no-op if subscription does not exist


Other Methods

addEncryptionKey

addEncryptionKey(key, publisherId): Promise\<void>

Adds an encryption key for a given publisher to the key store.

Parameters

NameType
keyEncryptionKey
publisherIdEthereumAddress

Returns

Promise\<void>

Remarks

Keys will be added to the store automatically by the client as encountered. This method can be used to manually add some known keys into the store.


addStreamToStorageNode

addStreamToStorageNode(streamIdOrPath, storageNodeAddress): Promise\<void>

Assigns a stream to a storage node.

Parameters

NameType
streamIdOrPathstring
storageNodeAddressstring

Returns

Promise\<void>


connect

connect(): Promise\<void>

Used to manually initialize the network stack and connect to the network.

Returns

Promise\<void>

Remarks

Connecting is handled automatically by the client. Generally this method need not be called by the user.


deleteStream

deleteStream(streamIdOrPath): Promise\<void>

Deletes a stream.

Parameters

NameType
streamIdOrPathstring

Returns

Promise\<void>


destroy

destroy(): Promise\<void>

Destroys an instance of a StreamrClient by disconnecting from peers, clearing any pending tasks, and freeing up resources. This should be called once a user is done with the instance.

Returns

Promise\<void>

Remarks

As the name implies, the client instance (or any streams or subscriptions returned by it) should not be used after calling this method.


findOperators

findOperators(streamId): Promise\<NetworkPeerDescriptor[]>

Parameters

NameType
streamIdStreamID

Returns

Promise\<NetworkPeerDescriptor[]>


getAddress

getAddress(): Promise\<EthereumAddress>

Gets the Ethereum address of the wallet associated with the current StreamrClient instance.

Returns

Promise\<EthereumAddress>


getConfig

getConfig(): StrictStreamrClientConfig

Returns

StrictStreamrClientConfig

Deprecated

This in an internal method


getDiagnosticInfo

getDiagnosticInfo(): Promise\<Record\<string, unknown>>

Get diagnostic info about the underlying network. Useful for debugging issues.

Returns

Promise\<Record\<string, unknown>>

Remark

returned object's structure can change without semver considerations


getEthersOverrides

getEthersOverrides(): Promise\<Overrides>

Get overrides for transaction options. Use as a parameter when submitting transactions via ethers library.

Returns

Promise\<Overrides>


getNode

getNode(): NetworkNodeFacade

Returns

NetworkNodeFacade

Deprecated

This in an internal method


getNodeId

getNodeId(): Promise\<DhtAddress>

Get the network-level node id of the client.

Returns

Promise\<DhtAddress>


getPeerDescriptor

getPeerDescriptor(): Promise\<NetworkPeerDescriptor>

Returns

Promise\<NetworkPeerDescriptor>


getPermissions

getPermissions(streamIdOrPath): Promise\<PermissionAssignment[]>

Returns the list of all permissions in effect for a given stream.

Parameters

NameType
streamIdOrPathstring

Returns

Promise\<PermissionAssignment[]>


getSigner

getSigner(): Promise\<SignerWithProvider>

Gets the Signer associated with the current StreamrClient instance.

Returns

Promise\<SignerWithProvider>


getStorageNodeMetadata

getStorageNodeMetadata(nodeAddress): Promise\<StorageNodeMetadata>

Gets the metadata of a storage node from the storage node registry.

Parameters

NameType
nodeAddressstring

Returns

Promise\<StorageNodeMetadata>

rejects if the storage node is not found


getStorageNodes

getStorageNodes(streamIdOrPath?): Promise\<EthereumAddress[]>

Gets a list of storage nodes.

Parameters

NameTypeDescription
streamIdOrPath?stringif a stream is given, returns the list of storage nodes the stream has been assigned to; leave as undefined to return all storage nodes

Returns

Promise\<EthereumAddress[]>


getStoredStreams

getStoredStreams(storageNodeAddress): Promise\<{ blockNumber: number ; streams: Stream[] }>

Gets all streams assigned to a storage node.

Parameters

NameType
storageNodeAddressstring

Returns

Promise\<{ blockNumber: number ; streams: Stream[] }>

a list of Stream as well as blockNumber of result (i.e. blockchain state)


getStreamPublishers

getStreamPublishers(streamIdOrPath): AsyncIterable\<EthereumAddress>

Gets all ethereum addresses that have PUBLISH permission to the stream.

Parameters

NameType
streamIdOrPathstring

Returns

AsyncIterable\<EthereumAddress>


getStreamSubscribers

getStreamSubscribers(streamIdOrPath): AsyncIterable\<EthereumAddress>

Gets all ethereum addresses that have SUBSCRIBE permission to the stream.

Parameters

NameType
streamIdOrPathstring

Returns

AsyncIterable\<EthereumAddress>


grantPermissions

grantPermissions(streamIdOrPath, ...assignments): Promise\<void>

Grants permissions on a given stream.

Parameters

NameType
streamIdOrPathstring
...assignmentsPermissionAssignment[]

Returns

Promise\<void>


hasPermission

hasPermission(query): Promise\<boolean>

Checks whether the given permission is in effect.

Parameters

NameType
queryPermissionQuery

Returns

Promise\<boolean>


inspect

inspect(node, streamDefinition): Promise\<boolean>

Parameters

NameType
nodeNetworkPeerDescriptor
streamDefinitionStreamDefinition

Returns

Promise\<boolean>


isStoredStream

isStoredStream(streamIdOrPath, storageNodeAddress): Promise\<boolean>

Checks whether a stream is assigned to a storage node.

Parameters

NameType
streamIdOrPathstring
storageNodeAddressstring

Returns

Promise\<boolean>


isStreamPublisher

isStreamPublisher(streamIdOrPath, userAddress): Promise\<boolean>

Checks whether a given ethereum address has PUBLISH permission to a stream.

Parameters

NameType
streamIdOrPathstring
userAddressstring

Returns

Promise\<boolean>


isStreamSubscriber

isStreamSubscriber(streamIdOrPath, userAddress): Promise\<boolean>

Checks whether a given ethereum address has SUBSCRIBE permission to a stream.

Parameters

NameType
streamIdOrPathstring
userAddressstring

Returns

Promise\<boolean>


off

off\<T>(eventName, listener): void

Removes an event listener from the client.

Type parameters

NameType
Textends keyof StreamrClientEvents

Parameters

NameTypeDescription
eventNameTevent name, see StreamrClientEvents for options
listenerStreamrClientEvents[T]the callback function to remove

Returns

void


on

on\<T>(eventName, listener): void

Adds an event listener to the client.

Type parameters

NameType
Textends keyof StreamrClientEvents

Parameters

NameTypeDescription
eventNameTevent name, see StreamrClientEvents for options
listenerStreamrClientEvents[T]the callback function

Returns

void


once

once\<T>(eventName, listener): void

Adds an event listener to the client that is invoked only once.

Type parameters

NameType
Textends keyof StreamrClientEvents

Parameters

NameTypeDescription
eventNameTevent name, see StreamrClientEvents for options
listenerStreamrClientEvents[T]the callback function

Returns

void


removeStreamFromStorageNode

removeStreamFromStorageNode(streamIdOrPath, storageNodeAddress): Promise\<void>

Unassigns a stream from a storage node.

Parameters

NameType
streamIdOrPathstring
storageNodeAddressstring

Returns

Promise\<void>


revokePermissions

revokePermissions(streamIdOrPath, ...assignments): Promise\<void>

Revokes permissions on a given stream.

Parameters

NameType
streamIdOrPathstring
...assignmentsPermissionAssignment[]

Returns

Promise\<void>


searchStreams

searchStreams(term, permissionFilter, orderBy?): AsyncIterable\<Stream>

Searches for streams based on given criteria.

Parameters

NameTypeDescription
termundefined | stringa search term that should be part of the stream id of a result
permissionFilterundefined | SearchStreamsPermissionFilterpermissions that should be in effect for a result
orderBySearchStreamsOrderBythe default is ascending order by stream id field

Returns

AsyncIterable\<Stream>


setPermissions

setPermissions(...items): Promise\<void>

Sets a list of permissions to be in effect.

Parameters

NameType
...items{ assignments: PermissionAssignment[] ; streamId: string }[]

Returns

Promise\<void>

Remarks

Can be used to set the permissions of multiple streams in one transaction. Great for doing bulk operations and saving gas costs. Notice that the behaviour is overwriting, therefore any existing permissions not defined will be removed (per stream).


setProxies

setProxies(streamDefinition, nodes, direction, connectionCount?): Promise\<void>

Parameters

NameType
streamDefinitionStreamDefinition
nodesNetworkPeerDescriptor[]
directionProxyDirection
connectionCount?number

Returns

Promise\<void>


setStorageNodeMetadata

setStorageNodeMetadata(metadata): Promise\<void>

Sets the metadata of a storage node in the storage node registry.

Parameters

NameTypeDescription
metadataundefined | StorageNodeMetadataif undefined, removes the storage node from the registry

Returns

Promise\<void>

Remarks

Acts on behalf of the wallet associated with the current StreamrClient instance.


setStreamPartitionEntryPoints

setStreamPartitionEntryPoints(streamDefinition, entryPoints): Promise\<void>

Used to set known entry points for a stream partition. If entry points are not set they will be automatically discovered from the Streamr Network.

Parameters

NameType
streamDefinitionStreamDefinition
entryPointsNetworkPeerDescriptor[]

Returns

Promise\<void>


updateEncryptionKey

updateEncryptionKey(opts): Promise\<void>

Manually updates the encryption key used when publishing messages to a given stream.

Parameters

NameType
optsUpdateEncryptionKeyOptions

Returns

Promise\<void>


updateStream

updateStream(props): Promise\<Stream>

Updates the metadata of a stream.

Parameters

NameTypeDescription
propsPartial\<StreamMetadata> & { id: string }the stream id and the metadata fields to be updated

Returns

Promise\<Stream>


waitForStorage

waitForStorage(message, options?): Promise\<void>

Waits for a message to be stored by a storage node.

Parameters

NameTypeDescription
messageMessagethe message to be awaited for
options?Objectadditional options for controlling waiting and message matching
options.count?numberControls size of internal resend used in polling.
options.interval?numberDetermines how often should storage node be polled.
options.timeout?numberTimeout after which to give up if message was not seen.

Returns

Promise\<void>

rejects if message was found in storage before timeout