@genkaku/protocol 0.0.0-stage → 0.1.1

package/dist/receipts.d.ts

@@ -0,0 +1,61 @@
+import { type Hex } from 'viem';
+import type { NetEnvironment } from './netconfig.ts';
+export type ReceiptPayloadV1 = {
+    chainId: 84532 | 8453;
+    escrow: `0x${string}`;
+    sessionId: `0x${string}`;
+    seq: number;
+    amount: bigint;
+    /** commit-challenge (P4.9f): keccak of the canonical REQUEST. Always set. */
+    inputHash: `0x${string}`;
+    /** keccak of the full answer. ZERO until the through-end receipt, which
+     *  commits the exact text the worker was paid for. */
+    outputHash: `0x${string}`;
+};
+/** All-zero bytes32 — "not committed yet" (never a real keccak in practice). */
+export declare const ZERO_HASH: "0x0000000000000000000000000000000000000000000000000000000000000000";
+/** Canonical request commitment. NUL separators make the field boundaries
+ *  unambiguous, so no two different requests can produce the same string. */
+export declare function inputHashOf(req: {
+    model: string;
+    prompt: string;
+    system?: string;
+    maxTokens?: number;
+}): `0x${string}`;
+/** Commitment to the exact answer text (byte-exact, no normalisation). */
+export declare function outputHashOf(text: string): `0x${string}`;
+export declare function makeReceiptBody(env: NetEnvironment, escrow: string, sessionId: `0x${string}`, seq: number, amount: bigint, inputHash?: `0x${string}`, outputHash?: `0x${string}`): ReceiptPayloadV1 & {
+    _domain: 'genkaku.receipt.v1';
+};
+/** Cumulative-receipt digest: keccak256(abi.encodePacked(chainId, escrow,
+ *  sessionId, seq, amount)) — the receiptHash JobEscrow.settle takes as an
+ *  opaque bytes32; a receipt replayed on chain verifies bit-for-bit. */
+export declare function digestFor(receipt: ReceiptPayloadV1): Uint8Array;
+/** Hex form of digestFor — what the settle wire/tx carry as `receiptHash`. */
+export declare function digestForHex(receipt: ReceiptPayloadV1): Hex;
+/**
+ * 32-byte stream handle for a session. Priced sessions (real escrow id) use
+ * the numeric id as a bytes32 big-endian — the same integer JobEscrow keys
+ * `sessions[id]` with. Unpriced self-test sessions carry a deterministic
+ * keccak of the jobId so already-wired clients still bind receipts to a stream.
+ */
+export declare function sessionIdHex(jobId: string, escrowId: string): `0x${string}`;
+/** EIP-191 personal_message signature over the 32-byte receipt digest —
+ *  recovers in JobEscrow._verify's `_verify(digest, sig, expected)` shape. */
+export declare function signDigest(key: `0x${string}`, digest: Uint8Array): Promise<string>;
+/** Recover the signer address (EIP-191) — rejects malformed sigs with null. */
+export declare function recoverSigner(digest: Uint8Array, sig: string): Promise<`0x${string}` | null>;
+/** Worker-side ledger: keep max signed receipt per session (SQLite later). */
+export declare class ReceiptLedger {
+    private max;
+    offer(sessionId: string, seq: number, amount: bigint): {
+        accepted: boolean;
+        reason?: string;
+    };
+    cumulative(sessionId: string): bigint;
+    settleDigest(sessionId: string): {
+        seq: number;
+        amount: bigint;
+    } | null;
+}
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,GAAG,EAAoD,MAAM,MAAM,CAAA;AAG/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAGpD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,KAAK,GAAG,IAAI,CAAA;IACrB,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,SAAS,EAAE,KAAK,MAAM,EAAE,CAAA;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,SAAS,EAAE,KAAK,MAAM,EAAE,CAAA;IACxB;0DACsD;IACtD,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,SAAS,EAAG,oEAA6E,CAAA;AAEtG;6EAC6E;AAC7E,wBAAgB,WAAW,CAAC,GAAG,EAAE;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,KAAK,MAAM,EAAE,CAUhB;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAExD;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,KAAK,MAAM,EAAE,EACxB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,KAAK,MAAM,EAAc,EACpC,UAAU,GAAE,KAAK,MAAM,EAAc,GACpC,gBAAgB,GAAG;IAAE,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAatD;AAED;;wEAEwE;AACxE,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CAE/D;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,GAAG,CAkB3D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAY3E;AAED;8EAC8E;AAC9E,wBAAsB,UAAU,CAAC,GAAG,EAAE,KAAK,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAWxF;AAED,+EAA+E;AAC/E,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,MAAM,EAAE,GAAG,IAAI,CAAC,CAQlG;AAED,8EAA8E;AAC9E,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAqD;IAEhE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAY7F,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIrC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAGxE"}

package/dist/receipts.js

@@ -0,0 +1,135 @@
+// GENKAKU: cumulative metered receipts (P2 §3, PDF-derived bounded-loss scheme).
+// Client signs; worker holds; the LARGEST cumulative receipt is co-signed at
+// settle. Zero gas — pure local crypto.
+//
+// P4.4 (cutover): digestFor is now REAL keccak256(abi.encodePacked(...)) over
+// the receipt struct, and signatures are EIP-191 personal-message over the
+// 32-byte digest — exactly the shape JobEscrow._verify recovers ("0x19Ethereum
+// Signed Message:\n32" prefix), so a receipt presented at settle verifies on
+// chain with no re-encoding.
+import { encodePacked, keccak256, recoverMessageAddress, toBytes, toHex } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { CHAIN_ID } from "./netconfig.js";
+/** All-zero bytes32 — "not committed yet" (never a real keccak in practice). */
+export const ZERO_HASH = '0x0000000000000000000000000000000000000000000000000000000000000000';
+/** Canonical request commitment. NUL separators make the field boundaries
+ *  unambiguous, so no two different requests can produce the same string. */
+export function inputHashOf(req) {
+    const canonical = [
+        'genkaku.commit.v1',
+        req.model,
+        req.system ?? '',
+        String(req.maxTokens ?? 0),
+        req.prompt,
+    ].join('\u0000');
+    return keccak256(toBytes(canonical));
+}
+/** Commitment to the exact answer text (byte-exact, no normalisation). */
+export function outputHashOf(text) {
+    return keccak256(toBytes(text));
+}
+export function makeReceiptBody(env, escrow, sessionId, seq, amount, inputHash = ZERO_HASH, outputHash = ZERO_HASH) {
+    if (seq < 1) {
+        throw new Error('[genkaku:receipt] seq starts at 1');
+    }
+    return {
+        _domain: 'genkaku.receipt.v1',
+        chainId: CHAIN_ID[env],
+        escrow: escrow,
+        sessionId,
+        seq,
+        amount,
+        inputHash,
+        outputHash,
+    };
+}
+/** Cumulative-receipt digest: keccak256(abi.encodePacked(chainId, escrow,
+ *  sessionId, seq, amount)) — the receiptHash JobEscrow.settle takes as an
+ *  opaque bytes32; a receipt replayed on chain verifies bit-for-bit. */
+export function digestFor(receipt) {
+    return toBytes(digestForHex(receipt));
+}
+/** Hex form of digestFor — what the settle wire/tx carry as `receiptHash`. */
+export function digestForHex(receipt) {
+    const fields = [
+        // uint256 / address / bytes32 / uint256 / uint256 / bytes32 / bytes32 —
+        // packed layout (each numeric field big-endian full-width; all sizes are
+        // multiples of 8 bits so nothing is right-padded).
+        BigInt(receipt.chainId),
+        receipt.escrow.toLowerCase(),
+        receipt.sessionId.toLowerCase(),
+        BigInt(receipt.seq),
+        receipt.amount,
+        receipt.inputHash,
+        receipt.outputHash,
+    ];
+    return keccak256(encodePacked(['uint256', 'address', 'bytes32', 'uint256', 'uint256', 'bytes32', 'bytes32'], fields));
+}
+/**
+ * 32-byte stream handle for a session. Priced sessions (real escrow id) use
+ * the numeric id as a bytes32 big-endian — the same integer JobEscrow keys
+ * `sessions[id]` with. Unpriced self-test sessions carry a deterministic
+ * keccak of the jobId so already-wired clients still bind receipts to a stream.
+ */
+export function sessionIdHex(jobId, escrowId) {
+    let id = 0n;
+    try {
+        id = BigInt(escrowId === '' ? '0' : escrowId);
+    }
+    catch {
+        id = 0n;
+    }
+    if (id > 0n) {
+        return toHex(id, { size: 32 });
+    }
+    return keccak256(toBytes(`genkaku.job:${jobId}`));
+}
+/** EIP-191 personal_message signature over the 32-byte receipt digest —
+ *  recovers in JobEscrow._verify's `_verify(digest, sig, expected)` shape. */
+export async function signDigest(key, digest) {
+    if (digest.length !== 32) {
+        throw new Error('[genkaku:receipt] digest must be 32 bytes');
+    }
+    const account = privateKeyToAccount(key);
+    const sig = await account.signMessage({ message: { raw: digest } });
+    // viem personal signatures are 65 bytes r||s||v with v in 27|28 — the exact
+    // split JobEscrow._verify calldata-loads.
+    if (toBytes(sig).length !== 65) {
+        throw new Error('[genkaku:receipt] signature must be 65 bytes');
+    }
+    return sig;
+}
+/** Recover the signer address (EIP-191) — rejects malformed sigs with null. */
+export async function recoverSigner(digest, sig) {
+    try {
+        if (toBytes(sig).length !== 65) {
+            return null;
+        }
+        return await recoverMessageAddress({ message: { raw: digest }, signature: sig });
+    }
+    catch {
+        return null;
+    }
+}
+/** Worker-side ledger: keep max signed receipt per session (SQLite later). */
+export class ReceiptLedger {
+    max = new Map();
+    offer(sessionId, seq, amount) {
+        const m = this.max.get(sessionId);
+        if (m && seq <= m.seq) {
+            return { accepted: false, reason: 'stale-seq' };
+        }
+        if (m && amount <= m.amount) {
+            return { accepted: false, reason: 'non-increasing' };
+        }
+        this.max.set(sessionId, { seq, amount });
+        return { accepted: true };
+    }
+    cumulative(sessionId) {
+        return this.max.get(sessionId)?.amount ?? 0n;
+    }
+    settleDigest(sessionId) {
+        return this.max.get(sessionId) ?? null;
+    }
+}
+//# sourceMappingURL=receipts.js.map

package/dist/registry.d.ts

@@ -0,0 +1,19 @@
+/** v0 content-policy version the sidecar serves and pins on registration. */
+export declare const POLICY_VERSION = "smoke-v1";
+/** bytes32 the worker pins into WorkerRegistry for its PeerId. */
+export declare function peerIdDigestOf(peerId: string): `0x${string}`;
+/** The content-policy code the worker declares with its registration. */
+export declare function policyHashOf(policy: string): `0x${string}`;
+/** The libp2p PeerId encoded in a worker multiaddr (the grain of the compare). */
+export declare function peerIdOf(addr: string): string | null;
+export type RegistryWorker = {
+    active: boolean;
+    peerId: `0x${string}`;
+    policyHash: `0x${string}`;
+};
+/** The data-plane half of the binding: does the on-chain record for `wallet`
+ *  pin EXACTLY this PeerId? A record that is missing is `absent` (testnet
+ *  grace — the wallet may simply be unfunded); a PRESENT record that pins a
+ *  different PeerId is an active spoofing attempt and fails hard. */
+export declare function bindingOf(reg: RegistryWorker | null, peerId: string): 'bound' | 'absent' | 'mismatch';
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAoBA,6EAA6E;AAC7E,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAM5D;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,MAAM,EAAE,CAE1D;AAED,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASpD;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACrB,UAAU,EAAE,KAAK,MAAM,EAAE,CAAA;CAC1B,CAAA;AAED;;;qEAGqE;AACrE,wBAAgB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAMrG"}

package/dist/registry.js

@@ -0,0 +1,50 @@
+// GENKAKU: WorkerRegistry binding (P4.5) — wallet ⇄ libp2p PeerId.
+// The on-chain half (WorkerRegistry.register, msg.sender = wallet) stores a
+// bytes32 digest of the worker's libp2p PeerId; EVERY data-plane participant
+// recomputes the digest from the PeerId it just dialed and compares — the two
+// halves only match if the same operator controls both keys.
+//
+// Digest scheme (v0, deterministic on both sides): keccak256 over a typed
+// UTF-8 tag + the PeerId STRING (its base58btc data-plane form, the same form
+// every libp2p address carries). Tagging binds the scheme, not the address —
+// a collision with other hashes is structurally impossible:
+//     peerIdDigestOf  = keccak("genkaku.peer.v0:<peerId string>")
+//     policyHashOf    = keccak("genkaku.policy.v0:<policy code>")
+// (WorkerRegistry stores the digest opaquely — bytes32 — so the algorithm is
+// an off-chain agreement; the contract comment's "blake2s" was aspirational.)
+import { keccak256, toBytes } from 'viem';
+const PEER_TAG = 'genkaku.peer.v0:';
+const POLICY_TAG = 'genkaku.policy.v0:';
+/** v0 content-policy version the sidecar serves and pins on registration. */
+export const POLICY_VERSION = 'smoke-v1';
+/** bytes32 the worker pins into WorkerRegistry for its PeerId. */
+export function peerIdDigestOf(peerId) {
+    if (peerId.includes('/') || peerId === '') {
+        throw new Error('[genkaku:registry] expected a bare PeerId string (not a multiaddr)');
+    }
+    return keccak256(toBytes(PEER_TAG + peerId));
+}
+/** The content-policy code the worker declares with its registration. */
+export function policyHashOf(policy) {
+    return keccak256(toBytes(POLICY_TAG + policy));
+}
+/** The libp2p PeerId encoded in a worker multiaddr (the grain of the compare). */
+export function peerIdOf(addr) {
+    const tail = addr.split('/p2p/')[1];
+    if (tail != null && tail !== '') {
+        // trim any stray suffix (addresses end at the peer id in our dialer)
+        return tail.split('/')[0] || null;
+    }
+    return null;
+}
+/** The data-plane half of the binding: does the on-chain record for `wallet`
+ *  pin EXACTLY this PeerId? A record that is missing is `absent` (testnet
+ *  grace — the wallet may simply be unfunded); a PRESENT record that pins a
+ *  different PeerId is an active spoofing attempt and fails hard. */
+export function bindingOf(reg, peerId) {
+    if (reg == null || !reg.active) {
+        return 'absent';
+    }
+    return reg.peerId === peerIdDigestOf(peerId) ? 'bound' : 'mismatch';
+}
+//# sourceMappingURL=registry.js.map

package/dist/rpc.d.ts

@@ -0,0 +1,24 @@
+import { type Transport } from 'viem';
+import type { NetEnvironment } from './netconfig.ts';
+/** Public endpoints, measured reachable 2026-11. Order is a last-resort tie
+ *  break only — the probe reorders per machine, and `fallback` handles failures. */
+export declare const PUBLIC_RPC_ENDPOINTS: Record<NetEnvironment, readonly string[]>;
+/** Explicit override, then last-good endpoint, then the rest.
+ *  `GENKAKU_RPC_URL` is kept FIRST and not removed: if the operator's endpoint
+ *  dies mid-session we still want to keep serving from a public one. */
+export declare function rpcUrls(env: NetEnvironment): string[];
+/** Transport with automatic failover — the part the user never sees. */
+export declare function rpcTransport(env: NetEnvironment): Transport;
+/** One `eth_blockNumber` per endpoint, keep the fastest. Fire-and-forget at
+ *  boot; a failure leaves the previous preference untouched. */
+export declare function probeRpc(env: NetEnvironment, log?: {
+    info: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+}): Promise<string | null>;
+/** Human-readable network state for the dashboard (no input field anywhere). */
+export declare function rpcSummary(env: NetEnvironment): {
+    url: string;
+    cached: boolean;
+    override: boolean;
+};
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,MAAM,CAAA;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD;oFACoF;AACpF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAe1E,CAAA;AAyCD;;wEAEwE;AACxE,wBAAgB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,EAAE,CAgBrD;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,CAO3D;AAED;gEACgE;AAChE,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,cAAc,EACnB,GAAG,CAAC,EAAE;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,GACzG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA0CxB;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,GAAG,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CASnG"}

package/dist/rpc.js

@@ -0,0 +1,143 @@
+// GENKAKU: zero-config Base RPC (P4.9b).
+//
+// The product promise is "no fields to fill": a user or worker never sees an
+// RPC URL unless every endpoint is down. That rules out shipping a metered key
+// (an Electron app's asar is readable — a bundled unlimited key becomes someone
+// else's free tier) and rules out asking a non-technical operator to sign up.
+//
+// So: a small list of public endpoints, probed once at boot to find the fastest
+// healthy one, cached on disk, and wrapped in viem's `fallback` transport so a
+// 429 / 5xx / timeout mid-session rolls to the next endpoint without user
+// involvement. `GENKAKU_RPC_URL` still wins when set — that is the escape hatch
+// for development and for a power user who wants privacy, never a product
+// requirement.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fallback, http } from 'viem';
+/** Public endpoints, measured reachable 2026-11. Order is a last-resort tie
+ *  break only — the probe reorders per machine, and `fallback` handles failures. */
+export const PUBLIC_RPC_ENDPOINTS = {
+    'base-sepolia': [
+        'https://sepolia.base.org',
+        'https://base-sepolia-rpc.publicnode.com',
+        'https://base-sepolia.drpc.org',
+        'https://base-sepolia.gateway.tenderly.co',
+        'https://base-sepolia.public.blastapi.io',
+    ],
+    base: [
+        'https://mainnet.base.org',
+        'https://base-rpc.publicnode.com',
+        'https://base.drpc.org',
+        'https://gateway.tenderly.co/public/base',
+        'https://base-pokt.nodies.app',
+    ],
+};
+const PROBE_TIMEOUT_MS = 4_000;
+const REQUEST_TIMEOUT_MS = 10_000;
+function keyDir() {
+    const dir = process.env.GENKAKU_KEY_DIR?.trim();
+    return dir != null && dir !== '' ? dir : join(homedir(), '.dsh', 'genkaku');
+}
+function cachePath() {
+    return join(keyDir(), 'rpc.json');
+}
+function readCache() {
+    try {
+        if (!existsSync(cachePath()))
+            return { version: 1 };
+        const raw = JSON.parse(readFileSync(cachePath(), 'utf8'));
+        return raw?.version === 1 ? raw : { version: 1 };
+    }
+    catch {
+        return { version: 1 };
+    }
+}
+function writeCache(cache) {
+    try {
+        mkdirSync(keyDir(), { recursive: true });
+        writeFileSync(cachePath(), JSON.stringify(cache, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // a cache miss only costs one probe next boot
+    }
+}
+/** Explicit override, then last-good endpoint, then the rest.
+ *  `GENKAKU_RPC_URL` is kept FIRST and not removed: if the operator's endpoint
+ *  dies mid-session we still want to keep serving from a public one. */
+export function rpcUrls(env) {
+    const override = (process.env.GENKAKU_RPC_URL ?? '')
+        .split(',')
+        .map(s => s.trim())
+        .filter(s => s.startsWith('http'));
+    const preferred = readCache().preferred?.[env];
+    const publicList = PUBLIC_RPC_ENDPOINTS[env];
+    const ordered = [
+        ...override,
+        ...(preferred != null ? [preferred] : []),
+        ...publicList,
+    ];
+    return [...new Set(ordered)];
+}
+/** Transport with automatic failover — the part the user never sees. */
+export function rpcTransport(env) {
+    return fallback(rpcUrls(env).map(url => http(url, { timeout: REQUEST_TIMEOUT_MS, retryCount: 1 })), 
+    // Keep the configured order: ranking samples would re-probe on every
+    // failure burst, which is exactly when the endpoints are least healthy.
+    { rank: false });
+}
+/** One `eth_blockNumber` per endpoint, keep the fastest. Fire-and-forget at
+ *  boot; a failure leaves the previous preference untouched. */
+export async function probeRpc(env, log) {
+    const urls = rpcUrls(env);
+    const results = await Promise.all(urls.map(async (url) => {
+        const started = Date.now();
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                return null;
+            const body = await response.json();
+            if (typeof body.result !== 'string')
+                return null;
+            return { url, ms: Date.now() - started, block: body.result };
+        }
+        catch {
+            return null;
+        }
+    }));
+    const healthy = results.filter((r) => r != null);
+    if (healthy.length === 0) {
+        log?.warn('rpc: no endpoint answered a probe; requests will still try all of them');
+        return null;
+    }
+    healthy.sort((a, b) => a.ms - b.ms);
+    const best = healthy[0];
+    if (best == null)
+        return null;
+    const cache = readCache();
+    cache.preferred = { ...cache.preferred, [env]: best.url };
+    cache.latency = {
+        ...cache.latency,
+        [env]: Object.fromEntries(healthy.map(h => [h.url, h.ms])),
+    };
+    writeCache(cache);
+    log?.info('rpc: %s (%dms, block %s) — %d/%d endpoints healthy', best.url, best.ms, BigInt(best.block).toString(), healthy.length, urls.length);
+    return best.url;
+}
+/** Human-readable network state for the dashboard (no input field anywhere). */
+export function rpcSummary(env) {
+    const override = (process.env.GENKAKU_RPC_URL ?? '').trim() !== '';
+    const preferred = readCache().preferred?.[env];
+    const first = rpcUrls(env)[0] ?? '';
+    return {
+        url: override ? first : (preferred ?? first),
+        cached: preferred != null,
+        override,
+    };
+}
+//# sourceMappingURL=rpc.js.map

package/dist/status.d.ts

@@ -0,0 +1,56 @@
+import type { RoleMode } from './modeManager.ts';
+import type { OfferWire } from './offer.ts';
+/** One offer row rendered by the dashboard. */
+export type StatusOffer = {
+    /** peer multiaddr serving this row; omitted for a purely local catalog */
+    addr?: string;
+    offer: OfferWire;
+};
+/** Live facts the status server renders; called once per HTTP request. */
+export type StatusSnapshot = {
+    role: string;
+    peerId: string;
+    peerAddrs: string[];
+    wallet: string;
+    offers: StatusOffer[];
+    activeSessions: number;
+    /** true when at least one announced address is globally dialable (P4.9i) */
+    reachable: boolean;
+    /** config.publishAddress: may a public address be written to the chain? */
+    publishAddress: boolean;
+};
+export type StatusHandle = {
+    url: string;
+    close: () => Promise<void>;
+};
+/** One validated catalog row accepted by POST /genkaku/catalog. */
+export type CatalogEntryInput = {
+    model: string;
+    pricePerHour: number;
+    [key: string]: unknown;
+};
+/** Applies a validated catalog replacement; may be async. */
+export type CatalogUpdateHandler = (catalog: CatalogEntryInput[]) => void | Promise<void>;
+/** Applies a validated role-mode switch; may be async. */
+export type ModeUpdateHandler = (mode: RoleMode) => void | Promise<void>;
+/** Applies a directory-publishing opt-in; may be async. */
+export type PublishUpdateHandler = (publish: boolean) => void | Promise<void>;
+/** Worker-side Ollama control the onboarding panel drives. */
+export type OllamaControl = {
+    /** Detect the install, probe the service and list local models. */
+    state: () => Promise<unknown>;
+    /** Start a stopped service; idempotent. */
+    ensureRunning: () => Promise<unknown>;
+    /** Download a registry model, forwarding NDJSON-friendly progress. */
+    pull: (model: string, onProgress: (progress: {
+        status: string;
+        percent?: number;
+    }) => void) => Promise<{
+        status: string;
+    }>;
+    /** Delete one locally installed model. */
+    remove: (model: string) => Promise<void>;
+};
+/** Serve the dashboard and live status JSON on 127.0.0.1. */
+export declare function startStatusServer(port: number, snapshot: () => StatusSnapshot | Promise<StatusSnapshot>, onCatalog?: CatalogUpdateHandler, onMode?: ModeUpdateHandler, ollama?: OllamaControl, onPublish?: PublishUpdateHandler): Promise<StatusHandle>;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG;IACxB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,SAAS,CAAA;CACjB,CAAA;AAED,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,SAAS,EAAE,OAAO,CAAA;IAClB,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B,CAAA;AAED,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB,CAAA;AAED,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzF,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAExE,2DAA2D;AAC3D,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE7E,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC1B,mEAAmE;IACnE,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACrC,sEAAsE;IACtE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1H,0CAA0C;IAC1C,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzC,CAAA;AAsKD,6DAA6D;AAC7D,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,EACxD,SAAS,CAAC,EAAE,oBAAoB,EAChC,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,aAAa,EACtB,SAAS,CAAC,EAAE,oBAAoB,GAC/B,OAAO,CAAC,YAAY,CAAC,CA+LvB"}