@serfab/cadre-core 1.14.0 → 1.16.0

package/dist/node-claim-payload.js

@@ -13,7 +13,7 @@
  * `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the browser.
  */
 import { peerIdFromString } from '@libp2p/peer-id';
-import { multiaddr, CODE_P2P, CODE_P2P_CIRCUIT } from '@multiformats/multiaddr';
+import { multiaddr, CODE_DNS, CODE_DNS4, CODE_DNS6, CODE_DNSADDR, CODE_IP4, CODE_IP6, CODE_IP6ZONE, CODE_P2P, CODE_P2P_CIRCUIT, CODE_WS, CODE_WSS, } from '@multiformats/multiaddr';
 import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
 import { canonicalJson } from './canonical-json.js';
 import { parseClaimSecret } from './claim-proof.js';
@@ -57,6 +57,108 @@ export function decodeNodeClaimPayload(text) {
         throw new Error('A claim payload must carry the claim secret');
     return requireNodeClaimPayload({ peerId, multiaddrs, secret });
 }
+/**
+ * The addresses a node code should carry, from the ones a node knows it has (`/status`,
+ * a NAT layer's public addresses). A phone dials them in turn, each on its own timeout, so
+ * every address it cannot reach only delays a failing claim, and makes the QR code bigger.
+ *
+ * - Each gains `/p2p/<peerId>` when it lacks a destination; loopback, unspecified and
+ *   unparsable ones are dropped, and so is plain TCP unless `includeTcp`.
+ * - Public names (`/dns*`) come first: they work away from home. Public IP addresses are
+ *   kept only when there is no public name, since they reach the same machine.
+ * - Private addresses follow, narrowed by {@link NodeClaimAddressOptions.lan}; relay
+ *   addresses last.
+ *
+ * Pure and dependency-light, like the codec beside it, so it loads on React Native too.
+ * Finding the LAN address is the caller's (Node: `@serfab/cadre-core/primary-lan-address`).
+ */
+export function selectNodeClaimAddresses(reported, peerId, options = {}) {
+    const names = [];
+    const publicIps = [];
+    const privates = [];
+    const relayed = [];
+    for (const raw of reported) {
+        const classified = classifyClaimAddress(raw.trim(), peerId, options);
+        if (!classified)
+            continue;
+        ({ name: names, public: publicIps, private: privates, relay: relayed })[classified.kind].push(classified.addr);
+    }
+    return [...new Set([...names, ...(names.length > 0 ? [] : publicIps), ...privates, ...relayed])];
+}
+/**
+ * `addr` as a node code carries it: with `/p2p/<peerId>` appended unless it already names a
+ * destination. A relay address that ends at its hop (`…/p2p/<relay>/p2p-circuit`) names none,
+ * so it gains the node's id too. Throws when `addr` does not parse. For callers that take
+ * exact addresses from an operator; {@link selectNodeClaimAddresses} applies it itself.
+ */
+export function withClaimDestination(addr, peerId) {
+    const trimmed = addr.trim();
+    return destinationPeerIdOf(trimmed) === null ? `${trimmed}/p2p/${peerId}` : trimmed;
+}
+/**
+ * Classify `addr` for a phone dialing it, or undefined when no phone can dial it at all: it
+ * does not parse, names the unspecified address, or is plain TCP without `includeTcp` (phones
+ * dial WebSocket and relay only).
+ */
+export function classifyDialAddress(addr, options = {}) {
+    const components = componentsOf(addr);
+    return components ? classifyComponents(components, options.includeTcp ?? false)?.kind : undefined;
+}
+function componentsOf(addr) {
+    try {
+        return multiaddr(addr).getComponents();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** {@link classifyDialAddress}, keeping the IP for a caller that narrows private addresses by it. */
+function classifyComponents(components, includeTcp) {
+    if (components.some((c) => c.code === CODE_P2P_CIRCUIT))
+        return { kind: 'relay' };
+    if (!includeTcp && !components.some((c) => c.code === CODE_WS || c.code === CODE_WSS))
+        return undefined;
+    const host = components[0];
+    if (!host?.value)
+        return undefined;
+    if (host.code === CODE_DNS || host.code === CODE_DNS4 || host.code === CODE_DNS6 || host.code === CODE_DNSADDR) {
+        return { kind: host.value === 'localhost' ? 'loopback' : 'name' };
+    }
+    if (host.code !== CODE_IP4 && host.code !== CODE_IP6 && host.code !== CODE_IP6ZONE)
+        return undefined;
+    const ip = host.code === CODE_IP6ZONE ? components[1]?.value ?? '' : host.value;
+    if (ip === '0.0.0.0' || ip === '::')
+        return undefined;
+    if (ip.startsWith('127.') || ip === '::1')
+        return { kind: 'loopback', ip };
+    if (host.code !== CODE_IP6ZONE && !isPrivateIp(ip))
+        return { kind: 'public', ip };
+    return { kind: 'private', ip };
+}
+/** One address's place in {@link selectNodeClaimAddresses}, or undefined to drop it. */
+function classifyClaimAddress(addr, peerId, options) {
+    const components = componentsOf(addr);
+    if (!components)
+        return undefined;
+    const classified = classifyComponents(components, options.includeTcp ?? false);
+    if (!classified || classified.kind === 'loopback')
+        return undefined;
+    if (classified.kind === 'private' && (options.lan === null || (options.lan !== undefined && classified.ip !== options.lan))) {
+        return undefined;
+    }
+    return { kind: classified.kind, addr: destinationIn(components) === null ? `${addr}/p2p/${peerId}` : addr };
+}
+/** RFC 1918, carrier-grade NAT (100.64/10), link-local, and IPv6 unique-local / link-local. */
+function isPrivateIp(ip) {
+    if (ip.includes(':'))
+        return /^(f[cd]|fe[89ab])/i.test(ip);
+    const [a, b] = ip.split('.').map(Number);
+    return a === 10
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 169 && b === 254)
+        || (a === 100 && b >= 64 && b <= 127);
+}
 /** The shape rules both directions apply. Returns the payload with its fields trimmed. */
 function requireNodeClaimPayload(payload) {
     const peerId = parsePeerId(payload.peerId);
@@ -104,10 +206,12 @@ function requireAddressOf(addr, peerId) {
  * The peer an address reaches: its last `/p2p/` component. A relayed address
  * (`…/p2p/<relay>/p2p-circuit/p2p/<destination>`) names its destination after the
  * circuit hop; one that ends at the hop names nobody. Same rule as
- * `groupAddrsByPeerId` in `peer-addr-book.ts`.
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`. Throws when `addr` does not parse.
  */
-function destinationPeerIdOf(addr) {
-    const components = multiaddr(addr).getComponents();
+export function destinationPeerIdOf(addr) {
+    return destinationIn(multiaddr(addr).getComponents());
+}
+function destinationIn(components) {
     for (let i = components.length - 1; i >= 0; i--) {
         const component = components[i];
         if (component.code === CODE_P2P_CIRCUIT)

package/dist/node-claim-payload.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-claim-payload.js","sourceRoot":"","sources":["../src/node-claim-payload.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node-claim-payload.js","sourceRoot":"","sources":["../src/node-claim-payload.ts"],"names":[],"mappings":"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"}

package/dist/node-default-transports.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Node-only: `@optimystic/db-p2p`'s default transport list, for `NetworkConfig.defaultTransports`.
+ *
+ * A node with configured relays is built from an explicit transport list, so that libp2p's relay
+ * discovery can be switched off in it (`node-transports.ts`). A Node host that supplies no
+ * `network.transports` passes this function so that list still matches what db-p2p would have
+ * built. A subpath module (`@serfab/cadre-core/node-default-transports`), like `push-node`,
+ * because it names `@libp2p/tcp`: some bundlers (the NativeScript reference app's webpack) take
+ * its Node implementation rather than its browser stub, and that needs `net`, `os` and `path`.
+ */
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import type { ListenTransportOptions } from './relay-addrs.js';
+/**
+ * TCP, WebSocket exactly when the node's listen entries switch it on, and the circuit-relay
+ * transport.
+ *
+ * Passing an explicit list makes db-p2p ignore `wsPort` for transports, which is why WebSocket is
+ * decided here from the same switch. Its other use of `wsPort`, a default WebSocket listen
+ * address, never applies: a node with configured relays always has explicit listen entries.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s default list in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (cadre never sets its `disableTcp`). That file
+ * is the source of truth; if its defaults change, this list has to follow. If db-p2p ever takes an
+ * option to build its default list with relay discovery off, use that and drop this module and
+ * `NetworkConfig.defaultTransports`.
+ */
+export declare function nodeDefaultTransports({ wsPort }: ListenTransportOptions): Libp2pTransports;

package/dist/node-default-transports.js

@@ -0,0 +1,35 @@
+/**
+ * Node-only: `@optimystic/db-p2p`'s default transport list, for `NetworkConfig.defaultTransports`.
+ *
+ * A node with configured relays is built from an explicit transport list, so that libp2p's relay
+ * discovery can be switched off in it (`node-transports.ts`). A Node host that supplies no
+ * `network.transports` passes this function so that list still matches what db-p2p would have
+ * built. A subpath module (`@serfab/cadre-core/node-default-transports`), like `push-node`,
+ * because it names `@libp2p/tcp`: some bundlers (the NativeScript reference app's webpack) take
+ * its Node implementation rather than its browser stub, and that needs `net`, `os` and `path`.
+ */
+import { tcp } from '@libp2p/tcp';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+/**
+ * TCP, WebSocket exactly when the node's listen entries switch it on, and the circuit-relay
+ * transport.
+ *
+ * Passing an explicit list makes db-p2p ignore `wsPort` for transports, which is why WebSocket is
+ * decided here from the same switch. Its other use of `wsPort`, a default WebSocket listen
+ * address, never applies: a node with configured relays always has explicit listen entries.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s default list in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (cadre never sets its `disableTcp`). That file
+ * is the source of truth; if its defaults change, this list has to follow. If db-p2p ever takes an
+ * option to build its default list with relay discovery off, use that and drop this module and
+ * `NetworkConfig.defaultTransports`.
+ */
+export function nodeDefaultTransports({ wsPort }) {
+    return [
+        tcp(),
+        ...(wsPort === undefined ? [] : [webSockets()]),
+        circuitRelayTransport()
+    ];
+}
+//# sourceMappingURL=node-default-transports.js.map

package/dist/node-default-transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-default-transports.js","sourceRoot":"","sources":["../src/node-default-transports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAIjE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAE,MAAM,EAA0B;IACtE,OAAO;QACL,GAAG,EAAE;QACL,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;QAC/C,qBAAqB,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/node-transports.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `transports` option for a cadre-built libp2p node, control and strand alike.
+ *
+ * A node whose bare `/p2p-circuit` search entries cadre generated for configured relays gets its
+ * transports through {@link withoutRelayDiscovery}, so libp2p's relay discovery cannot hand those
+ * slots to some other relay-capable peer before the per-relay supervisors fill them (see
+ * `relay-reservation.ts`, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other node gets
+ * the embedder's list as it was, or no option at all, and `@optimystic/db-p2p` builds its own
+ * default list.
+ *
+ * The wrapper needs a list to wrap. React Native and browser embedders always supply one
+ * (`network.transports`); a Node host supplies the default list through
+ * `network.defaultTransports` instead, since db-p2p builds its default internally and it names
+ * `@libp2p/tcp`, which this module's graph must not reach (`node-default-transports.ts`).
+ */
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import type { ListenTransportOptions } from './relay-addrs.js';
+import type { NetworkConfig } from './types.js';
+/**
+ * The `transports` option to spread into a node's `createLibp2pNode` options.
+ *
+ * @param listenTransports what the node's resolved listen entries imply (`resolveTransportOptions`
+ *   in `relay-addrs.ts`), handed to `network.defaultTransports`.
+ * @param relaySlotsSupervised whether cadre generated this node's bare `/p2p-circuit` entries for
+ *   configured relays and runs a supervisor over them — `network.relayAddrs` on the control node,
+ *   a non-empty relay list from `strandNodeAddrs` on a strand node.
+ */
+export declare function nodeTransportsOption(network: NetworkConfig | undefined, listenTransports: ListenTransportOptions, relaySlotsSupervised: boolean): {
+    transports?: Libp2pTransports;
+};

package/dist/node-transports.js

@@ -0,0 +1,40 @@
+/**
+ * The `transports` option for a cadre-built libp2p node, control and strand alike.
+ *
+ * A node whose bare `/p2p-circuit` search entries cadre generated for configured relays gets its
+ * transports through {@link withoutRelayDiscovery}, so libp2p's relay discovery cannot hand those
+ * slots to some other relay-capable peer before the per-relay supervisors fill them (see
+ * `relay-reservation.ts`, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other node gets
+ * the embedder's list as it was, or no option at all, and `@optimystic/db-p2p` builds its own
+ * default list.
+ *
+ * The wrapper needs a list to wrap. React Native and browser embedders always supply one
+ * (`network.transports`); a Node host supplies the default list through
+ * `network.defaultTransports` instead, since db-p2p builds its default internally and it names
+ * `@libp2p/tcp`, which this module's graph must not reach (`node-default-transports.ts`).
+ */
+import debug from 'debug';
+import { withoutRelayDiscovery } from './relay-reservation.js';
+const log = debug('sereus:cadre:node-transports');
+/**
+ * The `transports` option to spread into a node's `createLibp2pNode` options.
+ *
+ * @param listenTransports what the node's resolved listen entries imply (`resolveTransportOptions`
+ *   in `relay-addrs.ts`), handed to `network.defaultTransports`.
+ * @param relaySlotsSupervised whether cadre generated this node's bare `/p2p-circuit` entries for
+ *   configured relays and runs a supervisor over them — `network.relayAddrs` on the control node,
+ *   a non-empty relay list from `strandNodeAddrs` on a strand node.
+ */
+export function nodeTransportsOption(network, listenTransports, relaySlotsSupervised) {
+    if (!relaySlotsSupervised) {
+        return network?.transports ? { transports: network.transports } : {};
+    }
+    const transports = network?.transports ?? network?.defaultTransports?.(listenTransports);
+    if (transports === undefined) {
+        log('Relays are configured but no transport list was supplied (network.transports or ' +
+            'network.defaultTransports); libp2p relay discovery stays on and can take their slots');
+        return {};
+    }
+    return { transports: withoutRelayDiscovery(transports) };
+}
+//# sourceMappingURL=node-transports.js.map

package/dist/node-transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-transports.js","sourceRoot":"","sources":["../src/node-transports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,MAAM,GAAG,GAAG,KAAK,CAAC,8BAA8B,CAAC,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAkC,EAClC,gBAAwC,EACxC,oBAA6B;IAE7B,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,OAAO,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,iBAAiB,EAAE,CAAC,gBAAgB,CAAC,CAAC;IACzF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,GAAG,CAAC,kFAAkF;YACpF,sFAAsF,CAAC,CAAC;QAC1F,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,qBAAqB,CAAC,UAAU,CAAC,EAAE,CAAC;AAC3D,CAAC"}

package/dist/peer-dial.d.ts

@@ -16,17 +16,60 @@
  * borrowing a node from a cadre-host whose only reachable address was the
  * forwarded loopback one never connected for this reason.
  *
- * So the addresses are dialed here, each as its own `dial()` with its own time
- * limit ({@link PeerDialBudget.perAddressMs}), inside a limit for the whole peer
- * ({@link PeerDialBudget.totalMs}). One address per call also means libp2p's
- * sorter has nothing to reorder, so the order is chosen here
- * ({@link directBeforeRelayed}).
- *
- * Dependency-free apart from `control-stream.ts`, so any module may import it
- * without creating an import cycle.
+ * So the addresses are dialed here, each as its own transport-manager dial
+ * ({@link dialAddr}) with its own time limit ({@link PeerDialBudget.perAddressMs}),
+ * inside a limit for the whole peer ({@link PeerDialBudget.totalMs}). One address
+ * per call also means libp2p's sorter has nothing to reorder, so the order is
+ * chosen here ({@link directBeforeRelayed}). The dial goes around libp2p's dial
+ * queue because the queue joins any dial of a peer to a queued job for that peer
+ * id, whatever address the new dial names — see {@link dialAddr}. Every address
+ * is bound to the peer the caller expects ({@link withTrailingPeerId}) so the
+ * handshake verifies who answered.
+ *
+ * Dependency-free apart from `control-stream.ts` and `link-budget.ts`, so any
+ * module may import it without creating an import cycle. That is why the two
+ * address helpers ({@link trailingPeerId}, {@link withTrailingPeerId}) live here
+ * rather than in `peer-record.ts`, which pulls in the crypto plugin.
  */
-import type { Connection, PeerId } from '@libp2p/interface';
+import type { Connection, Libp2pStatus, PeerId } from '@libp2p/interface';
 import type { Multiaddr } from '@multiformats/multiaddr';
+/**
+ * The peer id a multiaddr terminates in, or `null` when it names none.
+ *
+ * The LAST `/p2p/` component is the dial target: a circuit address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<target>`) names the relay first and the peer
+ * being reached last. Replaces the deprecated `Multiaddr.getPeerId()`, which
+ * cannot express that distinction.
+ */
+export declare function trailingPeerId(addr: Multiaddr): string | null;
+/**
+ * `addr` guaranteed to terminate in `/p2p/<peerId>` — the shape every dial needs,
+ * since the upgrader verifies that id during the handshake — or `null` when it
+ * cannot, because the address already terminates in a DIFFERENT peer id and
+ * therefore does not reach `peerId` at all.
+ *
+ * Three input shapes, matching what a `CadrePeer` record can legitimately carry:
+ *
+ * - no `/p2p/` component (`/ip4/1.2.3.4/tcp/4001`) — the suffix is appended;
+ * - a relay hop with the destination missing (`…/p2p/<relay>/p2p-circuit`) — the
+ *   last component is the circuit, not a peer id, so the suffix is appended and
+ *   the address becomes the full `…/p2p/<relay>/p2p-circuit/p2p/<peerId>`;
+ * - already terminating in `/p2p/<X>` — returned untouched when `X` is `peerId`,
+ *   dropped otherwise.
+ *
+ * This is deliberately the same rule libp2p applies internally in
+ * `calculateMultiaddrs` (append when the LAST component is not `p2p`) followed by
+ * its wrong-peer-id filter, so a normalized list matches what libp2p would have
+ * built anyway. Normalizing before a list dial is what keeps a list from mixing
+ * suffixed and unsuffixed entries, which `getPeerAddress` rejects outright
+ * ("Multiaddrs must all have the same peer id or have no peer id") — taking the
+ * whole peer down with it, not just the odd address.
+ *
+ * Throws when `peerId` does not parse as a peer id (the encapsulation validates
+ * it). Never use before signature verification: verification runs against the
+ * original on-record strings.
+ */
+export declare function withTrailingPeerId(addr: Multiaddr, peerId: string): Multiaddr | null;
 /**
  * Default limit on ONE address's dial attempt, in ms, at the DEFAULT declared link round trip:
  * `RELAYED_DIAL_ROUND_TRIPS` (5) x `DECLARED_LINK_ROUND_TRIP_MS` (3500 ms) plus
@@ -103,14 +146,60 @@ export interface PeerDialBudget {
 }
 /** {@link PeerDialBudget} built from the two defaults above. */
 export declare const DEFAULT_PEER_DIAL_BUDGET: Readonly<PeerDialBudget>;
+/** What {@link dialAddr} reads of a connection the node holds, to decide whether to hand it back instead of dialing. */
+export interface ReusableConnection {
+    remotePeer: {
+        toString(): string;
+    };
+    status?: Connection['status'];
+    limits?: Connection['limits'];
+    /** Whether the connection is direct rather than relayed; absent counts as direct. */
+    direct?: boolean;
+}
 /** The slice of a libp2p node {@link dialPeerAddrs} uses. */
 export interface AddrDialer {
     /** This node's id, to recognise an address that relays through this node ({@link relaysThrough}). */
     readonly peerId: PeerId;
+    /** libp2p's lifecycle state: {@link dialAddr} refuses to start an attempt once it is not `started`. */
+    readonly status?: Libp2pStatus;
+    /**
+     * The connections this node holds to `peerId`. {@link dialAddr} returns an open one without relay
+     * limits rather than opening a second — what libp2p's dial queue did (`findExistingConnection`)
+     * and the transport manager does not. Optional so a double need not provide it, and typed by
+     * what is read of each connection so the strand redial's node slice (bare `remotePeer`s, which
+     * never count as open) satisfies it without a cast.
+     */
+    getConnections?(peerId?: PeerId): ReadonlyArray<ReusableConnection>;
     dial(addr: Multiaddr, options: {
         signal: AbortSignal;
     }): Promise<Connection>;
 }
+/**
+ * Dial ONE address outside libp2p's dial queue. The queue joins any new dial to a queued job
+ * for the same peer id, whatever address the new dial names, and a joined job ends only when
+ * every caller has aborted — so while another caller dials this peer (FRET's membership probe,
+ * an Optimystic cluster client), a per-address attempt through the queue waits on whatever
+ * address that job is on instead of its own. The transport manager dials exactly the address
+ * given; the two gater hooks the queue would have consulted are run here, and the upgrader
+ * still runs `denyOutboundConnection` and verifies the peer id the address carries during the
+ * Noise handshake, so the address must carry the id of the peer expected to answer
+ * ({@link withTrailingPeerId}). An open connection to that peer without relay limits is handed
+ * back instead of dialing ({@link reusableConnection}), as the queue would have. A relayed
+ * address still passes through the queue for its relay leg (the circuit transport dials the
+ * relay by peer id).
+ *
+ * The queue would also have aborted the attempt at shutdown; here the node's `status` is
+ * checked before dialing and its `stop` event aborts an attempt in flight. Without
+ * `transportManager.dial` (libp2p internals moved) the attempt goes through the queue, logged.
+ *
+ * What else the queue did that this does not: record the outcome in the peer store
+ * (`LAST_DIAL_SUCCESS_KEY` / `LAST_DIAL_FAILURE_KEY`, read only by libp2p's own address sorter,
+ * which these dials do not use); apply `maxParallelDials` and `maxDialQueueLength`; and refuse
+ * a dial of this node's own id before touching the network — the upgrader still throws
+ * `Can not dial self` after the handshake, `dialPeerAddrs` drops addresses relaying through this
+ * node, `applySeed` skips itself, and the reconcile pass never lists itself.
+ */
+export declare function dialAddr(dialer: AddrDialer, addr: Multiaddr, signal: AbortSignal, label: string): Promise<Connection>;
 /**
  * Thrown by {@link dialPeerAddrs} when it was given addresses but every one reaches the peer by
  * relaying through this node, so none was dialed.
@@ -138,25 +227,33 @@ export declare class PeerUnreachableError extends Error {
     constructor(peerId: string, cause: unknown);
 }
 /**
- * Dial one peer from `addrs`, one address per `dial()` call, and return the
+ * Dial `peerId` from `addrs`, one address per {@link dialAddr} call, and return the
  * first connection that forms. Direct addresses are tried before relayed ones
  * ({@link directBeforeRelayed}); otherwise the given order is kept.
  *
- * Addresses that relay through this node are dropped first ({@link relaysThrough}):
- * dialing one could only fail with `Can not dial self`. When that leaves nothing
- * of a non-empty list, this throws {@link SelfRelayOnlyError} without dialing.
+ * Every address is first bound to `peerId` ({@link withTrailingPeerId}), so the
+ * handshake verifies that the peer expected is the one that answered; an address
+ * naming another peer is dropped and logged. When that leaves nothing of a
+ * non-empty list — every address names someone else, or `peerId` does not parse —
+ * this throws without dialing.
+ *
+ * Addresses that relay through this node are dropped next ({@link relaysThrough}):
+ * dialing one could only fail with `Can not dial self`. When that leaves nothing,
+ * this throws {@link SelfRelayOnlyError} without dialing.
  *
- * Addresses naming a transport this node lacks are not filtered out first: a
- * one-address `dial()` rejects those at once (`NoValidAddressesError`), so they
+ * Addresses naming a transport this node lacks are not filtered out first: the
+ * transport manager rejects those at once (`TransportUnavailableError`), so they
  * cost a log line, not time.
  *
  * Otherwise throws when no address connects — see {@link tryAddrsInTurn} for the error.
  *
+ * @param peerId The peer every address must reach, as every caller already holds it
+ *   (a `CadrePeer` row key, a seed peer's id, a strand member's id).
  * @param label Names the dial in timeout messages and logs, e.g.
  *   `reconcileControlCohort dial of sibling <peerId>`; each attempt reads
  *   `<label> via <addr>`.
  */
-export declare function dialPeerAddrs(dialer: AddrDialer, addrs: readonly Multiaddr[], budget: PeerDialBudget, label: string): Promise<Connection>;
+export declare function dialPeerAddrs(dialer: AddrDialer, peerId: string, addrs: readonly Multiaddr[], budget: PeerDialBudget, label: string): Promise<Connection>;
 /**
  * Run `attempt` against each address in the given order until one succeeds, and
  * return its result.
@@ -171,17 +268,17 @@ export declare function dialPeerAddrs(dialer: AddrDialer, addrs: readonly Multia
  * failed, in order, with the first failure as `cause` — so the report shows the
  * address that mattered, not only whichever happened to be tried last.
  *
- * Between attempts this waits for one macrotask (`setTimeout(0)`). libp2p's dial
- * queue lets a new `dial()` join any queued dial job for the same peer id
- * WITHOUT checking whether that job has already finished, and an aborted job
- * leaves the queue a few microtasks after its callers are rejected. Timing out
- * one address and immediately dialing the next for the same peer therefore
- * joins the dying job, which rejects the new dial with `AbortError` before it
- * touches the network — the next address is never tried. Seen against libp2p
- * 3.1.3, and the queue's join is unchanged in 3.3.11; `test/peer-dial.spec.ts`
- * dials real nodes so an upgrade that changes it shows up there. All of the
- * queue's cleanup runs as microtasks, so it has finished by the time a
- * macrotask runs.
+ * Between attempts this waits for one macrotask (`setTimeout(0)`). A direct
+ * address is dialed outside libp2p's dial queue ({@link dialAddr}), but a relayed
+ * address still passes through it for the relay leg, and the queue lets a new
+ * dial join any queued job for the same peer id WITHOUT checking whether that
+ * job has already finished: an aborted job leaves the queue a few microtasks
+ * after its callers are rejected, so a next attempt through the same relay made
+ * at once would join the dying job and be rejected with `AbortError` before it
+ * touches the network. All of the queue's cleanup runs as microtasks, so it has
+ * finished by the time a macrotask runs. Seen against libp2p 3.1.3, and the
+ * queue's join is unchanged in 3.3.11; `test/peer-dial.spec.ts` dials real nodes
+ * so an upgrade that changes it shows up there.
  */
 export declare function tryAddrsInTurn<T>(addrs: readonly Multiaddr[], budget: PeerDialBudget, label: string, attempt: (addr: Multiaddr, signal: AbortSignal, attemptMs: number) => Promise<T>): Promise<T>;
 /**