@libp2p/interface-internal 2.3.0-4ab04faf0 → 2.3.0-68ad3663e

package/dist/src/address-manager.d.ts

@@ -48,42 +48,64 @@ export interface ConfirmAddressOptions {
      */
     type?: AddressType;
 }
+/**
+ * The `AddressManager` provides an interface for managing peer addresses
+ * in libp2p. It supports handling multiple types of addresses, verifying their validity,
+ * and storing mappings between internal and external addresses.
+ */
 export interface AddressManager {
     /**
      * Get peer listen multiaddrs
+     *
+     * @returns An array of `Multiaddr` objects representing listen addresses.
      */
     getListenAddrs(): Multiaddr[];
     /**
      * Get peer announcing multiaddrs
+     *
+     * @returns An array of `Multiaddr` objects representing announce addresses.
      */
     getAnnounceAddrs(): Multiaddr[];
     /**
      * Get observed multiaddrs - these addresses may not have been confirmed as
      * publicly dialable yet
+     *
+     * @returns An array of `Multiaddr` objects representing observed addresses.
      */
     getObservedAddrs(): Multiaddr[];
     /**
      * Signal that we have confidence an observed multiaddr is publicly dialable -
      * this will make it appear in the output of getAddresses()
+     *
+     * @param addr - The observed address.
+     * @param options - Additional options for confirmation.
      */
     confirmObservedAddr(addr: Multiaddr, options?: ConfirmAddressOptions): void;
     /**
      * Signal that we do not have confidence an observed multiaddr is publicly dialable -
      * this will remove it from the output of getObservedAddrs()
+     *
+     * @param addr - The observed address to remove.
      */
     removeObservedAddr(addr: Multiaddr): void;
     /**
      * Add peer observed addresses.  These will then appear in the output of getObservedAddrs
      * but not getAddresses() until their dialability has been confirmed via a call to
      * confirmObservedAddr.
+     *
+     * @param addr - The observed address to add.
      */
     addObservedAddr(addr: Multiaddr): void;
     /**
      * Get the current node's addresses
+     *
+     * @returns An array of `Multiaddr` objects representing node addresses.
      */
     getAddresses(): Multiaddr[];
     /**
      * Return all known addresses with metadata
+     *
+     * @returns An array of `NodeAddress` objects.
      */
     getAddressesWithMetadata(): NodeAddress[];
     /**
@@ -91,10 +113,15 @@ export interface AddressManager {
      * `getAddresses` is invoked, where the IP addresses are present in a
      * multiaddr, an additional multiaddr will be added with `ip4` and `ip6`
      * tuples replaced with `dns4` and `dns6 ones respectively.
+     *
+     * @param domain - The domain name to map.
+     * @param ipAddresses - The associated IP addresses.
      */
     addDNSMapping(domain: string, ipAddresses: string[]): void;
     /**
      * Remove a mapping previously added with `addDNSMapping`.
+     *
+     * @param domain - The domain name mapping to remove.
      */
     removeDNSMapping(domain: string): void;
     /**
@@ -106,10 +133,22 @@ export interface AddressManager {
      * It's possible to add a IPv6 address here and have it added to the address
      * list, this is for the case when a router has an external IPv6 address with
      * port forwarding configured, but it does IPv6 -> IPv4 NAT.
+     *
+     * @param internalIp - The internal IP address.
+     * @param internalPort - The internal port number.
+     * @param externalIp - The external IP address.
+     * @param externalPort - The external port number (optional).
+     * @param protocol - The transport protocol (`tcp` or `udp`).
      */
     addPublicAddressMapping(internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void;
     /**
      * Remove a publicly routable address that this node is no longer reachable on
+     *
+     * @param internalIp - The internal IP address.
+     * @param internalPort - The internal port number.
+     * @param externalIp - The external IP address.
+     * @param externalPort - The external port number (optional).
+     * @param protocol - The transport protocol (`tcp` or `udp`).
      */
     removePublicAddressMapping(internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void;
 }

package/dist/src/address-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"address-manager.d.ts","sourceRoot":"","sources":["../../src/address-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,CAAA;AAE9F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAA;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,cAAc,IAAI,SAAS,EAAE,CAAA;IAE7B;;OAEG;IACH,gBAAgB,IAAI,SAAS,EAAE,CAAA;IAE/B;;;OAGG;IACH,gBAAgB,IAAI,SAAS,EAAE,CAAA;IAE/B;;;OAGG;IACH,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAE3E;;;OAGG;IACH,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAEzC;;;;OAIG;IACH,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAEtC;;OAEG;IACH,YAAY,IAAI,SAAS,EAAE,CAAA;IAE3B;;OAEG;IACH,wBAAwB,IAAI,WAAW,EAAE,CAAA;IAEzC;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAE1D;;OAEG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtC;;;;;;;;;OASG;IACH,uBAAuB,CAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAA;IAE7I;;OAEG;IACH,0BAA0B,CAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAA;CACjJ"}
+{"version":3,"file":"address-manager.d.ts","sourceRoot":"","sources":["../../src/address-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,CAAA;AAE9F;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,SAAS,EAAE,SAAS,CAAA;IAEpB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAA;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,IAAI,EAAE,WAAW,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,cAAc,IAAI,SAAS,EAAE,CAAA;IAE7B;;;;OAIG;IACH,gBAAgB,IAAI,SAAS,EAAE,CAAA;IAE/B;;;;;OAKG;IACH,gBAAgB,IAAI,SAAS,EAAE,CAAA;IAE/B;;;;;;OAMG;IACH,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAA;IAE3E;;;;;OAKG;IACH,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAEzC;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAA;IAEtC;;;;OAIG;IACH,YAAY,IAAI,SAAS,EAAE,CAAA;IAE3B;;;;OAIG;IACH,wBAAwB,IAAI,WAAW,EAAE,CAAA;IAEzC;;;;;;;;OAQG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAE1D;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtC;;;;;;;;;;;;;;;OAeG;IACH,uBAAuB,CAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAA;IAE7I;;;;;;;;OAQG;IACH,0BAA0B,CAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAA;CACjJ"}

package/dist/src/connection-manager.d.ts

@@ -2,6 +2,9 @@ import type { AbortOptions, PendingDial, Connection, MultiaddrConnection, PeerId
 import type { PeerMap } from '@libp2p/peer-collections';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { ProgressOptions } from 'progress-events';
+/**
+ * Options for opening a connection to a remote peer.
+ */
 export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<OpenConnectionProgressEvents> {
     /**
      * Connection requests with a higher priority will be executed before those
@@ -30,45 +33,46 @@ export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<Ope
      */
     initiator?: boolean;
 }
+/**
+ * The `ConnectionManager` handles managing connections between peers in a libp2p network.
+ * It provides methods for opening, closing, and querying connections.This also provides methods
+ * for accessing the dial queue.
+ */
 export interface ConnectionManager {
     /**
      * Return connections, optionally filtering by a PeerId
      *
-     * @example
-     *
-     * ```TypeScript
-     * const connections = libp2p.connectionManager.get(peerId)
-     * // []
-     * ```
+     * @param peerId - The PeerId to filter connections (optional).
+     * @returns An array of active `Connection` objects.
      */
     getConnections(peerId?: PeerId): Connection[];
     /**
      * Return a map of all connections with their associated PeerIds
      *
-     * @example
-     *
-     * ```TypeScript
-     * const connectionsMap = libp2p.connectionManager.getConnectionsMap()
-     * ```
+     * @returns A `PeerMap` containing `Connection[]` objects.
      */
     getConnectionsMap(): PeerMap<Connection[]>;
     /**
      * Returns the configured maximum number of connections this connection
      * manager will accept
+     *
+     * @returns The maximum connection limit.
      */
     getMaxConnections(): number;
     /**
      * Open a connection to a remote peer
      *
-     * @example
-     *
-     * ```TypeScript
-     * const connection = await libp2p.connectionManager.openConnection(peerId)
-     * ```
+     * @param peer - The target `PeerId`, `Multiaddr`, or an array of `Multiaddr`s.
+     * @param options - Optional parameters for connection handling.
+     * @returns A promise that resolves to a `Connection` object.
      */
     openConnection(peer: PeerId | Multiaddr | Multiaddr[], options?: OpenConnectionOptions): Promise<Connection>;
     /**
      * Close our connections to a peer
+     *
+     * @param peer - The `PeerId` whose connections should be closed.
+     * @param options - Optional abort options.
+     * @returns A promise that resolves once the connections are closed.
      */
     closeConnections(peer: PeerId, options?: AbortOptions): Promise<void>;
     /**
@@ -76,6 +80,9 @@ export interface ConnectionManager {
      * exchanged, this lets the ConnectionManager check we have sufficient
      * resources to accept the connection in which case it will return true,
      * otherwise it will return false.
+     *
+     * @param maConn - The multiaddr connection to evaluate.
+     * @returns A promise that resolves to `true` if the connection can be accepted, `false` otherwise.
      */
     acceptIncomingConnection(maConn: MultiaddrConnection): Promise<boolean>;
     /**
@@ -85,11 +92,7 @@ export interface ConnectionManager {
     /**
      * Return the list of in-progress or queued dials
      *
-     * @example
-     *
-     * ```TypeScript
-     * const dials = libp2p.connectionManager.getDialQueue()
-     * ```
+     * @returns An array of `PendingDial` objects.
      */
     getDialQueue(): PendingDial[];
     /**
@@ -100,6 +103,10 @@ export interface ConnectionManager {
      * would not block the dial attempt.
      *
      * This may involve resolving DNS addresses so you should pass an AbortSignal.
+     *
+     * @param multiaddr - The target multiaddr or an array of multiaddrs.
+     * @param options - Optional parameters for dialability check.
+     * @returns A promise that resolves to `true` if the multiaddr is dialable, `false` otherwise.
      */
     isDialable(multiaddr: Multiaddr | Multiaddr[], options?: IsDialableOptions): Promise<boolean>;
 }

package/dist/src/connection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../src/connection-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAA;AAC5J,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,MAAM,WAAW,qBAAsB,SAAQ,YAAY,EAAE,eAAe,CAAC,4BAA4B,CAAC;IACxG;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;OASG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAAA;IAE7C;;;;;;;;OAQG;IACH,iBAAiB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAE1C;;;OAGG;IACH,iBAAiB,IAAI,MAAM,CAAA;IAE3B;;;;;;;;OAQG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE5G;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErE;;;;;OAKG;IACH,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAA;IAE3B;;;;;;;;OAQG;IACH,YAAY,IAAI,WAAW,EAAE,CAAA;IAE7B;;;;;;;;OAQG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9F"}
+{"version":3,"file":"connection-manager.d.ts","sourceRoot":"","sources":["../../src/connection-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAA;AAC5J,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY,EAAE,eAAe,CAAC,4BAA4B,CAAC;IACxG;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE,CAAA;IAE7C;;;;OAIG;IACH,iBAAiB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAE1C;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM,CAAA;IAE3B;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE5G;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErE;;;;;;;;OAQG;IACH,wBAAwB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAA;IAE3B;;;;OAIG;IACH,YAAY,IAAI,WAAW,EAAE,CAAA;IAE7B;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC9F"}

package/dist/src/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @packageDocumentation
+ *
+ * This module serves as the entry point for `@libp2p/interface-internal`,
+ * re-exporting key components such as `AddressManager`, `ConnectionManager`,
+ * `RandomWalk`, `Registrar`, and `TransportManager`.
+ *
+ * These interfaces and classes define the core internal behaviors of libp2p.
+ */
 export * from './address-manager.js';
 export * from './connection-manager.js';
 export * from './random-walk.js';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,wBAAwB,CAAA"}

package/dist/src/index.js

@@ -1,3 +1,12 @@
+/**
+ * @packageDocumentation
+ *
+ * This module serves as the entry point for `@libp2p/interface-internal`,
+ * re-exporting key components such as `AddressManager`, `ConnectionManager`,
+ * `RandomWalk`, `Registrar`, and `TransportManager`.
+ *
+ * These interfaces and classes define the core internal behaviors of libp2p.
+ */
 export * from './address-manager.js';
 export * from './connection-manager.js';
 export * from './random-walk.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,sBAAsB,CAAA;AACpC,cAAc,yBAAyB,CAAA;AACvC,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,wBAAwB,CAAA"}

package/dist/src/random-walk.d.ts

@@ -1,12 +1,19 @@
 import type { AbortOptions, PeerInfo } from '@libp2p/interface';
 /**
- * RandomWalk finds random peers on the network and dials them. Use this after
- * registering a Topology if you need to discover common network services.
+ * The `RandomWalk` component uses the libp2p peer routing to find arbitrary
+ * network peers. Consumers may then dial these peers, causing the Identify
+ * protocol to run and any registered topologies to be notified of their
+ * supported protocols.
  */
 export interface RandomWalk {
     /**
-     * Begin or join an existing walk. Abort the passed signal if you wish to
-     * abort the walk early.
+     * Initiates a random walk for peer discovery.
+     *
+     * This method either begins a new random walk or joins an existing one. The process
+     * continues to find and return random peers until it is aborted.
+     *
+     * @param options - Optional `AbortOptions` to allow early termination of the walk.
+     * @returns An `AsyncGenerator` that yields discovered `PeerInfo` objects.
      */
     walk(options?: AbortOptions): AsyncGenerator<PeerInfo>;
 }

package/dist/src/random-walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random-walk.d.ts","sourceRoot":"","sources":["../../src/random-walk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE/D;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;CACvD"}
+{"version":3,"file":"random-walk.d.ts","sourceRoot":"","sources":["../../src/random-walk.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;OAQG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;CACvD"}

package/dist/src/registrar.d.ts

@@ -16,21 +16,46 @@ StreamHandlerOptions,
  * @deprecated This type should be imported from @libp2p/interface directly
  */
 StreamHandlerRecord };
+/**
+ * The `Registrar` provides an interface for registering protocol handlers -
+ * these are invoked when remote peers open streams on the local node with the
+ * corresponding protocol name.
+ *
+ * It also allows configuring network topologies for a given protocol(s). The
+ * topology callbacks are invoked when a peer that supports those protocols
+ * connects or disconnects.
+ *
+ * The Identify protocol must be configured on the current node for topologies
+ * to function.
+ */
 export interface Registrar {
     /**
-     * Return the list of protocols with registered handlers
+     * Retrieve the list of registered protocol handlers.
+     *
+     * @returns An array of protocol strings.
      */
     getProtocols(): string[];
     /**
-     * Add a protocol handler
+     * Register a handler for a specific protocol.
+     *
+     * @param protocol - The protocol string (e.g., `/my-protocol/1.0.0`).
+     * @param handler - The function that handles incoming streams.
+     * @param options - Optional configuration options for the handler.
+     * @returns A promise that resolves once the handler is registered.
      */
     handle(protocol: string, handler: StreamHandler, options?: StreamHandlerOptions): Promise<void>;
     /**
-     * Remove a protocol handler
+     * Remove a registered protocol handler.
+     *
+     * @param protocol - The protocol to unhandle.
+     * @returns A promise that resolves once the handler is removed.
      */
     unhandle(protocol: string): Promise<void>;
     /**
-     * Return the handler for the passed protocol
+     * Retrieve the registered handler for a given protocol.
+     *
+     * @param protocol - The protocol to query.
+     * @returns A `StreamHandlerRecord` containing the handler and options.
      */
     getHandler(protocol: string): StreamHandlerRecord;
     /**
@@ -40,15 +65,24 @@ export interface Registrar {
      *
      * An id will be returned that can later be used to unregister the
      * topology.
+     *
+     * @param protocol - The protocol to register.
+     * @param topology - The topology handler to register.
+     * @returns A promise resolving to a unique ID for the registered topology.
      */
     register(protocol: string, topology: Topology): Promise<string>;
     /**
-     * Remove the topology handler with the passed id.
+     * Unregister a topology handler using its unique ID.
+     *
+     * @param id - The ID of the topology to unregister.
      */
     unregister(id: string): void;
     /**
-     * Return all topology handlers that wish to be informed about peers
-     * that support the passed protocol.
+     * Retrieve all topology handlers that are interested in peers
+     * supporting a given protocol.
+     *
+     * @param protocol - The protocol to query.
+     * @returns An array of registered `Topology` handlers.
      */
     getTopologies(protocol: string): Topology[];
 }

package/dist/src/registrar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/registrar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE/H,YAAY;AACV;;GAEG;AACH,kBAAkB;AAElB;;GAEG;AACH,aAAa;AAEb;;GAEG;AACH,oBAAoB;AAEpB;;GAEG;AACH,mBAAmB,EACpB,CAAA;AAED,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE,CAAA;IAExB;;OAEG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/F;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAA;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE/D;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAE5B;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAA;CAC5C"}
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/registrar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE/H,YAAY;AACV;;GAEG;AACH,kBAAkB;AAElB;;GAEG;AACH,aAAa;AAEb;;GAEG;AACH,oBAAoB;AAEpB;;GAEG;AACH,mBAAmB,EACpB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE,CAAA;IAExB;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/F;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAA;IAEjD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE/D;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAE5B;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAA;CAC5C"}

package/dist/src/transport-manager.d.ts

@@ -1,11 +1,25 @@
 import type { AbortOptions, Connection, Listener, Transport, TransportManagerDialProgressEvents } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
 import type { ProgressOptions } from 'progress-events';
+/**
+ * Options for dialing a connection using the `TransportManager`.
+ */
 export interface TransportManagerDialOptions extends AbortOptions, ProgressOptions<TransportManagerDialProgressEvents> {
 }
+/**
+ * The `TransportManager` handles the management of network transports, allowing
+ * opening connections or listening using specific transports, etc.
+ *
+ * This is a low-level component - any connections opened will not be managed by
+ * the `ConnectionManager` or included in any configured connection limits, etc.
+ *
+ * Most consumers will call `openConnection` on the `ConnectionManager` instead.
+ */
 export interface TransportManager {
     /**
-     * Add a transport to the transport manager
+     * Add a transport to the transport manager.
+     *
+     * @param transport - The transport instance to be added.
      */
     add(transport: Transport): void;
     /**
@@ -13,39 +27,63 @@ export interface TransportManager {
      * by the connection manager so can cause memory leaks. If you need to dial
      * a multiaddr, you may want to call openConnection on the connection manager
      * instead.
+     *
+     * @param ma - The multiaddr to dial.
+     * @param options - Optional dial options.
+     * @returns A promise that resolves to a `Connection` object.
      */
     dial(ma: Multiaddr, options?: TransportManagerDialOptions): Promise<Connection>;
     /**
      * Return all addresses currently being listened on
+     *
+     * @returns An array of `Multiaddr` objects.
      */
     getAddrs(): Multiaddr[];
     /**
      * Return all registered transports
+     *
+     * @returns An array of `Transport` instances.
      */
     getTransports(): Transport[];
     /**
      * Return all listeners
+     *
+     * @returns An array of `Listener` instances.
      */
     getListeners(): Listener[];
     /**
      * Get the transport to dial a given multiaddr, if one has been configured
+     *
+     * @param ma - The target multiaddr.
+     * @returns A `Transport` instance if available, otherwise `undefined`.
      */
     dialTransportForMultiaddr(ma: Multiaddr): Transport | undefined;
     /**
      * Get the transport to listen on a given multiaddr, if one has been
      * configured
+     *
+     * @param ma - The target multiaddr.
+     * @returns A `Transport` instance if available, otherwise `undefined`.
      */
     listenTransportForMultiaddr(ma: Multiaddr): Transport | undefined;
     /**
      * Listen on the passed multiaddrs
+     *
+     * @param addrs - An array of multiaddrs to listen on.
+     * @returns A promise that resolves once the transport is actively listening.
      */
     listen(addrs: Multiaddr[]): Promise<void>;
     /**
      * Remove a previously configured transport
+     *
+     * @param key - The transport key or identifier.
+     * @returns A promise that resolves once the transport is removed.
      */
     remove(key: string): Promise<void>;
     /**
      * Remove all transports
+     *
+     * @returns A promise that resolves once all transports are removed.
      */
     removeAll(): Promise<void>;
 }

package/dist/src/transport-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport-manager.d.ts","sourceRoot":"","sources":["../../src/transport-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,kCAAkC,EAAE,MAAM,mBAAmB,CAAA;AAC1H,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD,MAAM,WAAW,2BAA4B,SAAQ,YAAY,EAAE,eAAe,CAAC,kCAAkC,CAAC;CAErH;AAED,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAE/B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE/E;;OAEG;IACH,QAAQ,IAAI,SAAS,EAAE,CAAA;IAEvB;;OAEG;IACH,aAAa,IAAI,SAAS,EAAE,CAAA;IAE5B;;OAEG;IACH,YAAY,IAAI,QAAQ,EAAE,CAAA;IAE1B;;OAEG;IACH,yBAAyB,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAE/D;;;OAGG;IACH,2BAA2B,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAEjE;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}
+{"version":3,"file":"transport-manager.d.ts","sourceRoot":"","sources":["../../src/transport-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,kCAAkC,EAAE,MAAM,mBAAmB,CAAA;AAC1H,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,YAAY,EAAE,eAAe,CAAC,kCAAkC,CAAC;CAErH;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAE/B;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE/E;;;;OAIG;IACH,QAAQ,IAAI,SAAS,EAAE,CAAA;IAEvB;;;;OAIG;IACH,aAAa,IAAI,SAAS,EAAE,CAAA;IAE5B;;;;OAIG;IACH,YAAY,IAAI,QAAQ,EAAE,CAAA;IAE1B;;;;;OAKG;IACH,yBAAyB,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAE/D;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;IAEjE;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libp2p/interface-internal",
-  "version": "2.3.0-4ab04faf0",
+  "version": "2.3.0-68ad3663e",
   "description": "Interfaces implemented by internal libp2p components",
   "license": "Apache-2.0 OR MIT",
   "homepage": "https://github.com/libp2p/js-libp2p/tree/main/packages/interface-internal#readme",
@@ -48,8 +48,8 @@
     "build": "aegir build"
   },
   "dependencies": {
-    "@libp2p/interface": "2.5.0-4ab04faf0",
-    "@libp2p/peer-collections": "6.0.17-4ab04faf0",
+    "@libp2p/interface": "2.5.0-68ad3663e",
+    "@libp2p/peer-collections": "6.0.17-68ad3663e",
     "@multiformats/multiaddr": "^12.3.3",
     "progress-events": "^1.0.1"
   },

package/src/address-manager.ts

@@ -57,32 +57,48 @@ export interface ConfirmAddressOptions {
   type?: AddressType
 }
 
+/**
+ * The `AddressManager` provides an interface for managing peer addresses
+ * in libp2p. It supports handling multiple types of addresses, verifying their validity,
+ * and storing mappings between internal and external addresses.
+ */
 export interface AddressManager {
   /**
    * Get peer listen multiaddrs
+   *
+   * @returns An array of `Multiaddr` objects representing listen addresses.
    */
   getListenAddrs(): Multiaddr[]
 
   /**
    * Get peer announcing multiaddrs
+   *
+   * @returns An array of `Multiaddr` objects representing announce addresses.
    */
   getAnnounceAddrs(): Multiaddr[]
 
   /**
    * Get observed multiaddrs - these addresses may not have been confirmed as
    * publicly dialable yet
+   *
+   * @returns An array of `Multiaddr` objects representing observed addresses.
    */
   getObservedAddrs(): Multiaddr[]
 
   /**
    * Signal that we have confidence an observed multiaddr is publicly dialable -
    * this will make it appear in the output of getAddresses()
+   *
+   * @param addr - The observed address.
+   * @param options - Additional options for confirmation.
    */
   confirmObservedAddr(addr: Multiaddr, options?: ConfirmAddressOptions): void
 
   /**
    * Signal that we do not have confidence an observed multiaddr is publicly dialable -
    * this will remove it from the output of getObservedAddrs()
+   *
+   * @param addr - The observed address to remove.
    */
   removeObservedAddr(addr: Multiaddr): void
 
@@ -90,16 +106,22 @@ export interface AddressManager {
    * Add peer observed addresses.  These will then appear in the output of getObservedAddrs
    * but not getAddresses() until their dialability has been confirmed via a call to
    * confirmObservedAddr.
+   *
+   * @param addr - The observed address to add.
    */
   addObservedAddr(addr: Multiaddr): void
 
   /**
    * Get the current node's addresses
+   *
+   * @returns An array of `Multiaddr` objects representing node addresses.
    */
   getAddresses(): Multiaddr[]
 
   /**
    * Return all known addresses with metadata
+   *
+   * @returns An array of `NodeAddress` objects.
    */
   getAddressesWithMetadata(): NodeAddress[]
 
@@ -108,11 +130,16 @@ export interface AddressManager {
    * `getAddresses` is invoked, where the IP addresses are present in a
    * multiaddr, an additional multiaddr will be added with `ip4` and `ip6`
    * tuples replaced with `dns4` and `dns6 ones respectively.
+   *
+   * @param domain - The domain name to map.
+   * @param ipAddresses - The associated IP addresses.
    */
   addDNSMapping(domain: string, ipAddresses: string[]): void
 
   /**
    * Remove a mapping previously added with `addDNSMapping`.
+   *
+   * @param domain - The domain name mapping to remove.
    */
   removeDNSMapping(domain: string): void
 
@@ -125,11 +152,23 @@ export interface AddressManager {
    * It's possible to add a IPv6 address here and have it added to the address
    * list, this is for the case when a router has an external IPv6 address with
    * port forwarding configured, but it does IPv6 -> IPv4 NAT.
+   *
+   * @param internalIp - The internal IP address.
+   * @param internalPort - The internal port number.
+   * @param externalIp - The external IP address.
+   * @param externalPort - The external port number (optional).
+   * @param protocol - The transport protocol (`tcp` or `udp`).
    */
   addPublicAddressMapping (internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void
 
   /**
    * Remove a publicly routable address that this node is no longer reachable on
+   *
+   * @param internalIp - The internal IP address.
+   * @param internalPort - The internal port number.
+   * @param externalIp - The external IP address.
+   * @param externalPort - The external port number (optional).
+   * @param protocol - The transport protocol (`tcp` or `udp`).
    */
   removePublicAddressMapping (internalIp: string, internalPort: number, externalIp: string, externalPort?: number, protocol?: 'tcp' | 'udp'): void
 }

package/src/connection-manager.ts

@@ -3,6 +3,9 @@ import type { PeerMap } from '@libp2p/peer-collections'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { ProgressOptions } from 'progress-events'
 
+/**
+ * Options for opening a connection to a remote peer.
+ */
 export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<OpenConnectionProgressEvents> {
   /**
    * Connection requests with a higher priority will be executed before those
@@ -34,49 +37,50 @@ export interface OpenConnectionOptions extends AbortOptions, ProgressOptions<Ope
   initiator?: boolean
 }
 
+/**
+ * The `ConnectionManager` handles managing connections between peers in a libp2p network.
+ * It provides methods for opening, closing, and querying connections.This also provides methods
+ * for accessing the dial queue.
+ */
 export interface ConnectionManager {
   /**
    * Return connections, optionally filtering by a PeerId
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connections = libp2p.connectionManager.get(peerId)
-   * // []
-   * ```
+   * @param peerId - The PeerId to filter connections (optional).
+   * @returns An array of active `Connection` objects.
    */
   getConnections(peerId?: PeerId): Connection[]
 
   /**
    * Return a map of all connections with their associated PeerIds
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connectionsMap = libp2p.connectionManager.getConnectionsMap()
-   * ```
+   * @returns A `PeerMap` containing `Connection[]` objects.
    */
   getConnectionsMap(): PeerMap<Connection[]>
 
   /**
    * Returns the configured maximum number of connections this connection
    * manager will accept
+   *
+   * @returns The maximum connection limit.
    */
   getMaxConnections(): number
 
   /**
    * Open a connection to a remote peer
    *
-   * @example
-   *
-   * ```TypeScript
-   * const connection = await libp2p.connectionManager.openConnection(peerId)
-   * ```
+   * @param peer - The target `PeerId`, `Multiaddr`, or an array of `Multiaddr`s.
+   * @param options - Optional parameters for connection handling.
+   * @returns A promise that resolves to a `Connection` object.
    */
   openConnection(peer: PeerId | Multiaddr | Multiaddr[], options?: OpenConnectionOptions): Promise<Connection>
 
   /**
    * Close our connections to a peer
+   *
+   * @param peer - The `PeerId` whose connections should be closed.
+   * @param options - Optional abort options.
+   * @returns A promise that resolves once the connections are closed.
    */
   closeConnections(peer: PeerId, options?: AbortOptions): Promise<void>
 
@@ -85,6 +89,9 @@ export interface ConnectionManager {
    * exchanged, this lets the ConnectionManager check we have sufficient
    * resources to accept the connection in which case it will return true,
    * otherwise it will return false.
+   *
+   * @param maConn - The multiaddr connection to evaluate.
+   * @returns A promise that resolves to `true` if the connection can be accepted, `false` otherwise.
    */
   acceptIncomingConnection(maConn: MultiaddrConnection): Promise<boolean>
 
@@ -96,11 +103,7 @@ export interface ConnectionManager {
   /**
    * Return the list of in-progress or queued dials
    *
-   * @example
-   *
-   * ```TypeScript
-   * const dials = libp2p.connectionManager.getDialQueue()
-   * ```
+   * @returns An array of `PendingDial` objects.
    */
   getDialQueue(): PendingDial[]
 
@@ -112,6 +115,10 @@ export interface ConnectionManager {
    * would not block the dial attempt.
    *
    * This may involve resolving DNS addresses so you should pass an AbortSignal.
+   *
+   * @param multiaddr - The target multiaddr or an array of multiaddrs.
+   * @param options - Optional parameters for dialability check.
+   * @returns A promise that resolves to `true` if the multiaddr is dialable, `false` otherwise.
    */
   isDialable(multiaddr: Multiaddr | Multiaddr[], options?: IsDialableOptions): Promise<boolean>
 }

package/src/index.ts

@@ -1,3 +1,13 @@
+/**
+ * @packageDocumentation
+ *
+ * This module serves as the entry point for `@libp2p/interface-internal`,
+ * re-exporting key components such as `AddressManager`, `ConnectionManager`,
+ * `RandomWalk`, `Registrar`, and `TransportManager`.
+ *
+ * These interfaces and classes define the core internal behaviors of libp2p.
+ */
+
 export * from './address-manager.js'
 export * from './connection-manager.js'
 export * from './random-walk.js'

package/src/random-walk.ts

@@ -1,13 +1,20 @@
 import type { AbortOptions, PeerInfo } from '@libp2p/interface'
 
 /**
- * RandomWalk finds random peers on the network and dials them. Use this after
- * registering a Topology if you need to discover common network services.
+ * The `RandomWalk` component uses the libp2p peer routing to find arbitrary
+ * network peers. Consumers may then dial these peers, causing the Identify
+ * protocol to run and any registered topologies to be notified of their
+ * supported protocols.
  */
 export interface RandomWalk {
   /**
-   * Begin or join an existing walk. Abort the passed signal if you wish to
-   * abort the walk early.
+   * Initiates a random walk for peer discovery.
+   *
+   * This method either begins a new random walk or joins an existing one. The process
+   * continues to find and return random peers until it is aborted.
+   *
+   * @param options - Optional `AbortOptions` to allow early termination of the walk.
+   * @returns An `AsyncGenerator` that yields discovered `PeerInfo` objects.
    */
   walk(options?: AbortOptions): AsyncGenerator<PeerInfo>
 }

package/src/registrar.ts

@@ -22,24 +22,49 @@ export type {
   StreamHandlerRecord
 }
 
+/**
+ * The `Registrar` provides an interface for registering protocol handlers -
+ * these are invoked when remote peers open streams on the local node with the
+ * corresponding protocol name.
+ *
+ * It also allows configuring network topologies for a given protocol(s). The
+ * topology callbacks are invoked when a peer that supports those protocols
+ * connects or disconnects.
+ *
+ * The Identify protocol must be configured on the current node for topologies
+ * to function.
+ */
 export interface Registrar {
   /**
-   * Return the list of protocols with registered handlers
+   * Retrieve the list of registered protocol handlers.
+   *
+   * @returns An array of protocol strings.
    */
   getProtocols(): string[]
 
   /**
-   * Add a protocol handler
+   * Register a handler for a specific protocol.
+   *
+   * @param protocol - The protocol string (e.g., `/my-protocol/1.0.0`).
+   * @param handler - The function that handles incoming streams.
+   * @param options - Optional configuration options for the handler.
+   * @returns A promise that resolves once the handler is registered.
    */
   handle(protocol: string, handler: StreamHandler, options?: StreamHandlerOptions): Promise<void>
 
   /**
-   * Remove a protocol handler
+   * Remove a registered protocol handler.
+   *
+   * @param protocol - The protocol to unhandle.
+   * @returns A promise that resolves once the handler is removed.
    */
   unhandle(protocol: string): Promise<void>
 
   /**
-   * Return the handler for the passed protocol
+   * Retrieve the registered handler for a given protocol.
+   *
+   * @param protocol - The protocol to query.
+   * @returns A `StreamHandlerRecord` containing the handler and options.
    */
   getHandler(protocol: string): StreamHandlerRecord
 
@@ -50,17 +75,26 @@ export interface Registrar {
    *
    * An id will be returned that can later be used to unregister the
    * topology.
+   *
+   * @param protocol - The protocol to register.
+   * @param topology - The topology handler to register.
+   * @returns A promise resolving to a unique ID for the registered topology.
    */
   register(protocol: string, topology: Topology): Promise<string>
 
   /**
-   * Remove the topology handler with the passed id.
+   * Unregister a topology handler using its unique ID.
+   *
+   * @param id - The ID of the topology to unregister.
    */
   unregister(id: string): void
 
   /**
-   * Return all topology handlers that wish to be informed about peers
-   * that support the passed protocol.
+   * Retrieve all topology handlers that are interested in peers
+   * supporting a given protocol.
+   *
+   * @param protocol - The protocol to query.
+   * @returns An array of registered `Topology` handlers.
    */
   getTopologies(protocol: string): Topology[]
 }

package/src/transport-manager.ts

@@ -2,13 +2,27 @@ import type { AbortOptions, Connection, Listener, Transport, TransportManagerDia
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { ProgressOptions } from 'progress-events'
 
+/**
+ * Options for dialing a connection using the `TransportManager`.
+ */
 export interface TransportManagerDialOptions extends AbortOptions, ProgressOptions<TransportManagerDialProgressEvents> {
 
 }
 
+/**
+ * The `TransportManager` handles the management of network transports, allowing
+ * opening connections or listening using specific transports, etc.
+ *
+ * This is a low-level component - any connections opened will not be managed by
+ * the `ConnectionManager` or included in any configured connection limits, etc.
+ *
+ * Most consumers will call `openConnection` on the `ConnectionManager` instead.
+ */
 export interface TransportManager {
   /**
-   * Add a transport to the transport manager
+   * Add a transport to the transport manager.
+   *
+   * @param transport - The transport instance to be added.
    */
   add(transport: Transport): void
 
@@ -17,47 +31,71 @@ export interface TransportManager {
    * by the connection manager so can cause memory leaks. If you need to dial
    * a multiaddr, you may want to call openConnection on the connection manager
    * instead.
+   *
+   * @param ma - The multiaddr to dial.
+   * @param options - Optional dial options.
+   * @returns A promise that resolves to a `Connection` object.
    */
   dial(ma: Multiaddr, options?: TransportManagerDialOptions): Promise<Connection>
 
   /**
    * Return all addresses currently being listened on
+   *
+   * @returns An array of `Multiaddr` objects.
    */
   getAddrs(): Multiaddr[]
 
   /**
    * Return all registered transports
+   *
+   * @returns An array of `Transport` instances.
    */
   getTransports(): Transport[]
 
   /**
    * Return all listeners
+   *
+   * @returns An array of `Listener` instances.
    */
   getListeners(): Listener[]
 
   /**
    * Get the transport to dial a given multiaddr, if one has been configured
+   *
+   * @param ma - The target multiaddr.
+   * @returns A `Transport` instance if available, otherwise `undefined`.
    */
   dialTransportForMultiaddr(ma: Multiaddr): Transport | undefined
 
   /**
    * Get the transport to listen on a given multiaddr, if one has been
    * configured
+   *
+   * @param ma - The target multiaddr.
+   * @returns A `Transport` instance if available, otherwise `undefined`.
    */
   listenTransportForMultiaddr(ma: Multiaddr): Transport | undefined
 
   /**
    * Listen on the passed multiaddrs
+   *
+   * @param addrs - An array of multiaddrs to listen on.
+   * @returns A promise that resolves once the transport is actively listening.
    */
   listen(addrs: Multiaddr[]): Promise<void>
 
   /**
    * Remove a previously configured transport
+   *
+   * @param key - The transport key or identifier.
+   * @returns A promise that resolves once the transport is removed.
    */
   remove(key: string): Promise<void>
 
   /**
    * Remove all transports
+   *
+   * @returns A promise that resolves once all transports are removed.
    */
   removeAll(): Promise<void>
 }