@waku/interfaces 0.0.21 → 0.0.23-070b625.0

package/dist/protocols.d.ts

@@ -1,6 +1,6 @@
 import type { Libp2p } from "@libp2p/interface";
-import type { PeerId } from "@libp2p/interface/peer-id";
-import type { Peer, PeerStore } from "@libp2p/interface/peer-store";
+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";
@@ -11,13 +11,18 @@ export declare enum Protocols {
     LightPush = "lightpush",
     Filter = "filter"
 }
-export interface IBaseProtocol {
+export type IBaseProtocolCore = {
+    shardInfo?: ShardInfo;
     multicodec: string;
     peerStore: PeerStore;
-    peers: () => Promise<Peer[]>;
+    allPeers: () => Promise<Peer[]>;
+    connectedPeers: () => Promise<Peer[]>;
     addLibp2pEventListener: Libp2p["addEventListener"];
     removeLibp2pEventListener: Libp2p["removeEventListener"];
-}
+};
+export type IBaseProtocolSDK = {
+    numPeers: number;
+};
 export type ContentTopicInfo = {
     clusterId: number;
     contentTopics: string[];
@@ -51,15 +56,23 @@ export type ProtocolCreateOptions = {
      * See [Waku v2 Topic Usage Recommendations](https://rfc.vac.dev/spec/23/) for details.
      *
      */
-    shardInfo?: ShardingParams;
+    shardInfo?: Partial<ShardingParams>;
     /**
-     * You can pass options to the `Libp2p` instance used by {@link @waku/core!WakuNode} using the `libp2p` property.
+     * 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)
      * apart that we made the `modules` property optional and partial,
      * allowing its omission and letting Waku set good defaults.
-     * Notes that some values are overridden by {@link @waku/core!WakuNode} to ensure it implements the Waku protocol.
+     * Notes that some values are overridden by {@link @waku/sdk!WakuNode} to ensure it implements the Waku protocol.
      */
     libp2p?: Partial<CreateLibp2pOptions>;
+    /**
+     * Number of peers to connect to, for the usage of the protocol.
+     * This is used by:
+     * - Light Push to send messages,
+     * - Filter to retrieve messages.
+     * Defaults to 3.
+     */
+    numPeersToUse?: number;
     /**
      * Byte array used as key for the noise protocol used for connection encryption
      * by [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create)
@@ -70,9 +83,22 @@ export type ProtocolCreateOptions = {
      * Use recommended bootstrap method to discovery and connect to new nodes.
      */
     defaultBootstrap?: boolean;
+    /**
+     * List of peers to use to bootstrap the node. Ignored if defaultBootstrap is set to true.
+     */
+    bootstrapPeers?: string[];
 };
 export type Callback<T extends IDecodedMessage> = (msg: T) => void | Promise<void>;
-export declare enum SendError {
+export type ProtocolResult<SK extends string, SV, EK extends string = "error", EV = ProtocolError> = ({
+    [key in SK]: SV;
+} & {
+    [key in EK]: null;
+}) | ({
+    [key in SK]: null;
+} & {
+    [key in EK]: EV;
+});
+export declare enum ProtocolError {
     /** Could not determine the origin of the fault. Best to check connectivity and try again */
     GENERIC_FAIL = "Generic error",
     /**
@@ -117,9 +143,18 @@ export declare enum SendError {
      * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
      * or `DECODE_FAILED` can be used.
      */
-    REMOTE_PEER_REJECTED = "Remote peer rejected"
+    REMOTE_PEER_REJECTED = "Remote peer rejected",
+    /**
+     * 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"
+}
+export interface Failure {
+    error: ProtocolError;
+    peerId?: PeerId;
 }
 export interface SendResult {
-    errors?: SendError[];
-    recipients: PeerId[];
+    failures?: Failure[];
+    successes: PeerId[];
 }

package/dist/protocols.js

@@ -5,52 +5,57 @@ export var Protocols;
     Protocols["LightPush"] = "lightpush";
     Protocols["Filter"] = "filter";
 })(Protocols || (Protocols = {}));
-export var SendError;
-(function (SendError) {
+export var ProtocolError;
+(function (ProtocolError) {
     /** Could not determine the origin of the fault. Best to check connectivity and try again */
-    SendError["GENERIC_FAIL"] = "Generic error";
+    ProtocolError["GENERIC_FAIL"] = "Generic error";
     /**
      * Failure to protobuf encode the message. This is not recoverable and needs
      * further investigation.
      */
-    SendError["ENCODE_FAILED"] = "Failed to encode";
+    ProtocolError["ENCODE_FAILED"] = "Failed to encode";
     /**
      * Failure to protobuf decode the message. May be due to a remote peer issue,
      * ensuring that messages are sent via several peer enable mitigation of this error.
      */
-    SendError["DECODE_FAILED"] = "Failed to decode";
+    ProtocolError["DECODE_FAILED"] = "Failed to decode";
     /**
      * The message payload is empty, making the message invalid. Ensure that a non-empty
      * payload is set on the outgoing message.
      */
-    SendError["EMPTY_PAYLOAD"] = "Payload is empty";
+    ProtocolError["EMPTY_PAYLOAD"] = "Payload is empty";
     /**
      * The message size is above the maximum message size allowed on the Waku Network.
      * Compressing the message or using an alternative strategy for large messages is recommended.
      */
-    SendError["SIZE_TOO_BIG"] = "Size is too big";
+    ProtocolError["SIZE_TOO_BIG"] = "Size is too big";
     /**
      * The PubsubTopic passed to the send function is not configured on the Waku node.
      * Please ensure that the PubsubTopic is used when initializing the Waku node.
      */
-    SendError["TOPIC_NOT_CONFIGURED"] = "Topic not configured";
+    ProtocolError["TOPIC_NOT_CONFIGURED"] = "Topic not configured";
     /**
      * 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
      * to user or listening for `peer:connected:bootstrap` or `peer:connected:peer-exchange`
      * on the connection manager before retrying.
      */
-    SendError["NO_PEER_AVAILABLE"] = "No peer available";
+    ProtocolError["NO_PEER_AVAILABLE"] = "No peer available";
     /**
      * The remote peer did not behave as expected. Mitigation for `NO_PEER_AVAILABLE`
      * or `DECODE_FAILED` can be used.
      */
-    SendError["REMOTE_PEER_FAULT"] = "Remote peer fault";
+    ProtocolError["REMOTE_PEER_FAULT"] = "Remote peer fault";
     /**
      * The remote peer rejected the message. Information provided by the remote peer
      * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
      * or `DECODE_FAILED` can be used.
      */
-    SendError["REMOTE_PEER_REJECTED"] = "Remote peer rejected";
-})(SendError || (SendError = {}));
+    ProtocolError["REMOTE_PEER_REJECTED"] = "Remote peer rejected";
+    /**
+     * 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
+     */
+    ProtocolError["REQUEST_TIMEOUT"] = "Request timeout";
+})(ProtocolError || (ProtocolError = {}));
 //# sourceMappingURL=protocols.js.map

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;AAuED,MAAM,CAAN,IAAY,SA8CX;AA9CD,WAAY,SAAS;IACnB,4FAA4F;IAC5F,2CAA8B,CAAA;IAC9B;;;OAGG;IACH,+CAAkC,CAAA;IAClC;;;OAGG;IACH,+CAAkC,CAAA;IAClC;;;OAGG;IACH,+CAAkC,CAAA;IAClC;;;OAGG;IACH,6CAAgC,CAAA;IAChC;;;OAGG;IACH,0DAA6C,CAAA;IAC7C;;;;;OAKG;IACH,oDAAuC,CAAA;IACvC;;;OAGG;IACH,oDAAuC,CAAA;IACvC;;;;OAIG;IACH,0DAA6C,CAAA;AAC/C,CAAC,EA9CW,SAAS,KAAT,SAAS,QA8CpB"}
+{"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;AA8GD,MAAM,CAAN,IAAY,aAmDX;AAnDD,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;;;;;OAKG;IACH,wDAAuC,CAAA;IACvC;;;OAGG;IACH,wDAAuC,CAAA;IACvC;;;;OAIG;IACH,8DAA6C,CAAA;IAC7C;;;OAGG;IACH,oDAAmC,CAAA;AACrC,CAAC,EAnDW,aAAa,KAAb,aAAa,QAmDxB"}

package/dist/store.d.ts

@@ -1,5 +1,6 @@
+import { proto_store as proto } from "@waku/proto";
 import type { IDecodedMessage, IDecoder } from "./message.js";
-import type { IBaseProtocol } from "./protocols.js";
+import type { IBaseProtocolCore, IBaseProtocolSDK } from "./protocols.js";
 export declare enum PageDirection {
     BACKWARD = "backward",
     FORWARD = "forward"
@@ -38,10 +39,13 @@ export type StoreQueryOptions = {
      * Cursor as an index to start a query from. Must be generated from a Waku
      * Message.
      */
-    cursor?: Cursor;
+    cursor?: proto.Index;
 };
-export interface IStore extends IBaseProtocol {
+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>;
-    queryGenerator: <T extends IDecodedMessage>(decoders: IDecoder<T>[], options?: StoreQueryOptions) => AsyncGenerator<Promise<T | undefined>[]>;
-}
+};

package/dist/store.js.map

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

package/dist/waku.d.ts

@@ -1,19 +1,18 @@
-import type { Stream } from "@libp2p/interface/connection";
-import type { PeerId } from "@libp2p/interface/peer-id";
+import type { PeerId, Stream } from "@libp2p/interface";
 import type { Multiaddr } from "@multiformats/multiaddr";
 import { IConnectionManager } from "./connection_manager.js";
 import type { IFilter } from "./filter.js";
 import type { Libp2p } from "./libp2p.js";
-import type { ILightPush } from "./light_push.js";
+import type { ILightPushSDK } from "./light_push.js";
 import { Protocols } from "./protocols.js";
 import type { IRelay } from "./relay.js";
-import type { IStore } from "./store.js";
+import type { IStoreSDK } from "./store.js";
 export interface Waku {
     libp2p: Libp2p;
     relay?: IRelay;
-    store?: IStore;
+    store?: IStoreSDK;
     filter?: IFilter;
-    lightPush?: ILightPush;
+    lightPush?: ILightPushSDK;
     connectionManager: IConnectionManager;
     dial(peer: PeerId | Multiaddr, protocols?: Protocols[]): Promise<Stream>;
     start(): Promise<void>;
@@ -23,9 +22,9 @@ export interface Waku {
 }
 export interface LightNode extends Waku {
     relay: undefined;
-    store: IStore;
+    store: IStoreSDK;
     filter: IFilter;
-    lightPush: ILightPush;
+    lightPush: ILightPushSDK;
 }
 export interface RelayNode extends Waku {
     relay: IRelay;
@@ -35,7 +34,7 @@ export interface RelayNode extends Waku {
 }
 export interface FullNode extends Waku {
     relay: IRelay;
-    store: IStore;
+    store: IStoreSDK;
     filter: IFilter;
-    lightPush: ILightPush;
+    lightPush: ILightPushSDK;
 }

package/package.json

@@ -1,66 +1 @@
-{
-  "name": "@waku/interfaces",
-  "version": "0.0.21",
-  "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": "^10.1.1",
-    "@multiformats/multiaddr": "^12.0.0",
-    "cspell": "^7.3.2",
-    "npm-run-all": "^4.1.5",
-    "libp2p": "^0.46.14"
-  },
-  "files": [
-    "dist",
-    "bundle",
-    "src/**/*.ts",
-    "!**/*.spec.*",
-    "!**/*.json",
-    "CHANGELOG.md",
-    "LICENSE",
-    "README.md"
-  ]
-}
+{"name":"@waku/interfaces","version":"0.0.23-070b625.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.7-070b625.0"}}

package/src/connection_manager.ts

@@ -1,10 +1,9 @@
-import type { PeerId } from "@libp2p/interface/peer-id";
-import type { Peer } from "@libp2p/interface/peer-store";
-import type { EventEmitter } from "@libp2p/interfaces/events";
+import type { Peer, PeerId, TypedEventEmitter } from "@libp2p/interface";
 
 export enum Tags {
   BOOTSTRAP = "bootstrap",
-  PEER_EXCHANGE = "peer-exchange"
+  PEER_EXCHANGE = "peer-exchange",
+  LOCAL = "local-peer-cache"
 }
 
 export interface ConnectionManagerOptions {
@@ -42,10 +41,12 @@ export interface PeersByDiscoveryResult {
   DISCOVERED: {
     [Tags.BOOTSTRAP]: Peer[];
     [Tags.PEER_EXCHANGE]: Peer[];
+    [Tags.LOCAL]: Peer[];
   };
   CONNECTED: {
     [Tags.BOOTSTRAP]: Peer[];
     [Tags.PEER_EXCHANGE]: Peer[];
+    [Tags.LOCAL]: Peer[];
   };
 }
 
@@ -59,7 +60,7 @@ export interface IConnectionStateEvents {
 }
 
 export interface IConnectionManager
-  extends EventEmitter<IPeersByDiscoveryEvents & IConnectionStateEvents> {
+  extends TypedEventEmitter<IPeersByDiscoveryEvents & IConnectionStateEvents> {
   getPeersByDiscovery(): Promise<PeersByDiscoveryResult>;
   stop(): void;
 }

package/src/constants.ts

@@ -2,3 +2,8 @@
  * DefaultPubsubTopic is the default gossipsub topic to use for Waku.
  */
 export const DefaultPubsubTopic = "/waku/2/default-waku/proto";
+
+/**
+ * The default cluster ID for The Waku Network
+ */
+export const DEFAULT_CLUSTER_ID = 1;

package/src/dns_discovery.ts

@@ -1,4 +1,4 @@
-import { PeerStore } from "@libp2p/interface/peer-store";
+import { PeerStore } from "@libp2p/interface";
 
 export type SearchContext = {
   domain: string;

package/src/enr.ts

@@ -1,5 +1,5 @@
-import type { PeerId } from "@libp2p/interface/peer-id";
-import type { PeerInfo } from "@libp2p/interface/peer-info";
+import type { PeerId } from "@libp2p/interface";
+import type { PeerInfo } from "@libp2p/interface";
 import type { Multiaddr } from "@multiformats/multiaddr";
 
 export type ENRKey = string;

package/src/filter.ts

@@ -1,8 +1,8 @@
-import type { PeerId } from "@libp2p/interface/peer-id";
+import type { PeerId } from "@libp2p/interface";
 
 import type { IDecodedMessage, IDecoder, SingleShardInfo } from "./message.js";
 import type { ContentTopic, PubsubTopic } from "./misc.js";
-import type { Callback, IBaseProtocol } from "./protocols.js";
+import type { Callback, IBaseProtocolCore } from "./protocols.js";
 import type { IReceiver } from "./receiver.js";
 
 export type ContentFilter = {
@@ -23,7 +23,7 @@ export interface IFilterSubscription {
 }
 
 export type IFilter = IReceiver &
-  IBaseProtocol & {
+  IBaseProtocolCore & {
     createSubscription(
       pubsubTopicShardInfo?: SingleShardInfo | PubsubTopic,
       peerId?: PeerId

package/src/index.ts

@@ -16,3 +16,4 @@ export * from "./keep_alive_manager.js";
 export * from "./dns_discovery.js";
 export * from "./metadata.js";
 export * from "./constants.js";
+export * from "./local_storage.js";

package/src/libp2p.ts

@@ -1,8 +1,8 @@
 import type { GossipSub } from "@chainsafe/libp2p-gossipsub";
+import type { identify } from "@libp2p/identify";
 import type { Libp2p as BaseLibp2p } from "@libp2p/interface";
+import type { PingService } from "@libp2p/ping";
 import type { Libp2pInit, Libp2pOptions } from "libp2p";
-import type { identifyService } from "libp2p/identify";
-import type { PingService } from "libp2p/ping";
 
 import { IMetadata } from "./metadata";
 
@@ -10,7 +10,7 @@ export type Libp2pServices = {
   ping: PingService;
   metadata?: IMetadata;
   pubsub?: GossipSub;
-  identify: ReturnType<ReturnType<typeof identifyService>>;
+  identify: ReturnType<ReturnType<typeof identify>>;
 };
 
 // TODO: Get libp2p to export this.

package/src/light_push.ts

@@ -1,4 +1,5 @@
-import type { IBaseProtocol } from "./protocols.js";
+import { IBaseProtocolCore, IBaseProtocolSDK } from "./protocols.js";
 import type { ISender } from "./sender.js";
 
-export type ILightPush = ISender & IBaseProtocol;
+export type ILightPushSDK = ISender &
+  IBaseProtocolSDK & { protocol: IBaseProtocolCore };

package/src/local_storage.ts

@@ -0,0 +1,4 @@
+export type LocalStoragePeerInfo = {
+  id: string;
+  address: string;
+};

package/src/message.ts

@@ -5,7 +5,7 @@ export interface SingleShardInfo {
   /**
    * Specifying this field indicates to the encoder/decoder that static sharding must be used.
    */
-  shard?: number;
+  shard: number;
 }
 
 export interface IRateLimitProof {

package/src/metadata.ts

@@ -1,8 +1,17 @@
-import type { PeerId } from "@libp2p/interface/peer-id";
+import type { PeerId } from "@libp2p/interface";
 
-import type { ShardInfo } from "./enr.js";
-import type { IBaseProtocol } from "./protocols.js";
+import { type ShardInfo } from "./enr.js";
+import type {
+  IBaseProtocolCore,
+  ProtocolResult,
+  ShardingParams
+} from "./protocols.js";
 
-export interface IMetadata extends IBaseProtocol {
-  query(peerId: PeerId): Promise<ShardInfo | undefined>;
+export type QueryResult = ProtocolResult<"shardInfo", ShardInfo>;
+
+// IMetadata always has shardInfo defined while it is optionally undefined in IBaseProtocol
+export interface IMetadata extends Omit<IBaseProtocolCore, "shardInfo"> {
+  shardInfo: ShardingParams;
+  confirmOrAttemptHandshake(peerId: PeerId): Promise<QueryResult>;
+  query(peerId: PeerId): Promise<QueryResult>;
 }

package/src/peer_exchange.ts

@@ -1,17 +1,19 @@
-import type { PeerId } from "@libp2p/interface/peer-id";
-import type { PeerStore } from "@libp2p/interface/peer-store";
-import type { ConnectionManager } from "@libp2p/interface-internal/connection-manager";
+import type { PeerId } from "@libp2p/interface";
+import type { PeerStore } from "@libp2p/interface";
+import type { ConnectionManager } from "@libp2p/interface-internal";
 
 import { IEnr } from "./enr.js";
-import { IBaseProtocol } from "./protocols.js";
+import { IBaseProtocolCore, ProtocolResult } from "./protocols.js";
 
-export interface IPeerExchange extends IBaseProtocol {
-  query(params: PeerExchangeQueryParams): Promise<PeerInfo[] | undefined>;
+export interface IPeerExchange extends IBaseProtocolCore {
+  query(params: PeerExchangeQueryParams): Promise<PeerExchangeResult>;
 }
 
+export type PeerExchangeResult = ProtocolResult<"peerInfos", PeerInfo[]>;
+
 export interface PeerExchangeQueryParams {
   numPeers: number;
-  peerId?: PeerId;
+  peerId: PeerId;
 }
 
 export interface PeerExchangeResponse {

package/src/protocols.ts

@@ -1,6 +1,6 @@
 import type { Libp2p } from "@libp2p/interface";
-import type { PeerId } from "@libp2p/interface/peer-id";
-import type { Peer, PeerStore } from "@libp2p/interface/peer-store";
+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";
@@ -14,13 +14,19 @@ export enum Protocols {
   Filter = "filter"
 }
 
-export interface IBaseProtocol {
+export type IBaseProtocolCore = {
+  shardInfo?: ShardInfo;
   multicodec: string;
   peerStore: PeerStore;
-  peers: () => Promise<Peer[]>;
+  allPeers: () => Promise<Peer[]>;
+  connectedPeers: () => Promise<Peer[]>;
   addLibp2pEventListener: Libp2p["addEventListener"];
   removeLibp2pEventListener: Libp2p["removeEventListener"];
-}
+};
+
+export type IBaseProtocolSDK = {
+  numPeers: number;
+};
 
 export type ContentTopicInfo = {
   clusterId: number;
@@ -58,15 +64,23 @@ export type ProtocolCreateOptions = {
    * See [Waku v2 Topic Usage Recommendations](https://rfc.vac.dev/spec/23/) for details.
    *
    */
-  shardInfo?: ShardingParams;
+  shardInfo?: Partial<ShardingParams>;
   /**
-   * You can pass options to the `Libp2p` instance used by {@link @waku/core!WakuNode} using the `libp2p` property.
+   * 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)
    * apart that we made the `modules` property optional and partial,
    * allowing its omission and letting Waku set good defaults.
-   * Notes that some values are overridden by {@link @waku/core!WakuNode} to ensure it implements the Waku protocol.
+   * Notes that some values are overridden by {@link @waku/sdk!WakuNode} to ensure it implements the Waku protocol.
    */
   libp2p?: Partial<CreateLibp2pOptions>;
+  /**
+   * Number of peers to connect to, for the usage of the protocol.
+   * This is used by:
+   * - Light Push to send messages,
+   * - Filter to retrieve messages.
+   * Defaults to 3.
+   */
+  numPeersToUse?: number;
   /**
    * Byte array used as key for the noise protocol used for connection encryption
    * by [`Libp2p.create`](https://github.com/libp2p/js-libp2p/blob/master/doc/API.md#create)
@@ -77,13 +91,38 @@ export type ProtocolCreateOptions = {
    * Use recommended bootstrap method to discovery and connect to new nodes.
    */
   defaultBootstrap?: boolean;
+  /**
+   * List of peers to use to bootstrap the node. Ignored if defaultBootstrap is set to true.
+   */
+  bootstrapPeers?: string[];
 };
 
 export type Callback<T extends IDecodedMessage> = (
   msg: T
 ) => void | Promise<void>;
 
-export enum SendError {
+// SK = success key name
+// SV = success value type
+// EK = error key name (default: "error")
+// EV = error value type (default: ProtocolError)
+export type ProtocolResult<
+  SK extends string,
+  SV,
+  EK extends string = "error",
+  EV = ProtocolError
+> =
+  | ({
+      [key in SK]: SV;
+    } & {
+      [key in EK]: null;
+    })
+  | ({
+      [key in SK]: null;
+    } & {
+      [key in EK]: EV;
+    });
+
+export enum ProtocolError {
   /** Could not determine the origin of the fault. Best to check connectivity and try again */
   GENERIC_FAIL = "Generic error",
   /**
@@ -128,10 +167,20 @@ export enum SendError {
    * is logged. Review message validity, or mitigation for `NO_PEER_AVAILABLE`
    * or `DECODE_FAILED` can be used.
    */
-  REMOTE_PEER_REJECTED = "Remote peer rejected"
+  REMOTE_PEER_REJECTED = "Remote peer rejected",
+  /**
+   * 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"
+}
+
+export interface Failure {
+  error: ProtocolError;
+  peerId?: PeerId;
 }
 
 export interface SendResult {
-  errors?: SendError[];
-  recipients: PeerId[];
+  failures?: Failure[];
+  successes: PeerId[];
 }