@waku/core 0.0.36-10590da.0 → 0.0.36-3730abc.0

package/src/lib/light_push/light_push_v3.ts

@@ -0,0 +1,233 @@
+import type { PeerId, Stream } from "@libp2p/interface";
+import {
+  type CoreProtocolResult,
+  type IBaseProtocolCore,
+  type IEncoder,
+  type IMessage,
+  type Libp2p,
+  ProtocolError,
+  PubsubTopic,
+  type ThisOrThat
+} from "@waku/interfaces";
+import { proto_lightpush_v3, WakuMessage } from "@waku/proto";
+import { isMessageSizeUnderCap } from "@waku/utils";
+import { Logger } from "@waku/utils";
+import all from "it-all";
+import * as lp from "it-length-prefixed";
+import { pipe } from "it-pipe";
+import { Uint8ArrayList } from "uint8arraylist";
+
+import { BaseProtocol } from "../base_protocol.js";
+
+import { PushRpcV3 } from "./push_rpc_v3.js";
+import {
+  getLightPushStatusDescriptionV3,
+  isSuccessStatusCodeV3,
+  lightPushStatusCodeToProtocolErrorV3,
+  LightPushStatusCodeV3
+} from "./status_codes_v3.js";
+import { isRLNResponseError } from "./utils.js";
+
+const log = new Logger("light-push-v3");
+
+export const LightPushCodecV3 = "/vac/waku/lightpush/3.0.0";
+
+type PreparePushMessageResult = ThisOrThat<"query", PushRpcV3>;
+
+export class LightPushCoreV3 extends BaseProtocol implements IBaseProtocolCore {
+  public constructor(
+    public readonly pubsubTopics: PubsubTopic[],
+    libp2p: Libp2p
+  ) {
+    super(LightPushCodecV3, libp2p.components, pubsubTopics);
+  }
+
+  private async preparePushMessage(
+    encoder: IEncoder,
+    message: IMessage
+  ): Promise<PreparePushMessageResult> {
+    try {
+      if (!message.payload || message.payload.length === 0) {
+        log.error("Failed to send waku light push: payload is empty");
+        return { query: null, error: ProtocolError.EMPTY_PAYLOAD };
+      }
+
+      if (!(await isMessageSizeUnderCap(encoder, message))) {
+        log.error("Failed to send waku light push: message is bigger than 1MB");
+        return { query: null, error: ProtocolError.SIZE_TOO_BIG };
+      }
+
+      const protoMessage = await encoder.toProtoObj(message);
+      if (!protoMessage) {
+        log.error("Failed to encode to protoMessage, aborting push");
+        return {
+          query: null,
+          error: ProtocolError.ENCODE_FAILED
+        };
+      }
+
+      const query = PushRpcV3.createRequest(
+        protoMessage as WakuMessage,
+        encoder.pubsubTopic
+      );
+      return { query, error: null };
+    } catch (error) {
+      log.error("Failed to prepare push message", error);
+
+      return {
+        query: null,
+        error: ProtocolError.GENERIC_FAIL
+      };
+    }
+  }
+
+  public async send(
+    encoder: IEncoder,
+    message: IMessage,
+    peerId: PeerId
+  ): Promise<CoreProtocolResult> {
+    const { query, error: preparationError } = await this.preparePushMessage(
+      encoder,
+      message
+    );
+
+    if (preparationError || !query) {
+      return {
+        success: null,
+        failure: {
+          error: preparationError,
+          peerId
+        }
+      };
+    }
+
+    let stream: Stream;
+    try {
+      stream = await this.getStream(peerId);
+    } catch (error) {
+      log.error("Failed to get stream", error);
+      return {
+        success: null,
+        failure: {
+          error: ProtocolError.NO_STREAM_AVAILABLE,
+          peerId: peerId
+        }
+      };
+    }
+
+    let res: Uint8ArrayList[] | undefined;
+    try {
+      res = await pipe(
+        [query.encode()],
+        lp.encode,
+        stream,
+        lp.decode,
+        async (source) => await all(source)
+      );
+    } catch (err) {
+      log.error("Failed to send waku light push request", err);
+      return {
+        success: null,
+        failure: {
+          error: ProtocolError.STREAM_ABORTED,
+          peerId: peerId
+        }
+      };
+    }
+
+    const bytes = new Uint8ArrayList();
+    res.forEach((chunk) => {
+      bytes.append(chunk);
+    });
+
+    let response: proto_lightpush_v3.LightpushResponse | undefined;
+    try {
+      response = proto_lightpush_v3.LightpushResponse.decode(bytes);
+    } catch (err) {
+      log.error("Failed to decode push response", err);
+      return {
+        success: null,
+        failure: {
+          error: ProtocolError.DECODE_FAILED,
+          peerId: peerId
+        }
+      };
+    }
+
+    if (!response) {
+      log.error("Remote peer fault: No response received");
+      return {
+        success: null,
+        failure: {
+          error: ProtocolError.NO_RESPONSE,
+          peerId: peerId
+        }
+      };
+    }
+
+    // Validate request ID matches (except for rate limiting responses)
+    if (response.requestId !== query.query?.requestId) {
+      // nwaku sends "N/A" for rate limiting responses
+      if (response.statusCode !== LightPushStatusCodeV3.TOO_MANY_REQUESTS) {
+        log.error("Request ID mismatch", {
+          sent: query.query?.requestId,
+          received: response.requestId
+        });
+        return {
+          success: null,
+          failure: {
+            error: ProtocolError.GENERIC_FAIL,
+            peerId: peerId
+          }
+        };
+      }
+    }
+
+    const statusCode = response.statusCode;
+    const isSuccess = isSuccessStatusCodeV3(statusCode);
+
+    // Special handling for nwaku rate limiting
+    if (statusCode === LightPushStatusCodeV3.TOO_MANY_REQUESTS) {
+      if (response.requestId === "N/A") {
+        log.warn("Rate limited by nwaku node", {
+          statusDesc:
+            response.statusDesc || "Request rejected due to too many requests"
+        });
+      }
+    }
+
+    if (response.relayPeerCount !== undefined) {
+      log.info(`Message relayed to ${response.relayPeerCount} peers`);
+    }
+
+    if (response.statusDesc && isRLNResponseError(response.statusDesc)) {
+      log.error("Remote peer fault: RLN generation");
+      return {
+        success: null,
+        failure: {
+          error: ProtocolError.RLN_PROOF_GENERATION,
+          peerId: peerId
+        }
+      };
+    }
+
+    if (!isSuccess) {
+      const errorMessage = getLightPushStatusDescriptionV3(
+        statusCode,
+        response.statusDesc
+      );
+      log.error("Remote peer rejected the message: ", errorMessage);
+
+      const protocolError = lightPushStatusCodeToProtocolErrorV3(statusCode);
+      return {
+        success: null,
+        failure: {
+          error: protocolError,
+          peerId: peerId
+        }
+      };
+    }
+
+    return { success: peerId, failure: null };
+  }
+}

package/src/lib/light_push/push_rpc.ts

@@ -7,7 +7,7 @@ export class PushRpc {
 
   public static createRequest(
     message: proto.WakuMessage,
-    pubsubTopic: string
+    pubsubTopic?: string
   ): PushRpc {
     return new PushRpc({
       requestId: uuid(),

package/src/lib/light_push/push_rpc_v2.ts

@@ -0,0 +1,38 @@
+import { proto_lightpush_v2 as proto } from "@waku/proto";
+import type { Uint8ArrayList } from "uint8arraylist";
+import { v4 as uuid } from "uuid";
+
+export class PushRpcV2 {
+  public constructor(public proto: proto.PushRpc) {}
+
+  public static createRequest(
+    message: proto.WakuMessage,
+    pubsubTopic: string
+  ): PushRpcV2 {
+    return new PushRpcV2({
+      requestId: uuid(),
+      request: {
+        message: message,
+        pubsubTopic: pubsubTopic
+      },
+      response: undefined
+    });
+  }
+
+  public static decode(bytes: Uint8ArrayList): PushRpcV2 {
+    const res = proto.PushRpc.decode(bytes);
+    return new PushRpcV2(res);
+  }
+
+  public encode(): Uint8Array {
+    return proto.PushRpc.encode(this.proto);
+  }
+
+  public get query(): proto.PushRequest | undefined {
+    return this.proto.request;
+  }
+
+  public get response(): proto.PushResponse | undefined {
+    return this.proto.response;
+  }
+}

package/src/lib/light_push/push_rpc_v3.ts

@@ -0,0 +1,46 @@
+import { proto_lightpush_v3, WakuMessage } from "@waku/proto";
+import type { Uint8ArrayList } from "uint8arraylist";
+import { v4 as uuid } from "uuid";
+
+export class PushRpcV3 {
+  public request?: proto_lightpush_v3.LightpushRequest;
+  public response?: proto_lightpush_v3.LightpushResponse;
+
+  private constructor(
+    request?: proto_lightpush_v3.LightpushRequest,
+    response?: proto_lightpush_v3.LightpushResponse
+  ) {
+    this.request = request;
+    this.response = response;
+  }
+
+  public static createRequest(
+    message: WakuMessage,
+    pubsubTopic?: string
+  ): PushRpcV3 {
+    const request: proto_lightpush_v3.LightpushRequest = {
+      requestId: uuid(),
+      message: message,
+      // Only include pubsubTopic if explicitly provided (for nwaku autosharding compatibility)
+      ...(pubsubTopic && { pubsubTopic })
+    };
+
+    return new PushRpcV3(request, undefined);
+  }
+
+  public static decode(bytes: Uint8ArrayList | Uint8Array): PushRpcV3 {
+    const response = proto_lightpush_v3.LightpushResponse.decode(bytes);
+    return new PushRpcV3(undefined, response);
+  }
+
+  public encode(): Uint8Array {
+    if (!this.request) {
+      throw new Error("Cannot encode without a request");
+    }
+    return proto_lightpush_v3.LightpushRequest.encode(this.request);
+  }
+
+  public get query(): proto_lightpush_v3.LightpushRequest | undefined {
+    return this.request;
+  }
+}

package/src/lib/light_push/status_codes.ts

@@ -0,0 +1,71 @@
+import { ProtocolError } from "@waku/interfaces";
+
+export enum LightPushStatusCode {
+  SUCCESS = 200,
+  BAD_REQUEST = 400,
+  UNSUPPORTED_PUBSUB_TOPIC = 404,
+  REQUEST_TOO_LARGE = 413,
+  TOO_MANY_REQUESTS = 429,
+  INTERNAL_SERVER_ERROR = 500,
+  NO_PEERS_TO_RELAY = 503
+}
+
+export function lightPushStatusCodeToProtocolError(
+  statusCode: number
+): ProtocolError | null {
+  switch (statusCode) {
+    case LightPushStatusCode.SUCCESS:
+      return null;
+
+    case LightPushStatusCode.BAD_REQUEST:
+      return ProtocolError.GENERIC_FAIL;
+
+    case LightPushStatusCode.UNSUPPORTED_PUBSUB_TOPIC:
+      return ProtocolError.TOPIC_NOT_CONFIGURED;
+
+    case LightPushStatusCode.REQUEST_TOO_LARGE:
+      return ProtocolError.SIZE_TOO_BIG;
+
+    case LightPushStatusCode.TOO_MANY_REQUESTS:
+      return ProtocolError.GENERIC_FAIL;
+
+    case LightPushStatusCode.INTERNAL_SERVER_ERROR:
+      return ProtocolError.REMOTE_PEER_REJECTED;
+
+    case LightPushStatusCode.NO_PEERS_TO_RELAY:
+      return ProtocolError.NO_PEER_AVAILABLE;
+
+    default:
+      return ProtocolError.REMOTE_PEER_REJECTED;
+  }
+}
+
+export const lightPushStatusDescriptions: Record<number, string> = {
+  [LightPushStatusCode.SUCCESS]: "Message pushed successfully",
+  [LightPushStatusCode.BAD_REQUEST]:
+    "Invalid request format or missing required fields",
+  [LightPushStatusCode.UNSUPPORTED_PUBSUB_TOPIC]:
+    "The specified pubsub topic is not supported",
+  [LightPushStatusCode.REQUEST_TOO_LARGE]:
+    "Message size exceeds maximum allowed size",
+  [LightPushStatusCode.TOO_MANY_REQUESTS]:
+    "Rate limit exceeded, too many requests",
+  [LightPushStatusCode.INTERNAL_SERVER_ERROR]: "Internal server error occurred",
+  [LightPushStatusCode.NO_PEERS_TO_RELAY]:
+    "No relay peers available to forward the message"
+};
+
+export function isSuccessStatusCode(statusCode: number): boolean {
+  return statusCode === LightPushStatusCode.SUCCESS;
+}
+
+export function getLightPushStatusDescription(
+  statusCode: number,
+  statusDesc?: string
+): string {
+  return (
+    statusDesc ||
+    lightPushStatusDescriptions[statusCode] ||
+    `Unknown status code: ${statusCode}`
+  );
+}

package/src/lib/light_push/status_codes_v3.ts

@@ -0,0 +1,97 @@
+import { ProtocolError } from "@waku/interfaces";
+
+export enum LightPushStatusCodeV3 {
+  SUCCESS = 200,
+  BAD_REQUEST = 400,
+  PAYLOAD_TOO_LARGE = 413,
+  INVALID_MESSAGE_ERROR = 420,
+  UNSUPPORTED_PUBSUB_TOPIC = 421,
+  TOO_MANY_REQUESTS = 429,
+  INTERNAL_SERVER_ERROR = 500,
+  SERVICE_NOT_AVAILABLE = 503,
+  OUT_OF_RLN_PROOF = 504,
+  NO_PEERS_TO_RELAY = 505
+}
+
+export const lightPushStatusDescriptionsV3: Record<
+  LightPushStatusCodeV3,
+  string
+> = {
+  [LightPushStatusCodeV3.SUCCESS]: "Message sent successfully",
+  [LightPushStatusCodeV3.BAD_REQUEST]: "Bad request format",
+  [LightPushStatusCodeV3.PAYLOAD_TOO_LARGE]:
+    "Message payload exceeds maximum size",
+  [LightPushStatusCodeV3.INVALID_MESSAGE_ERROR]: "Message validation failed",
+  [LightPushStatusCodeV3.UNSUPPORTED_PUBSUB_TOPIC]: "Unsupported pubsub topic",
+  [LightPushStatusCodeV3.TOO_MANY_REQUESTS]: "Rate limit exceeded",
+  [LightPushStatusCodeV3.INTERNAL_SERVER_ERROR]: "Internal server error",
+  [LightPushStatusCodeV3.SERVICE_NOT_AVAILABLE]:
+    "Service temporarily unavailable",
+  [LightPushStatusCodeV3.OUT_OF_RLN_PROOF]: "RLN proof generation failed",
+  [LightPushStatusCodeV3.NO_PEERS_TO_RELAY]: "No relay peers available"
+};
+
+export function lightPushStatusCodeToProtocolErrorV3(
+  statusCode: LightPushStatusCodeV3 | number | undefined
+): ProtocolError {
+  if (!statusCode) {
+    return ProtocolError.GENERIC_FAIL;
+  }
+
+  switch (statusCode) {
+    case LightPushStatusCodeV3.SUCCESS:
+      return ProtocolError.GENERIC_FAIL;
+
+    case LightPushStatusCodeV3.BAD_REQUEST:
+      return ProtocolError.DECODE_FAILED;
+
+    case LightPushStatusCodeV3.PAYLOAD_TOO_LARGE:
+      return ProtocolError.SIZE_TOO_BIG;
+
+    case LightPushStatusCodeV3.INVALID_MESSAGE_ERROR:
+      return ProtocolError.EMPTY_PAYLOAD;
+
+    case LightPushStatusCodeV3.UNSUPPORTED_PUBSUB_TOPIC:
+      return ProtocolError.TOPIC_NOT_CONFIGURED;
+
+    case LightPushStatusCodeV3.TOO_MANY_REQUESTS:
+      return ProtocolError.REMOTE_PEER_REJECTED;
+
+    case LightPushStatusCodeV3.INTERNAL_SERVER_ERROR:
+      return ProtocolError.GENERIC_FAIL;
+
+    case LightPushStatusCodeV3.SERVICE_NOT_AVAILABLE:
+      return ProtocolError.NO_PEER_AVAILABLE;
+
+    case LightPushStatusCodeV3.OUT_OF_RLN_PROOF:
+      return ProtocolError.RLN_PROOF_GENERATION;
+
+    case LightPushStatusCodeV3.NO_PEERS_TO_RELAY:
+      return ProtocolError.NO_PEER_AVAILABLE;
+
+    default:
+      return ProtocolError.REMOTE_PEER_REJECTED;
+  }
+}
+
+export function isSuccessStatusCodeV3(statusCode: number | undefined): boolean {
+  return statusCode === LightPushStatusCodeV3.SUCCESS;
+}
+
+export function getLightPushStatusDescriptionV3(
+  statusCode: number | undefined,
+  customDesc?: string
+): string {
+  if (customDesc) {
+    return customDesc;
+  }
+
+  if (!statusCode) {
+    return "Unknown error";
+  }
+
+  return (
+    lightPushStatusDescriptionsV3[statusCode as LightPushStatusCodeV3] ||
+    `Unknown status code: ${statusCode}`
+  );
+}

package/src/lib/message/version_0.ts

@@ -22,7 +22,7 @@ export { proto };
 export class DecodedMessage implements IDecodedMessage {
   public constructor(
     public pubsubTopic: string,
-    protected proto: proto.WakuMessage
+    private proto: proto.WakuMessage
   ) {}
 
   public get ephemeral(): boolean {
@@ -37,10 +37,6 @@ export class DecodedMessage implements IDecodedMessage {
     return this.proto.contentTopic;
   }
 
-  public get _rawTimestamp(): bigint | undefined {
-    return this.proto.timestamp;
-  }
-
   public get timestamp(): Date | undefined {
     // In the case we receive a value that is bigger than JS's max number,
     // we catch the error and return undefined.
@@ -63,7 +59,7 @@ export class DecodedMessage implements IDecodedMessage {
   public get version(): number {
     // https://rfc.vac.dev/spec/14/
     // > If omitted, the value SHOULD be interpreted as version 0.
-    return this.proto.version ?? 0;
+    return this.proto.version ?? Version;
   }
 
   public get rateLimitProof(): IRateLimitProof | undefined {
@@ -160,7 +156,7 @@ export class Decoder implements IDecoder<IDecodedMessage> {
   public async fromProtoObj(
     pubsubTopic: string,
     proto: IProtoMessage
-  ): Promise<DecodedMessage | undefined> {
+  ): Promise<IDecodedMessage | undefined> {
     // https://rfc.vac.dev/spec/14/
     // > If omitted, the value SHOULD be interpreted as version 0.
     if (proto.version ?? 0 !== Version) {

package/src/lib/message_hash/index.ts

@@ -0,0 +1 @@
+export { messageHash, messageHashStr } from "./message_hash.js";

package/src/lib/message_hash/message_hash.ts

@@ -0,0 +1,106 @@
+import { sha256 } from "@noble/hashes/sha256";
+import type { IDecodedMessage, IProtoMessage } from "@waku/interfaces";
+import { isDefined } from "@waku/utils";
+import {
+  bytesToHex,
+  concat,
+  numberToBytes,
+  utf8ToBytes
+} from "@waku/utils/bytes";
+
+/**
+ * Deterministic Message Hashing as defined in
+ * [14/WAKU2-MESSAGE](https://rfc.vac.dev/spec/14/#deterministic-message-hashing)
+ *
+ * Computes a SHA-256 hash of the concatenation of pubsub topic, payload, content topic, meta, and timestamp.
+ *
+ * @param pubsubTopic - The pubsub topic string
+ * @param message - The message to be hashed
+ * @returns A Uint8Array containing the SHA-256 hash
+ *
+ * @example
+ * ```typescript
+ * import { messageHash } from "@waku/core";
+ *
+ * const pubsubTopic = "/waku/2/default-waku/proto";
+ * const message = {
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   contentTopic: "/waku/2/default-content/proto",
+ *   meta: new Uint8Array([5, 6, 7, 8]),
+ *   timestamp: new Date()
+ * };
+ *
+ * const hash = messageHash(pubsubTopic, message);
+ * ```
+ */
+export function messageHash(
+  pubsubTopic: string,
+  message: IProtoMessage | IDecodedMessage
+): Uint8Array {
+  const pubsubTopicBytes = utf8ToBytes(pubsubTopic);
+  const contentTopicBytes = utf8ToBytes(message.contentTopic);
+  const timestampBytes = tryConvertTimestampToBytes(message.timestamp);
+
+  const bytes = concat(
+    [
+      pubsubTopicBytes,
+      message.payload,
+      contentTopicBytes,
+      message.meta,
+      timestampBytes
+    ].filter(isDefined)
+  );
+
+  return sha256(bytes);
+}
+
+function tryConvertTimestampToBytes(
+  timestamp: Date | number | bigint | undefined
+): undefined | Uint8Array {
+  if (!timestamp) {
+    return;
+  }
+
+  let bigIntTimestamp: bigint;
+
+  if (typeof timestamp === "bigint") {
+    bigIntTimestamp = timestamp;
+  } else {
+    bigIntTimestamp = BigInt(timestamp.valueOf()) * 1000000n;
+  }
+
+  return numberToBytes(bigIntTimestamp);
+}
+
+/**
+ * Computes a deterministic message hash and returns it as a hexadecimal string.
+ * This is a convenience wrapper around messageHash that converts the result to a hex string.
+ *
+ * @param pubsubTopic - The pubsub topic string
+ * @param message - The message to be hashed
+ * @returns A string containing the hex representation of the SHA-256 hash
+ *
+ * @example
+ * ```typescript
+ * import { messageHashStr } from "@waku/core";
+ *
+ * const pubsubTopic = "/waku/2/default-waku/proto";
+ * const message = {
+ *   payload: new Uint8Array([1, 2, 3, 4]),
+ *   contentTopic: "/waku/2/default-content/proto",
+ *   meta: new Uint8Array([5, 6, 7, 8]),
+ *   timestamp: new Date()
+ * };
+ *
+ * const hashString = messageHashStr(pubsubTopic, message);
+ * console.log(hashString); // e.g. "a1b2c3d4..."
+ * ```
+ */
+export function messageHashStr(
+  pubsubTopic: string,
+  message: IProtoMessage | IDecodedMessage
+): string {
+  const hash = messageHash(pubsubTopic, message);
+  const hashStr = bytesToHex(hash);
+  return hashStr;
+}

package/src/lib/store/rpc.ts

@@ -14,6 +14,7 @@ export class StoreQueryRequest {
   public static create(params: QueryRequestParams): StoreQueryRequest {
     const request = new StoreQueryRequest({
       ...params,
+      contentTopics: params.contentTopics || [],
       requestId: uuid(),
       timeStart: params.timeStart
         ? BigInt(params.timeStart.getTime() * ONE_MILLION)
@@ -27,26 +28,29 @@ export class StoreQueryRequest {
         : undefined
     });
 
-    // Validate request parameters based on RFC
-    if (
-      (params.pubsubTopic && !params.contentTopics) ||
-      (!params.pubsubTopic && params.contentTopics)
-    ) {
-      throw new Error(
-        "Both pubsubTopic and contentTopics must be set or unset"
-      );
-    }
+    const isHashQuery = params.messageHashes && params.messageHashes.length > 0;
+    const hasContentTopics =
+      params.contentTopics && params.contentTopics.length > 0;
+    const hasTimeFilter = params.timeStart || params.timeEnd;
 
-    if (
-      params.messageHashes &&
-      (params.pubsubTopic ||
-        params.contentTopics ||
-        params.timeStart ||
-        params.timeEnd)
-    ) {
-      throw new Error(
-        "Message hash lookup queries cannot include content filter criteria"
-      );
+    if (isHashQuery) {
+      if (hasContentTopics || hasTimeFilter) {
+        throw new Error(
+          "Message hash lookup queries cannot include content filter criteria (contentTopics, timeStart, or timeEnd)"
+        );
+      }
+    } else {
+      if (
+        (params.pubsubTopic &&
+          (!params.contentTopics || params.contentTopics.length === 0)) ||
+        (!params.pubsubTopic &&
+          params.contentTopics &&
+          params.contentTopics.length > 0)
+      ) {
+        throw new Error(
+          "Both pubsubTopic and contentTopics must be set together for content-filtered queries"
+        );
+      }
     }
 
     return request;