@waku/interfaces 0.0.26-ce62600.0 → 0.0.26

package/src/protocols.ts

@@ -2,10 +2,10 @@ import type { Libp2p } from "@libp2p/interface";
 import type { PeerId } from "@libp2p/interface";
 import type { Peer, PeerStore } from "@libp2p/interface";
 
-import type { ShardInfo } from "./enr.js";
 import type { CreateLibp2pOptions } from "./libp2p.js";
 import type { IDecodedMessage } from "./message.js";
-import { PubsubTopic, ThisAndThat, ThisOrThat } from "./misc.js";
+import { ThisAndThat, ThisOrThat } from "./misc.js";
+import { AutoSharding, StaticSharding } from "./sharding.js";
 
 export enum Protocols {
   Relay = "relay",
@@ -15,7 +15,6 @@ export enum Protocols {
 }
 
 export type IBaseProtocolCore = {
-  shardInfo?: ShardInfo;
   multicodec: string;
   peerStore: PeerStore;
   allPeers: () => Promise<Peer[]>;
@@ -25,23 +24,12 @@ export type IBaseProtocolCore = {
 };
 
 export type IBaseProtocolSDK = {
-  renewPeer: (peerToDisconnect: PeerId) => Promise<Peer>;
   readonly connectedPeers: Peer[];
+  renewPeer: (peerToDisconnect: PeerId) => Promise<Peer>;
   readonly numPeersToUse: number;
 };
 
-export type ContentTopicInfo = {
-  clusterId?: number;
-  contentTopics: string[];
-};
-
-export type ApplicationInfo = {
-  clusterId: number;
-  application: string;
-  version: string;
-};
-
-export type ShardingParams = ShardInfo | ContentTopicInfo | ApplicationInfo;
+export type NetworkConfig = StaticSharding | AutoSharding;
 
 //TODO: merge this with ProtocolCreateOptions or establish distinction: https://github.com/waku-org/js-waku/issues/2048
 /**
@@ -72,34 +60,35 @@ export type ProtocolUseOptions = {
 
 export type ProtocolCreateOptions = {
   /**
-   * @deprecated
-   * Waku will stop supporting named sharding. Only static sharding and autosharding will be supported moving forward.
-   */
-  pubsubTopics?: PubsubTopic[];
-  /**
-   * Waku supports usage of multiple pubsub topics. This is achieved through static sharding for now, and auto-sharding in the future.
-   * The format to specify a shard is:
-   * clusterId: number, shards: number[]
-   * To learn more about the sharding specifications implemented, see [Relay Sharding](https://rfc.vac.dev/spec/51/).
-   * The Pubsub Topic to use. Defaults to {@link @waku/core!DefaultPubsubTopic }.
+   * Configuration for determining the network in use.
    *
-   * If no pubsub topic is specified, the default pubsub topic is used.
-   * The set of pubsub topics that are used to initialize the Waku node, will need to be used by the protocols as well
-   * You cannot currently add or remove pubsub topics after initialization.
-   * This is used by:
-   * - WakuRelay to receive, route and send messages,
-   * - WakuLightPush to send messages,
-   * - WakuStore to retrieve messages.
-   * See [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) for details.
+   * If using Static Sharding:
+   * Default value is configured for The Waku Network.
+   * The format to specify a shard is: clusterId: number, shards: number[]
+   * To learn more about the sharding specification, see [Relay Sharding](https://rfc.vac.dev/spec/51/).
    *
+   * If using Auto Sharding:
+   * See [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics) for details.
+   * You cannot add or remove content topics after initialization of the node.
    */
-  shardInfo?: Partial<ShardingParams>;
   /**
-   * Content topics are used to determine pubsubTopics
-   * If not provided pubsubTopics will be determined based on shardInfo
-   * See [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md) for details.
+   * Configuration for determining the network in use.
+   * Network configuration refers to the shards and clusters used in the network.
+   *
+   * If using Static Sharding:
+   * Cluster ID and shards are specified in the format: clusterId: number, shards: number[]
+   * The default value is configured for The Waku Network => clusterId: 0, shards: [0, 1, 2, 3, 4, 5, 6, 7]
+   * To learn more about the sharding specification, see [Relay Sharding](https://rfc.vac.dev/spec/51/).
+   *
+   * If using Auto Sharding:
+   * Cluster ID and content topics are specified in the format: clusterId: number, contentTopics: string[]
+   * Content topics are used to determine the shards to be configured for the network.
+   * Cluster ID is optional, and defaults to The Waku Network's cluster ID => 0
+   * To specify content topics, see [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#content-topics) for details
+   *
+   * @default { clusterId: 1, shards: [0, 1, 2, 3, 4, 5, 6, 7] }
    */
-  contentTopics?: string[];
+  networkConfig?: NetworkConfig;
   /**
    * You can pass options to the `Libp2p` instance used by {@link @waku/sdk!WakuNode} using the `libp2p` property.
    * This property is the same type as the one passed to [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create)
@@ -169,6 +158,11 @@ export enum ProtocolError {
    * Ensure that the pubsub topic used for decoder creation is the same as the one used for protocol.
    */
   TOPIC_DECODER_MISMATCH = "Topic decoder mismatch",
+  /**
+   * The topics passed in the decoders do not match each other, or don't exist at all.
+   * Ensure that all the pubsub topics used in the decoders are valid and match each other.
+   */
+  INVALID_DECODER_TOPICS = "Invalid decoder topics",
   /**
    * Failure to find a peer with suitable protocols. This may due to a connection issue.
    * Mitigation can be: retrying after a given time period, display connectivity issue
@@ -185,7 +179,7 @@ export enum ProtocolError {
    * The remote peer did not behave as expected. Mitigation for `NO_PEER_AVAILABLE`
    * or `DECODE_FAILED` can be used.
    */
-  REMOTE_PEER_FAULT = "Remote peer fault",
+  NO_RESPONSE = "No response received",
   /**
    * The remote peer rejected the message. Information provided by the remote peer
    * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
@@ -196,7 +190,27 @@ export enum ProtocolError {
    * The protocol request timed out without a response. This may be due to a connection issue.
    * Mitigation can be: retrying after a given time period
    */
-  REQUEST_TIMEOUT = "Request timeout"
+  REQUEST_TIMEOUT = "Request timeout",
+  /**
+   * Missing credentials info message.
+   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L186
+   */
+  RLN_IDENTITY_MISSING = "Identity credentials are not set",
+  /**
+   * Membership index missing info message.
+   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L188
+   */
+  RLN_MEMBERSHIP_INDEX = "Membership index is not set",
+  /**
+   * Message limit is missing.
+   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L190
+   */
+  RLN_LIMIT_MISSING = "User message limit is not set",
+  /**
+   * General proof generation error message.
+   * nwaku: https://github.com/waku-org/nwaku/blob/c3cb06ac6c03f0f382d3941ea53b330f6a8dd127/waku/waku_rln_relay/group_manager/group_manager_base.nim#L201C19-L201C42
+   */
+  RLN_PROOF_GENERATION = "Proof generation failed"
 }
 
 export interface Failure {

package/src/receiver.ts

@@ -13,8 +13,10 @@ export interface IReceiver {
   toSubscriptionIterator: <T extends IDecodedMessage>(
     decoders: IDecoder<T> | IDecoder<T>[]
   ) => Promise<IAsyncIterator<T>>;
-  subscribe: <T extends IDecodedMessage>(
-    decoders: IDecoder<T> | IDecoder<T>[],
-    callback: Callback<T>
-  ) => Unsubscribe | Promise<Unsubscribe>;
+  subscribeWithUnsubscribe: SubscribeWithUnsubscribe;
 }
+
+type SubscribeWithUnsubscribe = <T extends IDecodedMessage>(
+  decoders: IDecoder<T> | IDecoder<T>[],
+  callback: Callback<T>
+) => Unsubscribe | Promise<Unsubscribe>;

package/src/sharding.ts

@@ -0,0 +1,12 @@
+export type ShardInfo = {
+  clusterId: number;
+  shards: number[];
+};
+
+export type ContentTopicInfo = {
+  clusterId?: number;
+  contentTopics: string[];
+};
+
+export type StaticSharding = ShardInfo;
+export type AutoSharding = ContentTopicInfo;

package/src/store.ts

@@ -1,72 +1,101 @@
-import { proto_store as proto } from "@waku/proto";
-
 import type { IDecodedMessage, IDecoder } from "./message.js";
 import type { IBaseProtocolCore, IBaseProtocolSDK } from "./protocols.js";
 
-export enum PageDirection {
-  BACKWARD = "backward",
-  FORWARD = "forward"
-}
+export type StoreCursor = Uint8Array;
 
-export interface TimeFilter {
-  startTime: Date;
-  endTime: Date;
-}
+/**
+ * Parameters for a store query request, as specified in the Waku Store v3 RFC.
+ */
+export type QueryRequestParams = {
+  /**
+   * Whether to include the full message data in the response.
+   * - `true`: The response will include the message content and associated pubsub topic for each matching message.
+   * - `false`: The response will only include the message hashes for each matching message.
+   * @default true
+   */
+  includeData: boolean;
 
-export interface Cursor {
-  digest: Uint8Array;
-  receiverTime: bigint;
-  senderTime: bigint;
+  /**
+   * The pubsub topic to query. This field is mandatory.
+   * The query will only return messages that were published on this specific pubsub topic.
+   */
   pubsubTopic: string;
-}
 
-export type StoreQueryOptions = {
   /**
-   * The direction in which pages are retrieved:
-   * - { @link PageDirection.BACKWARD }: Most recent page first.
-   * - { @link PageDirection.FORWARD }: Oldest page first.
-   *
-   * Note: This does not affect the ordering of messages with the page
-   * (the oldest message is always first).
-   *
-   * @default { @link PageDirection.BACKWARD }
+   * The content topics to filter the messages.
+   * The query will only return messages that have a content topic included in this array.
+   * This field MUST be populated together with the `pubsubTopic` field for content topic filtering to be applied.
+   * If either `contentTopics` or `pubsubTopic` is not provided or empty, no content topic filtering will be applied.
    */
-  pageDirection?: PageDirection;
+  contentTopics: string[];
+
   /**
-   * The number of message per page.
+   * The start time for the time range filter.
+   * The query will only return messages with a timestamp greater than or equal to `timeStart`.
+   * If not provided, no start time filtering will be applied.
    */
-  pageSize?: number;
+  timeStart?: Date;
+
   /**
-   * Retrieve messages with a timestamp within the provided values.
+   * The end time for the time range filter.
+   * The query will only return messages with a timestamp strictly less than `timeEnd`.
+   * If not provided, no end time filtering will be applied.
    */
-  timeFilter?: TimeFilter;
+  timeEnd?: Date;
+
+  /**
+   * The message hashes to lookup.
+   * If provided, the query will be a message hash lookup query and will only return messages that match the specified hashes.
+   * If not provided or empty, the query will be a content filtered query based on the other filter parameters.
+   * @default undefined
+   */
+  messageHashes?: Uint8Array[];
+
+  /**
+   * The cursor to start the query from.
+   * The cursor represents the message hash of the last message returned in the previous query.
+   * The query will start from the message immediately following the cursor, excluding the message at the cursor itself.
+   * If not provided, the query will start from the beginning or end of the store, depending on the `paginationForward` option.
+   * @default undefined
+   */
+  paginationCursor?: Uint8Array;
+
+  /**
+   * The direction of pagination.
+   * - `true`: Forward pagination, starting from the oldest message and moving towards the newest.
+   * - `false`: Backward pagination, starting from the newest message and moving towards the oldest.
+   * @default false
+   */
+  paginationForward: boolean;
+
   /**
-   * Cursor as an index to start a query from. Must be generated from a Waku
-   * Message.
+   * The maximum number of messages to retrieve per page.
+   * If not provided, the store's default pagination limit will be used.
+   * @default undefined
    */
-  cursor?: proto.Index;
+  paginationLimit?: number;
 };
 
 export type IStoreCore = IBaseProtocolCore;
 
 export type IStoreSDK = IBaseProtocolSDK & {
   protocol: IBaseProtocolCore;
-  createCursor(message: IDecodedMessage): Cursor;
+  createCursor(message: IDecodedMessage): StoreCursor;
   queryGenerator: <T extends IDecodedMessage>(
     decoders: IDecoder<T>[],
-    options?: StoreQueryOptions
+    options?: Partial<QueryRequestParams>
   ) => AsyncGenerator<Promise<T | undefined>[]>;
 
   queryWithOrderedCallback: <T extends IDecodedMessage>(
     decoders: IDecoder<T>[],
     callback: (message: T) => Promise<void | boolean> | boolean | void,
-    options?: StoreQueryOptions
+    options?: Partial<QueryRequestParams>
   ) => Promise<void>;
   queryWithPromiseCallback: <T extends IDecodedMessage>(
     decoders: IDecoder<T>[],
     callback: (
       message: Promise<T | undefined>
     ) => Promise<void | boolean> | boolean | void,
-    options?: StoreQueryOptions
+    options?: Partial<QueryRequestParams>
   ) => Promise<void>;
 };

package/src/waku.ts

@@ -3,6 +3,7 @@ import type { MultiaddrInput } from "@multiformats/multiaddr";
 
 import { IConnectionManager } from "./connection_manager.js";
 import type { IFilterSDK } from "./filter.js";
+import { IHealthManager } from "./health_manager.js";
 import type { Libp2p } from "./libp2p.js";
 import type { ILightPushSDK } from "./light_push.js";
 import { Protocols } from "./protocols.js";
@@ -27,6 +28,8 @@ export interface Waku {
   isStarted(): boolean;
 
   isConnected(): boolean;
+
+  health: IHealthManager;
 }
 
 export interface LightNode extends Waku {