Endpoint lifecycle

Persist an identity, own the endpoint lifetime on each runtime, and shut down cleanly.

A Minip2p object owns one endpoint. Its identity, events, pending Promises, and streams all share that lifetime.

Identity first

The secret key is the node’s identity. Generate it once, store the raw 32 bytes somewhere protected, and supply the same bytes on later launches when the node needs a stable peer ID.

import { generateSecretKey, peerIdFromSecretKey } from "@minip2p/node";

const secretKey = generateSecretKey();
const peerId = peerIdFromSecretKey(secretKey);

import {
  generateSecretKey,
  peerIdFromSecretKey,
} from "@minip2p/react-native";

const secretKey = generateSecretKey();
const peerId = peerIdFromSecretKey(secretKey);

peerIdFromSecretKey derives the public peer identity without starting an endpoint. Treat secretKey as credentials: do not log it or transmit it.

• On Node.js, keep it in a file with restrictive permissions or a secret manager, and do not bake it into an image.
• On React Native, keep it in platform-appropriate secure storage, not in ordinary preferences.

Own the process lifetime

A started endpoint holds a strong event-loop reference. The process will not exit until close() is called, so a long-running service should wire shutdown to its termination signals:

import { Minip2p } from "@minip2p/node";

const endpoint = Minip2p.create({ secretKey });

for (const signal of ["SIGINT", "SIGTERM"] as const) {
  process.once(signal, () => {
    endpoint.close();
  });
}

close() returns quickly rather than blocking on network teardown, and it releases the event-loop reference, so the process can exit once nothing else keeps it alive.

Minip2p also implements Symbol.dispose. In a scoped tool or test, a using declaration closes the endpoint at scope exit:

using endpoint = Minip2p.create({ secretKey });

Prefer the lifecycle hook

useMinip2p is the normal component interface. It starts in starting, then exposes the endpoint after creation succeeds.

const node = useMinip2p(createConfig);

switch (node.status) {
  case "starting":
    return <LoadingView />;
  case "failed":
    return <ErrorView error={node.error} />;
  case "closed":
    return <ClosedView />;
  case "running":
    return <PeerView endpoint={node.endpoint} peerId={node.peerId} />;
}

Every state also carries an idempotent close() callback. Component cleanup unbinds AppState and closes the endpoint automatically.

Use isDriverFailure(node) to narrow a failed hook state to DriverFailedError when the UI needs the machine-readable failure kind.

Active and idle

An endpoint starts active. setActive(false) reduces background work at the cost of higher network latency. setActive(true) restores normal behavior on the same endpoint. Servers normally stay active.

Foreground and background

The hook immediately mirrors the current React Native AppState and keeps it in sync:

• active selects foreground polling;
• every other state reduces background work.

This does not destroy the endpoint. When the app returns to the foreground, the same endpoint becomes active again.

If the endpoint is not component-owned, bind and release AppState manually:

import {
  Minip2p,
  bindAppState,
  generateSecretKey,
} from "@minip2p/react-native";

const endpoint = Minip2p.create({
  secretKey: generateSecretKey(),
});
const unbindAppState = bindAppState(endpoint);

// Later, in the owner's cleanup path:
unbindAppState();
endpoint.close();

bindAppState applies the current state before it subscribes to later changes.

Close is terminal

endpoint.close() is idempotent. It:

1. rejects pending Promise operations;
2. closes owned Stream handles;
3. stops the endpoint;
4. invokes each onClose observer once.

const removeClose = endpoint.onClose((reason) => {
  if (reason.reason === "driverFailed") {
    console.error(reason.error.kind, reason.error.message);
  }
});

endpoint.close();
removeClose();

Next: Connections and streams and Networking and events, or the TypeScript API reference.