Class: StreamrClient
The main API used to interact with Streamr.
Constructors
constructor
• new StreamrClient(config?)
Parameters
| Name | Type |
|---|---|
config | StreamrClientConfig |
Properties
id
• Readonly id: string
generateEthereumAccount
▪ Static Readonly generateEthereumAccount: () => { address: string ; privateKey: string } = _generateEthereumAccount
Type declaration
▸ (): Object
Returns
Object
| Name | Type |
|---|---|
address | string |
privateKey | string |
Important Methods
createStream
▸ createStream(propsOrStreamIdOrPath): Promise\<Stream>
Creates a new stream.
Parameters
| Name | Type | Description |
|---|---|---|
propsOrStreamIdOrPath | string | 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
| Name | Type | Description |
|---|---|---|
props | Object | the stream id to get or create. Field partitions is only used if creating the stream. |
props.id | string | - |
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
| Name | Type |
|---|---|
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
| Name | Type | Description |
|---|---|---|
streamDefinition? | 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
| Name | Type | Description |
|---|---|---|
streamDefinition | 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? | PublishMetadata | provide 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
| Name | Type | Description |
|---|---|---|
streamDefinition | StreamDefinition | the stream partition for which data should be resent |
options | ResendOptions | defines the kind of resend that should be performed |
onMessage? | MessageListener | 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
| Name | Type | Description |
|---|---|---|
options | SubscribeOptions | the stream or stream partition to subscribe to, additionally a resend can be performed by providing resend options |
onMessage? | MessageListener | 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
| Name | Type | Description |
|---|---|---|
streamDefinitionOrSubscription? | StreamDefinition | Subscription | leave 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
| Name | Type |
|---|---|
key | EncryptionKey |
publisherId | EthereumAddress |
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
| Name | Type |
|---|---|
streamIdOrPath | string |
storageNodeAddress | string |
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
| Name | Type |
|---|---|
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\<EthereumAddress>
Gets the Ethereum address of the wallet associated with the current StreamrClient instance.
Returns
Promise\<EthereumAddress>
getConfig
▸ getConfig(): StrictStreamrClientConfig
Returns
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(): Overrides
Get overrides for transaction options. Use as a parameter when submitting transactions via ethers library.
Returns
getNode
▸ getNode(): Promise\<NetworkNodeStub>
Returns
Promise\<NetworkNodeStub>
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
| Name | Type |
|---|---|
streamIdOrPath | string |
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
| Name | Type |
|---|---|
nodeAddress | string |
Returns
Promise\<StorageNodeMetadata>
rejects if the storage node is not found
getStorageNodes
▸ getStorageNodes(streamIdOrPath?): Promise\<EthereumAddress[]>
Gets a list of storage nodes.
Parameters
| Name | Type | Description |
|---|---|---|
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\<EthereumAddress[]>
getStoredStreams
▸ getStoredStreams(storageNodeAddress): Promise\<{ blockNumber: number ; streams: Stream[] }>
Gets all streams assigned to a storage node.
Parameters
| Name | Type |
|---|---|
storageNodeAddress | string |
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
| Name | Type |
|---|---|
streamIdOrPath | string |
Returns
AsyncIterable\<EthereumAddress>
getStreamSubscribers
▸ getStreamSubscribers(streamIdOrPath): AsyncIterable\<EthereumAddress>
Gets all ethereum addresses that have SUBSCRIBE permission to the stream.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
Returns
AsyncIterable\<EthereumAddress>
grantPermissions
▸ grantPermissions(streamIdOrPath, ...assignments): Promise\<void>
Grants permissions on a given stream.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
...assignments | PermissionAssignment[] |
Returns
Promise\<void>
hasPermission
▸ hasPermission(query): Promise\<boolean>
Checks whether the given permission is in effect.
Parameters
| Name | Type |
|---|---|
query | PermissionQuery |
Returns
Promise\<boolean>
inspect
▸ inspect(node, streamDefinition): Promise\<boolean>
Parameters
| Name | Type |
|---|---|
node | NetworkPeerDescriptor |
streamDefinition | StreamDefinition |
Returns
Promise\<boolean>
isStoredStream
▸ isStoredStream(streamIdOrPath, storageNodeAddress): Promise\<boolean>
Checks whether a stream is assigned to a storage node.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
storageNodeAddress | string |
Returns
Promise\<boolean>
isStreamPublisher
▸ isStreamPublisher(streamIdOrPath, userAddress): Promise\<boolean>
Checks whether a given ethereum address has PUBLISH permission to a stream.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
userAddress | string |
Returns
Promise\<boolean>
isStreamSubscriber
▸ isStreamSubscriber(streamIdOrPath, userAddress): Promise\<boolean>
Checks whether a given ethereum address has SUBSCRIBE permission to a stream.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
userAddress | string |
Returns
Promise\<boolean>
off
▸ off\<T>(eventName, listener): void
Removes an event listener from the client.
Type parameters
| Name | Type |
|---|---|
T | extends keyof StreamrClientEvents |
Parameters
| Name | Type | Description |
|---|---|---|
eventName | T | event name, see StreamrClientEvents for options |
listener | StreamrClientEvents[T] | the callback function to remove |
Returns
void
on
▸ on\<T>(eventName, listener): void
Adds an event listener to the client.
Type parameters
| Name | Type |
|---|---|
T | extends keyof StreamrClientEvents |
Parameters
| Name | Type | Description |
|---|---|---|
eventName | T | event name, see StreamrClientEvents for options |
listener | StreamrClientEvents[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
| Name | Type |
|---|---|
T | extends keyof StreamrClientEvents |
Parameters
| Name | Type | Description |
|---|---|---|
eventName | T | event name, see StreamrClientEvents for options |
listener | StreamrClientEvents[T] | the callback function |
Returns
void
removeStreamFromStorageNode
▸ removeStreamFromStorageNode(streamIdOrPath, storageNodeAddress): Promise\<void>
Unassigns a stream from a storage node.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
storageNodeAddress | string |
Returns
Promise\<void>
revokePermissions
▸ revokePermissions(streamIdOrPath, ...assignments): Promise\<void>
Revokes permissions on a given stream.
Parameters
| Name | Type |
|---|---|
streamIdOrPath | string |
...assignments | PermissionAssignment[] |
Returns
Promise\<void>
searchStreams
▸ searchStreams(term, permissionFilter, orderBy?): AsyncIterable\<Stream>
Searches for streams based on given criteria.
Parameters
| Name | Type | Description |
|---|---|---|
term | undefined | string | a search term that should be part of the stream id of a result |
permissionFilter | undefined | SearchStreamsPermissionFilter | permissions that should be in effect for a result |
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
| Name | Type |
|---|---|
...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
| Name | Type |
|---|---|
streamDefinition | StreamDefinition |
nodes | NetworkPeerDescriptor[] |
direction | ProxyDirection |
connectionCount? | number |
Returns
Promise\<void>
setStorageNodeMetadata
▸ setStorageNodeMetadata(metadata): Promise\<void>
Sets the metadata of a storage node in the storage node registry.
Parameters
| Name | Type | Description |
|---|---|---|
metadata | undefined | StorageNodeMetadata | if 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
| Name | Type |
|---|---|
streamDefinition | StreamDefinition |
entryPoints | NetworkPeerDescriptor[] |
Returns
Promise\<void>
updateEncryptionKey
▸ updateEncryptionKey(opts): Promise\<void>
Manually updates the encryption key used when publishing messages to a given stream.
Parameters
| Name | Type |
|---|---|
opts | UpdateEncryptionKeyOptions |
Returns
Promise\<void>
updateStream
▸ updateStream(props): Promise\<Stream>
Updates the metadata of a stream.
Parameters
| Name | Type | Description |
|---|---|---|
props | Partial\<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
| Name | Type | Description |
|---|---|---|
message | Message | the message to be awaited for |
options? | Object | additional options for controlling waiting and message matching |
options.count? | number | Controls size of internal resend used in polling. |
options.interval? | number | Determines how often should storage node be polled. |
options.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