@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/sync.js

@@ -0,0 +1,467 @@
+// Overlay sync (shruggr/skein#150; the settled design, David 2026-10-30,
+// shruggr/skein-overlay 0.20.0): the host half of keeping an overlay topic's
+// admitted set equal across peers. The overlay engine keeps, per topic,
+// BRC-136's anchors and answers the sync protocol's frames; its beacon on
+// `<topic>-live` carries `{tipHeight, tipAnchor, tailDigest}`. No timer, no
+// retry on a clock, no backoff anywhere here ("a non-starter").
+//
+//   announce, then  a peer's `admit {txid, topics}` on `<topic>` (router.ts
+//   fetch           p2pInbound takes it, never delivers it to the instance):
+//                   unless the instance holds the txid (the engine's `holds`
+//                   read, by kernel call) or a fetch of it is under way, the
+//                   host asks that peer `{kind: "tx", topic, txid}` and hands
+//                   the BEEF to the overlay's receive row
+//                   /skein/overlay/beef/1.0.0 as from that peer. Per (handle,
+//                   txid) it keeps the SET of peers whose admit named it:
+//                   fetch from one; on a failure (no answer, no `beef`, the
+//                   delivery not taken) the next; the set exhausted, it stops
+//                   and waits for a new admit to add a peer (then one more
+//                   try, from that peer). A delivery taken (accepted, or the
+//                   transaction now held) drops the entry. Nothing logged in
+//                   the instance but the delivered BEEF.
+//   the beat        a beat newly kept from another peer on `<topic>-live`
+//                   starts a reconcile from it — at most one per (handle,
+//                   topic, peer) at a time, and a new one only when that
+//                   peer's LATEST beat body differs from the one that started
+//                   (or, at its end, was the latest for) the last one.
+//   mined history   the reconcile's first half: when its tip anchor is not
+//                   ours, the locator on the direct stream
+//                   /skein/overlay/sync/1.0.0 (our anchors at tip, tip-1,
+//                   tip-2, tip-4 … genesis; the peer answers the highest height
+//                   where it agrees, its genesis and its tip), then the
+//                   peer's admitted lists above the agreed height, by ranges
+//                   of `rangeHeights` spread across the peers whose last beat
+//                   has the same tip anchor; each block checked against our
+//                   headers (its hash, the BUMP's root for every txid) before
+//                   any transaction is fetched (a height we hold no header for
+//                   yet ends the range: the next changed beat resumes it); each
+//                   txid we lack fetched from the peer that listed it into the
+//                   receive row, block by block in height order. A peer whose
+//                   list fails the check is dropped for the rest of the host's
+//                   run.
+//   the tail        the reconcile's second half: when the mined side is equal
+//                   (its tip anchor is ours at its height, or neither has one)
+//                   and its `tailDigest` is not ours (our own beacon's body),
+//                   `{kind: "tail", topic}` to that peer, and each txid we do
+//                   not hold fetched as an announced one (the per-txid set,
+//                   that peer).
+//   a start         `reconnect`: the peers a topic's beats came from (host.db,
+//                   router.ts) asked at once — the locator and the tail —
+//                   without waiting for a beat.
+//   answering       not the host's (#154): the engine answers the stream
+//                   through the front door, on the libp2p row an app declares.
+//   our own reads   the locator, "what we lack" and "do we hold it" read our
+//                   own overlay's state by a kernel call of its engine (fn
+//                   `anchors`, `admitted`, `holds`; router.ts `overlayRead`).
+//
+// The wire, one dag-cbor frame each way:
+//
+//   {kind: "locator", topic, locator: [{height, anchor: bytes(32)}]}
+//       → {kind: "locator", topic, genesisHeight?, agreedHeight?, tipHeight?}
+//   {kind: "admitted", topic, fromHeight, toHeight, limit}
+//       → {kind: "admitted", topic, blocks: [{height, blockHash, txids, bump}], nextHeight}   (hex, as /admitted)
+//   {kind: "tx", topic, txid}
+//       → {kind: "tx", txid, beef?: bytes}                                                   (absent: not held)
+//   {kind: "tail", topic}
+//       → {kind: "tail", topic, txids: [hex]}                        the admitted, not mined, in admission order
+//   anything else → {kind: "error", message}
+import * as dagCbor from "@ipld/dag-cbor";
+import { MerklePath } from "@bsv/sdk";
+import { peerIdFromMultihash } from "@libp2p/peer-id";
+import * as Digest from "multiformats/hashes/digest";
+import { RECEIVE_PROTOCOL } from "./p2p.js";
+export const SYNC_PROTOCOL = "/skein/overlay/sync/1.0.0";
+/** The overlay's receive row (skein-overlay etc/app.json): the host's own entry, one Atomic BEEF per frame; never served to peers. */
+export const BEEF_PROTOCOL = RECEIVE_PROTOCOL;
+const LIVE = "-live";
+const hex = (b) => Buffer.from(b).toString("hex");
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const HEX64 = /^[0-9a-f]{64}$/;
+/** A peer ID's string from its multihash bytes. */
+export const peerOf = (mh) => peerIdFromMultihash(Digest.decode(mh)).toString();
+/**
+ * An `admit` announcement on `<topic>` (skein-overlay gossip.zig: dag-cbor `{kind: "admit", txid,
+ * topics: {<topic>: {outputsToAdmit, coinsToRetain}}}`) → its txid, or undefined when the body is
+ * not one naming `topic`.
+ */
+export function admitOf(topic, body) {
+    let v;
+    try {
+        v = dagCbor.decode(body);
+    }
+    catch {
+        return undefined;
+    }
+    if (!v || typeof v !== "object")
+        return undefined;
+    const m = v;
+    if (m.kind !== "admit" || typeof m.txid !== "string" || !HEX64.test(m.txid))
+        return undefined;
+    if (!m.topics || typeof m.topics !== "object" || !(topic in m.topics))
+        return undefined;
+    return m.txid;
+}
+export class OverlaySync {
+    o;
+    /** `${handle} ${txid}` → the announced transaction, while it is not taken. */
+    announced = new Map();
+    /** Reconciles running: `${handle} ${topic} ${peer}`. */
+    running = new Set();
+    /** The beat body (hex) that started, or ended, the last reconcile per `${handle} ${topic} ${peer}`. */
+    seen = new Map();
+    /** Peers caught serving a list that does not check: per handle. */
+    dropped = new Map();
+    inflight = new Set();
+    stopped = false;
+    constructor(o) { this.o = o; }
+    say(handle, line) { this.o.log?.(handle, `sync: ${line}`); }
+    track(p) {
+        const q = p.catch(() => { });
+        this.inflight.add(q);
+        void q.finally(() => this.inflight.delete(q));
+    }
+    /** Whether anything is under way (a reconcile, a fetch). */
+    busy() { return this.inflight.size > 0; }
+    async idle() { while (this.inflight.size)
+        await Promise.all([...this.inflight]); }
+    stop() { this.stopped = true; this.announced.clear(); }
+    /** The announced transactions not taken yet, per handle (tests). */
+    pending(handle) {
+        return [...this.announced].filter(([k]) => k.startsWith(`${handle} `)).map(([k, e]) => ({ txid: k.slice(handle.length + 1), peers: [...e.peers], fetching: e.fetching }));
+    }
+    isDropped(handle, peer) { return this.dropped.get(handle)?.has(peer) ?? false; }
+    // ---------------------------------------------------------------- announce, then fetch
+    /**
+     * A peer's `admit` for `txid` on `topic` (its announcement), at `handle` whose overlay `app` runs
+     * the topic: fetched from that peer unless the instance holds it or a fetch of it is under way;
+     * the peer joins the transaction's set either way.
+     */
+    admit(handle, app, topic, txid, peer) {
+        const p = this.announce(handle, app, topic, txid, peer);
+        if (p)
+            this.track(p);
+    }
+    /** `admit`'s work: the fetch it started, if any (the tail awaits it). */
+    announce(handle, app, topic, txid, peer) {
+        if (this.stopped || peer === this.o.self(handle))
+            return undefined;
+        const k = `${handle} ${txid}`;
+        const e = this.announced.get(k);
+        if (e) {
+            if (!e.peers.includes(peer))
+                e.peers.push(peer);
+            return e.fetching ? undefined : this.pursue(handle, k, e);
+        }
+        const fresh = { app, topic, peers: [peer], tried: new Set(), fetching: true };
+        this.announced.set(k, fresh);
+        return (async () => {
+            if (await this.holds(handle, app, txid)) {
+                this.announced.delete(k);
+                fresh.fetching = false;
+                return;
+            }
+            await this.pursue(handle, k, fresh);
+        })();
+    }
+    /** Whether `handle`'s overlay state reaches `txid` (its engine's `holds`). */
+    async holds(handle, app, txid) {
+        try {
+            const h = await this.o.local(handle, app, "holds", { txid });
+            return typeof h?.txid === "string";
+        }
+        catch (e) {
+            this.say(handle, `holds ${txid}: ${e.message}`);
+            return false;
+        }
+    }
+    /** Fetch an announced transaction from its peers, one after another, until one delivery is taken or none is left. */
+    async pursue(handle, k, e) {
+        e.fetching = true;
+        try {
+            for (;;) {
+                if (this.stopped || this.announced.get(k) !== e)
+                    return;
+                const peer = e.peers.find((p) => !e.tried.has(p));
+                if (!peer)
+                    return; // exhausted: a new admit adds a peer
+                e.tried.add(peer);
+                const txid = k.slice(handle.length + 1);
+                const taken = await this.fetchInto(handle, peer, e.topic, txid).catch((x) => { this.say(handle, `${e.topic}: ${txid} from ${peer}: ${x.message}`); return false; });
+                if (taken || await this.holds(handle, e.app, txid)) {
+                    this.announced.delete(k);
+                    return;
+                }
+            }
+        }
+        finally {
+            e.fetching = false;
+        }
+    }
+    // ---------------------------------------------------------------- the beat and the reconcile
+    /** A beat newly kept on `liveTopic` from another peer: a reconcile from it when its body changed since the last. */
+    beat(handle, liveTopic, b) {
+        if (this.stopped || !liveTopic.endsWith(LIVE))
+            return;
+        const app = this.o.overlayOf(handle, liveTopic);
+        if (!app || this.isDropped(handle, b.from) || b.from === this.o.self(handle))
+            return;
+        this.start(handle, app, liveTopic.slice(0, -LIVE.length), b.from, b.body);
+    }
+    /**
+     * A start (router.ts, the persisted peers): each peer that beat on the topic before asked at once,
+     * the locator and the tail, without a beat. One reconcile per peer, as for a beat.
+     */
+    reconnect(handle, app, topic, peer) {
+        if (this.stopped || this.isDropped(handle, peer) || peer === this.o.self(handle))
+            return;
+        this.start(handle, app, topic, peer, undefined);
+    }
+    start(handle, app, topic, peer, body) {
+        const k = `${handle} ${topic} ${peer}`;
+        if (this.running.has(k))
+            return; // its end looks at the peer's latest beat
+        if (body && this.seen.get(k) === hex(body))
+            return;
+        if (body)
+            this.seen.set(k, hex(body));
+        this.running.add(k);
+        this.track(this.reconcile(handle, app, topic, peer, body)
+            .catch((e) => this.say(handle, `${topic} from ${peer}: ${e.message}`))
+            .finally(() => {
+            this.running.delete(k);
+            // A beat that came while it ran: the latest, if it is not the one already reconciled from.
+            const latest = this.o.beats(handle, `${topic}${LIVE}`).find((x) => x.from === peer);
+            if (latest && !this.stopped && this.seen.get(k) !== hex(latest.body))
+                this.start(handle, app, topic, peer, latest.body);
+        }));
+    }
+    async anchors(handle, app, topic, heights) {
+        return await this.o.local(handle, app, "anchors", { topic, ...(heights ? { heights: heights.join(",") } : {}) });
+    }
+    async ask(handle, peer, req) {
+        const a = dagCbor.decode(await this.o.request(handle, peer, dagCbor.encode(req)));
+        if (a.kind === "error")
+            throw new Error(`${peer}: ${String(a.message)}`);
+        if (a.kind !== req.kind)
+            throw new Error(`${peer}: answered ${String(a.kind)} to ${String(req.kind)}`);
+        return a;
+    }
+    /** The beat body's sync fields, or undefined when it does not decode. */
+    static fields(body) {
+        if (!body)
+            return undefined;
+        try {
+            return dagCbor.decode(body);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * One reconcile with `peer` on `topic`: its mined history (the locator and the pulls) when its
+     * tip anchor is not ours, then its unmined tail when the mined side is equal and its tail digest
+     * is not ours. No beat (a start): both asked.
+     */
+    async reconcile(handle, app, topic, peer, body) {
+        const theirs = OverlaySync.fields(body);
+        if (body && !theirs)
+            return;
+        const hasTip = (b) => typeof b?.tipHeight === "number" && b.tipAnchor instanceof Uint8Array;
+        if (!theirs) {
+            await this.catchUp(handle, app, topic, peer);
+        }
+        else if (hasTip(theirs)) {
+            const at = await this.anchors(handle, app, topic, [theirs.tipHeight]);
+            if (!at.anchors.some((x) => x.height === theirs.tipHeight && x.anchor === hex(theirs.tipAnchor))) {
+                const done = await this.catchUp(handle, app, topic, peer, { height: theirs.tipHeight, anchor: hex(theirs.tipAnchor) });
+                if (!done)
+                    return; // a range left for a later beat: the mined side is not equal yet
+            }
+        }
+        if (this.stopped || this.isDropped(handle, peer))
+            return;
+        if (theirs) {
+            // The mined side equal: its tip anchor ours at its height (after any pull), or neither has one.
+            if (hasTip(theirs)) {
+                const at = await this.anchors(handle, app, topic, [theirs.tipHeight]);
+                if (!at.anchors.some((x) => x.height === theirs.tipHeight && x.anchor === hex(theirs.tipAnchor)))
+                    return;
+            }
+            else if (typeof (await this.anchors(handle, app, topic)).tipHeight === "number")
+                return;
+            const ours = OverlaySync.fields(this.o.ownBeat(handle, `${topic}${LIVE}`));
+            const a = theirs.tailDigest instanceof Uint8Array ? hex(theirs.tailDigest) : "";
+            const b = ours?.tailDigest instanceof Uint8Array ? hex(ours.tailDigest) : "";
+            if (a === b)
+                return;
+        }
+        await this.tail(handle, app, topic, peer);
+    }
+    /** The peer's unmined tail: each txid we do not hold fetched as an announced one from that peer. */
+    async tail(handle, app, topic, peer) {
+        const t = await this.ask(handle, peer, { kind: "tail", topic });
+        const txids = (Array.isArray(t.txids) ? t.txids : []).filter((x) => typeof x === "string" && HEX64.test(x));
+        let asked = 0;
+        // One at a time, in its order (admission order: parents first): each through the per-txid set.
+        for (const txid of txids) {
+            if (this.stopped)
+                return;
+            const known = this.announced.has(`${handle} ${txid}`);
+            if (!known && await this.holds(handle, app, txid))
+                continue;
+            asked++;
+            await this.announce(handle, app, topic, txid, peer);
+        }
+        if (asked)
+            this.say(handle, `${topic}: ${peer}'s tail: ${txids.length} unmined, ${asked} asked`);
+    }
+    /**
+     * Catch `topic` up from `peer`: the locator, then the pulls. `tip`: the tip its beat named (the
+     * ranges are spread across the peers whose last beat names the same); none (a start): that peer
+     * alone. → whether every range was taken (a height we hold no header for, or a list that fails,
+     * leaves it unfinished).
+     */
+    async catchUp(handle, app, topic, peer, tip) {
+        const mine = await this.anchors(handle, app, topic);
+        const answer = await this.ask(handle, peer, {
+            kind: "locator", topic,
+            locator: mine.anchors.map((x) => ({ height: x.height, anchor: Uint8Array.from(Buffer.from(x.anchor, "hex")) })),
+        });
+        if (typeof answer.tipHeight !== "number" || typeof answer.genesisHeight !== "number")
+            return true;
+        const from = typeof answer.agreedHeight === "number" ? answer.agreedHeight + 1 : answer.genesisHeight;
+        const to = answer.tipHeight;
+        if (from > to)
+            return true;
+        // The peers whose last beat has the same tip anchor: the ranges are spread across them.
+        const agreeing = [peer, ...(tip ? this.o.beats(handle, `${topic}${LIVE}`).filter((b) => {
+                if (b.from === peer || b.from === this.o.self(handle) || this.isDropped(handle, b.from))
+                    return false;
+                const t = OverlaySync.fields(b.body);
+                return t?.tipHeight === tip.height && t.tipAnchor instanceof Uint8Array && hex(t.tipAnchor) === tip.anchor;
+            }).map((b) => b.from) : [])];
+        this.say(handle, `${topic}: agreed with ${peer} through ${from - 1}; pulling ${from}..${to} from ${agreeing.length} peer(s)`);
+        const span = this.o.rangeHeights ?? 1_000;
+        const ranges = [];
+        for (let h = from, i = 0; h <= to; h += span, i++)
+            ranges.push({ from: h, to: Math.min(to, h + span - 1), peer: agreeing[i % agreeing.length] });
+        const lists = await Promise.all(ranges.map(async (r) => ({ r, blocks: await this.pullRange(handle, topic, r.peer, r.from, r.to).catch((e) => { this.say(handle, `${topic}: ${r.from}..${r.to} from ${r.peer}: ${e.message}`); return undefined; }) })));
+        let whole = true;
+        for (const { r, blocks } of lists) {
+            if (!blocks) {
+                whole = false;
+                continue;
+            }
+            const ok = await this.checked(handle, topic, r.peer, blocks);
+            if (!ok) {
+                whole = false;
+                continue;
+            }
+            const ours = new Set();
+            for (let h = r.from; h !== null && h <= r.to;) {
+                const page = await this.o.local(handle, app, "admitted", { topic, fromHeight: String(h), toHeight: String(r.to) });
+                for (const b of page.blocks)
+                    for (const t of b.txids)
+                        ours.add(t);
+                h = page.nextHeight;
+            }
+            for (const b of blocks) {
+                const lacking = b.txids.filter((t) => !ours.has(t));
+                for (const txid of lacking)
+                    await this.fetchInto(handle, r.peer, topic, txid);
+                if (lacking.length)
+                    await this.landed(handle, app, topic, b.height, lacking);
+            }
+        }
+        return whole;
+    }
+    /** The peer's admitted lists for `from..to`, every page. */
+    async pullRange(handle, topic, peer, from, to) {
+        const out = [];
+        for (let h = from; h !== null && h <= to;) {
+            const a = await this.ask(handle, peer, { kind: "admitted", topic, fromHeight: h, toHeight: to, limit: 1_000 });
+            const blocks = (a.blocks ?? []);
+            out.push(...blocks);
+            const next = a.nextHeight;
+            if (typeof next === "number" && next <= h)
+                throw new Error("nextHeight does not advance");
+            h = typeof next === "number" ? next : null;
+        }
+        return out;
+    }
+    /**
+     * Each block against our headers before any transaction is fetched: its hash ours at its height,
+     * the BUMP at that height and every listed txid in it with our merkle root. A failure drops the
+     * peer; a height we hold no header for yet stops the range (the next changed beat resumes it).
+     * → whether all checked.
+     */
+    async checked(handle, topic, peer, blocks) {
+        for (const b of blocks) {
+            if (!(await this.o.header(handle, b.height))) {
+                this.say(handle, `${topic}: no header of ours at ${b.height} yet: ${peer}'s range left for its next changed beat`);
+                return false;
+            }
+            const why = await this.problem(handle, b);
+            if (!why)
+                continue;
+            this.say(handle, `${topic}: ${peer}'s list at ${b.height}: ${why}; peer dropped`);
+            let d = this.dropped.get(handle);
+            if (!d)
+                this.dropped.set(handle, d = new Set());
+            d.add(peer);
+            return false;
+        }
+        return true;
+    }
+    async problem(handle, b) {
+        const h = await this.o.header(handle, b.height);
+        if (!h)
+            return "no header of ours at that height";
+        if (h.hash !== b.blockHash)
+            return `block ${b.blockHash} is not ours (${h.hash})`;
+        if (!b.txids.length)
+            return "no txids";
+        let mp;
+        try {
+            mp = MerklePath.fromHex(b.bump);
+        }
+        catch (e) {
+            return `a BUMP that does not parse: ${e.message}`;
+        }
+        if (mp.blockHeight !== b.height)
+            return `a BUMP at ${mp.blockHeight}`;
+        for (const t of b.txids) {
+            let root;
+            try {
+                root = mp.computeRoot(t);
+            }
+            catch {
+                return `${t} is not in its BUMP`;
+            }
+            if (root !== h.root)
+                return `${t}'s root is not our header's`;
+        }
+        return undefined;
+    }
+    /** One transaction asked of `peer` and handed to the receive row as from it. → whether it was accepted. */
+    async fetchInto(handle, peer, topic, txid) {
+        const a = await this.ask(handle, peer, { kind: "tx", topic, txid });
+        if (!(a.beef instanceof Uint8Array))
+            return false;
+        const r = await this.o.deliver(handle, peer, a.beef);
+        if (r.verdict !== "accept")
+            this.say(handle, `${topic}: ${txid} from ${peer}: ${r.verdict}${r.reason ? ` (${r.reason})` : ""}`);
+        return r.verdict === "accept";
+    }
+    /** Until the topic lists `txids` at `height` (admitted: each delivery is judged on its own thread), or 10 s. */
+    async landed(handle, app, topic, height, txids) {
+        const end = Date.now() + 10_000;
+        while (Date.now() < end && !this.stopped) {
+            const page = await this.o.local(handle, app, "admitted", { topic, fromHeight: String(height), toHeight: String(height) });
+            const have = new Set(page.blocks.flatMap((b) => b.txids));
+            if (txids.every((t) => have.has(t)))
+                return;
+            await sleep(100);
+        }
+    }
+}

package/dist/host/testbeef.d.ts

@@ -0,0 +1,21 @@
+import type { CID } from "multiformats/cid";
+export declare const HEIGHT_170 = 170;
+export declare const HEADER_170: Uint8Array<ArrayBuffer>;
+export declare const TX_170: Uint8Array<ArrayBuffer>;
+/** The transaction's `bitcoin-tx` block CID (its txid). */
+export declare const TX_170_CID: CID;
+/**
+ * BEEF V1 of TX_170 with its BUMP (height 170, two leaves: the coinbase, the transaction). `bad`: one
+ * byte of the coinbase's hash flipped, so the BUMP's merkle root is not the header's.
+ */
+export declare function beef170(o?: {
+    bad?: boolean;
+}): Uint8Array;
+/** The chain state holding block 170's header: its blocks (the header, the MST node, the record) and the record's CID. */
+export declare function chainState170(): {
+    blocks: Array<{
+        cid: CID;
+        bytes: Uint8Array;
+    }>;
+    state: CID;
+};

package/dist/host/testbeef.js

@@ -0,0 +1,37 @@
+// A BEEF whose BUMP checks, and the chain state it checks against (#121, #164): block 170's header,
+// its spend (the first person-to-person transaction) and a BUMP proving it beside the coinbase —
+// kernel-zig/src/door_test.zig's fixture, for the TS tests and equiv drivers. `chainState170` is the
+// chain app's record shape ({kind: "chain-state", maps: {headers: <MST root>}}, the MST height (u32
+// big-endian) → the header), one header, as blocks to put (root's `objects`, or the store directly)
+// and the record to point the head `chain/state` at.
+import { createHash } from "node:crypto";
+import { BITCOIN_BLOCK, BITCOIN_TX, hashCid } from "../runtime/bitcoin.js";
+import { encode } from "../runtime/cid.js";
+const unhex = (s) => Uint8Array.from(Buffer.from(s, "hex"));
+const sha256d = (b) => Uint8Array.from(createHash("sha256").update(createHash("sha256").update(b).digest()).digest());
+export const HEIGHT_170 = 170;
+export const HEADER_170 = unhex("0100000055bd840a78798ad0da853f68974f3d183e2bd1db6a842c1feecf222a00000000ff104ccb05421ab93e63f8c3ce5c2c2e9dbb37de2764b3a3175c8166562cac7d51b96a49ffff001d283e9e70");
+export const TX_170 = unhex("0100000001c997a5e56e104102fa209c6a852dd90660a20b2d9c352423edce25857fcd3704000000004847304402204e45e16932b8af514961a1d3a1a25fdf3f4f7732e9d624c6c61548ab5fb8cd410220181522ec8eca07de4860a4acdd12909d831cc56cbbac4622082221a8768d1d0901ffffffff0200ca9a3b00000000434104ae1a62fe09c5f51b13905f07f06b99a2f7159b2225f374cd378d71302fa28414e7aab37397f554a7df5f142c21c1b7303b8a0626f1baded5c72a704f7e6cd84cac00286bee0000000043410411db93e1dcdb8a016b49840f8c53bc1eb68a382e97b1482ecad7b148a6909a5cb2e0eaddfb84ccf9744464f82e160bfa9b8b64f9d4c03f999b8643f656b412a3ac00000000");
+const COINBASE_170 = unhex("82501c1178fa0b222c1f3d474ec726b832013f0a532b44bb620cce8624a5feb1");
+/** The transaction's `bitcoin-tx` block CID (its txid). */
+export const TX_170_CID = hashCid(BITCOIN_TX, sha256d(TX_170));
+/**
+ * BEEF V1 of TX_170 with its BUMP (height 170, two leaves: the coinbase, the transaction). `bad`: one
+ * byte of the coinbase's hash flipped, so the BUMP's merkle root is not the header's.
+ */
+export function beef170(o = {}) {
+    const cb = Uint8Array.from(COINBASE_170);
+    if (o.bad)
+        cb[0] ^= 0xff;
+    const bump = [0xaa, 1, 2, 0, 0, ...cb, 1, 2, ...sha256d(TX_170)];
+    return Uint8Array.from([1, 0, 0xbe, 0xef, 1, ...bump, 1, ...TX_170, 1, 0]);
+}
+/** The chain state holding block 170's header: its blocks (the header, the MST node, the record) and the record's CID. */
+export function chainState170() {
+    const header = { cid: hashCid(BITCOIN_BLOCK, sha256d(HEADER_170)), bytes: HEADER_170 };
+    const key = new Uint8Array(4);
+    new DataView(key.buffer).setUint32(0, HEIGHT_170);
+    const node = encode([null, [[key, header.cid, null]]]);
+    const state = encode({ kind: "chain-state", network: "main", maps: { headers: node.cid } });
+    return { blocks: [header, { cid: node.cid, bytes: node.bytes }, { cid: state.cid, bytes: state.bytes }], state: state.cid };
+}

package/dist/host/testhost.d.ts

@@ -0,0 +1,149 @@
+import { PrivateKey } from "@bsv/sdk";
+import type { CID } from "multiformats/cid";
+import type { Store } from "../runtime/store.ts";
+import { type PinnedApp } from "../testapps.ts";
+import { HostDb } from "./instances.ts";
+import { Router } from "./router.ts";
+export declare const until: <T>(what: string, f: () => Promise<T | undefined> | T | undefined, ms?: number) => Promise<T>;
+/**
+ * The messages an instance took in, in log order (#68): a mail entry of its
+ * own (a host that admits one directly), or a message a request's thread
+ * routed — the `admit` of the front door's answer on that thread's updates.
+ */
+export declare function messagesIn(store: Store): Promise<Array<Record<string, unknown>>>;
+/** A host with instances (mailbox instances among them), each instance's key its own (the signer's stand-in). */
+export declare function testHost(t: {
+    after(f: () => unknown): void;
+}, o?: {
+    idleMs?: number;
+    http?: Router["o"]["http"];
+    infer?: string;
+    ownerMessagebox?: string;
+    ownerKey?: PrivateKey;
+    genesis?: Router["o"]["genesis"];
+    now?: Router["o"]["now"];
+    arc?: Router["o"]["arc"];
+    arcRetry?: Router["o"]["arcRetry"];
+    headersFeed?: string;
+    billing?: Router["o"]["billing"];
+    lmdb?: boolean;
+    rocks?: boolean;
+    sqlite?: boolean;
+}): Promise<{
+    home: string;
+    db: HostDb;
+    router: Router;
+    base: string;
+    owner: import("@bsv/sdk").WalletInterface;
+    ownerKey: PrivateKey;
+    ownerId: string;
+    lines: string[];
+    keyOf: (h: string) => PrivateKey;
+    /**
+     * An instance's row (host.db kind `agent`: not a mailbox instance), its
+     * genesis at first hydration (the owner's mailbox must exist first to be
+     * named in it). Its identity key (hex).
+     */
+    instance(handle: string): string;
+    /** The same as `instance`, by its old name (for tests written before the rename). */
+    agent(handle: string): string;
+    /**
+     * An instance booted from an image (#89; default: the default image,
+     * images/default): no owner in its genesis, the claim row from anyone.
+     * Claim it with a message from the owner's wallet in box `claim`
+     * (src/testapps.ts sendPlan of planClaim, #127): its sender owns it.
+     */
+    image(handle: string, dir?: string): Promise<import("./boot.ts").Booted>;
+    /** A mailbox instance's row (a fixture's: its genesis at first hydration; the product path is the manager's create, Router.createInstance image `mailbox`). */
+    mailbox(handle: string, whose: string): void;
+    /**
+     * The host skein (#90, #113, #142): `host` from the host image (the
+     * default image with the onboarding app), its genesis naming the owner
+     * (the operator's key here), the instance manager and the certifier in
+     * its address book; the onboarding app's config at birth over its
+     * manifest's (default: domain `localhost`, origin this router's). Its own
+     * origin's BRC-169 requests are then the app's.
+     */
+    hostSkein(config?: Record<string, unknown>): Promise<{
+        handle: string;
+        identity: string;
+        url: string;
+    }>;
+    origin: (handle: string) => string;
+    storeSize(handle: string): number;
+    /**
+     * Install apps into an instance as the owner (#83: a genesis has no shell,
+     * no `run`, no `chat`): by default the shell app and the chat app, through
+     * the owner's messages (src/testapps.ts installApps, #124). Hydrates the instance first.
+     */
+    install(handle: string, apps?: PinnedApp[]): Promise<void>;
+    entries(handle: string): Promise<number>;
+}>;
+/**
+ * A small world on a test host (the explorer's and the store reader's tests):
+ * the owner's mailbox, the inference peer's, and instance `alpha` with the shell
+ * app and the chat app installed (#83); `dir` imported into alpha (objects →
+ * `main`); a chat whose turn makes one bash
+ * tool call (`ls | head -3`) and answers "README and **src**." into the
+ * owner's mailbox. The peer answers from a script, over its raw transport.
+ */
+export declare function chatWorld(t: {
+    after(f: () => unknown): void;
+}, dir: string, o?: {
+    sqlite?: boolean;
+}): Promise<{
+    h: {
+        home: string;
+        db: HostDb;
+        router: Router;
+        base: string;
+        owner: import("@bsv/sdk").WalletInterface;
+        ownerKey: PrivateKey;
+        ownerId: string;
+        lines: string[];
+        keyOf: (h: string) => PrivateKey;
+        /**
+         * An instance's row (host.db kind `agent`: not a mailbox instance), its
+         * genesis at first hydration (the owner's mailbox must exist first to be
+         * named in it). Its identity key (hex).
+         */
+        instance(handle: string): string;
+        /** The same as `instance`, by its old name (for tests written before the rename). */
+        agent(handle: string): string;
+        /**
+         * An instance booted from an image (#89; default: the default image,
+         * images/default): no owner in its genesis, the claim row from anyone.
+         * Claim it with a message from the owner's wallet in box `claim`
+         * (src/testapps.ts sendPlan of planClaim, #127): its sender owns it.
+         */
+        image(handle: string, dir?: string): Promise<import("./boot.ts").Booted>;
+        /** A mailbox instance's row (a fixture's: its genesis at first hydration; the product path is the manager's create, Router.createInstance image `mailbox`). */
+        mailbox(handle: string, whose: string): void;
+        /**
+         * The host skein (#90, #113, #142): `host` from the host image (the
+         * default image with the onboarding app), its genesis naming the owner
+         * (the operator's key here), the instance manager and the certifier in
+         * its address book; the onboarding app's config at birth over its
+         * manifest's (default: domain `localhost`, origin this router's). Its own
+         * origin's BRC-169 requests are then the app's.
+         */
+        hostSkein(config?: Record<string, unknown>): Promise<{
+            handle: string;
+            identity: string;
+            url: string;
+        }>;
+        origin: (handle: string) => string;
+        storeSize(handle: string): number;
+        /**
+         * Install apps into an instance as the owner (#83: a genesis has no shell,
+         * no `run`, no `chat`): by default the shell app and the chat app, through
+         * the owner's messages (src/testapps.ts installApps, #124). Hydrates the instance first.
+         */
+        install(handle: string, apps?: PinnedApp[]): Promise<void>;
+        entries(handle: string): Promise<number>;
+    };
+    alpha: string;
+    root: CID<unknown, number, number, import("multiformats/cid").Version>;
+    chat: CID<unknown, number, number, import("multiformats/cid").Version>;
+    store: string;
+}>;