@waku/interfaces 0.0.26-1887f4f.0 → 0.0.26-77b2cdd.0

package/dist/protocols.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,SAKX;AALD,WAAY,SAAS;IACnB,4BAAe,CAAA;IACf,4BAAe,CAAA;IACf,oCAAuB,CAAA;IACvB,8BAAiB,CAAA;AACnB,CAAC,EALW,SAAS,KAAT,SAAS,QAKpB;AAgID,MAAM,CAAN,IAAY,aA6DX;AA7DD,WAAY,aAAa;IACvB,4FAA4F;IAC5F,+CAA8B,CAAA;IAC9B;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,iDAAgC,CAAA;IAChC;;;OAGG;IACH,8DAA6C,CAAA;IAC7C;;;OAGG;IACH,kEAAiD,CAAA;IACjD;;;;;OAKG;IACH,wDAAuC,CAAA;IACvC;;;OAGG;IACH,4DAA2C,CAAA;IAC3C;;;OAGG;IACH,wDAAuC,CAAA;IACvC;;;;OAIG;IACH,8DAA6C,CAAA;IAC7C;;;OAGG;IACH,oDAAmC,CAAA;AACrC,CAAC,EA7DW,aAAa,KAAb,aAAa,QA6DxB"}
+{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../src/protocols.ts"],"names":[],"mappings":"AASA,MAAM,CAAN,IAAY,SAKX;AALD,WAAY,SAAS;IACnB,4BAAe,CAAA;IACf,4BAAe,CAAA;IACf,oCAAuB,CAAA;IACvB,8BAAiB,CAAA;AACnB,CAAC,EALW,SAAS,KAAT,SAAS,QAKpB;AAiHD,MAAM,CAAN,IAAY,aAkEX;AAlED,WAAY,aAAa;IACvB,4FAA4F;IAC5F,+CAA8B,CAAA;IAC9B;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,mDAAkC,CAAA;IAClC;;;OAGG;IACH,iDAAgC,CAAA;IAChC;;;OAGG;IACH,8DAA6C,CAAA;IAC7C;;;OAGG;IACH,kEAAiD,CAAA;IACjD;;;OAGG;IACH,kEAAiD,CAAA;IACjD;;;;;OAKG;IACH,wDAAuC,CAAA;IACvC;;;OAGG;IACH,4DAA2C,CAAA;IAC3C;;;OAGG;IACH,wDAAuC,CAAA;IACvC;;;;OAIG;IACH,8DAA6C,CAAA;IAC7C;;;OAGG;IACH,oDAAmC,CAAA;AACrC,CAAC,EAlEW,aAAa,KAAb,aAAa,QAkExB"}

package/dist/receiver.d.ts

@@ -4,5 +4,7 @@ import type { Callback } from "./protocols.js";
 export type ActiveSubscriptions = Map<PubsubTopic, ContentTopic[]>;
 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>;
+export {};

package/dist/sharding.d.ts

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

package/dist/sharding.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sharding.js.map

package/dist/sharding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.js","sourceRoot":"","sources":["../src/sharding.ts"],"names":[],"mappings":""}

package/dist/store.d.ts

@@ -1,51 +1,75 @@
-import { proto_store as proto } from "@waku/proto";
 import type { IDecodedMessage, IDecoder } from "./message.js";
 import type { IBaseProtocolCore, IBaseProtocolSDK } from "./protocols.js";
-export declare enum PageDirection {
-    BACKWARD = "backward",
-    FORWARD = "forward"
-}
-export interface TimeFilter {
-    startTime: Date;
-    endTime: Date;
-}
-export interface Cursor {
-    digest: Uint8Array;
-    receiverTime: bigint;
-    senderTime: bigint;
+export type StoreCursor = Uint8Array;
+/**
+ * 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;
+    /**
+     * 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.
+     */
+    contentTopics: string[];
+    /**
+     * 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.
+     */
+    timeStart?: Date;
+    /**
+     * 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.
+     */
+    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
      */
-    pageDirection?: PageDirection;
+    messageHashes?: Uint8Array[];
     /**
-     * The number of message per page.
+     * 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
      */
-    pageSize?: number;
+    paginationCursor?: Uint8Array;
     /**
-     * Retrieve messages with a timestamp within the provided values.
+     * 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
      */
-    timeFilter?: TimeFilter;
+    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;
-    queryGenerator: <T extends IDecodedMessage>(decoders: IDecoder<T>[], options?: StoreQueryOptions) => AsyncGenerator<Promise<T | undefined>[]>;
-    queryWithOrderedCallback: <T extends IDecodedMessage>(decoders: IDecoder<T>[], callback: (message: T) => Promise<void | boolean> | boolean | void, options?: StoreQueryOptions) => Promise<void>;
-    queryWithPromiseCallback: <T extends IDecodedMessage>(decoders: IDecoder<T>[], callback: (message: Promise<T | undefined>) => Promise<void | boolean> | boolean | void, options?: StoreQueryOptions) => Promise<void>;
+    createCursor(message: IDecodedMessage): StoreCursor;
+    queryGenerator: <T extends IDecodedMessage>(decoders: IDecoder<T>[], options?: Partial<QueryRequestParams>) => AsyncGenerator<Promise<T | undefined>[]>;
+    queryWithOrderedCallback: <T extends IDecodedMessage>(decoders: IDecoder<T>[], callback: (message: T) => Promise<void | boolean> | boolean | void, options?: Partial<QueryRequestParams>) => Promise<void>;
+    queryWithPromiseCallback: <T extends IDecodedMessage>(decoders: IDecoder<T>[], callback: (message: Promise<T | undefined>) => Promise<void | boolean> | boolean | void, options?: Partial<QueryRequestParams>) => Promise<void>;
 };

package/dist/store.js

@@ -1,6 +1,2 @@
-export var PageDirection;
-(function (PageDirection) {
-    PageDirection["BACKWARD"] = "backward";
-    PageDirection["FORWARD"] = "forward";
-})(PageDirection || (PageDirection = {}));
+export {};
 //# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAKA,MAAM,CAAN,IAAY,aAGX;AAHD,WAAY,aAAa;IACvB,sCAAqB,CAAA;IACrB,oCAAmB,CAAA;AACrB,CAAC,EAHW,aAAa,KAAb,aAAa,QAGxB"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":""}

package/dist/waku.d.ts

@@ -2,6 +2,7 @@ import type { PeerId, Stream } from "@libp2p/interface";
 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";
@@ -19,6 +20,7 @@ export interface Waku {
     stop(): Promise<void>;
     isStarted(): boolean;
     isConnected(): boolean;
+    health: IHealthManager;
 }
 export interface LightNode extends Waku {
     relay: undefined;

package/package.json

@@ -1 +1 @@
-{"name":"@waku/interfaces","version":"0.0.26-1887f4f.0","description":"Definition of Waku interfaces","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"type":"module","author":"Waku Team","homepage":"https://github.com/waku-org/js-waku/tree/master/packages/interfaces#readme","repository":{"type":"git","url":"https://github.com/waku-org/js-waku.git"},"bugs":{"url":"https://github.com/waku-org/js-waku/issues"},"license":"MIT OR Apache-2.0","keywords":["waku","decentralized","secure","communication","web3","ethereum","dapps","privacy"],"scripts":{"build":"run-s build:**","build:esm":"tsc","fix":"run-s fix:*","fix:lint":"eslint src --fix","check":"run-s check:*","check:lint":"eslint src","check:spelling":"cspell \"{README.md,src/**/*.ts}\"","check:tsc":"tsc -p tsconfig.dev.json","prepublish":"npm run build","reset-hard":"git clean -dfx -e .idea && git reset --hard && npm i && npm run build"},"engines":{"node":">=18"},"devDependencies":{"@chainsafe/libp2p-gossipsub":"^12.0.0","@multiformats/multiaddr":"^12.0.0","cspell":"^8.6.1","npm-run-all":"^4.1.5","libp2p":"^1.1.2"},"files":["dist","bundle","src/**/*.ts","!**/*.spec.*","!**/*.json","CHANGELOG.md","LICENSE","README.md"],"dependencies":{"@waku/proto":"0.0.8-1887f4f.0"}}
+{"name":"@waku/interfaces","version":"0.0.26-77b2cdd.0","description":"Definition of Waku interfaces","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"type":"module","author":"Waku Team","homepage":"https://github.com/waku-org/js-waku/tree/master/packages/interfaces#readme","repository":{"type":"git","url":"https://github.com/waku-org/js-waku.git"},"bugs":{"url":"https://github.com/waku-org/js-waku/issues"},"license":"MIT OR Apache-2.0","keywords":["waku","decentralized","secure","communication","web3","ethereum","dapps","privacy"],"scripts":{"build":"run-s build:**","build:esm":"tsc","fix":"run-s fix:*","fix:lint":"eslint src --fix","check":"run-s check:*","check:lint":"eslint src","check:spelling":"cspell \"{README.md,src/**/*.ts}\"","check:tsc":"tsc -p tsconfig.dev.json","prepublish":"npm run build","reset-hard":"git clean -dfx -e .idea && git reset --hard && npm i && npm run build"},"engines":{"node":">=18"},"devDependencies":{"@chainsafe/libp2p-gossipsub":"^13.1.0","@multiformats/multiaddr":"^12.0.0","cspell":"^8.6.1","npm-run-all":"^4.1.5","libp2p":"^1.8.1"},"files":["dist","bundle","src/**/*.ts","!**/*.spec.*","!**/*.json","CHANGELOG.md","LICENSE","README.md"],"dependencies":{"@waku/proto":"0.0.8-77b2cdd.0"}}

package/src/connection_manager.ts

@@ -1,5 +1,7 @@
 import type { Peer, PeerId, TypedEventEmitter } from "@libp2p/interface";
 
+import { PubsubTopic } from "./misc";
+
 export enum Tags {
   BOOTSTRAP = "bootstrap",
   PEER_EXCHANGE = "peer-exchange",
@@ -61,6 +63,7 @@ export interface IConnectionStateEvents {
 
 export interface IConnectionManager
   extends TypedEventEmitter<IPeersByDiscoveryEvents & IConnectionStateEvents> {
+  configuredPubsubTopics: PubsubTopic[];
   dropConnection(peerId: PeerId): Promise<void>;
   getPeersByDiscovery(): Promise<PeersByDiscoveryResult>;
   stop(): void;

package/src/constants.ts

@@ -1,4 +1,4 @@
-import { ShardInfo } from "./enr";
+import type { ShardInfo } from "./sharding";
 
 /**
  * The default cluster ID for The Waku Network
@@ -12,3 +12,5 @@ export const DefaultShardInfo: ShardInfo = {
   clusterId: DEFAULT_CLUSTER_ID,
   shards: [0, 1, 2, 3, 4, 5, 6, 7, 8]
 };
+
+export const DefaultNetworkConfig = DefaultShardInfo;

package/src/enr.ts

@@ -2,6 +2,8 @@ import type { PeerId } from "@libp2p/interface";
 import type { PeerInfo } from "@libp2p/interface";
 import type { Multiaddr } from "@multiformats/multiaddr";
 
+import { ShardInfo } from "./sharding";
+
 export type ENRKey = string;
 export type ENRValue = Uint8Array;
 /**
@@ -18,11 +20,6 @@ export interface Waku2 {
   lightPush: boolean;
 }
 
-export interface ShardInfo {
-  clusterId: number;
-  shards: number[];
-}
-
 export interface IEnr extends Map<ENRKey, ENRValue> {
   nodeId?: NodeId;
   peerId?: PeerId;

package/src/filter.ts

@@ -1,15 +1,14 @@
 import type { PeerId } from "@libp2p/interface";
 
 import type { IDecodedMessage, IDecoder } from "./message.js";
-import type { ContentTopic, PubsubTopic, ThisOrThat } from "./misc.js";
+import type { ContentTopic, ThisOrThat } from "./misc.js";
 import type {
   Callback,
   IBaseProtocolCore,
   IBaseProtocolSDK,
   ProtocolError,
   ProtocolUseOptions,
-  SDKProtocolResult,
-  ShardingParams
+  SDKProtocolResult
 } from "./protocols.js";
 import type { IReceiver } from "./receiver.js";
 
@@ -37,12 +36,28 @@ export interface ISubscriptionSDK {
 
 export type IFilterSDK = IReceiver &
   IBaseProtocolSDK & { protocol: IBaseProtocolCore } & {
-    createSubscription(
-      pubsubTopicShardInfo?: ShardingParams | PubsubTopic,
-      options?: ProtocolUseOptions
-    ): Promise<CreateSubscriptionResult>;
+    subscribe<T extends IDecodedMessage>(
+      decoders: IDecoder<T> | IDecoder<T>[],
+      callback: Callback<T>,
+      protocolUseOptions?: ProtocolUseOptions,
+      subscribeOptions?: SubscribeOptions
+    ): Promise<SubscribeResult>;
   };
 
+export type SubscribeResult = SubscriptionSuccess | SubscriptionError;
+
+type SubscriptionSuccess = {
+  subscription: ISubscriptionSDK;
+  error: null;
+  results: SDKProtocolResult;
+};
+
+type SubscriptionError = {
+  subscription: null;
+  error: ProtocolError;
+  results: null;
+};
+
 export type CreateSubscriptionResult = ThisOrThat<
   "subscription",
   ISubscriptionSDK,

package/src/health_manager.ts

@@ -0,0 +1,26 @@
+import { Protocols } from "./protocols";
+
+export enum HealthStatus {
+  Unhealthy = "Unhealthy",
+  MinimallyHealthy = "MinimallyHealthy",
+  SufficientlyHealthy = "SufficientlyHealthy"
+}
+
+export interface IHealthManager {
+  getHealthStatus: () => HealthStatus;
+  getProtocolStatus: (protocol: Protocols) => ProtocolHealth | undefined;
+  updateProtocolHealth: (multicodec: string, connectedPeers: number) => void;
+}
+
+export type NodeHealth = {
+  overallStatus: HealthStatus;
+  protocolStatuses: ProtocolsHealthStatus;
+};
+
+export type ProtocolHealth = {
+  name: Protocols;
+  status: HealthStatus;
+  lastUpdate: Date;
+};
+
+export type ProtocolsHealthStatus = Map<Protocols, ProtocolHealth>;

package/src/index.ts

@@ -17,3 +17,5 @@ export * from "./dns_discovery.js";
 export * from "./metadata.js";
 export * from "./constants.js";
 export * from "./local_storage.js";
+export * from "./health_manager.js";
+export * from "./sharding.js";

package/src/libp2p.ts

@@ -30,4 +30,9 @@ export type CreateLibp2pOptions = Libp2pOptions & {
    */
   hideWebSocketInfo?: boolean;
   pingMaxInboundStreams?: number;
+  /**
+   * Applies secure web socket filters.
+   * @default true
+   */
+  filterMultiaddrs?: boolean;
 };

package/src/metadata.ts

@@ -1,14 +1,14 @@
 import type { PeerId } from "@libp2p/interface";
 
-import { type ShardInfo } from "./enr.js";
-import { ThisOrThat } from "./misc.js";
-import type { IBaseProtocolCore, ShardingParams } from "./protocols.js";
+import { PubsubTopic, ThisOrThat } from "./misc.js";
+import type { IBaseProtocolCore } from "./protocols.js";
+import type { ShardInfo } from "./sharding.js";
 
 export type MetadataQueryResult = ThisOrThat<"shardInfo", ShardInfo>;
 
 // IMetadata always has shardInfo defined while it is optionally undefined in IBaseProtocol
 export interface IMetadata extends Omit<IBaseProtocolCore, "shardInfo"> {
-  shardInfo: ShardingParams;
+  pubsubTopics: PubsubTopic[];
   confirmOrAttemptHandshake(peerId: PeerId): Promise<MetadataQueryResult>;
   query(peerId: PeerId): Promise<MetadataQueryResult>;
 }

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,38 +60,35 @@ export type ProtocolUseOptions = {
 
 export type ProtocolCreateOptions = {
   /**
-   * @deprecated
-   * Should be used ONLY if some other than The Waku Network is in use.
-   *
-   * See [Waku v2 Topic Usage Recommendations](https://github.com/vacp2p/rfc-index/blob/main/waku/informational/23/topics.md#pubsub-topics) for details.
+   * Configuration for determining the network in use.
    *
-   * This is used by:
-   * - WakuRelay to receive, route and send messages,
-   * - WakuLightPush to send messages,
-   * - WakuStore to retrieve messages.
-   *
-   * If no pubsub topic is specified, the default pubsub topic will be determined from DefaultShardInfo.
+   * 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/).
    *
-   * You cannot add or remove pubsub topics after initialization of the node.
+   * 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.
    */
-  pubsubTopics?: PubsubTopic[];
   /**
-   * ShardInfo is used to determine which network is in use.
-   * Defaults to {@link @waku/interfaces!DefaultShardInfo}.
-   * Default value is configured for The Waku Network
+   * Configuration for determining the network in use.
+   * Network configuration refers to the shards and clusters used in the network.
    *
-   * The format to specify a shard is:
-   * clusterId: number, shards: number[]
+   * 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/).
-   */
-  shardInfo?: Partial<ShardingParams>;
-  /**
-   * Content topics are used to determine network in use.
-   * 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.
+   * 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)
@@ -173,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

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>;
 };