@dcasegr/skein 0.1.2 → 0.2.8

package/dist/host/instances.d.ts

@@ -83,6 +83,25 @@ export declare class HostDb {
     setStatus(handle: string, status: Status): boolean;
     /** Remove the row (not its store or wallet); false if there was none. */
     remove(handle: string): boolean;
+    /** A liveness beat kept (#138): the sender's row on `handle`'s `topic` replaced. */
+    putBeat(handle: string, topic: string, b: {
+        sender: string;
+        at: number;
+        from: string;
+        frame: Uint8Array;
+    }): void;
+    /** The liveness beats kept for `handle` (on `topic` only, when named). */
+    beatsOf(handle: string, topic?: string): Array<{
+        topic: string;
+        sender: string;
+        at: number;
+        from: string;
+        frame: Uint8Array;
+    }>;
+    /** Forget `handle`'s liveness beats: all, a topic's, or one sender's on a topic. */
+    dropBeats(handle: string, topic?: string, sender?: string): void;
+    /** Forget the liveness beats dated before `before` (ms). → how many rows went. */
+    pruneBeats(before: number): number;
     /** The enabled mailbox instance for identity `owner` (hex). */
     /** A beat kept from `peer` on `handle`'s overlay `topic` (sync): upserted with its addresses (kept when none are known now). */
     seenPeer(handle: string, topic: string, peer: string, addrs: string[], now: number): void;

package/dist/host/instances.js

@@ -20,7 +20,8 @@
 // the host last read it (asleep since when: the grace), the periods it ticked
 // (each period's log record, which its tick commits to), and the payments its
 // wallet made (the `payment` events). And overlay sync's: the peers each
-// instance's overlay topics heard beats from (`topic_peers`).
+// instance's overlay topics heard beats from (`topic_peers`). And the liveness
+// tool's (#138): the beats it kept, reloaded at a start (`live_beats`).
 import { DatabaseSync } from "node:sqlite";
 const DDL = `
 CREATE TABLE IF NOT EXISTS instances (
@@ -134,6 +135,17 @@ CREATE TABLE IF NOT EXISTS topic_peers (
   addrs             TEXT NOT NULL,                    -- JSON array of multiaddrs (may be empty)
   last_seen         INTEGER NOT NULL,                 -- ms: the last beat kept from it
   PRIMARY KEY (handle, topic, peer_id)
+) WITHOUT ROWID;
+-- The liveness tool's beats (#138, liveness.ts): per instance and liveness topic, the latest beat kept from each
+-- sender, the frame as received; a start feeds them through the tool again (signature and window re-checked).
+CREATE TABLE IF NOT EXISTS live_beats (
+  handle            TEXT NOT NULL,
+  topic             TEXT NOT NULL,                    -- the liveness topic (e.g. <topic>-live)
+  sender            TEXT NOT NULL,                    -- the beat's identity key (hex)
+  at                INTEGER NOT NULL,                 -- ms: the beat's own time
+  peer_id           TEXT NOT NULL,                    -- the libp2p peer that published it
+  frame             BLOB NOT NULL,                    -- the beacon frame (p2p.ts beaconFrame)
+  PRIMARY KEY (handle, topic, sender)
 ) WITHOUT ROWID;`;
 /**
  * A handle: one hostname label (lower-case letters, digits and "-", at most
@@ -249,6 +261,31 @@ export class HostDb {
     remove(handle) {
         return Number(this.db.prepare("DELETE FROM instances WHERE handle = ?").run(handle).changes) > 0;
     }
+    /** A liveness beat kept (#138): the sender's row on `handle`'s `topic` replaced. */
+    putBeat(handle, topic, b) {
+        this.db.prepare("INSERT INTO live_beats (handle, topic, sender, at, peer_id, frame) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT (handle, topic, sender) DO UPDATE SET at = excluded.at, peer_id = excluded.peer_id, frame = excluded.frame")
+            .run(handle, topic, b.sender, b.at, b.from, b.frame);
+    }
+    /** The liveness beats kept for `handle` (on `topic` only, when named). */
+    beatsOf(handle, topic) {
+        const rows = topic === undefined
+            ? this.db.prepare("SELECT topic, sender, at, peer_id, frame FROM live_beats WHERE handle = ? ORDER BY topic, sender").all(handle)
+            : this.db.prepare("SELECT topic, sender, at, peer_id, frame FROM live_beats WHERE handle = ? AND topic = ? ORDER BY sender").all(handle, topic);
+        return rows.map((r) => ({ topic: String(r.topic), sender: String(r.sender), at: Number(r.at), from: String(r.peer_id), frame: new Uint8Array(r.frame) }));
+    }
+    /** Forget `handle`'s liveness beats: all, a topic's, or one sender's on a topic. */
+    dropBeats(handle, topic, sender) {
+        if (topic === undefined)
+            this.db.prepare("DELETE FROM live_beats WHERE handle = ?").run(handle);
+        else if (sender === undefined)
+            this.db.prepare("DELETE FROM live_beats WHERE handle = ? AND topic = ?").run(handle, topic);
+        else
+            this.db.prepare("DELETE FROM live_beats WHERE handle = ? AND topic = ? AND sender = ?").run(handle, topic, sender);
+    }
+    /** Forget the liveness beats dated before `before` (ms). → how many rows went. */
+    pruneBeats(before) {
+        return Number(this.db.prepare("DELETE FROM live_beats WHERE at < ?").run(before).changes);
+    }
     /** The enabled mailbox instance for identity `owner` (hex). */
     /** A beat kept from `peer` on `handle`'s overlay `topic` (sync): upserted with its addresses (kept when none are known now). */
     seenPeer(handle, topic, peer, addrs, now) {

package/dist/host/liveness.d.ts

@@ -31,6 +31,20 @@ export interface LiveBeat {
     body: Uint8Array;
     from: string;
 }
+/** A beat as the store keeps it: the frame as received (re-verified on reload), its time, sender (hex), and the peer that published it. */
+export interface StoredBeat {
+    topic: string;
+    sender: string;
+    at: number;
+    from: string;
+    frame: Uint8Array;
+}
+/** Where the beats kept are persisted (host.db `live_beats`, instances.ts HostDb). */
+export interface BeatStore {
+    putBeat(handle: string, topic: string, beat: Omit<StoredBeat, "topic">): void;
+    beatsOf(handle: string, topic?: string): StoredBeat[];
+    dropBeats(handle: string, topic?: string, sender?: string): void;
+}
 /** A message's verdict for GossipSub: a verified beat is accepted (forwarded), a bad one rejected, a stale one ignored. */
 export type LiveVerdict = "accept" | "reject" | "ignore";
 /** The tool's state: per instance, the apps' liveness and the beats kept per topic (in memory). */
@@ -41,7 +55,11 @@ export declare class Liveness {
     private readonly now;
     /** Told each beat newly kept (shruggr/skein#150: the overlay's sync reads a peer's tip anchor from it). */
     kept?: (handle: string, topic: string, beat: LiveBeat) => void;
-    constructor(now?: () => number);
+    /** The store the kept beats are persisted in (absent: memory only). */
+    private readonly store?;
+    constructor(now?: () => number, store?: BeatStore);
+    /** A store write: its failure (a closed host.db at shutdown) changes nothing in memory nor any verdict. */
+    private persist;
     /** `handle`'s apps keep this liveness now: the beats of topics none keeps any more are dropped. */
     set(handle: string, lives: Live[]): void;
     /** The topics `handle`'s apps keep liveness for (each once). */
@@ -60,6 +78,8 @@ export declare class Liveness {
     read(handle: string, app: string, topic: string): LiveBeat[] | undefined;
     /** Every beat live on `topic` at `handle` (newer than the longest window on it), whichever app keeps it. */
     live(handle: string, topic: string): LiveBeat[];
-    /** Forget `handle`: its liveness and its beats. */
+    /** Forget `handle`: its liveness and its beats (the stored ones too). */
     drop(handle: string): void;
+    /** Forget `handle` in memory only (the host stopping): the stored beats stay for the next start. */
+    forget(handle: string): void;
 }

package/dist/host/liveness.js

@@ -19,8 +19,12 @@
 //     (identity key), with the peer that published it (`from`); the node's
 //     OWN beats on the topic are written into the same set (gossip does not
 //     echo them: P2PHost.beacons);
-//   - in memory only: empty after a restart until the next beats; dropped at
-//     the app's unliveness or uninstall.
+//   - in memory, and in the host's store when it gives one (host.db
+//     `live_beats`: the frame as received, its time, sender and peer): when
+//     the apps' liveness is set at a start, the frames kept for its topics go
+//     through `observe` again (signature re-checked, window re-applied; the
+//     ones that no longer count deleted); dropped at the app's unliveness or
+//     uninstall.
 //
 // The set is served to the app's page by the host itself, no program in
 // between (Router: GET /<app>/.live/<topic> on the instance's origin).
@@ -73,7 +77,18 @@ export class Liveness {
     now;
     /** Told each beat newly kept (shruggr/skein#150: the overlay's sync reads a peer's tip anchor from it). */
     kept;
-    constructor(now = Date.now) { this.now = now; }
+    /** The store the kept beats are persisted in (absent: memory only). */
+    store;
+    constructor(now = Date.now, store) { this.now = now; this.store = store; }
+    /** A store write: its failure (a closed host.db at shutdown) changes nothing in memory nor any verdict. */
+    persist(f) {
+        if (!this.store)
+            return;
+        try {
+            f(this.store);
+        }
+        catch { /* memory stays right; the row is caught up at the next beat */ }
+    }
     /** `handle`'s apps keep this liveness now: the beats of topics none keeps any more are dropped. */
     set(handle, lives) {
         if (!lives.length) {
@@ -86,6 +101,20 @@ export class Liveness {
             for (const t of kept.keys())
                 if (!lives.some((l) => l.topic === t))
                     kept.delete(t);
+        if (!this.store)
+            return;
+        let rows = [];
+        this.persist((s) => { rows = s.beatsOf(handle); });
+        for (const t of new Set(rows.map((r) => r.topic)))
+            if (!lives.some((l) => l.topic === t))
+                this.persist((s) => s.dropBeats(handle, t));
+        // The beats kept before (a restart): each frame judged again by `observe`; one that no longer counts is deleted.
+        for (const r of rows) {
+            if (!lives.some((l) => l.topic === r.topic))
+                continue;
+            if (this.observe(handle, r.topic, r.frame, r.from) !== "accept")
+                this.persist((s) => s.dropBeats(handle, r.topic, r.sender));
+        }
     }
     /** The topics `handle`'s apps keep liveness for (each once). */
     topics(handle) { return [...new Set((this.lives.get(handle) ?? []).map((l) => l.topic))]; }
@@ -123,12 +152,15 @@ export class Liveness {
         if (!was || b.at > was.at) {
             const beat = { sender, at: b.at, body: b.body, from };
             bySender.set(sender, beat);
+            this.persist((s) => s.putBeat(handle, topic, { sender, at: b.at, from, frame }));
             this.kept?.(handle, topic, beat);
         }
         // The stale ones go as the set is touched.
         for (const [k, x] of bySender)
-            if (now - x.at >= window)
+            if (now - x.at >= window) {
                 bySender.delete(k);
+                this.persist((s) => s.dropBeats(handle, topic, k));
+            }
         return "accept";
     }
     /** The beats live for `app`'s liveness on `topic` (newer than its window), newest first; undefined: the app keeps no liveness for the topic. */
@@ -147,8 +179,13 @@ export class Liveness {
         const now = this.now();
         return [...(this.beats.get(handle)?.get(topic)?.values() ?? [])].filter((b) => now - b.at < window);
     }
-    /** Forget `handle`: its liveness and its beats. */
+    /** Forget `handle`: its liveness and its beats (the stored ones too). */
     drop(handle) {
+        this.forget(handle);
+        this.persist((s) => s.dropBeats(handle));
+    }
+    /** Forget `handle` in memory only (the host stopping): the stored beats stay for the next start. */
+    forget(handle) {
         this.lives.delete(handle);
         this.beats.delete(handle);
     }

package/dist/host/p2p.d.ts

@@ -1,9 +1,12 @@
 import type { Libp2p, PeerId } from "@libp2p/interface";
-import type { PrivateKey } from "@bsv/sdk";
+import type { ComponentLogger } from "@libp2p/interface";
+import { type KadDHT } from "@libp2p/kad-dht";
+import { type Multiaddr } from "@multiformats/multiaddr";
+import { PrivateKey } from "@bsv/sdk";
 import type { Store } from "../runtime/store.ts";
 import { CID } from "multiformats/cid";
-import { Liveness, type Live, type LiveBeat } from "./liveness.ts";
-export type DhtMode = "off" | "client" | "server";
+import { Liveness, type BeatStore, type Live, type LiveBeat } from "./liveness.ts";
+export type DhtMode = "off" | "auto" | "client" | "server";
 /** The host-wide settings: every node gets these. */
 export interface P2PHostConfig {
     listen: string[];
@@ -11,12 +14,20 @@ export interface P2PHostConfig {
     dht: DhtMode;
     relays: string[];
     mdns: boolean;
+    /** UPnP/NAT-PMP port mapping (@libp2p/upnp-nat): SKEIN_LIBP2P_UPNP, on by default in hostP2PConfig; absent: off. */
+    upnp?: boolean;
     /** PEM certificate and key for the WebSocket listener (WSS). */
     tls?: {
         cert: string;
         key: string;
     };
+    /** The network (SKEIN_NETWORK's names): the skein DHT's protocol names it (skeinDhtProtocol); default main. */
+    network?: string;
 }
+/** SKEIN_NETWORK's names as the networks' own (the Teranode block topic's, the skein DHT's). */
+export declare const NETWORK_NAMES: Record<string, string>;
+/** The skein DHT's protocol for a network: the overlay's provider records, never merged with another network's. */
+export declare const skeinDhtProtocol: (network?: string) => string;
 /** One instance's libp2p config (the genesis's `libp2p`): what the router subscribes and serves for it. */
 export interface P2PInstanceConfig {
     topics: string[];
@@ -24,8 +35,18 @@ export interface P2PInstanceConfig {
     /** This instance's listen addresses (over the host's): a fixed port belongs to one node. */
     listen?: string[];
 }
-/** The default listeners: loopback TCP and WebSocket, ports chosen by the OS (plain WS on loopback: dev only). */
+/**
+ * The default TCP port (2026-11-01): one fixed port on every install, so a user who opens one port knows
+ * which. 7534 is "SKEI" on a phone keypad; unassigned in the IANA registry (not IPFS's 4001, not
+ * Teranode's 9905/9915).
+ */
+export declare const DEFAULT_PORT = 7534;
+/** The default listeners: TCP on every interface, IPv4 and IPv6, on DEFAULT_PORT; WebSocket on loopback, its port the OS's (plain WS off loopback: dev only). */
 export declare const DEFAULT_LISTEN: string[];
+/** Loopback only, ports chosen by the OS: the router's listeners when it is given no host settings (tests, an embedded router). */
+export declare const LOOPBACK_LISTEN: string[];
+/** `listen` with DEFAULT_PORT made an OS-chosen port (the fallback when the default port is taken). */
+export declare const anyPort: (listen: string[]) => string[];
 /** What the front door is called with for an inbound message or stream frame (#51). */
 export interface InboundCall {
     transport: "libp2p";
@@ -85,7 +106,16 @@ export interface P2POptions {
     hostProtocols?: Record<string, (handle: string, remote: PeerId, frame: Uint8Array) => Promise<Uint8Array>>;
     /** Each beat the liveness tool newly keeps from another peer (shruggr/skein#150). */
     beat?(handle: string, topic: string, beat: LiveBeat): void;
+    /** Where the liveness tool persists the beats it keeps (host.db `live_beats`), reloaded when an instance's liveness is set. Absent: memory only. */
+    beats?: BeatStore;
+    /**
+     * The host node's peer key (#156): on a one-key host the key every instance's node uses (keyOf's
+     * answer for every handle), so the instances join the host node. Absent: a fresh key (a test's).
+     */
+    hostKey?: PrivateKey;
 }
+/** A host topic's judge (hostTopic): each message's data and publisher → GossipSub's verdict. */
+export type HostTopicHandler = (data: Uint8Array, from: PeerId) => "accept" | "reject" | "ignore";
 /** A bsv secp256k1 key as a libp2p private key. */
 export declare function libp2pKey(k: PrivateKey): import("@libp2p/interface").PrivateKey;
 /** The peer ID of a key: the identity multihash of its protobuf (secp256k1, compressed). */
@@ -94,7 +124,20 @@ export declare function peerIdOf(k: PrivateKey): PeerId;
 export declare function keyOfPeerId(id: string | Uint8Array): string | undefined;
 /** A topic name's rendezvous CID: v1 raw over sha2-256 of the name (go-libp2p's nsToCid). */
 export declare function topicCid(topic: string): Promise<CID>;
-/** The host-wide settings: the environment's SKEIN_LIBP2P_*, else $SKEIN_HOME/host.env's. */
+/**
+ * The network's overlay bootstrap peers (SKEIN_NETWORK's names): the hosted Open Exchange node per network,
+ * dialled beside SKEIN_LIBP2P_BOOTSTRAP's (unioned, as TERANODE_BOOTSTRAP is with SKEIN_TERANODE_BOOTSTRAP).
+ * A node whose own peer id is one of them skips it (discover()). Mainnet and regtest have none yet.
+ */
+export declare const OVERLAY_BOOTSTRAP: Record<string, string[]>;
+/** SKEIN_LIBP2P_BOOTSTRAP over the network's defaults: unset, the network's; a list, unioned with them; `off`, none at all. */
+export declare function overlayBootstrap(network: string, named: string | undefined): string[];
+/**
+ * The bootstrap addresses a node dials now: not its own peer id (the hosted node is its network's default
+ * bootstrap), not a peer already connected; an address that does not parse is reported and skipped.
+ */
+export declare function bootstrapDials(bootstrap: string[], self: string, connected: Set<string>, bad?: (a: string) => void): string[];
+/** The host-wide settings: the environment's SKEIN_LIBP2P_* (and SKEIN_NETWORK), else $SKEIN_HOME/host.env's. */
 export declare function hostP2PConfig(vars: Record<string, string | undefined>, home?: string): P2PHostConfig;
 /** The libp2p config a genesis carries (`libp2p: {topics?, protocols?, listen?}`), or undefined: no node. */
 export declare function libp2pOf(g: Record<string, unknown> | null | undefined): P2PInstanceConfig | undefined;
@@ -214,7 +257,7 @@ export declare function foldBeacons(events: Iterable<BeaconEvent>, into?: Beacon
 export declare const TOPIC_REQUIRED = "topic required";
 export declare class P2PHost {
     readonly o: P2POptions;
-    /** The liveness tool's state (#138): the apps' liveness and the beats kept, in memory. */
+    /** The liveness tool's state (#138): the apps' liveness and the beats kept (persisted in `o.beats` when given). */
     readonly live: Liveness;
     /** The nodes, by peer ID (#160: one per key). */
     private nodes;
@@ -225,10 +268,35 @@ export declare class P2PHost {
     /** Each key's declares, in order (one at a time). */
     private starting;
     private stopped;
+    /** The host node's key (hostKey, else a fresh one) and its peer ID. */
+    private readonly hostKey;
+    readonly hostId: string;
     constructor(o: P2POptions);
     private say;
-    /** A node's name in a log line: its one handle (as before #160), else its first. */
+    /** A node's name in a log line: its one handle (as before #160), else its first; the host node with none: the router. */
     private nameOf;
+    /**
+     * The host node: the node of the host key, started (once) with no handles when no instance has
+     * started it yet; an instance on that key that starts later joins it (#160), one that started
+     * earlier made it.
+     */
+    hostNode(): Promise<Libp2p>;
+    /** The host node's record, once it runs. */
+    private hostOf;
+    /**
+     * A host topic on the host node (#156: the Teranode block topic): subscribed, each message judged
+     * by `take` alone (its verdict GossipSub's), never the front door, never advertised on the skein
+     * DHT. Undefined `take`: the topic left.
+     */
+    hostTopic(topic: string, take: HostTopicHandler | undefined): Promise<void>;
+    /** The peers the host node knows subscribe `topic` (GossipSub's view). */
+    hostSubscribers(topic: string): string[];
+    /** The host node's skein DHT's mode now (client | server; undefined: off or no host node yet). */
+    hostDhtMode(): "client" | "server" | undefined;
+    /** The host node's confirmed public addresses (AutoNAT's, or UPnP's once AutoNAT confirmed them): libp2p announces only confirmed ones; relay addresses aside. */
+    hostPublicAddrs(): string[];
+    /** The host node's DHT service, the skein DHT (undefined: SKEIN_LIBP2P_DHT=off, or no host node yet). */
+    hostDht(): KadDHT | undefined;
     /** The node of an instance, if it has one. */
     node(handle: string): Libp2p | undefined;
     /** An instance's peer ID (derived: whether or not its node runs). */
@@ -255,7 +323,7 @@ export declare class P2PHost {
     private subscribe;
     /** The topics `handle` takes: its config's and its apps' liveness topics (#138). */
     private takes;
-    /** Subscribe what the handles' configs and liveness tools (#138) take, unsubscribe the rest: the topics added and removed. */
+    /** Subscribe what the handles' configs and liveness tools (#138) take, and the host's own topics (#156), unsubscribe the rest: the topics added and removed. */
     private resubscribe;
     /** Handle the protocols the handles declare, unhandle those none declares any more (the host's own aside). */
     private rehandle;
@@ -271,6 +339,7 @@ export declare class P2PHost {
     private hostServed;
     private handleHostProtocol;
     private handleProtocol;
+    /** A node for `key` (its private key `pk`): with `handle` and its config, or the host node with none (#156). */
     private start;
     /** Keep the bootstrap peers connected; with the DHT on, advertise each topic and dial its providers. */
     private discover;
@@ -335,3 +404,33 @@ export declare class P2PHost {
     private drop;
     stop(): Promise<void>;
 }
+/** A multiaddr on a loopback or private network (dev: the DHT keeps such addresses). */
+export declare function isPrivateAddr(ma: Multiaddr): boolean;
+/**
+ * kad-DHT's clientMode for a mode of the skein DHT (2026-11-01; @libp2p/kad-dht 16.4.5 kad-dht.js): `auto` leaves it
+ * unset — the DHT's own switch (a client, a server while the node has a confirmed public address);
+ * `client` true — only ever a client; `server` false — a server from its start (its start sets the mode),
+ * never switched back. An explicit false is NOT auto in this version: the switch listens only when unset.
+ */
+export declare function dhtClientMode(mode: Exclude<DhtMode, "off">): {
+    clientMode?: boolean;
+};
+/**
+ * The libp2p logger, with the UPnP service's outcome told once per distinct line (2026-11-01): the gateway
+ * search's result, the public IP found, each mapping made or refused, an error. The service reports its
+ * outcome nowhere else (its log only); every other component's log is the default, untouched.
+ */
+export declare function upnpTold(tell: (line: string) => void): ComponentLogger;
+/** A node's DHT service, the skein DHT (#156), or undefined (SKEIN_LIBP2P_DHT=off). */
+export declare function dhtOf(node: Libp2p): KadDHT | undefined;
+/** The providers a DHT finds for `cid` (its PROVIDER events' peers), on that DHT alone. */
+export declare function providersOf(dht: KadDHT, cid: CID, options?: {
+    signal?: AbortSignal;
+}): AsyncIterable<{
+    id: PeerId;
+    multiaddrs: Multiaddr[];
+}>;
+/** Run a DHT operation's events to the end. */
+export declare function drain(events: AsyncIterable<unknown>): Promise<void>;
+/** A DHT's routing table size (undefined: no such DHT). */
+export declare function tableSize(dht: KadDHT | undefined): number | undefined;