@dcasegr/skein 0.1.1 → 0.2.8

package/dist/host/teranode.d.ts

@@ -0,0 +1,132 @@
+import type { Libp2p } from "@libp2p/interface";
+import { type P2PHost } from "./p2p.ts";
+/** The network's bootstrap peers (go-teranode-p2p-client config.go); regtest has none. */
+export declare const TERANODE_BOOTSTRAP: Record<string, string[]>;
+/** The default data hub per network (first sync; the gorillanode Teranode asset API); regtest has none. */
+export declare const DEFAULT_HUBS: Record<string, string>;
+/** The block topic of a network (SKEIN_NETWORK's names, or the topic's own). */
+export declare function blockTopic(network: string): string;
+/** A header's hash, display hex. */
+export declare const hashOf: (raw: Uint8Array) => string;
+/** A header's parent's hash, display hex. */
+export declare const prevOf: (raw: Uint8Array) => string;
+/** One block announcement, as the tracker reads it. */
+export interface Announcement {
+    hash: string;
+    height: number;
+    header: Uint8Array;
+    hub?: string;
+    peer?: string;
+}
+/**
+ * A block announcement out of a message on the block topic: the bus's envelope or a bare
+ * BlockMessage. Undefined (dropped) when it is neither, its header is not 80 bytes of hex, or the
+ * header's hash is not the `Hash` it names.
+ */
+export declare function parseAnnouncement(data: Uint8Array): Announcement | undefined;
+export interface HubOptions {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** The hub's best header (80 bytes) and, when it says, its height (`bestblockheader/json`). */
+export declare function hubBest(hub: string, o?: HubOptions): Promise<{
+    header: Uint8Array;
+    hash: string;
+    height?: number;
+}>;
+/**
+ * Up to `n` headers from `hash` back (child to parent, `hash` first): each one's proof of work and
+ * every link checked; a page that does not start at `hash` or does not link is refused.
+ */
+export declare function hubBack(hub: string, hash: string, n: number, o?: HubOptions): Promise<Uint8Array[]>;
+/** What the tracker reads and writes: the host's image chain and the intake behind it (Router). */
+export interface TrackerChain {
+    /** The tip held (undefined: nothing held). */
+    tip(): {
+        height: number;
+        hash: string;
+    } | undefined;
+    /** The height of a header held near the tip, by hash (display hex). */
+    find(hash: string): number | undefined;
+    /** A run of headers, parents first, at `height` (its first one's): into the image chain and on to the host chain and the instances. */
+    take(height: number, raws: Uint8Array[]): Promise<void>;
+}
+export interface TrackerOptions {
+    network: string;
+    /** Bootstrap multiaddrs (dnsaddr resolved by libp2p): the network's and SKEIN_TERANODE_BOOTSTRAP's; dialled while the host node has few peers. */
+    bootstrap: string[];
+    /** The host's libp2p (#156): the tracker rides its host node. None: no mesh (a hub-only first sync). */
+    p2p?: P2PHost;
+    /** The hub for the first sync (DEFAULT_HUBS, SKEIN_HEADERS_HUB); none: the first announcement's. */
+    hub?: string;
+    /**
+     * Where the peers met are kept between runs (go-p2p-message-bus's peer cache): dialled at start
+     * beside the bootstrap peers, so a restart does not hang on the bootstrap; none: not kept.
+     */
+    peersFile?: string;
+    chain: TrackerChain;
+    /** Headers per hub request: a gap's crawl (default 2 000) and the first sync's (default 10 000; a hub may answer fewer). */
+    page?: number;
+    bulkPage?: number;
+    /** The most headers a gap's crawl walks back before it gives up (default 20 160). */
+    maxCrawl?: number;
+    /** Peer upkeep: bootstrap redialled while too few are on the block topic (ms, default 30 000). */
+    discoveryMs?: number;
+    hub_?: HubOptions;
+    log?(line: string): void;
+}
+export declare class TeranodeTracker {
+    readonly o: TrackerOptions;
+    readonly topic: string;
+    node?: Libp2p;
+    /** Settles when the first sync is done (or there was nothing to do); rejects never. */
+    ready: Promise<void>;
+    private queue;
+    private stopped;
+    private timer?;
+    private syncing;
+    /** The newest announcement seen while the first sync ran (caught up from after it). */
+    private pending?;
+    private peers;
+    private lastBootErr;
+    /** Counts for the logs and tests. */
+    readonly stats: {
+        announcements: number;
+        dropped: number;
+        taken: number;
+        crawled: number;
+        known: number;
+    };
+    constructor(o: TrackerOptions);
+    private say;
+    /** Join the mesh (on the host node) and start the first sync when the image chain is empty. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** The block topic on the host node: each message judged here (an announcement Accept and followed, anything else Reject); upkeep every round. */
+    private join;
+    /** The bootstrap peers dialled while too few are on the block topic. */
+    private upkeep;
+    /** The host node's DHT routing table's size, the skein DHT's (undefined: the DHT off). */
+    tables(): {
+        skein?: number;
+    };
+    /** The peers on the block topic the host node knows (GossipSub's view). */
+    onTopic(): number;
+    /** The peers kept from earlier runs (their dialable addresses). */
+    private cached;
+    /** The peers connected now — the block topic's first — kept for the next run (at most 32). */
+    private keep;
+    /** An announcement: in turn with the others (one change to the chain at a time). */
+    announce(a: Announcement): void;
+    /** go-chaintracks processBlockMessage: known, a child of a header near the tip, or a crawl back from its hub. */
+    private follow;
+    /**
+     * go-chaintracks SyncFromRemoteTip: back from `hash` through the hub until a header held (its
+     * height `base`), or the genesis header (base -1: the run starts at 0); the run parents first.
+     */
+    private crawl;
+    /** The first sync: an empty chain filled from a hub (the default, else the first announcement's). */
+    private initial;
+    /** The whole chain, from `best` back to genesis through `hub`, written in height order. */
+    private bulk;
+}

package/dist/host/teranode.js

@@ -0,0 +1,406 @@
+// The host's headers tracker over the Teranode P2P network (shruggr/skein#156):
+// a packaged host learns block headers itself, as any ChainTracks instance
+// does (bsv-blockchain/go-chaintracks chainmanager p2p.go + sync.go), with no
+// headers service configured.
+//
+// The Teranode network is libp2p (go-p2p-message-bus): TCP, noise, yamux, a
+// kad-DHT (which skein does not join: see below), GossipSub with StrictSign. Bootstrap peers are the network's
+// `/dnsaddr/<net>.bootstrap.teranode.bsvb.tech` (go-teranode-p2p-client
+// config.go); the block topic is `teranode/bitcoin/1.0.0/<network>-block`
+// (topics.go: main → mainnet, test → testnet, regtest → regtest). A message on
+// it is the bus's envelope `{"name", "data": <base64>}` (client.go Publish)
+// whose data is teranode's BlockMessage as Go marshals it (no JSON tags:
+// services/p2p/message_types.go): `{PeerID, ClientName, DataHubURL, Hash,
+// Height, Header (80 bytes, hex), Coinbase}`. A bare BlockMessage (no
+// envelope) is taken too. Anything else on the topic is dropped.
+//
+// What it does with an announcement (TrackerChain: the host's image chain,
+// image-chain.ts, and the router's intake behind it):
+//
+//   - a header the host holds near its tip: nothing;
+//   - one whose parent it holds near its tip: taken at the parent's height + 1
+//     (the intake replaces from there: a reorg one deep);
+//   - otherwise: crawl back from the announcer's data hub (`GET
+//     <hub>/headers/<hash>?n=<count>`: up to `count` 80-byte headers, child to
+//     parent, the asked one first) until a header the host holds, then the run,
+//     parents first, to the intake. Capped (`maxCrawl` headers), every page's
+//     links checked and each header's proof of work, a timeout per request, no
+//     redirect followed.
+//
+// First boot (`initial`): with an empty image chain, the whole chain from the
+// network's default hub (gorillanode, or SKEIN_HEADERS_HUB) — `bestblockheader`
+// then `headers/<hash>?n=` back to genesis — written in height order; one log
+// line per page ("headers: initial sync <have>/<tip height>"). No default hub
+// (regtest) and none named: it waits for the first announcement and syncs from
+// ITS hub. Same crawl both ways.
+//
+// The node is the HOST node (p2p.ts P2PHost.hostNode, #156 one node): the
+// node of the host key, which on a one-key host carries the instances' overlay
+// too. The block topic is a host topic on it (judged here: Accept when the
+// message reads as an announcement, else Reject; never the front door). Its
+// block-topic peers come from the bootstrap list (SKEIN_TERANODE_BOOTSTRAP, the
+// network's defaults unioned), redialled while fewer than 4 are on the topic,
+// and from GossipSub; there is no Teranode DHT (2026-11-02): it is the public
+// IPFS DHT, and even a kad client crawls it and fills a js-libp2p node's
+// connection cap, which then refuses every newcomer. The peers met are kept in
+// teranode-peers.json between runs.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { multiaddr } from "@multiformats/multiaddr";
+import { headerProblem } from "./image-chain.js";
+import { NETWORK_NAMES, tableSize } from "./p2p.js";
+/** The network's bootstrap peers (go-teranode-p2p-client config.go); regtest has none. */
+export const TERANODE_BOOTSTRAP = {
+    main: ["/dnsaddr/mainnet.bootstrap.teranode.bsvb.tech"],
+    test: ["/dnsaddr/testnet.bootstrap.teranode.bsvb.tech"],
+};
+/** The default data hub per network (first sync; the gorillanode Teranode asset API); regtest has none. */
+export const DEFAULT_HUBS = {
+    main: "https://mainnet.gorillanode.io/api/v1",
+    test: "https://testnet.gorillanode.io/api/v1",
+};
+/** The block topic of a network (SKEIN_NETWORK's names, or the topic's own). */
+export function blockTopic(network) {
+    return `teranode/bitcoin/1.0.0/${NETWORK_NAMES[network] ?? network}-block`;
+}
+const SIZE = 80;
+const sha256d = (b) => createHash("sha256").update(createHash("sha256").update(b).digest()).digest();
+const display = (h) => Buffer.from(h).reverse().toString("hex");
+/** A header's hash, display hex. */
+export const hashOf = (raw) => display(sha256d(raw));
+/** A header's parent's hash, display hex. */
+export const prevOf = (raw) => display(raw.subarray(4, 36));
+const ZERO = "0".repeat(64);
+/**
+ * A block announcement out of a message on the block topic: the bus's envelope or a bare
+ * BlockMessage. Undefined (dropped) when it is neither, its header is not 80 bytes of hex, or the
+ * header's hash is not the `Hash` it names.
+ */
+export function parseAnnouncement(data) {
+    let v;
+    try {
+        v = JSON.parse(Buffer.from(data).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    } // not JSON: not a block message
+    let o = v;
+    if (!o || typeof o !== "object")
+        return undefined;
+    if (typeof o.data === "string" && o.Header === undefined) {
+        try {
+            o = JSON.parse(Buffer.from(o.data, "base64").toString("utf8"));
+        }
+        catch {
+            return undefined;
+        } // an envelope whose data is not a BlockMessage
+        if (!o || typeof o !== "object")
+            return undefined;
+    }
+    if (typeof o.Header !== "string" || !/^[0-9a-fA-F]{160}$/.test(o.Header))
+        return undefined;
+    const header = Uint8Array.from(Buffer.from(o.Header, "hex"));
+    const hash = hashOf(header);
+    if (typeof o.Hash !== "string" || o.Hash.toLowerCase() !== hash)
+        return undefined;
+    const height = typeof o.Height === "number" && Number.isInteger(o.Height) && o.Height >= 0 ? o.Height : -1;
+    if (height < 0)
+        return undefined;
+    const hub = typeof o.DataHubURL === "string" && /^https?:\/\//.test(o.DataHubURL) ? o.DataHubURL.replace(/\/+$/, "") : undefined;
+    return { hash, height, header, ...(hub ? { hub } : {}), ...(typeof o.PeerID === "string" ? { peer: o.PeerID } : {}) };
+}
+async function hubGet(url, o, max) {
+    const res = await (o.fetch ?? fetch)(url, { redirect: "error", signal: AbortSignal.timeout(o.timeoutMs ?? 30_000) });
+    if (!res.ok)
+        throw new Error(`${url}: HTTP ${res.status}`);
+    const b = Buffer.from(await res.arrayBuffer());
+    if (b.length > max)
+        throw new Error(`${url}: ${b.length} bytes, more than ${max}`);
+    return b;
+}
+/** The hub's best header (80 bytes) and, when it says, its height (`bestblockheader/json`). */
+export async function hubBest(hub, o = {}) {
+    const b = await hubGet(`${hub}/bestblockheader`, o, SIZE);
+    if (b.length !== SIZE)
+        throw new Error(`${hub}/bestblockheader: ${b.length} bytes, not a header`);
+    const why = headerProblem(b);
+    if (why)
+        throw new Error(`${hub}/bestblockheader: ${why}`);
+    let height;
+    try {
+        const j = JSON.parse((await hubGet(`${hub}/bestblockheader/json`, o, 64 * 1024)).toString("utf8"));
+        if (j.hash === hashOf(b) && typeof j.height === "number")
+            height = j.height;
+    }
+    catch { /* the height is only for the progress line */ }
+    return { header: Uint8Array.from(b), hash: hashOf(b), ...(height !== undefined ? { height } : {}) };
+}
+/**
+ * Up to `n` headers from `hash` back (child to parent, `hash` first): each one's proof of work and
+ * every link checked; a page that does not start at `hash` or does not link is refused.
+ */
+export async function hubBack(hub, hash, n, o = {}) {
+    const url = `${hub}/headers/${hash}?n=${n}`;
+    const b = await hubGet(url, o, n * SIZE);
+    if (b.length === 0 || b.length % SIZE)
+        throw new Error(`${url}: ${b.length} bytes, not whole headers`);
+    const out = [];
+    for (let i = 0; i < b.length; i += SIZE)
+        out.push(Uint8Array.from(b.subarray(i, i + SIZE)));
+    if (hashOf(out[0]) !== hash)
+        throw new Error(`${url}: its first header is not ${hash}`);
+    for (const [i, raw] of out.entries()) {
+        const why = headerProblem(raw);
+        if (why)
+            throw new Error(`${url}: header ${i}: ${why}`);
+        if (i > 0 && prevOf(out[i - 1]) !== hashOf(raw))
+            throw new Error(`${url}: header ${i} is not header ${i - 1}'s parent`);
+    }
+    return out;
+}
+export class TeranodeTracker {
+    o;
+    topic;
+    node;
+    /** Settles when the first sync is done (or there was nothing to do); rejects never. */
+    ready = Promise.resolve();
+    queue = Promise.resolve();
+    stopped = false;
+    timer;
+    syncing = false;
+    /** The newest announcement seen while the first sync ran (caught up from after it). */
+    pending;
+    peers = "";
+    lastBootErr = "";
+    /** Counts for the logs and tests. */
+    stats = { announcements: 0, dropped: 0, taken: 0, crawled: 0, known: 0 };
+    constructor(o) {
+        this.o = o;
+        this.topic = blockTopic(o.network);
+    }
+    say(line) { this.o.log?.(line); }
+    /** Join the mesh (on the host node) and start the first sync when the image chain is empty. */
+    async start() {
+        if (this.o.p2p)
+            await this.join(this.o.p2p);
+        // In turn with the announcements (one change to the chain at a time).
+        const p = this.queue.then(() => this.initial()).catch((e) => this.say(`headers: initial sync failed: ${e.message}; the next announcement syncs from its hub`));
+        this.queue = p;
+        this.ready = p;
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        // The node is the host's: it stops with the host's libp2p (P2PHost.stop), the block topic left first.
+        await this.o.p2p?.hostTopic(this.topic, undefined).catch(() => { });
+    }
+    /** The block topic on the host node: each message judged here (an announcement Accept and followed, anything else Reject); upkeep every round. */
+    async join(p2p) {
+        const t0 = Date.now();
+        const node = await p2p.hostNode();
+        this.node = node;
+        if (this.stopped)
+            return;
+        await p2p.hostTopic(this.topic, (data) => {
+            const a = parseAnnouncement(data);
+            if (!a) {
+                this.stats.dropped++;
+                return "reject";
+            }
+            this.announce(a);
+            return "accept";
+        });
+        this.say(`headers: Teranode ${this.o.network} mesh on the host node ${node.peerId}, ${this.topic}; bootstrap ${this.o.bootstrap.join(" ") || "none"}`);
+        const upkeep = () => void this.upkeep(t0).catch((e) => this.say(`headers: Teranode peers: ${e.message}`));
+        upkeep();
+        this.timer = setInterval(upkeep, this.o.discoveryMs ?? 30_000);
+        this.timer.unref?.();
+    }
+    /** The bootstrap peers dialled while too few are on the block topic. */
+    async upkeep(t0) {
+        const node = this.node;
+        if (!node || this.stopped)
+            return;
+        // One node carries the overlay too (#156): its Teranode side counts the peers on the block topic.
+        if (this.o.p2p.hostSubscribers(this.topic).length < 4) {
+            const errs = [];
+            await Promise.all([...this.o.bootstrap, ...this.cached()].map(async (a, i) => {
+                try {
+                    await node.dial(multiaddr(a), { signal: AbortSignal.timeout(20_000) });
+                }
+                catch (e) {
+                    if (i < this.o.bootstrap.length)
+                        errs.push(`${a}: ${e.message}`);
+                }
+            }));
+            // One line when the bootstrap's answer changes (it is retried every round).
+            const err = errs.join("; ");
+            if (err !== this.lastBootErr) {
+                this.lastBootErr = err;
+                this.say(err ? `headers: Teranode bootstrap ${err}` : "headers: Teranode bootstrap reached");
+            }
+        }
+        const p2p = this.o.p2p;
+        const subs = p2p.hostSubscribers(this.topic);
+        const n = node.getConnections().length, onTopic = subs.length;
+        this.keep(node, subs);
+        const t = this.tables();
+        // 2026-11-01: the skein DHT's mode (auto flips to server on a confirmed public address) and those addresses.
+        const m = p2p.hostDhtMode(), pub = p2p.hostPublicAddrs();
+        const now = `${n} ${onTopic} ${t.skein} ${m} ${pub.join(" ")}`;
+        if (now !== this.peers) {
+            this.peers = now;
+            this.say(`headers: Teranode peers ${n} (${onTopic} on the block topic; skein DHT table ${t.skein ?? "off"}, mode ${m ?? "off"}; public ${pub.join(" ") || "none confirmed"}) at ${((Date.now() - t0) / 1000).toFixed(1)} s`);
+        }
+    }
+    /** The host node's DHT routing table's size, the skein DHT's (undefined: the DHT off). */
+    tables() {
+        return { skein: tableSize(this.o.p2p?.hostDht()) };
+    }
+    /** The peers on the block topic the host node knows (GossipSub's view). */
+    onTopic() { return this.o.p2p?.hostSubscribers(this.topic).length ?? 0; }
+    /** The peers kept from earlier runs (their dialable addresses). */
+    cached() {
+        const f = this.o.peersFile;
+        if (!f || !existsSync(f))
+            return [];
+        try {
+            const v = JSON.parse(readFileSync(f, "utf8"));
+            return Array.isArray(v) ? v.filter((x) => typeof x === "string").slice(0, 32) : [];
+        }
+        catch {
+            return [];
+        } // an unreadable cache: none
+    }
+    /** The peers connected now — the block topic's first — kept for the next run (at most 32). */
+    keep(node, onTopic) {
+        const f = this.o.peersFile;
+        if (!f)
+            return;
+        const conns = node.getConnections().filter((c) => c.direction === "outbound" && !c.remoteAddr.toString().includes("/p2p-circuit"));
+        conns.sort((a, b) => Number(onTopic.includes(b.remotePeer.toString())) - Number(onTopic.includes(a.remotePeer.toString())));
+        const addrs = [...new Set(conns.map((c) => `${c.remoteAddr.toString().replace(/\/p2p\/[^/]+$/, "")}/p2p/${c.remotePeer}`))].slice(0, 32);
+        if (!addrs.length)
+            return;
+        try {
+            writeFileSync(f, `${JSON.stringify(addrs)}\n`);
+        }
+        catch (e) {
+            this.say(`headers: the Teranode peers not kept: ${e.message}`);
+        }
+    }
+    /** An announcement: in turn with the others (one change to the chain at a time). */
+    announce(a) {
+        this.stats.announcements++;
+        if (this.syncing) {
+            this.pending = a;
+            return;
+        }
+        this.queue = this.queue.then(() => this.follow(a)).catch((e) => this.say(`headers: block ${a.height} ${a.hash}: ${e.message}`));
+    }
+    /** go-chaintracks processBlockMessage: known, a child of a header near the tip, or a crawl back from its hub. */
+    async follow(a) {
+        const c = this.o.chain;
+        if (!c.tip()) {
+            // The first sync failed or had no hub: this announcement's hub, from it.
+            if (!a.hub)
+                throw new Error("nothing held yet, and the announcement names no data hub: dropped");
+            await this.bulk(a.hub, { hash: a.hash, height: a.height });
+            return;
+        }
+        if (c.find(a.hash) !== undefined) {
+            this.stats.known++;
+            return;
+        }
+        const parent = c.find(prevOf(a.header));
+        if (parent !== undefined) {
+            await c.take(parent + 1, [a.header]);
+            this.stats.taken++;
+            this.say(`headers: block ${parent + 1} ${a.hash}${a.peer ? ` (announced by ${a.peer})` : ""}`);
+            return;
+        }
+        if (!a.hub)
+            throw new Error("links to no header near the tip, and names no data hub: dropped");
+        const { base, run } = await this.crawl(a.hub, a.hash, this.o.page ?? 2000, this.o.maxCrawl ?? 20_160);
+        await c.take(base + 1, run);
+        this.stats.crawled += run.length;
+        this.say(`headers: ${run.length} header${run.length === 1 ? "" : "s"} from ${a.hub} to ${a.height} (from ${base + 1})`);
+    }
+    /**
+     * go-chaintracks SyncFromRemoteTip: back from `hash` through the hub until a header held (its
+     * height `base`), or the genesis header (base -1: the run starts at 0); the run parents first.
+     */
+    async crawl(hub, hash, page, max, progress) {
+        const c = this.o.chain;
+        const pages = [];
+        let have = 0;
+        let at = hash;
+        for (;;) {
+            if (this.stopped)
+                throw new Error("stopped");
+            const got = await hubBack(hub, at, page, this.o.hub_);
+            if (pages.length && prevOf(pages.at(-1).at(-1)) !== hashOf(got[0]))
+                throw new Error(`${hub}: a page that does not continue the last`);
+            for (const [i, raw] of got.entries()) {
+                const h = c.find(hashOf(raw));
+                if (h !== undefined) {
+                    pages.push(got.slice(0, i));
+                    return { base: h, run: pages.flat().reverse() };
+                }
+            }
+            pages.push(got);
+            have += got.length;
+            progress?.(have);
+            const last = got.at(-1);
+            if (prevOf(last) === ZERO)
+                return { base: -1, run: pages.flat().reverse() }; // the genesis header: the whole chain
+            if (have >= max)
+                throw new Error(`${hub}: no header held within ${have} back from ${hash}`);
+            at = prevOf(last);
+        }
+    }
+    /** The first sync: an empty chain filled from a hub (the default, else the first announcement's). */
+    async initial() {
+        const hub = this.o.hub;
+        if (hub) {
+            // Every start: to the hub's best (go-chaintracks's bootstrap sync) — the whole chain when none is held,
+            // else what was missed while the host was down (the mesh may take a while to find).
+            const best = await hubBest(hub, this.o.hub_);
+            if (this.o.chain.find(best.hash) !== undefined)
+                return;
+            if (!this.o.chain.tip())
+                return await this.bulk(hub, best);
+            const { base, run } = await this.crawl(hub, best.hash, this.o.bulkPage ?? 10_000, Number.POSITIVE_INFINITY);
+            await this.o.chain.take(base + 1, run);
+            this.say(`headers: caught up from ${hub}: ${run.length} header${run.length === 1 ? "" : "s"} to ${this.o.chain.tip()?.height}`);
+            return;
+        }
+        if (this.o.chain.tip())
+            return;
+        this.say(`headers: no data hub for ${this.o.network}: waiting for the first block announcement to sync from its hub`);
+        // follow() runs the sync for the first announcement (bulk from its hub).
+    }
+    /** The whole chain, from `best` back to genesis through `hub`, written in height order. */
+    async bulk(hub, best) {
+        const c = this.o.chain;
+        this.syncing = true;
+        try {
+            const t0 = Date.now();
+            const of = best.height !== undefined ? String(best.height + 1) : "?";
+            this.say(`headers: initial sync from ${hub}: ${of} headers to ${best.hash}`);
+            const { base, run } = await this.crawl(hub, best.hash, this.o.bulkPage ?? 10_000, Number.POSITIVE_INFINITY, (have) => this.say(`headers: initial sync ${have}/${of}`));
+            const fetched = Date.now() - t0;
+            await c.take(base + 1, run);
+            this.say(`headers: initial sync done: ${run.length} headers to ${c.tip()?.height} in ${((Date.now() - t0) / 1000).toFixed(1)} s (fetch ${(fetched / 1000).toFixed(1)} s)`);
+        }
+        finally {
+            this.syncing = false;
+        }
+        // What was announced meanwhile: followed now.
+        const p = this.pending;
+        this.pending = undefined;
+        if (p)
+            this.announce(p);
+    }
+}

package/dist/host/testhost.d.ts

@@ -25,10 +25,15 @@ export declare function testHost(t: {
     arc?: Router["o"]["arc"];
     arcRetry?: Router["o"]["arcRetry"];
     headersFeed?: string;
+    teranode?: Router["o"]["teranode"];
     billing?: Router["o"]["billing"];
     lmdb?: boolean;
     rocks?: boolean;
     sqlite?: boolean;
+    reuse?: {
+        home: string;
+        keyOf(handle: string): PrivateKey;
+    };
 }): Promise<{
     home: string;
     db: HostDb;

package/dist/host/testhost.js

@@ -74,16 +74,19 @@ export async function messagesIn(store) {
 }
 /** A host with instances (mailbox instances among them), each instance's key its own (the signer's stand-in). */
 export async function testHost(t, o = {}) {
-    const home = await fs.mkdtemp(join(tmpdir(), "skein-router-"));
+    // #156: `reuse` — a second host over the first's home and keys (a restart: the first's router stopped first).
+    const home = o.reuse?.home ?? await fs.mkdtemp(join(tmpdir(), "skein-router-"));
     // #96: o.lmdb — every instance a set of one LMDB environment, <home>/store (host.db `lmdb:<dir>`), else a file each.
     // #158: o.rocks — every instance a set of one RocksDB database, <home>/store-rocksdb, run by one `skein-kernel host` process.
     // The settled split: o.sqlite (or SKEIN_TEST_STORE=sqlite) — every instance a set of one SQLite database, <home>/store.sqlite, on the wasm kernel.
     const sqlite = o.sqlite ?? process.env.SKEIN_TEST_STORE === "sqlite";
     const storeOf = (handle) => (sqlite ? `sqlite:${join(home, "store.sqlite")}` : o.rocks ? `rocksdb:${join(home, "store-rocksdb")}` : o.lmdb ? `lmdb:${join(home, "store")}` : join(home, "instances", handle, "runtime.db"));
-    t.after(() => fs.rm(home, { recursive: true, force: true }));
+    if (!o.reuse)
+        t.after(() => fs.rm(home, { recursive: true, force: true }));
     const db = new HostDb(join(home, "host.db"));
     const keys = new Map();
-    const keyOf = (h) => { let k = keys.get(h); if (!k) {
+    const keyOf = (h) => { if (o.reuse)
+        return o.reuse.keyOf(h); let k = keys.get(h); if (!k) {
         k = PrivateKey.fromRandom();
         keys.set(h, k);
     } return k; };
@@ -98,6 +101,8 @@ export async function testHost(t, o = {}) {
         ...(o.arc ? { arc: o.arc } : {}), ...(o.arcRetry ? { arcRetry: o.arcRetry } : {}),
         // The host's headers feed (#102).
         ...(o.headersFeed ? { headersFeed: o.headersFeed } : {}),
+        // #156: the Teranode headers tracker (a fake mesh and hub in the tests).
+        ...(o.teranode ? { teranode: o.teranode } : {}),
         // #130: what the host bills (billing.ts); none: it bills no one.
         ...(o.billing ? { billing: o.billing } : {}),
         ...(o.lmdb ? { lmdbStore: join(home, "store") } : {}),

package/dist/host/wasm-kernel.d.ts

@@ -1,6 +1,8 @@
 import { Worker } from "node:worker_threads";
 import type { CID } from "multiformats/cid";
 import { KernelSurface, type HostChainTip, type KernelOptions } from "./kernel.ts";
+/** The set an image's chain part is put in for a host chain's import (#156), emptied after it. */
+export declare const IMAGE_SET = "host/image";
 /** The wasm kernel: $SKEIN_KERNEL_WASM, else kernel-zig's `zig build web` output (the package ships it there). */
 export declare const KERNEL_WASM: string;
 /** The pinned modules (the boundary programs): $SKEIN_WASM_DIR, else the repo's (the package's) wasm/. */
@@ -58,6 +60,13 @@ export declare class WasmHost {
     chainHeaders(raws: Uint8Array[]): Promise<HostChainTip>;
     /** #156: an image's chain/headers (the tree `root`, whose blocks the set `set` holds) into the empty host chain. */
     chainImport(set: string, root: CID): Promise<HostChainTip>;
+    /**
+     * #156: an image's chain part (the `chain` tree and every object under it) into the EMPTY host
+     * chain, as an instance born with it would bring it (`chain-import`): its objects put in a set of
+     * their own (IMAGE_SET), a tree naming them `chain` as the root, the import, then that set's
+     * members and the blocks no other set holds removed.
+     */
+    importChain(chain: CID, objects: Array<[CID, Uint8Array]>): Promise<HostChainTip>;
     /** #156: the host chain as it stands, or undefined (empty). */
     chainTip(): Promise<HostChainTip | undefined>;
     /** One holder less; the last stops every machine. */

package/dist/host/wasm-kernel.js

@@ -24,7 +24,11 @@ import { WalletWireProcessor } from "@bsv/sdk";
 import { decode, encode } from "../runtime/cid.js";
 import { CHAIN_SET, parseSqliteSpec } from "../runtime/index-store.js";
 import { Rejected } from "../runtime/store.js";
+import { hashTree } from "../runtime/tree.js";
 import { KernelSurface } from "./kernel.js";
+import { openHostDb, SqliteSetStore } from "./store-sqlite.js";
+/** The set an image's chain part is put in for a host chain's import (#156), emptied after it. */
+export const IMAGE_SET = "host/image";
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolvePath(HERE, "../..");
 /** The wasm kernel: $SKEIN_KERNEL_WASM, else kernel-zig's `zig build web` output (the package ships it there). */
@@ -204,6 +208,48 @@ export class WasmHost {
     }
     /** #156: an image's chain/headers (the tree `root`, whose blocks the set `set` holds) into the empty host chain. */
     async chainImport(set, root) { return tipOf(await (await this.holder()).call("chain-import", { set, root })); }
+    /**
+     * #156: an image's chain part (the `chain` tree and every object under it) into the EMPTY host
+     * chain, as an instance born with it would bring it (`chain-import`): its objects put in a set of
+     * their own (IMAGE_SET), a tree naming them `chain` as the root, the import, then that set's
+     * members and the blocks no other set holds removed.
+     */
+    async importChain(chain, objects) {
+        const db = openHostDb(this.db);
+        try {
+            const s = new SqliteSetStore(db, IMAGE_SET);
+            const root = hashTree([{ mode: "40000", name: "chain", cid: chain }]);
+            s.begin();
+            for (const [cid, bytes] of objects)
+                s.putBlock(cid.bytes, bytes);
+            s.putBlock(root.cid.bytes, root.object);
+            s.commit();
+            try {
+                return await this.chainImport(IMAGE_SET, root.cid);
+            }
+            finally {
+                db.exec("BEGIN IMMEDIATE");
+                try {
+                    // members has no index by cid: each object looked up in every other set by its key.
+                    const sets = db.prepare(`SELECT DISTINCT "set" FROM members`).all().map((r) => r.set).filter((x) => x !== IMAGE_SET);
+                    const held = db.prepare(`SELECT 1 FROM members WHERE "set" = ? AND cid = ?`);
+                    const drop = db.prepare("DELETE FROM blocks WHERE cid = ?");
+                    for (const cid of [...objects.map(([c]) => c), root.cid])
+                        if (!sets.some((x) => held.get(x, cid.bytes)))
+                            drop.run(cid.bytes);
+                    db.prepare(`DELETE FROM members WHERE "set" = ?`).run(IMAGE_SET);
+                    db.exec("COMMIT");
+                }
+                catch (e) {
+                    db.exec("ROLLBACK");
+                    throw e;
+                }
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
     /** #156: the host chain as it stands, or undefined (empty). */
     async chainTip() { const v = await (await this.holder()).call("chain"); return v == null ? undefined : tipOf(v); }
     /** One holder less; the last stops every machine. */