libp2p/circuit-relay-v2: a static relay reservation (`CircuitListen`) is never re-established after the relay connection closes

• Version:
  Verified in @libp2p/circuit-relay-v2@4.2.11 (with libp2p@3.3.8), and the
  relevant code is unchanged on main at the time of filing
  (packages/transport-circuit-relay-v2/src/transport/index.ts and
  transport/listener.ts).

• Platform:
  Linux 7.0.0-29-generic #29-Ubuntu SMP PREEMPT_DYNAMIC Fri Jul 17 20:52:35 UTC 2026 x86_64 GNU/Linux

• Subsystem:
  circuit-relay-v2

Severity:

High

Description:

If you give libp2p a static relay in your listen addresses (/dns4/relay/.../p2p/Qm.../p2p-circuit), the reservation only ever gets made once. When the relay restarts (or the connection drops for any reason), the client reconnects fine but never re-reserves, so it's unreachable through the relay until you restart the whole process. There's no error either, it just silently stays broken. The internal re-add path assumes every relay was found via discovery and throws HadEnoughRelaysError for static ones, then swallows it. Bonus problem: if the relay happens to be down when your node boots, start() just throws. Repro script attached, ~100 lines, fails on 4.2.11 and current main.

Steps to reproduce the error:

Scenario A — the headline bug:

1. Relay up; client listens on <relayAddr>/p2p/<relayId>/p2p-circuit
2. Reservation established — client announces .../p2p-circuit (sanity check)
3. Relay stops; reservation removed
4. Relay restarts with the same key and port; client dials it again, identify completes
5. Expected: the /p2p-circuit address comes back
   Actual (bug): it never does

Scenario B — the boot-time sharp edge:

With the relay down, a node configured with the same listen address fails start() outright (no retry exists).

import { createLibp2p } from "libp2p";
import { webSockets } from "@libp2p/websockets";
import { noise } from "@chainsafe/libp2p-noise";
import { yamux } from "@chainsafe/libp2p-yamux";
import { identify } from "@libp2p/identify";
import { circuitRelayServer, circuitRelayTransport } from "@libp2p/circuit-relay-v2";
import { generateKeyPair } from "@libp2p/crypto/keys";
import { peerIdFromPrivateKey } from "@libp2p/peer-id";
import { multiaddr } from "@multiformats/multiaddr";

const RELAY_PORT = 40881;

function makeRelay(privateKey) {
  return createLibp2p({
    privateKey,
    addresses: { listen: [`/ip4/127.0.0.1/tcp/${RELAY_PORT}/ws`] },
    transports: [webSockets()],
    connectionEncrypters: [noise()],
    streamMuxers: [yamux()],
    services: {
      identify: identify(),
      relay: circuitRelayServer(),
    },
  });
}

function makeClient(relayListenAddr) {
  return createLibp2p({
    addresses: { listen: [relayListenAddr] },
    transports: [webSockets(), circuitRelayTransport()],
    connectionEncrypters: [noise()],
    streamMuxers: [yamux()],
    services: {
      identify: identify(),
    },
  });
}

const hasCircuitAddr = (node) =>
  node.getMultiaddrs().some((ma) => ma.toString().includes("/p2p-circuit"));

async function pollFor(label, predicate, timeoutMs) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    if (predicate()) {
      return true;
    }
    await new Promise((resolve) => setTimeout(resolve, 250));
  }
  return false;
}

const results = [];
const report = (name, ok, detail) => {
  results.push({ name, ok });
  console.log(`${ok ? "  PASS" : "  FAIL"}  ${name}${detail ? ` — ${detail}` : ""}`);
};

// ---------------------------------------------------------------- scenario A
console.log("scenario A: reservation is never re-established after relay restart");

const relayKey = await generateKeyPair("Ed25519");
const relayId = peerIdFromPrivateKey(relayKey);
const relayWsAddr = `/ip4/127.0.0.1/tcp/${RELAY_PORT}/ws/p2p/${relayId}`;
const relayListenAddr = `${relayWsAddr}/p2p-circuit`;

let relay = await makeRelay(relayKey);
const client = await makeClient(relayListenAddr);

report(
  "initial reservation established",
  await pollFor("reserve", () => hasCircuitAddr(client), 10_000),
  client.getMultiaddrs().map(String).join(", ") || "no addresses announced",
);

await relay.stop();
report(
  "reservation withdrawn after relay stops",
  await pollFor("withdraw", () => !hasCircuitAddr(client), 10_000),
);

relay = await makeRelay(relayKey);
await client.dial(multiaddr(relayWsAddr));
const reconnected = await pollFor(
  "reconnect",
  () => client.getConnections(relayId).length > 0,
  10_000,
);
report("client reconnected to the restarted relay", reconnected);

// Give the topology/identify/relay:discover path every opportunity to heal it.
const healed = await pollFor("re-reserve", () => hasCircuitAddr(client), 30_000);
if (healed) {
  report("reservation re-established after reconnect", true, "bug NOT reproduced on this version");
} else {
  report(
    "BUG REPRODUCED: connected to the relay for 30s, reservation never re-established",
    true,
    `announced: [${client.getMultiaddrs().map(String).join(", ") || "nothing"}]`,
  );
}

await client.stop();
await relay.stop();

// ---------------------------------------------------------------- scenario B
console.log("scenario B: node start() fails outright when the configured relay is down");
try {
  const orphan = await makeClient(relayListenAddr); // relay is stopped now
  await orphan.stop();
  report("BUG NOT REPRODUCED: start() succeeded with the relay down", true);
} catch (error) {
  report(
    `BUG REPRODUCED: start() threw with the relay down`,
    true,
    `${error.name}: ${String(error.message).slice(0, 120)}`,
  );
}

console.log(`\n${results.every((r) => r.ok) ? "all checks completed" : "CHECKS FAILED"}`);
process.exit(results.every((r) => r.ok) ? 0 : 1);

Start with packages/transport-circuit-relay-v2/src/transport/index.ts and transport/listener.ts, then run the attached reproduction script for scenarios A and B. Trace static relay reservation setup, reconnect handling, and startup when the relay is unavailable. Done means reservations return after reconnect and startup does not fail permanently when the relay is down.