@genkaku/protocol 0.0.0-stage → 0.1.1

package/dist/p2pNode.js

@@ -0,0 +1,454 @@
+// GENKAKU: libp2p nodes (P4.2 sidecar / P4.3 client / P4.4 settle co-sign).
+// Workers serve the /genkaku/* protocols (sidecar); users get a bare dial node.
+// The mode manager gates handler installs — user mode never constructs the
+// worker side, and worker modes never open remote sessions (D-block defense
+// in depth, P4-ADAPTATION §2).
+import { noise } from '@chainsafe/libp2p-noise';
+import { yamux } from '@chainsafe/libp2p-yamux';
+import { Secp256k1PrivateKey } from '@libp2p/crypto/keys';
+import { identify } from '@libp2p/identify';
+import { createFromPrivKey, createSecp256k1PeerId } from '@libp2p/peer-id-factory';
+import { tcp } from '@libp2p/tcp';
+import { createLibp2p } from 'libp2p';
+import { toBytes } from 'viem';
+import { settleDigest, walletAddress } from "./chain.js";
+import { signHello } from "./hello.js";
+import { FrameReader, lpEncode, WriteQueue } from "./lp.js";
+import { CHAIN_ID, CONTRACTS } from "./netconfig.js";
+import { cumulativeBilled, toWire } from "./offer.js";
+import { digestForHex, inputHashOf, outputHashOf, ReceiptLedger, recoverSigner, sessionIdHex, signDigest, ZERO_HASH, } from "./receipts.js";
+import { POLICY_VERSION, policyHashOf } from "./registry.js";
+// re-exported for consumers of the codec (tests, user-side dialer)
+export { FrameReader, lpEncode, lpFrames } from "./lp.js";
+export const GENKAKU_PROTOCOLS = [
+    '/genkaku/open/0',
+    '/genkaku/token/0',
+    '/genkaku/receipt/0',
+    '/genkaku/settle/0',
+    '/genkaku/offers/0',
+    '/genkaku/policy/0',
+    '/genkaku/hello/0',
+];
+// libp2p 1.9.4's own default nodeInfo omits the REQUIRED `userAgent` field,
+// which makes @libp2p/identify crash on start (getAgentVersion →
+// nodeInfo.userAgent → undefined → uint8ArrayFromString throws). Provide a
+// full NodeInfo; also advertised in identify metadata.
+const NODE_INFO = { name: 'genkaku', version: '0.1.0', userAgent: 'genkaku/0.1.0 (desktop)' };
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+/** Bounded window AFTER the token EOF in which the client's through-end
+ *  receipt may still land before we stop watching. Sidecar-scope: the receipt
+ *  protocol stream stays alive independently of the released token stream. */
+const RECEIPT_DRAIN_MS = 250;
+/** Slack for worker/client clock differences in the receipt clock bound. */
+const CLOCK_SLACK_MS = 2_000;
+/** A bare libp2p node for the USER side (no genkaku handlers — dials only). */
+export async function createUserNode(listen = []) {
+    const peerId = await createSecp256k1PeerId();
+    return createLibp2p({
+        peerId,
+        nodeInfo: NODE_INFO,
+        addresses: { listen },
+        transports: [tcp()],
+        connectionEncryption: [noise()],
+        streamMuxers: [yamux()],
+        services: { identify: identify() },
+    });
+}
+export async function createSidecar(opts) {
+    // D-block: do not even construct listeners without a sharing-capable mode.
+    const mode = opts.modeManager.current();
+    if (mode.mode === 'user') {
+        throw new Error('[genkaku:sidecar] refusing to build worker listeners in user mode (D-block)');
+    }
+    opts.modeManager.installWorkerListeners();
+    const ledger = new ReceiptLedger();
+    const inbox = new Map();
+    /** jobId → escrowId as declared in the open envelope (receipt/bind side). */
+    const escrowByJob = new Map();
+    /** jobId → wall time the open envelope arrived (the clock-bound anchor). */
+    const openedAtByJob = new Map();
+    /** jobId → the escrow payer proven by the paywall (receipt signer must match). */
+    const payerByJob = new Map();
+    /** jobId → commitment to the request the open envelope asked for. */
+    const inputHashByJob = new Map();
+    /** jobId → the answer text emitted so far (the reveal side of a challenge). */
+    const outputByJob = new Map();
+    /** jobId → the model the open envelope asked for (bounds price lookup). */
+    const sessionModelByJob = new Map();
+    /** jobId → the client's billing tick (granularity, wallet: the worker owns price). */
+    const sessionUnitMsByJob = new Map();
+    let sessions = 0;
+    let currentCatalog = [...opts.catalog];
+    // The worker-side receipt constructor: EXACTLY what the user signed —
+    // chainId/escrow from NETCONFIG (one deployment per env), sessionId from
+    // (jobId, escrowId). Nothing the caller controls feeds the struct, so a
+    // forged sig can't bind a different amount or stream handle.
+    const receiptOf = (jobId, held) => {
+        if (held == null) {
+            return null;
+        }
+        return {
+            chainId: CHAIN_ID[ENV],
+            escrow: (CONTRACTS[ENV].escrow || ZERO_ADDRESS),
+            sessionId: sessionIdHex(jobId, held.escrowId),
+            seq: held.seq,
+            amount: held.amount,
+            inputHash: held.inputHash,
+            outputHash: held.outputHash,
+        };
+    };
+    // Identity: secp256k1 peer key — libp2p supports it natively and it is the
+    // SAME curve as the EVM wallet, so the P4.4 registry binding proves one key
+    // owns both sides of (PeerId, wallet) address. With a worker wallet, derive
+    // the PeerId from that exact key; otherwise keep a random identity.
+    const peerId = opts.workerKey != null
+        ? await createFromPrivKey(new Secp256k1PrivateKey(toBytes(opts.workerKey)))
+        : await createSecp256k1PeerId();
+    const node = await createLibp2p({
+        peerId,
+        nodeInfo: NODE_INFO,
+        addresses: { listen: opts.listen },
+        transports: [tcp()],
+        connectionEncryption: [noise()],
+        streamMuxers: [yamux()],
+        services: { identify: identify() },
+    });
+    await node.handle('/genkaku/open/0', ({ connection, stream }) => {
+        void (async () => {
+            // Read ONLY the open envelope, then start serving — the client keeps its
+            // write half open for the session, so a drain-to-EOS read would deadlock
+            // with muxer window backpressure.
+            const reader = new FrameReader();
+            let env;
+            for await (const chunk of stream.source) {
+                reader.push(chunk);
+                const frame = reader.next();
+                if (frame != null) {
+                    env = frame;
+                    break;
+                }
+            }
+            if (!env || (env.proto !== 'open/0' && env.proto !== 'open/1')) {
+                await stream.close();
+                return;
+            }
+            let payer = null;
+            if (opts.paywall != null) {
+                const verdict = await opts.paywall({
+                    jobId: env.jobId,
+                    escrowId: env.escrowId || '0',
+                    clientPeer: env.clientPeer ?? '',
+                }).catch(() => ({ ok: false, code: 'paywall-error', reason: 'paywall check failed' }));
+                if (!verdict.ok) {
+                    opts.sessionEvents?.({
+                        type: 'session-error',
+                        message: `refused ${env.jobId}: ${verdict.code} (${verdict.reason})`,
+                    });
+                    try {
+                        await stream.sink([lpEncode({
+                                proto: 'err/0',
+                                jobId: env.jobId,
+                                code: verdict.code,
+                                message: verdict.reason,
+                            })]);
+                    }
+                    catch {
+                        // the client may already have gone; the close below still ends it
+                    }
+                    await stream.close().catch(() => { });
+                    return;
+                }
+                payer = verdict.payer;
+            }
+            if (payer != null)
+                payerByJob.set(env.jobId, payer);
+            inputHashByJob.set(env.jobId, inputHashOf({
+                model: env.model,
+                prompt: env.prompt,
+                system: env.system,
+                maxTokens: env.maxTokens,
+            }));
+            outputByJob.set(env.jobId, '');
+            escrowByJob.set(env.jobId, env.escrowId || '0');
+            openedAtByJob.set(env.jobId, Date.now());
+            sessionModelByJob.set(env.jobId, env.model);
+            sessionUnitMsByJob.set(env.jobId, env.billing?.unitMs ?? 60_000);
+            // ONE sink for the whole session: token frames push through a durable
+            // write queue (a second stream.sink() call would explode it).
+            const dq = new WriteQueue();
+            const sinkDone = stream.sink(dq.source()).catch(() => { });
+            // Admission ack (P4.9d): the client waits for this before it reports a
+            // success to its own caller, so a paywall refusal reaches the caller as
+            // an error instead of an empty completion.
+            dq.push(lpEncode({ proto: 'ok/0', jobId: env.jobId }));
+            const emit = (e) => opts.sessionEvents?.(e);
+            const session = await import("./workerSession.js").then(({ createWorkerSession }) => createWorkerSession(env, {
+                modeManager: opts.modeManager,
+                source: opts.source,
+                ...(opts.chatSource === undefined ? {} : { chatSource: opts.chatSource }),
+                onToolCall: (call) => {
+                    dq.push(lpEncode({ proto: 'tool/0', ...call }));
+                },
+                ledger,
+                emit,
+                onDelta: (delta) => {
+                    outputByJob.set(env.jobId, (outputByJob.get(env.jobId) ?? '') + delta);
+                    dq.push(lpEncode({ proto: 'tok/0', delta }));
+                },
+                latestReceipt: () => inbox.get(env.jobId) ?? null,
+            }));
+            sessions += 1;
+            try {
+                await session.run();
+                // P2 §3 / P4.4: the client sends its THROUGH-END receipt only after
+                // the token EOF reaches it — i.e. after this handler would have
+                // closed. Release the token stream first (never meter artificial
+                // hold time), then poll the shared inbox for one bounded window and
+                // push any post-end receipt through the SAME strictly-increasing
+                // ledger rule as the live session did. The settle co-sign (below)
+                // defends the final evidence either way.
+                dq.end();
+                await sinkDone;
+                await stream.close();
+                const deadline = Date.now() + RECEIPT_DRAIN_MS;
+                while (Date.now() < deadline) {
+                    const held = inbox.get(env.jobId);
+                    if (held != null) {
+                        const verdict = ledger.offer(env.jobId, held.seq, held.amount);
+                        if (verdict.accepted) {
+                            emit({ type: 'receipt-accepted', seq: held.seq, amount: held.amount });
+                            break;
+                        }
+                        // Stale (already merged into the ledger during the live session):
+                        // keep the window open — a newer receipt may still be in flight.
+                    }
+                    await new Promise(r => setTimeout(r, 20));
+                }
+            }
+            finally {
+                sessions -= 1;
+                if (!dq.ended) { // drain-parked path already closed — safe no-op here
+                    dq.end();
+                    await sinkDone;
+                    await stream.close();
+                }
+            }
+            void connection;
+        })();
+    });
+    await node.handle('/genkaku/receipt/0', ({ stream }) => {
+        void (async () => {
+            const reader = new FrameReader();
+            for await (const chunk of stream.source) {
+                reader.push(chunk);
+                while (true) {
+                    const f = reader.next();
+                    if (f == null) {
+                        break;
+                    }
+                    if (f.proto === 'receipt/0' && typeof f.seq === 'number' && typeof f.amount === 'string' && typeof f.jobId === 'string') {
+                        // escrowId comes from the OPEN envelope, never from this frame —
+                        // the binding is the session's, not the receipt-sender's claim.
+                        const stored = {
+                            seq: f.seq,
+                            amount: BigInt(f.amount),
+                            sig: f.sig ?? '',
+                            escrowId: escrowByJob.get(f.jobId) ?? '0',
+                            inputHash: (f.inputHash ?? ZERO_HASH),
+                            outputHash: (f.outputHash ?? ZERO_HASH),
+                        };
+                        // P4.9f commit-challenge: the client may not pay for a different
+                        // request, and a non-zero output commitment must match the text
+                        // this worker actually emitted.
+                        const expectedInput = inputHashByJob.get(f.jobId);
+                        if (expectedInput != null && stored.inputHash !== expectedInput) {
+                            opts.sessionEvents?.({ type: 'session-error', message: `receipt ${stored.seq}: input commitment mismatch` });
+                            continue;
+                        }
+                        if (stored.outputHash !== ZERO_HASH
+                            && stored.outputHash !== outputHashOf(outputByJob.get(f.jobId) ?? '')) {
+                            opts.sessionEvents?.({ type: 'session-error', message: `receipt ${stored.seq}: output commitment mismatch` });
+                            continue;
+                        }
+                        // P4.4: priced receipts are SIGNATURE-BOUND evidence — a forged
+                        // or anonymous offer never reaches the escrow at settle.
+                        if (opts.workerKey != null && stored.escrowId !== '0') {
+                            const bad = await rejectUnsigned(stored, f.jobId);
+                            if (bad) {
+                                opts.sessionEvents?.({ type: 'session-error', message: `receipt ${stored.seq}: unsigned/malformed offer dropped` });
+                                continue;
+                            }
+                            const over = overClockBound(stored, f.jobId);
+                            if (over != null) {
+                                opts.sessionEvents?.({ type: 'session-error', message: `receipt ${stored.seq} for ${stored.amount}: ${over}` });
+                                continue;
+                            }
+                        }
+                        // Inbox ONLY: the ledger entry is claimed by the session that owns
+                        // this jobId (single ingestion point — a pre-offer here would make
+                        // the session's own offer stale).
+                        inbox.set(f.jobId, stored);
+                    }
+                }
+            }
+            await stream.close();
+        })();
+    });
+    // P4.4 settle co-sign: one request frame, one reply frame. The digest is
+    // rebuilt WORKER-SIDE from the held receipt (the caller's receiptHash is
+    // only compared against it), and the spend must equal the held max
+    // cumulative receipt — anti-inflation by construction (P1 §8). JobEscrow.
+    // settle() then recovers this EIP-191 sig against the session's worker.
+    await node.handle('/genkaku/settle/0', ({ stream }) => {
+        void (async () => {
+            const reader = new FrameReader();
+            let req;
+            for await (const chunk of stream.source) {
+                reader.push(chunk);
+                const f = reader.next();
+                if (f != null) {
+                    req = f;
+                    break;
+                }
+            }
+            const reply = (ok, sig, reason) => stream.sink([lpEncode({ proto: 'settle/0', ok, sig, reason })]).then(() => stream.close());
+            if (req?.proto !== 'settle/0') {
+                await reply(false, undefined, 'bad frame');
+                return;
+            }
+            if (opts.workerKey == null) {
+                await reply(false, undefined, 'worker has no wallet');
+                return;
+            }
+            const jobId = String(req.jobId ?? '');
+            const escrowId = escrowByJob.get(jobId) ?? '0';
+            const held = inbox.get(jobId);
+            if (escrowId === '0' || held == null) {
+                await reply(false, undefined, 'no priced session bound for this jobId');
+                return;
+            }
+            // Defense in depth: the caller's escrowId must agree with the session's
+            // binding. A mismatch can never settle on chain anyway (the worker's
+            // digest carries ONLY the envelope escrowId; JobEscrow.settle recovers
+            // against the session id), but failing here keeps wire errors local.
+            if (req.escrowId != null && String(req.escrowId) !== escrowId) {
+                await reply(false, undefined, 'escrowId does not match the session envelope');
+                return;
+            }
+            if (req.spend == null) {
+                await reply(false, undefined, 'spend is required');
+                return;
+            }
+            const spend = BigInt(req.spend);
+            if (spend !== held.amount) {
+                await reply(false, undefined, 'spend does not match the held max cumulative receipt');
+                return;
+            }
+            const receipt = receiptOf(jobId, held);
+            const receiptHash = receipt == null ? null : digestForHex(receipt);
+            if (receiptHash == null || String(req.receiptHash ?? '').toLowerCase() !== receiptHash.toLowerCase()) {
+                await reply(false, undefined, 'receiptHash does not match the held receipt');
+                return;
+            }
+            const sig = await signDigest(opts.workerKey, settleDigest(BigInt(escrowId), receiptHash, spend));
+            await reply(true, sig);
+        })();
+    });
+    // P4.9e identity proof: one nonce in, one signed proof out. The client
+    // recovers the signer and refuses offers whose wallet it cannot prove.
+    await node.handle('/genkaku/hello/0', ({ stream }) => {
+        void (async () => {
+            const reader = new FrameReader();
+            let req;
+            for await (const chunk of stream.source) {
+                reader.push(chunk);
+                const f = reader.next();
+                if (f != null) {
+                    req = f;
+                    break;
+                }
+            }
+            const reply = (body) => stream.sink([lpEncode({ proto: 'hello/0', ...body })]).then(() => stream.close());
+            if (req?.proto !== 'hello/0' || typeof req.nonce !== 'string' || !req.nonce.startsWith('0x')) {
+                await reply({ ok: false, reason: 'bad frame' });
+                return;
+            }
+            if (opts.workerKey == null) {
+                await reply({ ok: false, reason: 'worker has no wallet' });
+                return;
+            }
+            const proof = await signHello(opts.workerKey, node.peerId.toString(), req.nonce);
+            await reply({ ok: true, peerId: proof.peerId, wallet: proof.wallet, sig: proof.sig });
+        })();
+    });
+    // The offer board: a user dials this on every discovered peer and sorts
+    // locally (P4.3). bigint prices travel as decimal strings (OfferWire); the
+    // wallet here is a CLAIM — the client only trusts it after /genkaku/hello/0
+    // proves the key (P4.9e) or the registry binds it (P4.5).
+    await node.handle('/genkaku/offers/0', ({ stream }) => {
+        const wallet = opts.workerKey != null ? walletAddress(opts.workerKey) : undefined;
+        const board = currentCatalog.map(o => toWire(wallet == null ? o : { ...o, workerWallet: wallet }));
+        void stream.sink([lpEncode({ proto: 'offers/0', board })]).then(() => stream.close());
+    });
+    // token is served in-session (open handler); policy is reserved v0.
+    await node.handle('/genkaku/token/0', ({ stream }) => { void stream.close(); });
+    await node.handle('/genkaku/policy/0', ({ stream }) => {
+        // P4.5: the wire advertises the SAME digest the worker pins on
+        // WorkerRegistry, so a user can compare registry.policyHash against it.
+        void stream.sink([lpEncode({ proto: 'policy/0', policyHash: policyHashOf(POLICY_VERSION), policyVersion: POLICY_VERSION })]).then(() => stream.close());
+    });
+    // ── helpers (close over netconfig + maps, never over the wire) ──────────
+    /** Starts true when a priced receipt cannot be signature-verified. P4.9e:
+     *  the signer must also equal the escrow's payer, so evidence and money name
+     *  the same party (a third party can no longer sign for someone's escrow). */
+    async function rejectUnsigned(stored, jobId) {
+        if (stored.sig === '' || !stored.sig.startsWith('0x')) {
+            return true;
+        }
+        const receipt = receiptOf(jobId, stored);
+        if (receipt == null) {
+            return true;
+        }
+        const signer = await recoverSigner(toBytes(digestForHex(receipt)), stored.sig);
+        if (signer == null) {
+            return true;
+        }
+        const payer = payerByJob.get(jobId);
+        if (payer != null && payer !== ZERO_ADDRESS && signer.toLowerCase() !== payer.toLowerCase()) {
+            return true;
+        }
+        return false;
+    }
+    /** The P2 §3 clock bound: a receipt can never exceed what the worker's OWN
+     *  catalog price + wall time since the open envelope allow. Returns a
+     *  reason string when the receipt is over, null when within the bound. */
+    function overClockBound(stored, jobId) {
+        const openedAt = openedAtByJob.get(jobId);
+        if (openedAt == null) {
+            return 'session was never opened here';
+        }
+        const env = currentCatalog.find(o => o.model === sessionModelByJob.get(jobId)) ?? currentCatalog[0];
+        if (env == null) {
+            return 'worker has no priced model';
+        }
+        const unitMs = sessionUnitMsByJob.get(jobId) ?? 60_000;
+        const elapsed = Date.now() - openedAt + CLOCK_SLACK_MS;
+        const max = cumulativeBilled(env.pricePerHour, unitMs, Math.max(elapsed, unitMs));
+        if (stored.amount > max) {
+            return `exceeds the clock bound (${stored.amount} > ${max})`;
+        }
+        return null;
+    }
+    return {
+        node,
+        peerAddrs: () => node.getMultiaddrs().map(m => m.toString()),
+        stop: async () => { await opts.modeManager.removeWorkerListeners(); await node.stop(); },
+        activeSessions: () => sessions,
+        peerIdStr: () => peerId.toString(),
+        setCatalog: (offers) => { currentCatalog = [...offers]; },
+    };
+}
+// data-plane net env the sidecar binds receipts to (single deployment — the
+// base mainnet bindings stay empty until P6).
+const ENV = 'base-sepolia';
+//# sourceMappingURL=p2pNode.js.map

package/dist/paywall.d.ts

@@ -0,0 +1,30 @@
+import { type GenkakuPublic } from './chain.ts';
+import type { NetEnvironment } from './netconfig.ts';
+export type PaywallRequest = {
+    jobId: string;
+    escrowId: string;
+    clientPeer: string;
+};
+export type PaywallVerdict = {
+    ok: true; /** the escrow's payer — receipts must be signed by this wallet */
+    payer: `0x${string}`;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export type Paywall = (request: PaywallRequest) => Promise<PaywallVerdict>;
+export type PaywallOptions = {
+    publicC: GenkakuPublic;
+    env: NetEnvironment;
+    /** the wallet that must be the escrow's payee */
+    worker: `0x${string}`;
+    /** dev escape hatch: allow `escrowId: "0"` (unpriced) sessions */
+    allowUnpriced?: boolean;
+    now?: () => number;
+    log?: {
+        warn: (msg: string, ...args: unknown[]) => void;
+    };
+};
+export declare function createPaywall(opts: PaywallOptions): Paywall;
+//# sourceMappingURL=paywall.d.ts.map

package/dist/paywall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paywall.d.ts","sourceRoot":"","sources":["../src/paywall.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAA;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC,CAAC,kEAAkE;IAAC,KAAK,EAAE,KAAK,MAAM,EAAE,CAAA;CAAE,GACrG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/C,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;AAK1E,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,aAAa,CAAA;IACtB,GAAG,EAAE,cAAc,CAAA;IACnB,iDAAiD;IACjD,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,GAAG,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAC1D,CAAA;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CA4C3D"}

package/dist/paywall.js

@@ -0,0 +1,84 @@
+// GENKAKU: worker paywall (P4.9d).
+//
+// A public directory makes a worker dialable by strangers. Without a gate,
+// "dialable" means "free GPU": anyone who scans the chain can open a stream and
+// burn inference time. The gate is therefore not a billing nicety — it is the
+// condition for publishing an address at all.
+//
+// The check is cheap and self-contained: the client names an escrow id in the
+// OPEN envelope; the worker reads that session from JobEscrow and serves only
+// if the record exists, pays THIS worker, is still open, and has money in it.
+// The money itself never moves here — settlement stays the client's signed
+// receipt + JobEscrow.settle.
+//
+// Deliberate properties:
+//   * a verdict is cached for a few seconds (a retry storm must not become RPC
+//     load) but never longer than the escrow can change state;
+//   * the amount is a ceiling, not a reservation: two clients may name the same
+//     escrow, and the ledger still caps what can be settled;
+//   * `unpriced` (escrowId "0") is allowed ONLY when the operator explicitly
+//     disabled the paywall, so a dev session can never be reached by a stranger
+//     that merely guessed "0".
+import { readEscrowSession } from "./chain.js";
+const VERDICT_TTL_MS = 15_000;
+const ZERO = '0x0000000000000000000000000000000000000000';
+export function createPaywall(opts) {
+    const cache = new Map();
+    const now = opts.now ?? Date.now;
+    return async (request) => {
+        const raw = (request.escrowId ?? '').trim();
+        if (raw === '' || raw === '0') {
+            // Unpriced sessions have no payer to certify; the dev escape hatch keeps
+            // them working for an explicit opt-out only.
+            return opts.allowUnpriced === true
+                ? { ok: true, payer: ZERO }
+                : { ok: false, code: 'payment-required', reason: 'unpriced session rejected: open an escrow first' };
+        }
+        let id;
+        try {
+            id = BigInt(raw);
+        }
+        catch {
+            return { ok: false, code: 'bad-escrow', reason: 'escrow id is not an integer' };
+        }
+        const key = id.toString();
+        const hit = cache.get(key);
+        if (hit != null && now() - hit.at < VERDICT_TTL_MS)
+            return hit.verdict;
+        let verdict;
+        try {
+            const session = await readEscrowSession(opts.publicC, opts.env, id);
+            verdict = judge(session, opts.worker);
+        }
+        catch (error) {
+            // An RPC failure must not silently turn into free compute: fail closed,
+            // but say so, because a flaky endpoint should be retried by the client.
+            const message = error instanceof Error ? error.message : String(error);
+            opts.log?.warn('paywall: escrow %s read failed (%s)', key, message);
+            verdict = { ok: false, code: 'chain-unavailable', reason: 'could not verify the escrow; retry shortly' };
+        }
+        // Cache failures too: a stranger replaying a dead escrow id must not turn
+        // into one chain read per attempt.
+        cache.set(key, { at: now(), verdict });
+        return verdict;
+    };
+}
+function judge(session, worker) {
+    if (session == null) {
+        return { ok: false, code: 'unknown-escrow', reason: 'escrow session does not exist' };
+    }
+    if (session.worker.toLowerCase() !== worker.toLowerCase()) {
+        return { ok: false, code: 'wrong-worker', reason: 'escrow pays a different worker' };
+    }
+    if (session.settled || session.refunded) {
+        return { ok: false, code: 'closed-escrow', reason: 'escrow is already settled or refunded' };
+    }
+    if (session.amount <= 0n) {
+        return { ok: false, code: 'empty-escrow', reason: 'escrow has no funds' };
+    }
+    if (session.user.toLowerCase() === ZERO) {
+        return { ok: false, code: 'unknown-escrow', reason: 'escrow has no payer' };
+    }
+    return { ok: true, payer: session.user };
+}
+//# sourceMappingURL=paywall.js.map

package/dist/publishOptIn.d.ts

@@ -0,0 +1,15 @@
+/** File name under the GenKaKu key directory. */
+export declare const PUBLISH_OPT_IN_FILE = "publish.json";
+/**
+ * Read the worker's directory opt-in.
+ * @param keyDir - GenKaKu state directory.
+ * @returns true only when the worker explicitly opted in.
+ */
+export declare function readPublishOptIn(keyDir: string): boolean;
+/**
+ * Persist the worker's directory opt-in.
+ * @param keyDir - GenKaKu state directory.
+ * @param publish - whether a public address may be written to the chain.
+ */
+export declare function writePublishOptIn(keyDir: string, publish: boolean): void;
+//# sourceMappingURL=publishOptIn.d.ts.map

package/dist/publishOptIn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publishOptIn.d.ts","sourceRoot":"","sources":["../src/publishOptIn.ts"],"names":[],"mappings":"AAUA,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,iBAAiB,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAGxE"}

package/dist/publishOptIn.js

@@ -0,0 +1,34 @@
+// GENKAKU: worker directory opt-in (P4.7b).
+//
+// `config.publishAddress` is the deployment default and stays false for
+// privacy. The settings page writes this per-machine opt-in instead of editing
+// the profile YAML, so a non-technical worker can join the global directory
+// after reading the warning that a public address is permanent on chain.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** File name under the GenKaKu key directory. */
+export const PUBLISH_OPT_IN_FILE = 'publish.json';
+/**
+ * Read the worker's directory opt-in.
+ * @param keyDir - GenKaKu state directory.
+ * @returns true only when the worker explicitly opted in.
+ */
+export function readPublishOptIn(keyDir) {
+    try {
+        const value = JSON.parse(readFileSync(join(keyDir, PUBLISH_OPT_IN_FILE), 'utf8'));
+        return typeof value === 'object' && value !== null && value.publish === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Persist the worker's directory opt-in.
+ * @param keyDir - GenKaKu state directory.
+ * @param publish - whether a public address may be written to the chain.
+ */
+export function writePublishOptIn(keyDir, publish) {
+    mkdirSync(keyDir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(keyDir, PUBLISH_OPT_IN_FILE), `${JSON.stringify({ publish }, undefined, 2)}\n`, { mode: 0o600 });
+}
+//# sourceMappingURL=publishOptIn.js.map