@genkaku/protocol 0.0.0-stage → 0.1.0

package/dist/credit.d.ts

@@ -0,0 +1,35 @@
+import { type GenkakuPublic } from './chain.ts';
+import { type NetEnvironment } from './netconfig.ts';
+export type WorkerStats = {
+    opened: number;
+    settled: number;
+    /** cumulative settled USDC (6 decimals) */
+    spend: bigint;
+};
+export type CreditSnapshot = {
+    score: number;
+    sessions: number;
+    spend: bigint;
+};
+/** The published formula; pure so tests and the UI can reuse it verbatim. */
+export declare function creditScoreOf(stats: Pick<WorkerStats, 'opened' | 'settled'>): number;
+/** Incremental, process-local index. The chain is the source of truth; this is
+ *  only a cache so a status page never pays for a full re-scan. */
+export declare class CreditTracker {
+    private readonly publicC;
+    private readonly env;
+    private stats;
+    private next;
+    private running;
+    private lastBlock;
+    constructor(publicC: GenkakuPublic, env: NetEnvironment);
+    /** Scan only the blocks nobody has scanned yet. Concurrent callers share one
+     *  pass; a failed pass leaves the cursor where it was so the next one retries. */
+    refresh(): Promise<void>;
+    /** null = this wallet has no history (leave the offer's self-report alone). */
+    snapshot(wallet: string): CreditSnapshot | null;
+    statsOf(wallet: string): WorkerStats | null;
+    blockNumber(): bigint;
+    private scan;
+}
+//# sourceMappingURL=credit.d.ts.map

package/dist/credit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credit.d.ts","sourceRoot":"","sources":["../src/credit.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAe/D,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,SAAS,CAAC,GAAG,MAAM,CAOpF;AAID;mEACmE;AACnE,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,IAAI,CAAQ;IACpB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAK;gBAGH,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,cAAc;IAKtC;sFACkF;IAC5E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAQ/C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAI3C,WAAW,IAAI,MAAM;YAIP,IAAI;CAwCnB"}

package/dist/credit.js

@@ -0,0 +1,112 @@
+// GENKAKU: behavioural credit (trust layer A) — derived off-chain from escrow
+// events. There is no token, no oracle and no extra transaction: anyone with a
+// Base RPC can re-derive exactly these numbers from the same logs, which is the
+// whole point of putting the formula in the open (strata-migration §36).
+//
+// A worker's score answers one question a payer asks before funding an escrow:
+// "when this peer opens a session, does it finish?" It does NOT attest to model
+// quality or honesty — that is P4.10 (deposits) and the commit-challenge.
+//
+//   opened   = SessionOpened(worker=w)      sessions funded for w
+//   settled  = SessionSettled(worker=w)     sessions that reached settlement
+//   completion = settled / opened           (in-flight sessions count as not yet)
+//   confidence = settled / (settled + 5)    (shrink small samples toward 0)
+//   score    = round(100 * completion * confidence)
+//
+// New worker = 0. 5 settled of 5 = 50. 20 of 20 = 80. 95 of 95 = 95.
+import { collectLogs, ESCROW_ABI, ESCROW_DEPLOY_BLOCK, } from "./chain.js";
+import { CONTRACTS } from "./netconfig.js";
+function escrowEvent(name) {
+    const found = ESCROW_ABI.find(entry => entry.type === 'event' && entry.name === name);
+    if (found == null || found.type !== 'event') {
+        throw new Error('[genkaku:credit] escrow ABI is missing event ' + name);
+    }
+    return found;
+}
+/** The published formula; pure so tests and the UI can reuse it verbatim. */
+export function creditScoreOf(stats) {
+    if (stats.settled <= 0) {
+        return 0;
+    }
+    const completion = stats.opened > 0 ? stats.settled / stats.opened : 0;
+    const confidence = stats.settled / (stats.settled + 5);
+    return Math.round(100 * Math.min(1, completion) * confidence);
+}
+const SCAN_CHUNK = 50000n;
+/** Incremental, process-local index. The chain is the source of truth; this is
+ *  only a cache so a status page never pays for a full re-scan. */
+export class CreditTracker {
+    publicC;
+    env;
+    stats = new Map();
+    next;
+    running = null;
+    lastBlock = 0n;
+    constructor(publicC, env) {
+        this.publicC = publicC;
+        this.env = env;
+        this.next = ESCROW_DEPLOY_BLOCK[env];
+    }
+    /** Scan only the blocks nobody has scanned yet. Concurrent callers share one
+     *  pass; a failed pass leaves the cursor where it was so the next one retries. */
+    async refresh() {
+        if (CONTRACTS[this.env].escrow === '') {
+            return;
+        }
+        if (this.running != null) {
+            return await this.running;
+        }
+        this.running = this.scan().finally(() => { this.running = null; });
+        return await this.running;
+    }
+    /** null = this wallet has no history (leave the offer's self-report alone). */
+    snapshot(wallet) {
+        const stats = this.stats.get(wallet.toLowerCase());
+        if (stats == null) {
+            return null;
+        }
+        return { score: creditScoreOf(stats), sessions: stats.settled, spend: stats.spend };
+    }
+    statsOf(wallet) {
+        return this.stats.get(wallet.toLowerCase()) ?? null;
+    }
+    blockNumber() {
+        return this.lastBlock;
+    }
+    async scan() {
+        const latest = await this.publicC.getBlockNumber();
+        if (latest < this.next) {
+            return;
+        }
+        const escrow = CONTRACTS[this.env].escrow;
+        const openedEvent = escrowEvent('SessionOpened');
+        const settledEvent = escrowEvent('SessionSettled');
+        const bump = (wallet, change) => {
+            const key = wallet.toLowerCase();
+            const row = this.stats.get(key) ?? { opened: 0, settled: 0, spend: 0n };
+            change(row);
+            this.stats.set(key, row);
+        };
+        for (let start = this.next; start <= latest; start += SCAN_CHUNK) {
+            const end = start + SCAN_CHUNK - 1n > latest ? latest : start + SCAN_CHUNK - 1n;
+            const [opens, settles] = await Promise.all([
+                collectLogs(this.publicC, escrow, openedEvent, start, end),
+                collectLogs(this.publicC, escrow, settledEvent, start, end),
+            ]);
+            for (const log of opens) {
+                const a = log.args;
+                bump(a.worker, (row) => { row.opened += 1; });
+            }
+            for (const log of settles) {
+                const a = log.args;
+                bump(a.worker, (row) => {
+                    row.settled += 1;
+                    row.spend += a.spend;
+                });
+            }
+        }
+        this.next = latest + 1n;
+        this.lastBlock = latest;
+    }
+}
+//# sourceMappingURL=credit.js.map

package/dist/dial.d.ts

@@ -0,0 +1,43 @@
+import type { Libp2p } from 'libp2p';
+import { type HelloProof } from './hello.ts';
+import { type Offer } from './offer.ts';
+import type { OpenEnvelopeV0 } from './workerSession.ts';
+export type WorkerTransport = {
+    open(env: OpenEnvelopeV0): Promise<void>;
+    onToken(cb: (delta: string) => void): void;
+    onEnd(cb: () => void): void;
+    onError(cb: (e: Error) => void): void;
+    /** sig: EIP-191 signature over the packed receipt digest (P4.4 priced
+     *  sessions; empty string for escrowless self-tests). */
+    sendReceipt(jobId: string, seq: number, amount: bigint, sig?: string, inputHash?: `0x${string}`, outputHash?: `0x${string}`): Promise<void>;
+    close(): Promise<void>;
+};
+export declare function dialWorker(node: Libp2p, addr: string): Promise<WorkerTransport>;
+/** Fetch + deserialize a worker's offer board (one dial, whole-board read). */
+/** P4.9e: ask the peer to prove it holds the EVM key of the wallet it puts on
+ *  its offers. Throws when the answer is missing, malformed, signed by another
+ *  key, or claims a different PeerId than the one we dialed. */
+export declare function helloWorker(node: Libp2p, addr: string): Promise<HelloProof>;
+export declare function fetchOffers(node: Libp2p, addr: string): Promise<Offer[]>;
+/** P4.5 seed discovery: ask a bootstrap seed which peers it currently sees.
+ *  The seed is a pure matchmaker — one frame in, one frame out, no storage. */
+export declare function fetchSeedPeers(node: Libp2p, addr: string): Promise<string[]>;
+/**
+ * P4.4 settle co-sign (one dial, one frame each way): the user, at session
+ * end, presents (jobId, escrowId, receiptHash, spend); the worker checks its
+ * held max-cumulative receipt (anti-inflation: it never signs beyond the
+ * largest receipt the client piped — P1 §8) and returns an EIP-191 signature
+ * over keccak256(abi.encodePacked(escrowId, receiptHash, spend)) — the exact
+ * digest JobEscrow.settle recovers against the session's worker address.
+ */
+export declare function requestSettleCosign(node: Libp2p, addr: string, args: {
+    jobId: string;
+    escrowId: string;
+    receiptHash: `0x${string}`;
+    spend: bigint;
+}): Promise<{
+    ok: boolean;
+    sig: `0x${string}` | null;
+    reason?: string;
+}>;
+//# sourceMappingURL=dial.d.ts.map

package/dist/dial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dial.d.ts","sourceRoot":"","sources":["../src/dial.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAEnE,OAAO,EAAY,KAAK,KAAK,EAAE,MAAM,YAAY,CAAA;AAGjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAQxD,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAA;IAC1C,KAAK,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC3B,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;IACrC;6DACyD;IACzD,WAAW,CACT,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,KAAK,MAAM,EAAE,EACzB,UAAU,CAAC,EAAE,KAAK,MAAM,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAAA;IAChB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,CAAA;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAsIrF;AAED,+EAA+E;AAC/E;;gEAEgE;AAChE,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqDjF;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAqB9E;AAuBD;+EAC+E;AAC/E,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBlF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,KAAK,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnF,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,KAAK,MAAM,EAAE,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgCtE"}

package/dist/dial.js

@@ -0,0 +1,266 @@
+// GENKAKU: user-side worker transport (P4.3).
+// Dials a worker's sidecar over real libp2p: open stream carries the envelope
+// out and tok/0 frames in; receipts flow over a second stream so the worker's
+// open handler never blocks on them. Offers are fetched per-discovered peer
+// and sorted locally — the marketplace columns never touch the wire twice.
+import { multiaddr } from '@multiformats/multiaddr';
+import { newNonce, verifyHello } from "./hello.js";
+import { FrameReader, lpEncode, WriteQueue } from "./lp.js";
+import { fromWire } from "./offer.js";
+import { ZERO_HASH } from "./receipts.js";
+import { peerIdOf } from "./registry.js";
+/** How long to wait for the worker's admission ack before assuming an older
+ *  worker that streams without one. */
+const ADMISSION_TIMEOUT_MS = 8_000;
+export async function dialWorker(node, addr) {
+    const ma = multiaddr(addr);
+    const oq = new WriteQueue();
+    const rq = new WriteQueue();
+    let openStream = null;
+    let receiptStream = null;
+    let openSinkDone = Promise.resolve();
+    let receiptSinkDone = Promise.resolve();
+    const tokenCbs = new Set();
+    const endCbs = new Set();
+    const errCbs = new Set();
+    /** Resolved once the worker admits the session (ok/0) or sends a token;
+     *  rejected when it refuses (err/0). An older worker never acks, so a
+     *  timeout keeps this from hanging on compatibility. */
+    let admitted = null;
+    let refused = null;
+    function fail(e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        for (const cb of errCbs) {
+            cb(err);
+        }
+    }
+    function startPosixRead(s) {
+        void (async () => {
+            const reader = new FrameReader();
+            let dead = false;
+            try {
+                for await (const chunk of s.source) {
+                    reader.push(chunk);
+                    while (!dead) {
+                        const f = reader.next();
+                        if (f == null) {
+                            break;
+                        }
+                        if (f.proto === 'ok/0') {
+                            admitted?.();
+                        }
+                        else if (f.proto === 'err/0') {
+                            // The worker refused the session (P4.9d paywall). This must reach
+                            // the caller as an error, never as an empty successful answer.
+                            const err = new Error(`${f.code ?? 'refused'}: ${f.message ?? 'worker refused the session'}`);
+                            err.code = f.code;
+                            dead = true;
+                            refused?.(err);
+                            for (const cb of errCbs) {
+                                cb(err);
+                            }
+                        }
+                        else if (f.proto === 'tok/0') {
+                            admitted?.();
+                            for (const cb of tokenCbs) {
+                                cb(String(f.delta ?? ''));
+                            }
+                        }
+                    }
+                    if (dead) {
+                        break;
+                    }
+                }
+                if (!dead) {
+                    for (const cb of endCbs) {
+                        cb();
+                    }
+                }
+            }
+            catch (e) {
+                fail(e);
+            }
+        })();
+    }
+    return {
+        async open(env) {
+            openStream = await node.dialProtocol(ma, '/genkaku/open/0');
+            // errors surface via the read side
+            openSinkDone = openStream.sink(oq.source()).catch(() => { });
+            oq.push(lpEncode(env));
+            const admission = new Promise((resolve, reject) => {
+                admitted = resolve;
+                refused = reject;
+            });
+            startPosixRead(openStream);
+            // Compatibility: a worker that predates the ack simply starts streaming,
+            // so wait for a token forever would be wrong — but neither should a slow
+            // model look like a refusal. Bound the wait, then trust the stream.
+            let timer = null;
+            const timeout = new Promise((resolve) => {
+                timer = setTimeout(resolve, ADMISSION_TIMEOUT_MS);
+            });
+            try {
+                await Promise.race([admission, timeout]);
+            }
+            finally {
+                if (timer != null)
+                    clearTimeout(timer);
+                admitted = null;
+                refused = null;
+            }
+        },
+        onToken(cb) { tokenCbs.add(cb); },
+        onEnd(cb) { endCbs.add(cb); },
+        onError(cb) { errCbs.add(cb); },
+        async sendReceipt(jobId, seq, amount, sig = '', inputHash = ZERO_HASH, outputHash = ZERO_HASH) {
+            if (!receiptStream) {
+                receiptStream = await node.dialProtocol(ma, '/genkaku/receipt/0');
+                receiptSinkDone = receiptStream.sink(rq.source()).catch(() => { });
+            }
+            rq.push(lpEncode({
+                proto: 'receipt/0',
+                jobId,
+                seq,
+                amount: amount.toString(),
+                sig,
+                inputHash,
+                outputHash,
+            }));
+        },
+        async close() {
+            oq.end();
+            rq.end();
+            // drain queued writes before the CLOSE frame hits the wire
+            await Promise.allSettled([openSinkDone, receiptSinkDone]);
+            await Promise.allSettled([openStream?.close(), receiptStream?.close()]);
+        },
+    };
+}
+/** Fetch + deserialize a worker's offer board (one dial, whole-board read). */
+/** P4.9e: ask the peer to prove it holds the EVM key of the wallet it puts on
+ *  its offers. Throws when the answer is missing, malformed, signed by another
+ *  key, or claims a different PeerId than the one we dialed. */
+export async function helloWorker(node, addr) {
+    const expectedPeer = peerIdOf(addr);
+    const nonce = newNonce();
+    const stream = await node.dialProtocol(multiaddr(addr), '/genkaku/hello/0');
+    let reply;
+    try {
+        stream.sink([lpEncode({ proto: 'hello/0', nonce })]).catch(() => { });
+        const reader = new FrameReader();
+        for await (const chunk of stream.source) {
+            reader.push(chunk);
+            const frame = reader.next();
+            if (frame != null) {
+                reply = frame;
+                break;
+            }
+        }
+    }
+    finally {
+        await stream.close().catch(() => { });
+    }
+    if (reply?.proto !== 'hello/0' || reply.ok !== true) {
+        throw new Error(`hello: ${reply?.reason ?? 'no reply from the worker'}`);
+    }
+    if (typeof reply.peerId !== 'string' || typeof reply.wallet !== 'string' || typeof reply.sig !== 'string') {
+        throw new Error('hello: malformed proof');
+    }
+    // The signature binds the peerId it was made for; a mismatch means the peer
+    // replayed someone else's proof or the address was rewritten in transit.
+    if (expectedPeer != null && reply.peerId !== expectedPeer) {
+        throw new Error(`hello: peer ${reply.peerId} is not ${expectedPeer}`);
+    }
+    const proof = { peerId: reply.peerId, wallet: reply.wallet, sig: reply.sig };
+    if (!(await verifyHello(proof, nonce))) {
+        throw new Error(`hello: signature does not recover to ${proof.wallet}`);
+    }
+    return proof;
+}
+export async function fetchOffers(node, addr) {
+    const offers = await fetchOfferBoard(node, addr);
+    let proof;
+    try {
+        proof = await helloWorker(node, addr);
+    }
+    catch {
+        // An older worker (or one with no wallet) cannot prove anything; the board
+        // stays unverified and the caller decides whether that is acceptable.
+        return offers;
+    }
+    return offers.map((offer) => {
+        if (offer.workerWallet?.startsWith('0x') && offer.workerWallet.toLowerCase() !== proof.wallet.toLowerCase()) {
+            throw new Error(`offers: ${proof.peerId} claims ${offer.workerWallet} but proved ${proof.wallet}`);
+        }
+        // The proven wallet wins: a worker that omits its wallet still becomes
+        // payable, and a lying one was already rejected above.
+        return { ...offer, workerWallet: proof.wallet, walletVerified: true };
+    });
+}
+async function fetchOfferBoard(node, addr) {
+    const s = await node.dialProtocol(multiaddr(addr), '/genkaku/offers/0');
+    const reader = new FrameReader();
+    let board = [];
+    for await (const chunk of s.source) {
+        reader.push(chunk);
+        const f = reader.next();
+        if (f?.proto === 'offers/0' && Array.isArray(f.board)) {
+            board = f.board;
+            break;
+        }
+    }
+    await s.close().catch(() => { });
+    return board.filter(w => w.proto === 'offers/0').map(w => fromWire(w));
+}
+/** P4.5 seed discovery: ask a bootstrap seed which peers it currently sees.
+ *  The seed is a pure matchmaker — one frame in, one frame out, no storage. */
+export async function fetchSeedPeers(node, addr) {
+    const s = await node.dialProtocol(multiaddr(addr), '/genkaku/peers/0');
+    const reader = new FrameReader();
+    for await (const chunk of s.source) {
+        reader.push(chunk);
+        const f = reader.next();
+        if (f?.proto === 'peers/0' && Array.isArray(f.peers)) {
+            await s.close().catch(() => { });
+            return f.peers.filter((p) => typeof p === 'string' && p.startsWith('/'));
+        }
+    }
+    await s.close().catch(() => { });
+    return [];
+}
+/**
+ * P4.4 settle co-sign (one dial, one frame each way): the user, at session
+ * end, presents (jobId, escrowId, receiptHash, spend); the worker checks its
+ * held max-cumulative receipt (anti-inflation: it never signs beyond the
+ * largest receipt the client piped — P1 §8) and returns an EIP-191 signature
+ * over keccak256(abi.encodePacked(escrowId, receiptHash, spend)) — the exact
+ * digest JobEscrow.settle recovers against the session's worker address.
+ */
+export async function requestSettleCosign(node, addr, args) {
+    const s = await node.dialProtocol(multiaddr(addr), '/genkaku/settle/0');
+    const reader = new FrameReader();
+    let reply = null;
+    const sinkDone = s.sink([lpEncode({
+            proto: 'settle/0',
+            jobId: args.jobId,
+            escrowId: args.escrowId,
+            receiptHash: args.receiptHash,
+            spend: args.spend.toString(),
+        })]).catch(() => { });
+    for await (const chunk of s.source) {
+        reader.push(chunk);
+        const f = reader.next();
+        if (f?.proto === 'settle/0') {
+            reply = f;
+            break;
+        }
+    }
+    await sinkDone; // empty the queue BEFORE CLOSE or the request frame dies
+    await s.close().catch(() => { });
+    if (reply?.ok === true && typeof reply.sig === 'string' && reply.sig.startsWith('0x')) {
+        return { ok: true, sig: reply.sig };
+    }
+    return { ok: false, sig: null, reason: reply?.reason ?? 'worker did not co-sign' };
+}
+//# sourceMappingURL=dial.js.map

package/dist/directory.d.ts

@@ -0,0 +1,39 @@
+import { type GenkakuPublic } from './chain.ts';
+import type { NetEnvironment } from './netconfig.ts';
+export type DirectoryCacheEntry = {
+    wallet: `0x${string}`;
+    peerId: `0x${string}`;
+    locator: string;
+    updatedAt: number;
+    blockNumber: string;
+};
+export type DirectoryCache = {
+    version: 1;
+    env: NetEnvironment;
+    lastBlock: string;
+    entries: DirectoryCacheEntry[];
+    updatedAt: number;
+};
+type Logger = {
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+};
+export declare function directoryPath(keyDir: string): string;
+export declare function loadDirectory(keyDir: string, env: NetEnvironment): DirectoryCache;
+export type DirectorySync = {
+    entries: DirectoryCacheEntry[];
+    scannedFrom: bigint;
+    scannedTo: bigint;
+    added: number;
+    removed: number;
+};
+/** Scan forward from the checkpoint, merge into the cache, and persist.
+ *  Returns the merged directory (live entries only). */
+export declare function syncDirectory(publicC: GenkakuPublic, env: NetEnvironment, keyDir: string, log: Logger): Promise<DirectorySync>;
+/** Every dialable multiaddr in the directory, newest worker first. */
+export declare function workerAddrs(cache: DirectoryCache): string[];
+/** Drop a wallet from the cache after repeated dial failures, so a dead worker
+ *  stops costing a connection attempt on every boot until it advertises again. */
+export declare function dropEntry(keyDir: string, env: NetEnvironment, wallet: string): void;
+export {};
+//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAeA,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAGpD,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,CAAC,CAAA;IACV,GAAG,EAAE,cAAc,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,mBAAmB,EAAE,CAAA;IAC9B,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,MAAM,GAAG;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,CAAA;AAElH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,cAAc,CAiBjF;AAgCD,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,mBAAmB,EAAE,CAAA;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;wDACwD;AACxD,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,aAAa,CAAC,CAoDxB;AAYD,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,EAAE,CAc3D;AAED;kFACkF;AAClF,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnF"}

package/dist/directory.js

@@ -0,0 +1,149 @@
+// GENKAKU: on-chain worker discovery (P4.9b).
+//
+// Replaces the bootstrap seed. The directory is built from `WorkerLocated` logs
+// and never from a server we run: a cold client with an empty config and no
+// cache can find workers using nothing but a public Base RPC.
+//
+// Two cost controls make that affordable at scale:
+//   1. a persisted checkpoint (`lastBlock`) so a normal boot scans only the
+//      blocks since the last run — usually a handful;
+//   2. an on-disk entry cache, so the offer list is available even when the
+//      chain read fails (offline start, RPC trouble).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readWorkerDeactivations, readWorkerLocators, REGISTRY_DEPLOY_BLOCK, } from "./chain.js";
+import { peerIdDigestOf } from "./registry.js";
+export function directoryPath(keyDir) {
+    return join(keyDir, 'directory.json');
+}
+export function loadDirectory(keyDir, env) {
+    const empty = {
+        version: 1,
+        env,
+        lastBlock: (REGISTRY_DEPLOY_BLOCK[env] - 1n).toString(),
+        entries: [],
+        updatedAt: 0,
+    };
+    try {
+        if (!existsSync(directoryPath(keyDir)))
+            return empty;
+        const raw = JSON.parse(readFileSync(directoryPath(keyDir), 'utf8'));
+        if (raw?.version !== 1 || raw.env !== env || !Array.isArray(raw.entries))
+            return empty;
+        return raw;
+    }
+    catch {
+        return empty;
+    }
+}
+function saveDirectory(keyDir, cache) {
+    try {
+        mkdirSync(keyDir, { recursive: true });
+        writeFileSync(directoryPath(keyDir), JSON.stringify(cache, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // the cache is an optimisation; never fail discovery because of it
+    }
+}
+/** Does the locator actually point at the peerId the wallet pinned?
+ *  A worker could advertise someone else's address (or an old one); the digest
+ *  compare is the only thing that makes the directory trustworthy. */
+function locatorMatchesPeer(entry) {
+    const wanted = entry.peerId.toLowerCase();
+    const ids = entry.locator
+        .split(/[;\n]+/)
+        .map(part => part.split('/p2p/').pop()?.split('/')[0])
+        .filter((id) => id != null && id !== '');
+    if (ids.length === 0)
+        return false;
+    return ids.every((id) => {
+        try {
+            return peerIdDigestOf(id).toLowerCase() === wanted;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Scan forward from the checkpoint, merge into the cache, and persist.
+ *  Returns the merged directory (live entries only). */
+export async function syncDirectory(publicC, env, keyDir, log) {
+    const cache = loadDirectory(keyDir, env);
+    const floor = REGISTRY_DEPLOY_BLOCK[env] - 1n;
+    const scannedFrom = BigInt(cache.lastBlock) + 1n > floor ? BigInt(cache.lastBlock) + 1n : floor;
+    const latest = await publicC.getBlockNumber();
+    const byWallet = new Map();
+    for (const entry of cache.entries)
+        byWallet.set(entry.wallet.toLowerCase(), entry);
+    let added = 0;
+    let removed = 0;
+    if (latest >= scannedFrom) {
+        const [located, dead] = await Promise.all([
+            readWorkerLocators(publicC, env, { fromBlock: scannedFrom, toBlock: latest }),
+            readWorkerDeactivations(publicC, env, { fromBlock: scannedFrom, toBlock: latest }),
+        ]);
+        for (const entry of located) {
+            if (!locatorMatchesPeer(entry)) {
+                log.warn('directory: %s advertises a locator that does not contain its pinned peerId — ignored', entry.wallet);
+                continue;
+            }
+            const key = entry.wallet.toLowerCase();
+            const prev = byWallet.get(key);
+            if (prev == null || BigInt(prev.blockNumber) < entry.blockNumber)
+                added++;
+            byWallet.set(key, toCacheEntry(entry));
+        }
+        for (const gone of dead) {
+            const key = gone.wallet.toLowerCase();
+            const prev = byWallet.get(key);
+            if (prev != null && BigInt(prev.blockNumber) < gone.blockNumber) {
+                byWallet.delete(key);
+                removed++;
+            }
+        }
+        log.info('directory: scanned %s..%s (%d located, %d deactivated, %d new, %d dropped)', scannedFrom.toString(), latest.toString(), located.length, dead.length, added, removed);
+    }
+    const next = {
+        version: 1,
+        env,
+        lastBlock: latest.toString(),
+        entries: [...byWallet.values()],
+        updatedAt: Date.now(),
+    };
+    saveDirectory(keyDir, next);
+    return { entries: next.entries, scannedFrom, scannedTo: latest, added, removed };
+}
+function toCacheEntry(entry) {
+    return {
+        wallet: entry.wallet,
+        peerId: entry.peerId,
+        locator: entry.locator,
+        updatedAt: entry.updatedAt,
+        blockNumber: entry.blockNumber.toString(),
+    };
+}
+/** Every dialable multiaddr in the directory, newest worker first. */
+export function workerAddrs(cache) {
+    const addrs = [];
+    const newestFirst = [...cache.entries].sort((a, b) => {
+        const delta = BigInt(b.blockNumber) - BigInt(a.blockNumber);
+        return delta === 0n ? 0 : delta > 0n ? 1 : -1;
+    });
+    for (const entry of newestFirst) {
+        for (const addr of entry.locator.split(/[;\n]+/).map(s => s.trim())) {
+            if (addr.startsWith('/'))
+                addrs.push(addr);
+        }
+    }
+    return [...new Set(addrs)];
+}
+/** Drop a wallet from the cache after repeated dial failures, so a dead worker
+ *  stops costing a connection attempt on every boot until it advertises again. */
+export function dropEntry(keyDir, env, wallet) {
+    const cache = loadDirectory(keyDir, env);
+    const next = cache.entries.filter(e => e.wallet.toLowerCase() !== wallet.toLowerCase());
+    if (next.length === cache.entries.length)
+        return;
+    saveDirectory(keyDir, { ...cache, entries: next, updatedAt: Date.now() });
+}
+//# sourceMappingURL=directory.js.map