Class: StreamrClient
The main API used to interact with Streamr.
Constructors
new StreamrClient()
new StreamrClient(
config):StreamrClient
Parameters
config
StreamrClientConfig = {}
Returns
Properties
id
readonlyid:string
generateEthereumAccount()
readonlystaticgenerateEthereumAccount: () =>object=_generateEthereumAccount
Returns
object
address
address:
string
privateKey
privateKey:
string
Methods
Important
createStream()
createStream(
propsOrStreamIdOrPath):Promise<Stream>
Creates a new stream.
Parameters
propsOrStreamIdOrPath
the stream id to be used for the new stream, and optionally, any associated metadata
string | StreamMetadata & object
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
props
the stream id to get or create. Field partitions is only used if creating the stream.
id
string
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
streamIdOrPath
string
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
streamDefinition?
leave 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
streamDefinition
the stream or stream partition to publish the message to
content
unknown
the content (the payload) of the message (must be JSON serializable)
metadata?
provide additional metadata to be included in the message or to control the publishing process
Returns
Promise<Message>
the published message (note: the field Message.content is encrypted if the stream is private)
resend()
resend(
streamDefinition,options,onMessage?):Promise<MessageStream>
Performs a resend of stored historical data.
Parameters
streamDefinition
the stream partition for which data should be resent
options
defines the kind of resend that should be performed
onMessage?
callback 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
options
the stream or stream partition to subscribe to, additionally a resend can be performed by providing resend options
onMessage?
callback 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
streamDefinitionOrSubscription?
leave as undefined to unsubscribe from all existing subscriptions.
StreamDefinition | Subscription
Returns
Promise<unknown>
Remarks
no-op if subscription does not exist
Other
addEncryptionKey()
addEncryptionKey(
key,publisherId):Promise<void>
Adds an encryption key for a given publisher to the key store.
Parameters
key
publisherId
string
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,opts):Promise<void>
Assigns a stream to a storage node.
Parameters
streamIdOrPath
string
storageNodeAddress
string
opts
control how long to wait for storage node to pick up on assignment
timeout
number
wait
boolean
Returns
Promise<void>
If opts.wait=true, the promise resolves when the storage node acknowledges the assignment and
is therefore ready to store published messages. If we don't receive the acknowledgment within the timeout,
the promise rejects, but the assignment may still succeed later.
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
streamIdOrPath
string
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.
getAddress()
getAddress():
Promise<string>
Alias to getUserId()
Returns
Promise<string>
getDiagnosticInfo()
getDiagnosticInfo():
Promise<Record<string,unknown>>
Get diagnostic info about the underlying network. Useful for debugging issues.
Returns
Promise<Record<string, unknown>>
Remarks
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.
The Overrides type is from the ethers library.
Returns
Promise<Overrides>
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
streamIdOrPath
string
Returns
Promise<PermissionAssignment[]>
getSigner()
getSigner():
Promise<SignerWithProvider>
Gets the Signer associated with the current StreamrClient instance.
Returns
Promise<SignerWithProvider>
getStorageNodeMetadata()
getStorageNodeMetadata(
storageNodeAddress):Promise<StorageNodeMetadata>
Gets the metadata of a storage node from the storage node registry.
Parameters
storageNodeAddress
string
Returns
Promise<StorageNodeMetadata>
rejects if the storage node is not found
getStorageNodes()
getStorageNodes(
streamIdOrPath?):Promise<string[]>
Gets a list of storage nodes.
Parameters
streamIdOrPath?
string
if 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<string[]>
getStoredStreams()
getStoredStreams(
storageNodeAddress):Promise<{blockNumber:number;streams:Stream[]; }>
Gets all streams assigned to a storage node.
Parameters
storageNodeAddress
string
Returns
Promise<{ blockNumber: number; streams: Stream[]; }>
a list of Stream as well as blockNumber of result (i.e. blockchain state)
getStreamMetadata()
getStreamMetadata(
streamIdOrPath):Promise<StreamMetadata>
Returns the metadata of a stream.
Parameters
streamIdOrPath
string
Returns
Promise<StreamMetadata>
getStreamPublishers()
getStreamPublishers(
streamIdOrPath):AsyncIterable<string>
Gets all user ids that have StreamPermission.PUBLISH permission to the stream.
Parameters
streamIdOrPath
string
Returns
AsyncIterable<string>
getStreamSubscribers()
getStreamSubscribers(
streamIdOrPath):AsyncIterable<string>
Gets all user ids that have StreamPermission.SUBSCRIBE permission to the stream.
Parameters
streamIdOrPath
string
Returns
AsyncIterable<string>
getUserId()
getUserId():
Promise<string>
Gets the user id (i.e. Ethereum address) of the wallet associated with the current StreamrClient instance.
Returns
Promise<string>
grantPermissions()
grantPermissions(
streamIdOrPath, ...assignments):Promise<void>
Grants permissions on a given stream.
Parameters
streamIdOrPath
string
assignments
...PermissionAssignment[]
Returns
Promise<void>
hasPermission()
hasPermission(
query):Promise<boolean>
Checks whether the given permission is in effect.
Parameters
query
Returns
Promise<boolean>
inspect()
inspect(
node,streamDefinition):Promise<boolean>
Parameters
node
streamDefinition
Returns
Promise<boolean>
isStoredStream()
isStoredStream(
streamIdOrPath,storageNodeAddress):Promise<boolean>
Checks whether a stream is assigned to a storage node.
Parameters
streamIdOrPath
string
storageNodeAddress
string
Returns
Promise<boolean>
isStreamPublisher()
isStreamPublisher(
streamIdOrPath,userId):Promise<boolean>
Checks whether a given ethereum address has StreamPermission.PUBLISH permission to a stream.
Parameters
streamIdOrPath
string
userId
string
Returns
Promise<boolean>
isStreamSubscriber()
isStreamSubscriber(
streamIdOrPath,userId):Promise<boolean>
Checks whether a given ethereum address has StreamPermission.SUBSCRIBE permission to a stream.
Parameters
streamIdOrPath
string
userId
string
Returns
Promise<boolean>
off()
off<
T>(eventName,listener):void
Removes an event listener from the client.
Type Parameters
• T extends keyof StreamrClientEvents
Parameters
eventName
T
event name, see StreamrClientEvents for options
listener
the callback function to remove
Returns
void
on()
on<
T>(eventName,listener):void
Adds an event listener to the client.
Type Parameters
• T extends keyof StreamrClientEvents
Parameters
eventName
T
event name, see StreamrClientEvents for options
listener
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
• T extends keyof StreamrClientEvents
Parameters
eventName
T
event name, see StreamrClientEvents for options
listener
the callback function
Returns
void
removeStreamFromStorageNode()
removeStreamFromStorageNode(
streamIdOrPath,storageNodeAddress):Promise<void>
Unassigns a stream from a storage node.
Parameters
streamIdOrPath
string
storageNodeAddress
string
Returns
Promise<void>
revokePermissions()
revokePermissions(
streamIdOrPath, ...assignments):Promise<void>
Revokes permissions on a given stream.
Parameters
streamIdOrPath
string
assignments
...PermissionAssignment[]
Returns
Promise<void>
searchStreams()
searchStreams(
term,permissionFilter,orderBy):AsyncIterable<Stream>
Searches for streams based on given criteria.
Parameters
term
a search term that should be part of the stream id of a result
undefined | string
permissionFilter
permissions that should be in effect for a result
undefined | SearchStreamsPermissionFilter
orderBy
SearchStreamsOrderBy = ...
the 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
items
...object[]
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
streamDefinition
nodes
direction
connectionCount?
number
Returns
Promise<void>
setStorageNodeMetadata()
setStorageNodeMetadata(
metadata):Promise<void>
Sets the metadata of a storage node in the storage node registry.
Parameters
metadata
if undefined, removes the storage node from the registry
undefined | StorageNodeMetadata
Returns
Promise<void>
Remarks
Acts on behalf of the wallet associated with the current StreamrClient instance.
setStreamMetadata()
setStreamMetadata(
streamIdOrPath,metadata):Promise<void>
Updates the metadata of a stream.
Parameters
streamIdOrPath
string
metadata
Returns
Promise<void>
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
streamDefinition
entryPoints
Returns
Promise<void>
updateEncryptionKey()
updateEncryptionKey(
opts):Promise<void>
Manually updates the encryption key used when publishing messages to a given stream.
Parameters
opts
Returns
Promise<void>
waitForStorage()
waitForStorage(
message,options?):Promise<void>
Waits for a message to be stored by a storage node.
Parameters
message
the message to be awaited for
options?
additional options for controlling waiting and message matching
count
number
Controls size of internal resend used in polling.
interval
number
Determines how often should storage node be polled.
timeout
number
Timeout after which to give up if message was not seen.
Returns
Promise<void>
rejects if message was found in storage before timeout