p2p-fret 1.0.0-beta.4 → 1.0.0

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 import type { Libp2p } from 'libp2p';
-import type { SerializedPeerEntry, SerializedTable } from './store/digitree-store.js';
+import type { PrivateKey } from '@libp2p/interface';
+import type { SerializedAddressRecord, SerializedPeerEntry, SerializedTable } from './store/digitree-store.js';
 import { FretService as FretServiceClass } from './service/fret-service.js';
 export type FretMode = 'active' | 'passive';
 export interface FretConfig {
@@ -17,6 +18,28 @@ export interface FretConfig {
      * spacing window count once, so the run is genuinely spread over time.
      */
     deadAfterFailures?: number;
+    /**
+     * This node's libp2p private key — the key `node.peerId` was derived from.
+     *
+     * Used to seal this node's own signed address record (a libp2p `PeerRecord` envelope) for the
+     * `hints` field of its outgoing neighbour snapshots, so peers that only ever hear of this node
+     * through FRET can still dial it. libp2p hands the key to services as the `privateKey`
+     * component, so `Libp2pFretService` fills this in automatically; a caller constructing the core
+     * service directly passes it here. The constructor throws if the key does not derive
+     * `node.peerId`. Absent → this node advertises no record for itself (logged once at `start()`);
+     * forwarding other peers' records and consuming received ones are unaffected.
+     */
+    privateKey?: PrivateKey;
+}
+/**
+ * One signed address record riding on a neighbour snapshot: `record` is the base64url encoding
+ * of a marshaled libp2p `RecordEnvelope` over a `PeerRecord` whose signer and payload peer id are
+ * both `id`. The receiver verifies all of that before the record touches its peerStore — see
+ * `FretService.ingestAddressHints`.
+ */
+export interface AddressHintV1 {
+    id: string;
+    record: string;
 }
 export interface NeighborSnapshotV1 {
     v: 1;
@@ -33,6 +56,12 @@ export interface NeighborSnapshotV1 {
     confidence?: number;
     sig: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Signed address records for peers this snapshot names (`from`, the id lists, the sample).
+     * Optional and unversioned: a reader that predates it ignores the field. An array rather than
+     * an id-keyed object so it truncates like the other lists and has no `__proto__`-key hazard.
+     */
+    hints?: AddressHintV1[];
 }
 export interface RouteAndMaybeActV1 {
     v: 1;
@@ -121,7 +150,7 @@ export interface FretService {
     exportTable(): SerializedTable;
     importTable(table: SerializedTable): Promise<number>;
 }
-export type { SerializedPeerEntry, SerializedTable };
+export type { SerializedAddressRecord, SerializedPeerEntry, SerializedTable };
 export { FretServiceClass as FretServiceImpl };
 export { FretPeerDiscovery, type DiscoverySnapshotSource, type FretPeerDiscoveryInput, type FretPeerDiscoveryConfig } from './service/peer-discovery.js';
 export { Libp2pFretService, fretService } from './service/libp2p-fret-service.js';
@@ -129,7 +158,7 @@ export { hashKey, hashPeerId } from './ring/hash.js';
 export type { RingCoord } from './ring/hash.js';
 export { clockwiseDistance, minDistance, lexLess } from './ring/distance.js';
 export { DigitreeStore } from './store/digitree-store.js';
-export type { PeerEntry, PeerPatch, PeerState, MembershipState, RingCursor, RingWalkPage } from './store/digitree-store.js';
+export type { PeerEntry, PeerAddressRecord, PeerPatch, PeerState, MembershipState, RingCursor, RingWalkPage } from './store/digitree-store.js';
 export { estimateSizeAndConfidence } from './estimate/size-estimator.js';
 export type { SizeEstimate, SizeEstimateOptions } from './estimate/size-estimator.js';
 export { assembleCohort } from './service/cohort.js';

package/dist/src/rpc/neighbors.d.ts

@@ -35,7 +35,9 @@ export declare function fetchNeighbors(node: Libp2p, peerIdOrStr: string, protoc
  * that deliberately target *non-connected* peers — the "tell peers we just learned about"
  * paths, whose whole point is reaching someone we are not talking to yet — pass `dial: true`.
  * Those callers own the reachability check: dialing a peer libp2p holds no address for can
- * only fail (FRET's wire format carries peer ids, never multiaddrs).
+ * only fail. The dial itself is by bare peer id; the addresses it resolves to are whatever the
+ * peerStore holds, which since address hints includes the signed records FRET verified out of
+ * earlier snapshots (`FretService.ingestAddressHints`).
  */
 export declare function announceNeighbors(node: Libp2p, peerIdOrStr: string, snapshot: NeighborSnapshotV1, protocol?: string, opts?: {
     dial?: boolean;

package/dist/src/rpc/neighbors.js

@@ -106,7 +106,9 @@ export async function fetchNeighbors(node, peerIdOrStr, protocol = PROTOCOL_NEIG
  * that deliberately target *non-connected* peers — the "tell peers we just learned about"
  * paths, whose whole point is reaching someone we are not talking to yet — pass `dial: true`.
  * Those callers own the reachability check: dialing a peer libp2p holds no address for can
- * only fail (FRET's wire format carries peer ids, never multiaddrs).
+ * only fail. The dial itself is by bare peer id; the addresses it resolves to are whatever the
+ * peerStore holds, which since address hints includes the signed records FRET verified out of
+ * earlier snapshots (`FretService.ingestAddressHints`).
  */
 export async function announceNeighbors(node, peerIdOrStr, snapshot, protocol = PROTOCOL_NEIGHBORS_ANNOUNCE, opts = {}) {
     // Write-only: `ok` proves the body reached the transport, nothing more. No swallow — the

package/dist/src/rpc/request.js

@@ -4,7 +4,7 @@ import { abortReasonError, deadline } from '../utils/deadline.js';
 /**
  * Default declared-length cap for a reply when the caller passes none: 8 KiB. It tracks no other
  * cap in the system — every FRET sender passes its own explicitly (`sendPing` 1024, the neighbors
- * senders `MAX_NEIGHBORS_BYTES` (16 KiB), maybeAct 144 KiB), so this value is only ever reached by a
+ * senders `MAX_NEIGHBORS_BYTES` (64 KiB), maybeAct 144 KiB), so this value is only ever reached by a
  * direct consumer of `rpcRequest` who forgot one. 8 KiB is chosen as a conservative floor for a
  * reply whose shape we do not know: large enough that a small JSON reply is never truncated,
  * small enough that a forgotten cap still bounds the read.

package/dist/src/rpc/validate.d.ts

@@ -41,42 +41,61 @@ export declare const MAYBE_ACT_OVERHEAD_BYTES: number;
  * Per-message byte cap for both neighbors protocols (request/reply and announce). **One number
  * for both profiles**, because this is an *acceptance* limit: it bounds the largest message a
  * *peer* may send us, and Edge and Core peers talk to each other, so it has to cover the largest
- * snapshot any profile can legitimately emit. Sizing it per-profile — as it was, Core 16 KiB /
+ * snapshot any profile can legitimately emit. Sizing it per-profile — as it once was, Core 16 KiB /
  * Edge 8 KiB — made a legal Core snapshot unreadable by every Edge peer.
  *
  * Derived, not picked. The Core worst legal emission, measured by encoding the shape
  * `FretService.snapshot` produces (53-char peer ids, a 32-byte base64url coordinate per sample
  * entry, `metadata` grown until `JSON.stringify(metadata)` hits
- * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, and 256 bytes reserved for the still-empty
- * `sig` field):
+ * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, 256 bytes reserved for the still-empty `sig`
+ * field, and a `hints` array packed to {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
  *
  *   16 successors + 16 predecessors + 8 sample entries (the *merge* caps, which are wider than
  *   today's emission caps of 12/12/8)  ....................................  3,371 bytes
  *   + 8 KiB metadata (including the `,"metadata":` key)  ..................  8,204 bytes
- *   = 11,575 bytes
+ *   = 11,575 bytes of fixed fields
+ *   + 48 KiB of hints (the whole array, plus its `,"hints":[]` framing)  ....  49,163 bytes
+ *   = 60,738 bytes
  *
- * 16 KiB leaves ~4.8 KiB of headroom over that. The 256-byte `sig` reservation is already inside
- * the number, so landing message signatures does not disturb it.
+ * 64 KiB leaves ~4.7 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
  *
  * The invariant this constant carries, pinned by `test/rpc.codec-properties.spec.ts`: **the
- * largest legal emission of *any* profile encodes under this cap.** Re-splitting it per profile
- * breaks that and fails there.
+ * largest legal emission of *any* profile — fixed fields, metadata allowance and hint budget
+ * together — encodes under this cap.** Re-splitting it per profile breaks that and fails there.
  */
 export declare const MAX_NEIGHBORS_BYTES: number;
 /** Cap on the encoded size of the caller-supplied `metadata` a Core node attaches to its
  *  outgoing snapshot. This is an **emission budget** — the Core profile's own choice of how much
  *  application metadata it will carry — not an acceptance limit; acceptance is
- *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the two budgets must keep
- *  is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core fixed
- *  fields cost 3,371 bytes, so this allowance plus them lands at 11,575, comfortably under.
- *  Over-cap metadata is omitted from the snapshot rather than truncated — see
- *  `FretService.snapshot`. */
+ *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the emission budgets must
+ *  keep is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core
+ *  fixed fields cost 3,371 bytes, so this allowance plus them lands at 11,575, and the hint budget
+ *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,738 — under. Over-cap metadata is
+ *  omitted from the snapshot rather than truncated — see `FretService.snapshot`. */
 export declare const MAX_SNAPSHOT_METADATA_BYTES_CORE: number;
 /** Same, Edge profile: an emission budget, half of Core's because an edge node carries less.
- *  Its worst legal emission is 6,301 bytes, also under {@link MAX_NEIGHBORS_BYTES} — which is the
- *  only bound either budget has to satisfy. Deliberately *not* sized against a per-profile
- *  acceptance cap; there is no such thing. */
+ *  Its worst legal emission is 6,301 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
+ *  of hints, also under {@link MAX_NEIGHBORS_BYTES} — which is the only bound any budget has to
+ *  satisfy. Deliberately *not* sized against a per-profile acceptance cap; there is no such thing. */
 export declare const MAX_SNAPSHOT_METADATA_BYTES_EDGE: number;
+/**
+ * Cap on one base64url-encoded address record in a snapshot's `hints`, in characters (one byte
+ * each — base64url is ASCII). An Ed25519 envelope over a handful of addresses encodes to roughly
+ * 300–700 characters; 2048 leaves room for an RSA key and the eight addresses a self record may
+ * carry (`MAX_SELF_RECORD_ADDRS` in `service/address-records.ts`). Applied on both sides: the parser drops a longer record, and
+ * `SelfAddressRecord` omits its own record rather than emit one the receiver would drop.
+ */
+export declare const MAX_ADDRESS_RECORD_CHARS = 2048;
+/**
+ * Emission budget for the whole `hints` array of a Core snapshot — the sum over hints of
+ * `JSON.stringify(hint).length + 1` (the `+ 1` is the separating comma), which is what
+ * `FretService.snapshot` counts. Profile-split like the metadata allowance, and for the same
+ * reason: it is this node's own choice of how much it forwards, not a limit on what it accepts.
+ * Worst case: 11,575 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
+ */
+export declare const MAX_SNAPSHOT_HINT_BYTES_CORE: number;
+/** Same, Edge profile: an edge node forwards less. 6,301 + 16,384 + framing is far under the cap. */
+export declare const MAX_SNAPSHOT_HINT_BYTES_EDGE: number;
 /**
  * Structural validity of an inbound `RouteAndMaybeAct` — everything downstream code touches
  * without checking, and nothing more. The caller runs it immediately after taking the rate-limit

package/dist/src/rpc/validate.js

@@ -71,42 +71,61 @@ export const MAYBE_ACT_OVERHEAD_BYTES = 16 * 1024;
  * Per-message byte cap for both neighbors protocols (request/reply and announce). **One number
  * for both profiles**, because this is an *acceptance* limit: it bounds the largest message a
  * *peer* may send us, and Edge and Core peers talk to each other, so it has to cover the largest
- * snapshot any profile can legitimately emit. Sizing it per-profile — as it was, Core 16 KiB /
+ * snapshot any profile can legitimately emit. Sizing it per-profile — as it once was, Core 16 KiB /
  * Edge 8 KiB — made a legal Core snapshot unreadable by every Edge peer.
  *
  * Derived, not picked. The Core worst legal emission, measured by encoding the shape
  * `FretService.snapshot` produces (53-char peer ids, a 32-byte base64url coordinate per sample
  * entry, `metadata` grown until `JSON.stringify(metadata)` hits
- * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, and 256 bytes reserved for the still-empty
- * `sig` field):
+ * {@link MAX_SNAPSHOT_METADATA_BYTES_CORE} exactly, 256 bytes reserved for the still-empty `sig`
+ * field, and a `hints` array packed to {@link MAX_SNAPSHOT_HINT_BYTES_CORE}):
  *
  *   16 successors + 16 predecessors + 8 sample entries (the *merge* caps, which are wider than
  *   today's emission caps of 12/12/8)  ....................................  3,371 bytes
  *   + 8 KiB metadata (including the `,"metadata":` key)  ..................  8,204 bytes
- *   = 11,575 bytes
+ *   = 11,575 bytes of fixed fields
+ *   + 48 KiB of hints (the whole array, plus its `,"hints":[]` framing)  ....  49,163 bytes
+ *   = 60,738 bytes
  *
- * 16 KiB leaves ~4.8 KiB of headroom over that. The 256-byte `sig` reservation is already inside
- * the number, so landing message signatures does not disturb it.
+ * 64 KiB leaves ~4.7 KiB of headroom over that. Sereus used the same 64 KiB for the same payload.
  *
  * The invariant this constant carries, pinned by `test/rpc.codec-properties.spec.ts`: **the
- * largest legal emission of *any* profile encodes under this cap.** Re-splitting it per profile
- * breaks that and fails there.
+ * largest legal emission of *any* profile — fixed fields, metadata allowance and hint budget
+ * together — encodes under this cap.** Re-splitting it per profile breaks that and fails there.
  */
-export const MAX_NEIGHBORS_BYTES = 16 * 1024;
+export const MAX_NEIGHBORS_BYTES = 64 * 1024;
 /** Cap on the encoded size of the caller-supplied `metadata` a Core node attaches to its
  *  outgoing snapshot. This is an **emission budget** — the Core profile's own choice of how much
  *  application metadata it will carry — not an acceptance limit; acceptance is
- *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the two budgets must keep
- *  is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core fixed
- *  fields cost 3,371 bytes, so this allowance plus them lands at 11,575, comfortably under.
- *  Over-cap metadata is omitted from the snapshot rather than truncated — see
- *  `FretService.snapshot`. */
+ *  {@link MAX_NEIGHBORS_BYTES}, one network-wide number. The invariant the emission budgets must
+ *  keep is `largest emission of any profile <= MAX_NEIGHBORS_BYTES`: at the merge caps the Core
+ *  fixed fields cost 3,371 bytes, so this allowance plus them lands at 11,575, and the hint budget
+ *  ({@link MAX_SNAPSHOT_HINT_BYTES_CORE}) on top of that at 60,738 — under. Over-cap metadata is
+ *  omitted from the snapshot rather than truncated — see `FretService.snapshot`. */
 export const MAX_SNAPSHOT_METADATA_BYTES_CORE = 8 * 1024;
 /** Same, Edge profile: an emission budget, half of Core's because an edge node carries less.
- *  Its worst legal emission is 6,301 bytes, also under {@link MAX_NEIGHBORS_BYTES} — which is the
- *  only bound either budget has to satisfy. Deliberately *not* sized against a per-profile
- *  acceptance cap; there is no such thing. */
+ *  Its worst legal emission is 6,301 bytes of fixed fields plus {@link MAX_SNAPSHOT_HINT_BYTES_EDGE}
+ *  of hints, also under {@link MAX_NEIGHBORS_BYTES} — which is the only bound any budget has to
+ *  satisfy. Deliberately *not* sized against a per-profile acceptance cap; there is no such thing. */
 export const MAX_SNAPSHOT_METADATA_BYTES_EDGE = 4 * 1024;
+/**
+ * Cap on one base64url-encoded address record in a snapshot's `hints`, in characters (one byte
+ * each — base64url is ASCII). An Ed25519 envelope over a handful of addresses encodes to roughly
+ * 300–700 characters; 2048 leaves room for an RSA key and the eight addresses a self record may
+ * carry (`MAX_SELF_RECORD_ADDRS` in `service/address-records.ts`). Applied on both sides: the parser drops a longer record, and
+ * `SelfAddressRecord` omits its own record rather than emit one the receiver would drop.
+ */
+export const MAX_ADDRESS_RECORD_CHARS = 2048;
+/**
+ * Emission budget for the whole `hints` array of a Core snapshot — the sum over hints of
+ * `JSON.stringify(hint).length + 1` (the `+ 1` is the separating comma), which is what
+ * `FretService.snapshot` counts. Profile-split like the metadata allowance, and for the same
+ * reason: it is this node's own choice of how much it forwards, not a limit on what it accepts.
+ * Worst case: 11,575 (fixed fields) + 49,152 + the field's own framing < {@link MAX_NEIGHBORS_BYTES}.
+ */
+export const MAX_SNAPSHOT_HINT_BYTES_CORE = 48 * 1024;
+/** Same, Edge profile: an edge node forwards less. 6,301 + 16,384 + framing is far under the cap. */
+export const MAX_SNAPSHOT_HINT_BYTES_EDGE = 16 * 1024;
 /**
  * Structural validity of an inbound `RouteAndMaybeAct` — everything downstream code touches
  * without checking, and nothing more. The caller runs it immediately after taking the rate-limit
@@ -247,10 +266,58 @@ export function makeSnapshotParser(caps) {
             delete out.metadata;
         else
             out.metadata = msg.metadata;
+        // Hints are tied to the ids this message names *after* truncation, so the merge caps above
+        // bound the receiver's verify work as well as its hash-and-upsert work: a message cannot
+        // carry more records than it carries ids, whatever its `hints` array holds.
+        const named = new Set([msg.from, ...out.successors, ...out.predecessors, ...out.sample.map((s) => s.id)]);
+        const hints = parseHints(msg.hints, named, msg.from);
+        if (hints.length === 0)
+            delete out.hints;
+        else
+            out.hints = hints;
         // `sig` is deliberately unchecked: message signing is unimplemented, so nothing reads it.
         return out;
     };
 }
+/**
+ * The address hints, vetted per entry against the snapshot's named set — see
+ * {@link makeSnapshotParser}. An entry survives when it is an object whose `id` is a named id not
+ * already hinted and whose `record` is a base64url string of at most {@link MAX_ADDRESS_RECORD_CHARS}
+ * characters. Structural only: the decode proves the string is base64url, nothing about what it
+ * encodes — envelope structure and the signature are checked at ingestion, where the store entry
+ * and the peerStore are. Same skip-and-log-per-entry rule as the sample; never throws.
+ *
+ * The count is bounded by the named set's size through the `seen` set, and the loop stops once
+ * every named id has a hint, so a long junk array costs a per-entry type check and nothing more.
+ */
+function parseHints(value, named, from) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (seen.size >= named.size)
+            break;
+        if (!isPlainObject(entry))
+            continue;
+        if (typeof entry.id !== 'string' || !named.has(entry.id) || seen.has(entry.id))
+            continue;
+        if (typeof entry.record !== 'string' || entry.record.length > MAX_ADDRESS_RECORD_CHARS)
+            continue;
+        try {
+            u8FromString(entry.record, 'base64url');
+        }
+        catch (err) {
+            // NOTE: one line per dropped entry, bounded by the named set — the same terms as the
+            // sample's per-entry line above.
+            log.error('snapshot from %s: dropping address hint for %s with undecodable record - %e', from, entry.id, err);
+            continue;
+        }
+        seen.add(entry.id);
+        out.push({ id: entry.id, record: entry.record });
+    }
+    return out;
+}
 /**
  * The sparsity sample, truncated then vetted per entry. A `coord` is checked by *decoding* it
  * through {@link base64urlToCoord}, which already rejects anything that is not exactly 32 bytes —

package/dist/src/service/address-records.d.ts

@@ -0,0 +1,136 @@
+import type { Multiaddr } from '@multiformats/multiaddr';
+import type { Libp2p } from 'libp2p';
+import type { PrivateKey } from '@libp2p/interface';
+import { type SerializedPeerEntry } from '../store/digitree-store.js';
+/**
+ * Signed address records — what FRET carries in a snapshot's `hints` so a peer known only
+ * through gossip can still be dialed.
+ *
+ * The record is libp2p's own: a `RecordEnvelope` (signed, domain-separated) over a `PeerRecord`
+ * (`peerId`, `multiaddrs`, `seqNumber`). Verification is `peerStore.consumePeerRecord`, which
+ * checks the signature and the signer, refuses a sequence number not newer than the one it holds,
+ * and replaces the peer's addresses with the record's — the same code path identify feeds. What
+ * this module adds is the part libp2p leaves to the caller: a cheap structural peek so the common
+ * path (a neighbour re-sending records we already hold) never reaches the signature check, and a
+ * sealer for *this* node's record, since libp2p keeps no self record in the peerStore (identify
+ * seals one per request and discards it).
+ */
+/** How many of this node's own addresses a self record carries — bounds the record's size. */
+export declare const MAX_SELF_RECORD_ADDRS = 8;
+/**
+ * How long a record for a peer we are **not** connected to keeps being forwarded after we last
+ * accepted it. Measured on our own clock (`PeerEntry.addressRecord.confirmedAt`) — never on a
+ * timestamp a remote supplied — so clock skew between peers cannot extend it. A stale record
+ * cannot be refreshed by re-hearing it either (an equal sequence number is refused), so a record
+ * keeps circulating only while some node is connected to its subject or the subject re-seals.
+ */
+export declare const ADDRESS_HINT_FORWARD_MAX_AGE_MS: number;
+/**
+ * How long a peer's record survives in an exported routing table, measured from when we last
+ * confirmed it (a peer connected at export time counts as confirmed at that moment). Older
+ * records are left out of the export and dropped on import.
+ *
+ * Far longer than the forwarding window, because the two answer different questions: forwarding
+ * vouches for a record to *other* peers, while a persisted record only seeds *our own* first
+ * dials after a restart — the case where nothing else knows the address at all (gotchoices/sereus#18).
+ * The cost of keeping one too long is a dead address, and a failed relayed dial costs seconds
+ * (Sereus measured up to 14 s at a 3 s link round trip), so every stale record slows a restart;
+ * 14 days still covers a node switched off for a holiday. No separate count cap: at most one
+ * record rides on each routing-table entry, so the table's capacity already bounds them.
+ */
+export declare const ADDRESS_RECORD_PERSIST_MAX_AGE_MS: number;
+/**
+ * The export half of the persist-age rule, for one entry the store serialized: a peer connected
+ * at export time is confirmed *now* (a live connection is the confirmation), and a record last
+ * confirmed more than {@link ADDRESS_RECORD_PERSIST_MAX_AGE_MS} ago is left out.
+ */
+export declare function freshenExportedAddressRecord(entry: SerializedPeerEntry, now: number, isConnected: (id: string) => boolean): SerializedPeerEntry;
+/**
+ * The import-time check of one persisted entry's address record — structural, no signature
+ * check, run over the whole table before anything is written. The signature is verified once,
+ * later, inside `consumePeerRecord`.
+ *
+ * - **Corrupt** → throws, so the caller refuses the whole table: an envelope that is not base64url
+ *   or does not decode as a signed peer record, a `confirmedAt` that is not a finite number, or a
+ *   signer or payload peer id that is not the entry's own id. Our own export cannot produce any of
+ *   these, so the file was damaged.
+ * - **Stale** (last confirmed more than {@link ADDRESS_RECORD_PERSIST_MAX_AGE_MS} ago) → the record
+ *   is dropped and the entry kept. Age is not damage.
+ * - A `confirmedAt` later than `now` is clamped to `now`: our clock went backwards since the
+ *   export, or the file was edited — and an edited file is the table-signing work's concern
+ *   (`tickets/backlog/23-debt-routing-table-export-signing.md`), not something an age check can see.
+ */
+export declare function vetPersistedAddressRecord(entry: SerializedPeerEntry, now: number): SerializedPeerEntry;
+/** The base64url string a record travels as on the wire. */
+export declare function encodeAddressRecord(envelope: Uint8Array): string;
+/** Inverse of {@link encodeAddressRecord}. Throws on a string that is not base64url. */
+export declare function decodeAddressRecord(record: string): Uint8Array;
+/** What {@link peekPeerRecord} reads off an envelope without verifying it. */
+export interface PeekedPeerRecord {
+    /** Peer id derived from the envelope's public key — who signed it. */
+    signer: string;
+    /** Peer id the payload names — whose addresses it claims to be. */
+    peerId: string;
+    seq: bigint;
+}
+/**
+ * Decode an envelope and its peer record **structurally** — no signature check, no domain check,
+ * never throws. `undefined` means the bytes do not parse as an envelope over a peer record.
+ *
+ * Two uses. The identity pre-check: a receiver must refuse a record whose `signer` or `peerId`
+ * is not the id it was labelled with *before* it reaches `consumePeerRecord`, because that call
+ * checks only the signer against `expectedPeer` and then patches the *payload's* peer id blindly —
+ * so a peer could sign a record that rewrites another peer's addresses. And the sequence pre-check:
+ * comparing `seq` against the record already held is what keeps a re-sent record free of crypto.
+ */
+export declare function peekPeerRecord(bytes: Uint8Array): PeekedPeerRecord | undefined;
+/**
+ * This node's addresses as its self record should state them.
+ *
+ * Projected the way identify does — `decapsulateCode(CODE_P2P)` strips the trailing `/p2p/<self>`
+ * the address manager appends, since a `PeerRecord` names its peer once, in `peerId` — deduped,
+ * and then two rules of our own:
+ *
+ * - A circuit address with **no relay hop** (the bare `/p2p-circuit` listen placeholder, reported
+ *   from start-up until a reservation lands) is dropped: nobody can dial it.
+ * - **Reserved** circuit addresses (`…/p2p/<relay>/p2p-circuit`) come first. For a NAT-only peer
+ *   they are the only addresses a third party can use, so they must survive the cap.
+ *
+ * Nothing else is filtered — no public/private test. The address manager already applied the
+ * host's announce / noAnnounce configuration, and a private address is harmless in a record
+ * (a dial to it fails fast) where a missing circuit address is the whole bug this exists to fix.
+ * Capped at {@link MAX_SELF_RECORD_ADDRS}.
+ */
+export declare function selfRecordAddrs(node: Libp2p): Multiaddr[];
+/**
+ * This node's own signed address record, sealed lazily and cached until its address list changes.
+ *
+ * Lazy rather than event-driven on purpose: a snapshot build asks {@link current}, which compares
+ * the projected address list against the one last sealed and re-seals only on a difference. That
+ * catches a reservation landing after `start()` (the next snapshot carries a fresher record with a
+ * higher sequence number, which receivers accept over the earlier one) without a listener that
+ * `stop()` would have to detach.
+ */
+export declare class SelfAddressRecord {
+    /** The address list the cached record describes, as one string. `''` = nothing sealed yet
+     *  — which is also the key of an empty address list, and both mean "no record". */
+    private sealedFor;
+    private cached;
+    private lastSeq;
+    /**
+     * Bumped at the start of every seal. A seal that finds it changed after its signature
+     * returns was overtaken by a seal for a *newer* address list, so it must not commit: two
+     * snapshot builds straddling a reservation landing would otherwise let the earlier (lower
+     * sequence number) record land in the cache last and ride the next snapshot.
+     */
+    private generation;
+    /** A seal in progress, so two concurrent snapshot builds share one signature. */
+    private inflight;
+    /**
+     * The base64url record for `node`'s current addresses, or `undefined` when there is nothing
+     * to advertise: no dialable address yet (a relay-only node before its reservation lands), or a
+     * record that would not fit {@link MAX_ADDRESS_RECORD_CHARS}.
+     */
+    current(node: Libp2p, privateKey: PrivateKey): Promise<string | undefined>;
+    private seal;
+}