@waku/discovery 0.0.1

package/src/dns/dns_over_https.ts

@@ -0,0 +1,83 @@
+import type { DnsClient } from "@waku/interfaces";
+import { Logger } from "@waku/utils";
+import { bytesToUtf8 } from "@waku/utils/bytes";
+import { Endpoint, query, wellknown } from "dns-query";
+
+const log = new Logger("dns-over-https");
+
+export class DnsOverHttps implements DnsClient {
+  /**
+   * Create new Dns-Over-Http DNS client.
+   *
+   * @param endpoints The endpoints for Dns-Over-Https queries;
+   * Defaults to using dns-query's API..
+   * @param retries Retries if a given endpoint fails.
+   *
+   * @throws {code: string} If DNS query fails.
+   */
+  public static async create(
+    endpoints?: Endpoint[],
+    retries?: number
+  ): Promise<DnsOverHttps> {
+    const _endpoints = endpoints ?? (await wellknown.endpoints("doh"));
+
+    return new DnsOverHttps(_endpoints, retries);
+  }
+
+  private constructor(
+    private endpoints: Endpoint[],
+    private retries: number = 3
+  ) {}
+
+  /**
+   * Resolves a TXT record
+   *
+   * @param domain The domain name
+   *
+   * @throws if the query fails
+   */
+  async resolveTXT(domain: string): Promise<string[]> {
+    let answers;
+    try {
+      const res = await query(
+        {
+          question: { type: "TXT", name: domain }
+        },
+        {
+          endpoints: this.endpoints,
+          retries: this.retries
+        }
+      );
+      answers = res.answers;
+    } catch (error) {
+      log.error("query failed: ", error);
+      throw new Error("DNS query failed");
+    }
+
+    if (!answers) throw new Error(`Could not resolve ${domain}`);
+
+    const data = answers.map((a) => a.data) as
+      | Array<string | Uint8Array>
+      | Array<Array<string | Uint8Array>>;
+
+    const result: string[] = [];
+
+    data.forEach((d) => {
+      if (typeof d === "string") {
+        result.push(d);
+      } else if (Array.isArray(d)) {
+        d.forEach((sd) => {
+          if (typeof sd === "string") {
+            result.push(sd);
+          } else {
+            result.push(bytesToUtf8(sd));
+          }
+        });
+      } else {
+        result.push(bytesToUtf8(d));
+      }
+    });
+
+    return result;
+  }
+}

package/src/dns/enrtree.ts

@@ -0,0 +1,123 @@
+import { ENR } from "@waku/enr";
+import { keccak256, verifySignature } from "@waku/enr";
+import { utf8ToBytes } from "@waku/utils/bytes";
+import base32 from "hi-base32";
+import { fromString } from "uint8arrays/from-string";
+
+export type ENRRootValues = {
+  eRoot: string;
+  lRoot: string;
+  seq: number;
+  signature: string;
+};
+
+export type ENRTreeValues = {
+  publicKey: string;
+  domain: string;
+};
+
+export class ENRTree {
+  public static readonly RECORD_PREFIX = ENR.RECORD_PREFIX;
+  public static readonly TREE_PREFIX = "enrtree:";
+  public static readonly BRANCH_PREFIX = "enrtree-branch:";
+  public static readonly ROOT_PREFIX = "enrtree-root:";
+
+  /**
+   * Extracts the branch subdomain referenced by a DNS tree root string after verifying
+   * the root record signature with its base32 compressed public key.
+   */
+  static parseAndVerifyRoot(root: string, publicKey: string): string {
+    if (!root.startsWith(this.ROOT_PREFIX))
+      throw new Error(
+        `ENRTree root entry must start with '${this.ROOT_PREFIX}'`
+      );
+
+    const rootValues = ENRTree.parseRootValues(root);
+    const decodedPublicKey = base32.decode.asBytes(publicKey);
+
+    // The signature is a 65-byte secp256k1 over the keccak256 hash
+    // of the record content, excluding the `sig=` part, encoded as URL-safe base64 string
+    // (Trailing recovery bit must be trimmed to pass `ecdsaVerify` method)
+    const signedComponent = root.split(" sig")[0];
+
+    const signedComponentBuffer = utf8ToBytes(signedComponent);
+    const signatureBuffer = fromString(rootValues.signature, "base64url").slice(
+      0,
+      64
+    );
+
+    const isVerified = verifySignature(
+      signatureBuffer,
+      keccak256(signedComponentBuffer),
+      new Uint8Array(decodedPublicKey)
+    );
+
+    if (!isVerified) throw new Error("Unable to verify ENRTree root signature");
+
+    return rootValues.eRoot;
+  }
+
+  static parseRootValues(txt: string): ENRRootValues {
+    const matches = txt.match(
+      /^enrtree-root:v1 e=([^ ]+) l=([^ ]+) seq=(\d+) sig=([^ ]+)$/
+    );
+
+    if (!Array.isArray(matches))
+      throw new Error("Could not parse ENRTree root entry");
+
+    matches.shift(); // The first entry is the full match
+    const [eRoot, lRoot, seq, signature] = matches;
+
+    if (!eRoot)
+      throw new Error("Could not parse 'e' value from ENRTree root entry");
+    if (!lRoot)
+      throw new Error("Could not parse 'l' value from ENRTree root entry");
+
+    if (!seq)
+      throw new Error("Could not parse 'seq' value from ENRTree root entry");
+    if (!signature)
+      throw new Error("Could not parse 'sig' value from ENRTree root entry");
+
+    return { eRoot, lRoot, seq: Number(seq), signature };
+  }
+
+  /**
+   * Returns the public key and top level domain of an ENR tree entry.
+   * The domain is the starting point for traversing a set of linked DNS TXT records
+   * and the public key is used to verify the root entry record
+   */
+  static parseTree(tree: string): ENRTreeValues {
+    if (!tree.startsWith(this.TREE_PREFIX))
+      throw new Error(
+        `ENRTree tree entry must start with '${this.TREE_PREFIX}'`
+      );
+
+    const matches = tree.match(/^enrtree:\/\/([^@]+)@(.+)$/);
+
+    if (!Array.isArray(matches))
+      throw new Error("Could not parse ENRTree tree entry");
+
+    matches.shift(); // The first entry is the full match
+    const [publicKey, domain] = matches;
+
+    if (!publicKey)
+      throw new Error("Could not parse public key from ENRTree tree entry");
+    if (!domain)
+      throw new Error("Could not parse domain from ENRTree tree entry");
+
+    return { publicKey, domain };
+  }
+
+  /**
+   * Returns subdomains listed in an ENR branch entry. These in turn lead to
+   * either further branch entries or ENR records.
+   */
+  static parseBranch(branch: string): string[] {
+    if (!branch.startsWith(this.BRANCH_PREFIX))
+      throw new Error(
+        `ENRTree branch entry must start with '${this.BRANCH_PREFIX}'`
+      );
+
+    return branch.split(this.BRANCH_PREFIX)[1].split(",");
+  }
+}

package/src/dns/fetch_nodes.ts

@@ -0,0 +1,181 @@
+import type { IEnr, NodeCapabilityCount, Waku2 } from "@waku/interfaces";
+import { Logger } from "@waku/utils";
+
+const log = new Logger("discovery:fetch_nodes");
+
+/**
+ * Fetch nodes using passed [[getNode]] until all wanted capabilities are
+ * fulfilled or the number of [[getNode]] call exceeds the sum of
+ * [[wantedNodeCapabilityCount]] plus [[errorTolerance]].
+ */
+export async function fetchNodesUntilCapabilitiesFulfilled(
+  wantedNodeCapabilityCount: Partial<NodeCapabilityCount>,
+  errorTolerance: number,
+  getNode: () => Promise<IEnr | null>
+): Promise<IEnr[]> {
+  const wanted = {
+    relay: wantedNodeCapabilityCount.relay ?? 0,
+    store: wantedNodeCapabilityCount.store ?? 0,
+    filter: wantedNodeCapabilityCount.filter ?? 0,
+    lightPush: wantedNodeCapabilityCount.lightPush ?? 0
+  };
+
+  const maxSearches =
+    wanted.relay + wanted.store + wanted.filter + wanted.lightPush;
+
+  const actual = {
+    relay: 0,
+    store: 0,
+    filter: 0,
+    lightPush: 0
+  };
+
+  let totalSearches = 0;
+  const peers: IEnr[] = [];
+
+  while (
+    !isSatisfied(wanted, actual) &&
+    totalSearches < maxSearches + errorTolerance
+  ) {
+    const peer = await getNode();
+    if (peer && isNewPeer(peer, peers)) {
+      // ENRs without a waku2 key are ignored.
+      if (peer.waku2) {
+        if (helpsSatisfyCapabilities(peer.waku2, wanted, actual)) {
+          addCapabilities(peer.waku2, actual);
+          peers.push(peer);
+        }
+      }
+      log.info(
+        `got new peer candidate from DNS address=${peer.nodeId}@${peer.ip}`
+      );
+    }
+
+    totalSearches++;
+  }
+  return peers;
+}
+
+/**
+ * Fetch nodes using passed [[getNode]] until all wanted capabilities are
+ * fulfilled or the number of [[getNode]] call exceeds the sum of
+ * [[wantedNodeCapabilityCount]] plus [[errorTolerance]].
+ */
+export async function* yieldNodesUntilCapabilitiesFulfilled(
+  wantedNodeCapabilityCount: Partial<NodeCapabilityCount>,
+  errorTolerance: number,
+  getNode: () => Promise<IEnr | null>
+): AsyncGenerator<IEnr> {
+  const wanted = {
+    relay: wantedNodeCapabilityCount.relay ?? 0,
+    store: wantedNodeCapabilityCount.store ?? 0,
+    filter: wantedNodeCapabilityCount.filter ?? 0,
+    lightPush: wantedNodeCapabilityCount.lightPush ?? 0
+  };
+
+  const maxSearches =
+    wanted.relay + wanted.store + wanted.filter + wanted.lightPush;
+
+  const actual = {
+    relay: 0,
+    store: 0,
+    filter: 0,
+    lightPush: 0
+  };
+
+  let totalSearches = 0;
+  const peerNodeIds = new Set();
+
+  while (
+    !isSatisfied(wanted, actual) &&
+    totalSearches < maxSearches + errorTolerance
+  ) {
+    const peer = await getNode();
+    if (peer && peer.nodeId && !peerNodeIds.has(peer.nodeId)) {
+      peerNodeIds.add(peer.nodeId);
+      // ENRs without a waku2 key are ignored.
+      if (peer.waku2) {
+        if (helpsSatisfyCapabilities(peer.waku2, wanted, actual)) {
+          addCapabilities(peer.waku2, actual);
+          yield peer;
+        }
+      }
+      log.info(
+        `got new peer candidate from DNS address=${peer.nodeId}@${peer.ip}`
+      );
+    }
+    totalSearches++;
+  }
+}
+
+function isSatisfied(
+  wanted: NodeCapabilityCount,
+  actual: NodeCapabilityCount
+): boolean {
+  return (
+    actual.relay >= wanted.relay &&
+    actual.store >= wanted.store &&
+    actual.filter >= wanted.filter &&
+    actual.lightPush >= wanted.lightPush
+  );
+}
+
+function isNewPeer(peer: IEnr, peers: IEnr[]): boolean {
+  if (!peer.nodeId) return false;
+
+  for (const existingPeer of peers) {
+    if (peer.nodeId === existingPeer.nodeId) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function addCapabilities(node: Waku2, total: NodeCapabilityCount): void {
+  if (node.relay) total.relay += 1;
+  if (node.store) total.store += 1;
+  if (node.filter) total.filter += 1;
+  if (node.lightPush) total.lightPush += 1;
+}
+
+/**
+ * Checks if the proposed ENR [[node]] helps satisfy the [[wanted]] capabilities,
+ * considering the [[actual]] capabilities of nodes retrieved so far..
+ *
+ * @throws If the function is called when the wanted capabilities are already fulfilled.
+ */
+function helpsSatisfyCapabilities(
+  node: Waku2,
+  wanted: NodeCapabilityCount,
+  actual: NodeCapabilityCount
+): boolean {
+  if (isSatisfied(wanted, actual)) {
+    throw "Internal Error: Waku2 wanted capabilities are already fulfilled";
+  }
+
+  const missing = missingCapabilities(wanted, actual);
+
+  return (
+    (missing.relay && node.relay) ||
+    (missing.store && node.store) ||
+    (missing.filter && node.filter) ||
+    (missing.lightPush && node.lightPush)
+  );
+}
+
+/**
+ * Return a [[Waku2]] Object for which capabilities are set to true if they are
+ * [[wanted]] yet missing from [[actual]].
+ */
+function missingCapabilities(
+  wanted: NodeCapabilityCount,
+  actual: NodeCapabilityCount
+): Waku2 {
+  return {
+    relay: actual.relay < wanted.relay,
+    store: actual.store < wanted.store,
+    filter: actual.filter < wanted.filter,
+    lightPush: actual.lightPush < wanted.lightPush
+  };
+}

package/src/dns/index.ts

@@ -0,0 +1,3 @@
+export { PeerDiscoveryDns, wakuDnsDiscovery } from "./dns_discovery.js";
+export { enrTree } from "./constants.js";
+export { DnsNodeDiscovery } from "./dns.js";

package/src/index.ts

@@ -0,0 +1,21 @@
+// DNS Discovery
+export { PeerDiscoveryDns, wakuDnsDiscovery } from "./dns/dns_discovery.js";
+export { enrTree } from "./dns/constants.js";
+export { DnsNodeDiscovery } from "./dns/dns.js";
+
+// Peer Exchange Discovery
+export {
+  wakuPeerExchange,
+  PeerExchangeCodec,
+  WakuPeerExchange
+} from "./peer-exchange/waku_peer_exchange.js";
+export {
+  wakuPeerExchangeDiscovery,
+  PeerExchangeDiscovery
+} from "./peer-exchange/waku_peer_exchange_discovery.js";
+
+// Local Peer Cache Discovery
+export {
+  LocalPeerCacheDiscovery,
+  wakuLocalPeerCacheDiscovery
+} from "./local-peer-cache/index.js";

package/src/local-peer-cache/index.ts

@@ -0,0 +1,160 @@
+import { TypedEventEmitter } from "@libp2p/interface";
+import {
+  CustomEvent,
+  IdentifyResult,
+  PeerDiscovery,
+  PeerDiscoveryEvents,
+  PeerInfo,
+  Startable
+} from "@libp2p/interface";
+import { createFromJSON } from "@libp2p/peer-id-factory";
+import { multiaddr } from "@multiformats/multiaddr";
+import {
+  type Libp2pComponents,
+  type LocalStoragePeerInfo,
+  Tags
+} from "@waku/interfaces";
+import { getWsMultiaddrFromMultiaddrs, Logger } from "@waku/utils";
+
+const log = new Logger("peer-exchange-discovery");
+
+type LocalPeerCacheDiscoveryOptions = {
+  tagName?: string;
+  tagValue?: number;
+  tagTTL?: number;
+};
+
+export const DEFAULT_LOCAL_TAG_NAME = Tags.LOCAL;
+const DEFAULT_LOCAL_TAG_VALUE = 50;
+const DEFAULT_LOCAL_TAG_TTL = 100_000_000;
+
+export class LocalPeerCacheDiscovery
+  extends TypedEventEmitter<PeerDiscoveryEvents>
+  implements PeerDiscovery, Startable
+{
+  private isStarted: boolean;
+  private peers: LocalStoragePeerInfo[] = [];
+
+  constructor(
+    private readonly components: Libp2pComponents,
+    private readonly options?: LocalPeerCacheDiscoveryOptions
+  ) {
+    super();
+    this.isStarted = false;
+    this.peers = this.getPeersFromLocalStorage();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return "@waku/local-peer-cache-discovery";
+  }
+
+  async start(): Promise<void> {
+    if (this.isStarted) return;
+
+    log.info("Starting Local Storage Discovery");
+    this.components.events.addEventListener(
+      "peer:identify",
+      this.handleNewPeers
+    );
+
+    for (const { id: idStr, address } of this.peers) {
+      const peerId = await createFromJSON({ id: idStr });
+      if (await this.components.peerStore.has(peerId)) continue;
+
+      await this.components.peerStore.save(peerId, {
+        multiaddrs: [multiaddr(address)],
+        tags: {
+          [this.options?.tagName ?? DEFAULT_LOCAL_TAG_NAME]: {
+            value: this.options?.tagValue ?? DEFAULT_LOCAL_TAG_VALUE,
+            ttl: this.options?.tagTTL ?? DEFAULT_LOCAL_TAG_TTL
+          }
+        }
+      });
+
+      this.dispatchEvent(
+        new CustomEvent<PeerInfo>("peer", {
+          detail: {
+            id: peerId,
+            multiaddrs: [multiaddr(address)]
+          }
+        })
+      );
+    }
+
+    log.info(`Discovered ${this.peers.length} peers`);
+
+    this.isStarted = true;
+  }
+
+  stop(): void | Promise<void> {
+    if (!this.isStarted) return;
+    log.info("Stopping Local Storage Discovery");
+    this.components.events.removeEventListener(
+      "peer:identify",
+      this.handleNewPeers
+    );
+    this.isStarted = false;
+
+    this.savePeersToLocalStorage();
+  }
+
+  handleNewPeers = (event: CustomEvent<IdentifyResult>): void => {
+    const { peerId, listenAddrs } = event.detail;
+
+    const websocketMultiaddr = getWsMultiaddrFromMultiaddrs(listenAddrs);
+
+    const localStoragePeers = this.getPeersFromLocalStorage();
+
+    const existingPeerIndex = localStoragePeers.findIndex(
+      (_peer) => _peer.id === peerId.toString()
+    );
+
+    if (existingPeerIndex >= 0) {
+      localStoragePeers[existingPeerIndex].address =
+        websocketMultiaddr.toString();
+    } else {
+      localStoragePeers.push({
+        id: peerId.toString(),
+        address: websocketMultiaddr.toString()
+      });
+    }
+
+    this.peers = localStoragePeers;
+    this.savePeersToLocalStorage();
+  };
+
+  private getPeersFromLocalStorage(): LocalStoragePeerInfo[] {
+    try {
+      const storedPeersData = localStorage.getItem("waku:peers");
+      if (!storedPeersData) return [];
+      const peers = JSON.parse(storedPeersData);
+      return peers.filter(isValidStoredPeer);
+    } catch (error) {
+      log.error("Error parsing peers from local storage:", error);
+      return [];
+    }
+  }
+
+  private savePeersToLocalStorage(): void {
+    localStorage.setItem("waku:peers", JSON.stringify(this.peers));
+  }
+}
+
+function isValidStoredPeer(peer: any): peer is LocalStoragePeerInfo {
+  return (
+    peer &&
+    typeof peer === "object" &&
+    typeof peer.id === "string" &&
+    typeof peer.address === "string"
+  );
+}
+
+export function wakuLocalPeerCacheDiscovery(): (
+  components: Libp2pComponents,
+  options?: LocalPeerCacheDiscoveryOptions
+) => LocalPeerCacheDiscovery {
+  return (
+    components: Libp2pComponents,
+    options?: LocalPeerCacheDiscoveryOptions
+  ) => new LocalPeerCacheDiscovery(components, options);
+}

package/src/peer-exchange/index.ts

@@ -0,0 +1,11 @@
+export {
+  wakuPeerExchange,
+  PeerExchangeCodec,
+  WakuPeerExchange
+} from "./waku_peer_exchange.js";
+export {
+  wakuPeerExchangeDiscovery,
+  PeerExchangeDiscovery,
+  Options,
+  DEFAULT_PEER_EXCHANGE_TAG_NAME
+} from "./waku_peer_exchange_discovery.js";

package/src/peer-exchange/rpc.ts

@@ -0,0 +1,44 @@
+import { proto_peer_exchange as proto } from "@waku/proto";
+import type { Uint8ArrayList } from "uint8arraylist";
+
+/**
+ * PeerExchangeRPC represents a message conforming to the Waku Peer Exchange protocol
+ */
+export class PeerExchangeRPC {
+  public constructor(public proto: proto.PeerExchangeRPC) {}
+
+  static createRequest(params: proto.PeerExchangeQuery): PeerExchangeRPC {
+    const { numPeers } = params;
+    return new PeerExchangeRPC({
+      query: {
+        numPeers: numPeers
+      },
+      response: undefined
+    });
+  }
+
+  /**
+   * Encode the current PeerExchangeRPC request to bytes
+   * @returns Uint8Array
+   */
+  encode(): Uint8Array {
+    return proto.PeerExchangeRPC.encode(this.proto);
+  }
+
+  /**
+   * Decode the current PeerExchangeRPC request to bytes
+   * @returns Uint8Array
+   */
+  static decode(bytes: Uint8ArrayList): PeerExchangeRPC {
+    const res = proto.PeerExchangeRPC.decode(bytes);
+    return new PeerExchangeRPC(res);
+  }
+
+  get query(): proto.PeerExchangeQuery | undefined {
+    return this.proto.query;
+  }
+
+  get response(): proto.PeerExchangeResponse | undefined {
+    return this.proto.response;
+  }
+}