@dcasegr/skein 0.1.2 → 0.2.8

package/README.md

@@ -314,6 +314,43 @@ bin/skein-host run        # the first run: operator.key, master.key, host.db and
   default image with the whole header chain from that chaintracks' history
   at start and appends every header the feed brings, so a new skein is born
   with the chain (#132, docs/BOOTSTRAP.md, "The image's chain part").
+  With no setting at all (#156, `src/host/teranode.ts`), `skein-host run`
+  follows the network's Teranode P2P mesh for block announcements (the
+  block topic `teranode/bitcoin/1.0.0/<network>-block`, bootstrap
+  `/dnsaddr/<network>.bootstrap.teranode.bsvb.tech`), crawls a gap back from
+  the announcer's data hub, and on an empty image chain syncs the whole
+  chain first from the network's default hub (gorillanode;
+  `SKEIN_HEADERS_HUB`); an empty host chain is then filled from the image
+  chain. Beside `SKEIN_HEADERS_URL` both feed the same intake;
+  `SKEIN_TERANODE=off` turns it off. The tracker rides the host's ONE
+  libp2p node (the host key's; a one-key host's instances are on it too),
+  which carries ONE Kademlia DHT, the skein DHT
+  (`/skein/kad/<network>/1.0.0`, the overlay's topics). It does not join
+  Teranode's DHT: that 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. Teranode peers come from the bootstrap list and GossipSub:
+  `SKEIN_TERANODE_BOOTSTRAP` adds peers beside the network's defaults
+  (gorillanode in DHT-server mode, the bsvb seeds, a hosted skein node are
+  all fine entries; any one that accepts is enough), redialled while fewer
+  than 4 are on the block topic.
+- **Per-network defaults** (`SKEIN_NETWORK`, default `main`): a host needs
+  no setting to find the overlay or broadcast. Unset means the network's;
+  `off` turns the default off.
+
+  | setting | unset = the network's | |
+  |---|---|---|
+  | `SKEIN_LIBP2P_BOOTSTRAP` | test: `/dns4/p2p.testnet.openex.dev/tcp/7534/p2p/16Uiu2HAmVN7Cc7TrFGVrbdoV1mMGBF8LQBvPZ5trzgPArfagBRSB` (the hosted Open Exchange node); main, regtest: none yet | skein peers named here are dialled beside the network's (unioned); `off`: none at all. A node whose own peer id is a default skips it |
+  | `SKEIN_ARC_URL` | test: `https://testnet.arcade.1sat.app`; main: `https://arcade.1sat.app`; regtest: none | `off`: no Arcade (a broadcast event is dropped). With the network's Arcade and no `SKEIN_ARC_TOKEN`, the host makes its callback token once (32 random bytes, hex) and appends `SKEIN_ARC_TOKEN=…` to `$SKEIN_HOME/host.env`, read from there after, as the key file is. A URL named here needs its token named too |
+- The defaults are tuned for discovery: the node listens on TCP port
+  **7534** on every interface (IPv4 and IPv6; another port if 7534 is
+  taken), asks the router to open it by UPnP/NAT-PMP where allowed
+  (`SKEIN_LIBP2P_UPNP=off` stops that), and runs the skein DHT in `auto`
+  mode — a client until AutoNAT confirms a public address, then a server
+  (`SKEIN_LIBP2P_DHT` sets its mode).
+  Nobody has to open a firewall; to be a bootstrap for others, open
+  TCP 7534 (or forward it on the router) and the node becomes a DHT
+  server by itself. A hosted node needs nothing set; `SKEIN_LIBP2P_DHT=server`
+  makes it a server from the start instead of waiting for AutoNAT.
 
 ## Talk to it
 

package/dist/host/arc.d.ts

@@ -13,8 +13,18 @@ export interface ArcConfig {
 }
 /** The webhook's path on the router. */
 export declare const ARC_ROUTE = "/arc";
-/** The host's Arcade from SKEIN_ARC_URL, SKEIN_ARC_TOKEN, SKEIN_ARC_EVENTS_URL, SKEIN_ARC_CALLBACK_URL (the environment, else $SKEIN_HOME/host.env); none without a URL. */
-export declare function hostArcConfig(vars: Record<string, string | undefined>, home?: string): ArcConfig | undefined;
+/** The network's Arcade (SKEIN_NETWORK's names) when SKEIN_ARC_URL is unset; regtest has none. */
+export declare const DEFAULT_ARC: Record<string, string>;
+/**
+ * The host's Arcade from SKEIN_ARC_URL, SKEIN_ARC_TOKEN, SKEIN_ARC_EVENTS_URL, SKEIN_ARC_CALLBACK_URL (the
+ * environment, else $SKEIN_HOME/host.env). SKEIN_ARC_URL unset: the network's (DEFAULT_ARC, by SKEIN_NETWORK,
+ * default main); `off`: none, as on regtest. With an Arcade and no SKEIN_ARC_TOKEN, the host's token is made
+ * (32 random bytes, hex) and appended to $SKEIN_HOME/host.env (the file made if absent), then read from it after —
+ * as the key file is; `made` reports it. Without a home there is nowhere to keep one: an error.
+ */
+export declare function hostArcConfig(vars: Record<string, string | undefined>, home?: string, o?: {
+    made?: (file: string) => void;
+}): ArcConfig | undefined;
 export interface ArcAnswer {
     status: number;
     headers: Record<string, string>;

package/dist/host/arc.js

@@ -52,30 +52,58 @@
 // Arcade itself may later sign its statuses (a signed-message callback beside
 // webhook and SSE): it would then be the status provider an instance
 // subscribes to, and nothing on the instance's side changes.
-import { existsSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Transaction } from "@bsv/sdk";
 import { DEFAULT_BOX, SseStream, statusOf, txCid } from "./feeds.js";
 /** The webhook's path on the router. */
 export const ARC_ROUTE = "/arc";
-/** The host's Arcade from SKEIN_ARC_URL, SKEIN_ARC_TOKEN, SKEIN_ARC_EVENTS_URL, SKEIN_ARC_CALLBACK_URL (the environment, else $SKEIN_HOME/host.env); none without a URL. */
-export function hostArcConfig(vars, home) {
-    const file = {};
+/** The network's Arcade (SKEIN_NETWORK's names) when SKEIN_ARC_URL is unset; regtest has none. */
+export const DEFAULT_ARC = {
+    main: "https://arcade.1sat.app",
+    test: "https://testnet.arcade.1sat.app",
+};
+/**
+ * The host's Arcade from SKEIN_ARC_URL, SKEIN_ARC_TOKEN, SKEIN_ARC_EVENTS_URL, SKEIN_ARC_CALLBACK_URL (the
+ * environment, else $SKEIN_HOME/host.env). SKEIN_ARC_URL unset: the network's (DEFAULT_ARC, by SKEIN_NETWORK,
+ * default main); `off`: none, as on regtest. With an Arcade and no SKEIN_ARC_TOKEN, the host's token is made
+ * (32 random bytes, hex) and appended to $SKEIN_HOME/host.env (the file made if absent), then read from it after —
+ * as the key file is; `made` reports it. Without a home there is nowhere to keep one: an error.
+ */
+export function hostArcConfig(vars, home, o = {}) {
     const envFile = home ? join(home, "host.env") : undefined;
-    if (envFile && existsSync(envFile)) {
-        for (const line of readFileSync(envFile, "utf8").split("\n")) {
-            const m = /^\s*(?:export\s+)?(SKEIN_ARC_[A-Z_]+)=(.*)$/.exec(line);
-            if (m)
-                file[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, "$2");
+    const readFile = () => {
+        const file = {};
+        if (envFile && existsSync(envFile)) {
+            for (const line of readFileSync(envFile, "utf8").split("\n")) {
+                const m = /^\s*(?:export\s+)?(SKEIN_ARC_[A-Z_]+|SKEIN_NETWORK)=(.*)$/.exec(line);
+                if (m)
+                    file[m[1]] = m[2].trim().replace(/^(["'])(.*)\1$/, "$2");
+            }
         }
-    }
+        return file;
+    };
+    const file = readFile();
     const get = (k) => vars[k] || file[k] || undefined;
-    const url = get("SKEIN_ARC_URL");
+    const set = get("SKEIN_ARC_URL");
+    if (set?.toLowerCase() === "off")
+        return undefined;
+    const url = set ?? DEFAULT_ARC[get("SKEIN_NETWORK") || "main"];
     if (!url)
         return undefined;
-    const token = get("SKEIN_ARC_TOKEN");
-    if (!token)
+    let token = get("SKEIN_ARC_TOKEN");
+    if (!token && set)
         throw new Error("SKEIN_ARC_URL is set but SKEIN_ARC_TOKEN is not: the host's callback token scopes its status stream");
+    if (!token) {
+        if (!envFile)
+            throw new Error(`the network's Arcade (${url}) needs the host's callback token (SKEIN_ARC_TOKEN), and there is no SKEIN_HOME to keep a new one in`);
+        token = randomBytes(32).toString("hex");
+        mkdirSync(home, { recursive: true });
+        const before = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
+        appendFileSync(envFile, `${before && !before.endsWith("\n") ? "\n" : ""}# The host's Arcade callback token (made on first run; it ties this host's transactions together at the Arcade).\nSKEIN_ARC_TOKEN=${token}\n`, { mode: 0o600 });
+        o.made?.(envFile);
+    }
     const events = get("SKEIN_ARC_EVENTS_URL"), callbackUrl = get("SKEIN_ARC_CALLBACK_URL");
     return { url: url.replace(/\/+$/, ""), token, ...(events ? { events } : {}), ...(callbackUrl ? { callbackUrl } : {}) };
 }

package/dist/host/cli.d.ts

@@ -39,6 +39,11 @@ export interface Host {
     port?: number;
     stop(): Promise<void>;
 }
+/**
+ * #156: the host's Teranode headers tracker (`skein-host run`): on unless SKEIN_TERANODE=off, where the
+ * network has bootstrap peers or SKEIN_TERANODE_BOOTSTRAP names some, or a hub is known for the first sync.
+ */
+export declare function teranodeOptions(v: Record<string, string | undefined>, home: string): Pick<RouterOptions, "teranode">;
 /** The default image (#89): one genesis for everyone, no owner in it, a claim row (boot.ts). */
 export { DEFAULT_IMAGE };
 /**

package/dist/host/cli.js

@@ -130,7 +130,10 @@
 //                         SKEIN_STORE_ROCKSDB and SKEIN_STORE. Unset, and no native kernel binary here (the npm package
 //                         ships none): $SKEIN_HOME/store.sqlite
 //   SKEIN_ARC_URL         the host's Arcade (#58, #65, arc.ts): where the instances' broadcast events go (a durable
-//                         queue), one status subscription, the instances' status provider; SKEIN_ARC_TOKEN its one callback token (required with it);
+//                         queue), one status subscription, the instances' status provider. Unset: the network's (arc.ts DEFAULT_ARC:
+//                         test https://testnet.arcade.1sat.app, main https://arcade.1sat.app, regtest none); `off`: none.
+//                         SKEIN_ARC_TOKEN its one callback token (required with a named URL; with the network's and none set,
+//                         made once and appended to $SKEIN_HOME/host.env, read from there after);
 //                         SKEIN_ARC_EVENTS_URL its SSE service (default <url>/events); SKEIN_ARC_CALLBACK_URL where Arcade
 //                         posts webhooks (this router's /arc/callback as Arcade reaches it; unset: SSE only)
 //   SKEIN_BILLING         `off`: this host bills no one (#130, billing.ts); else it bills a skein whose host row names its
@@ -144,6 +147,19 @@
 //                         and the default image's chain part (#132, image-chain.ts): every header it brings is
 //                         appended to the image, which a chaintracks URL's history (`…/tip/stream` → `…/headers`)
 //                         fills from genesis at start
+//   SKEIN_TERANODE        #156: `off` turns the host's headers tracker over the Teranode P2P network off (teranode.ts;
+//                         `skein-host run` only). On by default where the network has bootstrap peers (main, test):
+//                         it joins the network's block topic (`teranode/bitcoin/1.0.0/<network>-block`), takes each
+//                         announced header into the same intake as SKEIN_HEADERS_URL's, crawls a gap back from the
+//                         announcer's data hub, and, with an empty image chain, syncs the whole chain first from the
+//                         network's default hub (gorillanode). It rides the host node (the host key's, one per host:
+//                         the instances' overlay on the same node), its block-topic peers from the
+//                         bootstrap list and GossipSub (no Teranode DHT; the overlay's on its skein DHT, /skein/kad/<network>/1.0.0)
+//   SKEIN_TERANODE_BOOTSTRAP  more Teranode bootstrap peers (multiaddrs, comma separated) beside the network's
+//                         (/dnsaddr/<mainnet|testnet>.bootstrap.teranode.bsvb.tech); regtest has none: set it to run one
+//   SKEIN_HEADERS_HUB     the data hub the tracker's first sync reads (a Teranode asset API: `bestblockheader`,
+//                         `headers/<hash>?n=`) over the network's default (https://<mainnet|testnet>.gorillanode.io/api/v1);
+//                         regtest has none: without one the first sync waits for the first announcement's hub
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { CID as CIDClass, decode as decodeCbor, parse as parseCid } from "../runtime/cid.js";
@@ -162,6 +178,7 @@ import { CONTROL_SOCKET, controlRequest } from "./control.js";
 import { homeOf as homeOfVars, identityOf, operatorKey, withHostEnv } from "./hostenv.js";
 import { hostArcConfig } from "./arc.js";
 import { hostP2PConfig, peerIdOf } from "./p2p.js";
+import { DEFAULT_HUBS, TERANODE_BOOTSTRAP } from "./teranode.js";
 import { addressBook } from "./deploy.js";
 import { fetchHttp, hostDomain, Router } from "./router.js";
 import { billingConfig, DEV_BILLING, NSAT } from "./billing.js";
@@ -822,6 +839,7 @@ function wallets(v, home) {
     const signer = signerOf(v, home); // #160: one-key mode (SKEIN_KEY_FILE / SKEIN_KEY), else the master key's
     return {
         walletFor: (row) => signer.wallet(row.handle), peerKeyFor: (handle) => signer.peerKey(handle), providerKeyFor: (name) => signer.providerKey(name),
+        hostPeerKey: signer.hostPeerKey(), // #156: the host node's (the tracker rides it; a one-key host's instances share it)
         // #162: a one-key host claims the instances it creates with its own key.
         ...(signer.shared ? { claimer: signer.wallet("") } : {}),
     };
@@ -850,11 +868,26 @@ function routerOptions(db, env) {
         ...(Number(v.SKEIN_ANSWER_WAIT_MS) > 0 ? { answerWaitMs: Number(v.SKEIN_ANSWER_WAIT_MS) } : {}),
         libp2p: hostP2PConfig(v, home),
         headersFeed: v.SKEIN_HEADERS_URL || undefined,
-        arc: hostArcConfig(v, home),
+        arc: hostArcConfig(v, home, { made: (f) => env.out(`skein-host: the host's Arcade callback token made and kept in ${f} (SKEIN_ARC_TOKEN)`) }),
         billing: billingConfig(v),
         log: (source, line) => env.out(`[${source}] ${line}`),
     };
 }
+/**
+ * #156: the host's Teranode headers tracker (`skein-host run`): on unless SKEIN_TERANODE=off, where the
+ * network has bootstrap peers or SKEIN_TERANODE_BOOTSTRAP names some, or a hub is known for the first sync.
+ */
+export function teranodeOptions(v, home) {
+    if ((v.SKEIN_TERANODE ?? "").toLowerCase() === "off")
+        return {};
+    const net = hostNetwork(v);
+    const named = (v.SKEIN_TERANODE_BOOTSTRAP ?? "").split(/[,\s]+/).map((x) => x.trim()).filter(Boolean);
+    const bootstrap = [...new Set([...(TERANODE_BOOTSTRAP[net] ?? []), ...named])]; // #156: the network's and the named ones
+    const hub = (v.SKEIN_HEADERS_HUB || DEFAULT_HUBS[net])?.replace(/\/+$/, "");
+    if (!bootstrap.length && !hub)
+        return {};
+    return { teranode: { bootstrap, ...(hub ? { hub } : {}), peersFile: join(home, "teranode-peers.json") } };
+}
 /** `skein-host billing [handle]` (#130): what host.db holds of billing — the instances, their ticks, their payments. */
 function billingCmd(db, rest, env) {
     const [handle] = rest;
@@ -1159,7 +1192,7 @@ async function migrateStoreCmd(db, rest, env) {
 export async function runHost(db, env, o = {}) {
     const v = env.vars;
     const home = homeOf(v);
-    const router = new Router({ ...routerOptions(db, env), ...o.router });
+    const router = new Router({ ...routerOptions(db, env), ...teranodeOptions(v, home), ...o.router });
     const mport = Number(v.SKEIN_ROUTER_PORT ?? 8100);
     const binds = (v.SKEIN_ROUTER_BIND ?? "").split(",").map((x) => x.trim()).filter(Boolean);
     const mserver = await router.listen(mport, binds.length ? binds : undefined).then((s) => s, (e) => { env.err(`skein-host: router: ${e.message}`); return undefined; });
@@ -1178,7 +1211,7 @@ export async function runHost(db, env, o = {}) {
     if (router.arc)
         env.out(`skein-host: broadcaster: broadcast events → Arcade ${router.o.arc.url}; proofs and statuses (the status provider) from ${router.arc.eventsUrl()}${router.o.arc.callbackUrl ? ` and webhooks at /arc/callback (${router.o.arc.callbackUrl})` : ""}`);
     else
-        env.out("skein-host: no Arcade (SKEIN_ARC_URL): a broadcast event is dropped; a new genesis names no status provider");
+        env.out(`skein-host: no Arcade (SKEIN_ARC_URL ${(v.SKEIN_ARC_URL ?? "").toLowerCase() === "off" ? "off" : `unset, and network ${hostNetwork(v)} has none`}): a broadcast event is dropped; a new genesis names no status provider`);
     await router.start();
     // #142: the first run makes the host skein (owned by the operator's key); later runs start what exists.
     if (!db.hostSkein() && o.firstRun !== false) {

package/dist/host/fake-teranode.d.ts

@@ -0,0 +1,29 @@
+import type { Libp2p } from "@libp2p/interface";
+export declare const REGTEST_GENESIS: Buffer<ArrayBuffer>;
+/** A regtest header on `prev` (its merkle root `root`, else one from `salt`). */
+export declare function mineHeader(prev: Uint8Array, salt: number | string, root?: Uint8Array): Buffer;
+export declare class FakeTeranode {
+    /** The chain the hub serves (height = index). */
+    chain: Buffer[];
+    node: Libp2p;
+    hub: string;
+    /** Every hub request's path and query, in order. */
+    readonly asked: string[];
+    readonly topic: string;
+    private server?;
+    constructor(network?: string);
+    static start(network?: string): Promise<FakeTeranode>;
+    private pubsub;
+    /** The node's address (the tracker's bootstrap). */
+    addr(): string;
+    /** Peers subscribed to the block topic. */
+    subscribers(): number;
+    /** Mine to `height` on the served chain. */
+    mineTo(height: number): void;
+    /** Announce the header at `height` as a Teranode node does (the bus envelope around a BlockMessage). */
+    announce(height: number, o?: {
+        hub?: string | null;
+        raw?: unknown;
+    }): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/host/fake-teranode.js

@@ -0,0 +1,100 @@
+// A fake Teranode network for the tests (#156; fake-arcade.ts is the pattern):
+// one js-libp2p node on 127.0.0.1 (TCP, noise, yamux, GossipSub with
+// StrictSign) that publishes block announcements on the block topic as the
+// Teranode message bus does (`{"name", "data": <base64 BlockMessage JSON>}`),
+// and a data hub (the Teranode asset API's two reads the tracker uses:
+// `GET /bestblockheader` (+ `/json`) and `GET /headers/<hash>?n=` — child to
+// parent, binary) serving a regtest chain the test mines. No DHT: skein nodes
+// find Teranode peers by their bootstrap list and GossipSub alone (2026-11-02).
+import { createHash } from "node:crypto";
+import { createServer } from "node:http";
+import { noise } from "@chainsafe/libp2p-noise";
+import { yamux } from "@chainsafe/libp2p-yamux";
+import { gossipsub } from "@libp2p/gossipsub";
+import { identify } from "@libp2p/identify";
+import { tcp } from "@libp2p/tcp";
+import { createLibp2p } from "libp2p";
+import { headerProblem } from "./image-chain.js";
+import { blockTopic } from "./teranode.js";
+const sha256d = (b) => createHash("sha256").update(createHash("sha256").update(b).digest()).digest();
+const display = (h) => Buffer.from(h).reverse().toString("hex");
+export const REGTEST_GENESIS = Buffer.from("0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4adae5494dffff7f2002000000", "hex");
+/** A regtest header on `prev` (its merkle root `root`, else one from `salt`). */
+export function mineHeader(prev, salt, root) {
+    const h = Buffer.alloc(80);
+    h.writeInt32LE(1, 0);
+    Buffer.from(prev).copy(h, 4);
+    Buffer.from(root ?? sha256d(Buffer.from(`block ${salt}`))).copy(h, 36);
+    h.writeUInt32LE(1_790_300_000 + (typeof salt === "number" ? salt : 7) * 600, 68);
+    h.writeUInt32LE(0x207fffff, 72);
+    for (let nonce = 0;; nonce++) {
+        h.writeUInt32LE(nonce, 76);
+        if (!headerProblem(h))
+            return h;
+    }
+}
+export class FakeTeranode {
+    /** The chain the hub serves (height = index). */
+    chain = [REGTEST_GENESIS];
+    node;
+    hub = "";
+    /** Every hub request's path and query, in order. */
+    asked = [];
+    topic;
+    server;
+    constructor(network = "regtest") { this.topic = blockTopic(network); }
+    static async start(network = "regtest") {
+        const f = new FakeTeranode(network);
+        f.node = await createLibp2p({
+            addresses: { listen: ["/ip4/127.0.0.1/tcp/0"] },
+            transports: [tcp()], connectionEncrypters: [noise()], streamMuxers: [yamux()],
+            services: {
+                identify: identify(), pubsub: gossipsub({ globalSignaturePolicy: "StrictSign", allowPublishToZeroTopicPeers: true, emitSelf: false }),
+            },
+        });
+        f.pubsub().subscribe(f.topic);
+        f.server = createServer((req, res) => {
+            const u = new URL(req.url ?? "/", "http://x");
+            f.asked.push(`${u.pathname}${u.search}`);
+            const best = f.chain.at(-1);
+            if (u.pathname === "/bestblockheader")
+                return void res.writeHead(200, { "content-type": "application/octet-stream" }).end(best);
+            if (u.pathname === "/bestblockheader/json")
+                return void res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ hash: display(sha256d(best)), height: f.chain.length - 1 }));
+            const m = /^\/headers\/([0-9a-f]{64})$/.exec(u.pathname);
+            if (m) {
+                const at = f.chain.findIndex((h) => display(sha256d(h)) === m[1]);
+                if (at < 0)
+                    return void res.writeHead(404).end();
+                const n = Math.min(Number(u.searchParams.get("n") ?? 1), 10_000);
+                const out = [];
+                for (let h = at; h >= 0 && out.length < n; h--)
+                    out.push(f.chain[h]);
+                return void res.writeHead(200, { "content-type": "application/octet-stream" }).end(Buffer.concat(out));
+            }
+            res.writeHead(404).end();
+        });
+        await new Promise((r) => f.server.listen(0, "127.0.0.1", r));
+        f.hub = `http://127.0.0.1:${f.server.address().port}`;
+        return f;
+    }
+    pubsub() { return this.node.services.pubsub; }
+    /** The node's address (the tracker's bootstrap). */
+    addr() { return this.node.getMultiaddrs().find((a) => a.toString().includes("127.0.0.1")).toString(); }
+    /** Peers subscribed to the block topic. */
+    subscribers() { return this.pubsub().getSubscribers(this.topic).length; }
+    /** Mine to `height` on the served chain. */
+    mineTo(height) { while (this.chain.length <= height)
+        this.chain.push(mineHeader(sha256d(this.chain.at(-1)), this.chain.length)); }
+    /** Announce the header at `height` as a Teranode node does (the bus envelope around a BlockMessage). */
+    async announce(height, o = {}) {
+        const h = this.chain[height];
+        const msg = o.raw ?? { PeerID: this.node.peerId.toString(), ClientName: "fake", DataHubURL: o.hub === null ? "" : (o.hub ?? this.hub), Hash: display(sha256d(h)), Height: height, Header: h.toString("hex"), Coinbase: "" };
+        const data = Buffer.from(typeof msg === "string" ? msg : JSON.stringify({ name: "fake", data: Buffer.from(JSON.stringify(msg)).toString("base64") }));
+        await this.pubsub().publish(this.topic, data);
+    }
+    async stop() {
+        await this.node.stop();
+        await new Promise((r) => this.server?.close(r));
+    }
+}

package/dist/host/feeds.d.ts

@@ -107,7 +107,7 @@ export declare class Feeds {
      * chain part grows by it): every header the stream brings, as well as the
      * subscribers'. The connection stays open while a listener is on it.
      */
-    listen(url: string, fn: (raws: Uint8Array[]) => void): void;
+    listen(url: string, fn: (raws: Uint8Array[], at?: number) => Promise<void> | void): void;
     /** Whether `handle` is subscribed to the host's own feed. */
     hosts(handle: string): boolean;
     /** Subscribe `handle` to what it declared and the host's feed for it, and to nothing else. */
@@ -124,4 +124,12 @@ export declare class Feeds {
     pending(handle: string): number;
     private drain;
     private dispatch;
+    /**
+     * #156: headers the host brings itself (the Teranode tracker) as if `url`'s stream had: to its
+     * listener (the image chain, the host chain), then to its subscribers in runs of BACKFILL_RUN.
+     * `at`: the height of the first (a run that may replace from there).
+     */
+    inject(url: string, raws: Uint8Array[], at?: number): Promise<void>;
+    /** The listener first (awaited: the host chain holds the run before an instance is told), then every subscriber. */
+    private deliver;
 }

package/dist/host/feeds.js

@@ -341,7 +341,7 @@ export class Feeds {
             if (s.subscribers.has(handle) && !specs.some((f) => f.kind === "headers" && f.url === url))
                 s.subscribers.delete(handle);
             if (!s.subscribers.size && !this.listeners.has(url)) {
-                void s.stream.stop();
+                void s.stream?.stop();
                 this.sse.delete(url);
             }
         }
@@ -354,6 +354,11 @@ export class Feeds {
     /** The one connection to `url`, opened if it is not. */
     connect(url) {
         let s = this.sse.get(url);
+        if (!s && !/^https?:/i.test(url)) {
+            // #156: a source the host feeds itself (the Teranode tracker, `inject`): subscribers, no connection.
+            s = { subscribers: new Map() };
+            this.sse.set(url, s);
+        }
         if (!s) {
             const subscribers = new Map();
             const stream = new SseStream(url, (ev) => this.dispatch(url, subscribers, ev.data), {
@@ -370,7 +375,7 @@ export class Feeds {
     /** Close every connection (no reconnect); resolves once their loops have ended. */
     async stop() {
         this.stopped = true;
-        const streams = [...this.sse.values()].map((s) => s.stream.stop());
+        const streams = [...this.sse.values()].map((s) => s.stream?.stop());
         this.sse.clear();
         await Promise.all(streams);
     }
@@ -407,7 +412,7 @@ export class Feeds {
             q.running = false;
         }
     }
-    dispatch(url, subscribers, data) {
+    async dispatch(url, subscribers, data) {
         let dropped = false;
         const hs = headersOf(data, (why) => { dropped = true; this.say("router", `feed ${url}: ${why}`); });
         if (!hs.length) {
@@ -415,8 +420,28 @@ export class Feeds {
                 this.say("router", `feed ${url}: an event with no header in it: ignored`);
             return;
         }
-        this.listeners.get(url)?.(hs);
+        await this.deliver(url, subscribers, hs);
+    }
+    /**
+     * #156: headers the host brings itself (the Teranode tracker) as if `url`'s stream had: to its
+     * listener (the image chain, the host chain), then to its subscribers in runs of BACKFILL_RUN.
+     * `at`: the height of the first (a run that may replace from there).
+     */
+    async inject(url, raws, at) {
+        if (this.stopped || !raws.length)
+            return;
+        await this.deliver(url, this.connect(url).subscribers, raws, at);
+    }
+    /** The listener first (awaited: the host chain holds the run before an instance is told), then every subscriber. */
+    async deliver(url, subscribers, hs, at) {
+        try {
+            await this.listeners.get(url)?.(hs, at);
+        }
+        catch (e) {
+            this.say("router", `feed ${url}: ${hs.length} header${hs.length === 1 ? "" : "s"} not taken: ${e.message}`);
+        }
         for (const [handle, box] of subscribers)
-            this.push(handle, box, hs);
+            for (let i = 0; i < hs.length; i += BACKFILL_RUN)
+                this.push(handle, box, hs.slice(i, i + BACKFILL_RUN));
     }
 }

package/dist/host/image-chain.d.ts

@@ -1,3 +1,4 @@
+import type { CID } from "multiformats/cid";
 import type { Store } from "../runtime/store.ts";
 import { type BootSource } from "./boot.ts";
 import type { HostDb } from "./instances.ts";
@@ -33,6 +34,10 @@ export declare class ImageChain {
     private stat?;
     /** #142, #152: the overlay images' static parts (images/host, a directory with no `bin/`), each merged over the default image once. */
     private merged;
+    /** Boots reading the image now (`hold`): while any, a write's drops wait in `pending`. */
+    private holds;
+    /** The objects writes replaced while a boot read the image: dropped once none does. */
+    private pending;
     /** Settles once the first sync (start) is done: what a creation waits for. */
     ready: Promise<void>;
     constructor(o: ImageChainOptions);
@@ -47,6 +52,24 @@ export declare class ImageChain {
         height: number;
         hash: string;
     } | undefined;
+    /**
+     * The height of a header held within `depth` of the tip (default two blocks' worth), by its hash
+     * (display hex); undefined when none there is it. An index over that window, rebuilt when the tip moves.
+     */
+    find(hash: string, depth?: number): number | undefined;
+    private window?;
+    /**
+     * The chain part as objects (#156: what an empty host chain imports): the `chain` tree's CID and
+     * every object under it (the tree, `headers` and its blocks, `tip`), as host.db holds them.
+     */
+    chainPart(): {
+        chain: CID;
+        objects: Array<[CID, Uint8Array]>;
+    } | undefined;
+    /** The header held at a height (raw, a copy), or undefined. */
+    headerAt(height: number): Uint8Array | undefined;
+    /** The headers held from `from` to the tip, `run` at a time (copies; the chain read as it stands at each run). */
+    runs(from: number, run: number): Generator<Uint8Array[]>;
     /** The header at a height (raw), from its block. */
     private at;
     /** One at a time: every change to the chain part goes through here. */
@@ -60,6 +83,13 @@ export declare class ImageChain {
      */
     put(height: number, raws: Uint8Array[]): Promise<boolean>;
     private write;
+    /**
+     * A boot reads the image (its root, then every object under it) from `source()` on: hold it from
+     * before `source()` until the walk is done. Until the last hold is released, a write keeps the
+     * objects it replaces (their deletes wait); the release returned (once) applies them when no
+     * other boot holds.
+     */
+    hold(): () => void;
     /** The static part: the image directory, scanned once (boot.ts imageDir: the apps it names beside it too). */
     private static;
     /**

package/dist/host/image-chain.js

@@ -19,7 +19,10 @@
 // two trees above them and the root; every full block stays as it is. The
 // chain part's objects live in host.db (`image_blocks`: only the current ones;
 // a replaced object is deleted with the write that replaces it), the current
-// root and `chain` tree in `host_settings` (`image`, `image_chain`).
+// root and `chain` tree in `host_settings` (`image`, `image_chain`). While a
+// boot reads the image (`hold()`, Router.createInstance), a write puts its new
+// objects and settings but keeps the replaced ones: their deletes wait for the
+// next write with no boot in flight, or the last boot's release.
 //
 // Where the headers come from: the host's headers feed (SKEIN_HEADERS_URL,
 // feeds.ts), each one appended as it arrives; and its history, from the same
@@ -95,6 +98,10 @@ export class ImageChain {
     stat;
     /** #142, #152: the overlay images' static parts (images/host, a directory with no `bin/`), each merged over the default image once. */
     merged = new Map();
+    /** Boots reading the image now (`hold`): while any, a write's drops wait in `pending`. */
+    holds = 0;
+    /** The objects writes replaced while a boot read the image: dropped once none does. */
+    pending = new Set();
     /** Settles once the first sync (start) is done: what a creation waits for. */
     ready = Promise.resolve();
     constructor(o) {
@@ -132,6 +139,54 @@ export class ImageChain {
         const h = this.height();
         return h < 0 ? undefined : { height: h, hash: display(sha256d(this.last.subarray(this.last.length - SIZE))) };
     }
+    /**
+     * The height of a header held within `depth` of the tip (default two blocks' worth), by its hash
+     * (display hex); undefined when none there is it. An index over that window, rebuilt when the tip moves.
+     */
+    find(hash, depth = 2 * PER_BLOCK) {
+        const t = this.tip();
+        if (!t)
+            return undefined;
+        if (this.window?.tip !== t.hash || this.window.depth !== depth) {
+            const map = new Map();
+            for (let h = t.height; h >= Math.max(0, t.height - depth); h--)
+                map.set(display(sha256d(this.at(h))), h);
+            this.window = { tip: t.hash, depth, map };
+        }
+        return this.window.map.get(hash);
+    }
+    window;
+    /**
+     * The chain part as objects (#156: what an empty host chain imports): the `chain` tree's CID and
+     * every object under it (the tree, `headers` and its blocks, `tip`), as host.db holds them.
+     */
+    chainPart() {
+        const c = this.o.db.setting("image_chain");
+        if (!c)
+            return undefined;
+        const chain = Cid.parse(c);
+        const objects = [[chain, this.object(chain)]];
+        for (const e of parseTree(this.object(chain))) {
+            objects.push([e.cid, this.object(e.cid)]);
+            if (e.name === "headers")
+                for (const b of parseTree(this.object(e.cid)))
+                    objects.push([b.cid, this.object(b.cid)]);
+        }
+        return { chain, objects };
+    }
+    /** The header held at a height (raw, a copy), or undefined. */
+    headerAt(height) {
+        return height >= 0 && height <= this.height() ? new Uint8Array(this.at(height)) : undefined;
+    }
+    /** The headers held from `from` to the tip, `run` at a time (copies; the chain read as it stands at each run). */
+    *runs(from, run) {
+        for (let h = Math.max(0, from); h <= this.height(); h += run) {
+            const out = [];
+            for (let i = h; i < h + run && i <= this.height(); i++)
+                out.push(new Uint8Array(this.at(i)));
+            yield out;
+        }
+    }
     /** The header at a height (raw), from its block. */
     at(height) {
         const b = Math.floor(height / PER_BLOCK);
@@ -204,13 +259,40 @@ export class ImageChain {
         const oldRoot = this.o.db.setting("image");
         if (oldRoot)
             drops.add(oldRoot);
+        for (const d of this.pending)
+            drops.add(d);
         for (const k of puts.keys())
             drops.delete(k);
-        this.o.db.writeImage(puts, drops, { image: root.cid.toString(), image_chain: chain.cid.toString() });
+        // A boot reading the image (hold): the replaced objects stay until it is done.
+        const now = this.holds === 0 ? drops : new Set();
+        this.pending = this.holds === 0 ? new Set() : drops;
+        this.o.db.writeImage(puts, now, { image: root.cid.toString(), image_chain: chain.cid.toString() });
         this.blocks = blocks;
         this.last = Buffer.from(last);
         return true;
     }
+    /**
+     * A boot reads the image (its root, then every object under it) from `source()` on: hold it from
+     * before `source()` until the walk is done. Until the last hold is released, a write keeps the
+     * objects it replaces (their deletes wait); the release returned (once) applies them when no
+     * other boot holds.
+     */
+    hold() {
+        this.holds++;
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            if (--this.holds === 0 && this.pending.size)
+                void this.serial(() => {
+                    if (this.holds !== 0 || !this.pending.size)
+                        return;
+                    this.o.db.writeImage(new Map(), this.pending, {});
+                    this.pending = new Set();
+                }).catch((e) => this.say(`the image's replaced objects not dropped: ${e.message}`));
+        };
+    }
     /** The static part: the image directory, scanned once (boot.ts imageDir: the apps it names beside it too). */
     static() {
         this.stat ??= (async () => {