@genkaku/protocol 0.0.0-stage → 0.1.0

package/dist/chain.js

@@ -0,0 +1,763 @@
+// GENKAKU: settlement layer bindings (P4.4) — JobEscrow v0.2 on Base Sepolia.
+// Writes are testnet-only until P6: env 'base' (mainnet) write paths throw.
+// Gas is paid by the calling wallet (user → open/settle; worker → claim,
+// self-paid per the locked design in contracts/README.md).
+//
+// Every digest goes through the packed hashing the escrow's `_verify`
+// recovers against, so wire-held receipts verify bit-for-bit on chain.
+// ABI DTOs are `as const` so viem's contract-call typing narrows exactly.
+import { createPublicClient, createWalletClient, decodeEventLog, encodePacked, keccak256, maxUint256, toBytes, } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { baseSepolia } from 'viem/chains';
+import { CONTRACTS } from "./netconfig.js";
+import { rpcTransport } from "./rpc.js";
+import { digestForHex, signDigest } from "./receipts.js";
+export const ESCROW_ABI = [
+    {
+        name: 'openSession',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'worker', type: 'address' },
+            { name: 'amount', type: 'uint128' },
+        ],
+        outputs: [{ name: 'id', type: 'uint256' }],
+    },
+    {
+        name: 'settle',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'id', type: 'uint256' },
+            { name: 'receiptHash', type: 'bytes32' },
+            { name: 'spend', type: 'uint128' },
+            { name: 'workerSig', type: 'bytes' },
+        ],
+        outputs: [],
+    },
+    {
+        name: 'claim',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [],
+        outputs: [],
+    },
+    {
+        name: 'refund',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'id', type: 'uint256' }],
+        outputs: [],
+    },
+    {
+        name: 'sessions',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'id', type: 'uint256' }],
+        outputs: [
+            { name: 'user', type: 'address' },
+            { name: 'worker', type: 'address' },
+            { name: 'amount', type: 'uint128' },
+            { name: 'openedAt', type: 'uint64' },
+            { name: 'settled', type: 'bool' },
+            { name: 'refunded', type: 'bool' },
+        ],
+    },
+    {
+        name: 'accrued',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'worker', type: 'address' }],
+        outputs: [{ name: 'balance', type: 'uint128' }],
+    },
+    {
+        name: 'SessionOpened',
+        type: 'event',
+        anonymous: false,
+        inputs: [
+            { name: 'id', type: 'uint256', indexed: true },
+            { name: 'user', type: 'address', indexed: true },
+            { name: 'worker', type: 'address', indexed: true },
+            { name: 'amount', type: 'uint128', indexed: false },
+        ],
+    },
+    {
+        name: 'SessionSettled',
+        type: 'event',
+        anonymous: false,
+        inputs: [
+            { name: 'id', type: 'uint256', indexed: true },
+            { name: 'worker', type: 'address', indexed: true },
+            { name: 'user', type: 'address', indexed: true },
+            { name: 'spend', type: 'uint128', indexed: false },
+            { name: 'fee', type: 'uint128', indexed: false },
+            { name: 'leftover', type: 'uint128', indexed: false },
+            { name: 'receiptHash', type: 'bytes32', indexed: false },
+        ],
+    },
+    {
+        name: 'SessionRefunded',
+        type: 'event',
+        anonymous: false,
+        inputs: [
+            { name: 'id', type: 'uint256', indexed: true },
+            { name: 'user', type: 'address', indexed: true },
+            { name: 'amount', type: 'uint128', indexed: false },
+        ],
+    },
+];
+/** Read the escrow record a client claims to have funded. The paywall (P4.9d)
+ *  refuses to serve unless this returns a live session that pays THIS worker. */
+export async function readEscrowSession(publicC, env, id) {
+    if (CONTRACTS[env].escrow === '')
+        return null;
+    const row = await publicC.readContract({
+        address: CONTRACTS[env].escrow,
+        abi: ESCROW_ABI,
+        functionName: 'sessions',
+        args: [id],
+        authorizationList: undefined,
+    });
+    const [user, worker, amount, openedAt, settled, refunded] = row;
+    if (user === '0x0000000000000000000000000000000000000000')
+        return null;
+    return { id, user, worker, amount, openedAt: Number(openedAt), settled, refunded };
+}
+/** WorkerRegistry v0.2 (P4.9a) — wallet ⇄ PeerId binding + on-chain directory.
+ *  Register/advertise writes are worker-key-gas (self-paid); reads are the
+ *  data-plane compare. The locator lives ONLY in the `WorkerLocated` log, so
+ *  the directory is rebuilt by scanning logs — never by storage reads. */
+export const REGISTRY_ABI = [
+    {
+        name: 'register',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'peerId', type: 'bytes32' },
+            { name: 'policyHash', type: 'bytes32' },
+        ],
+        outputs: [],
+    },
+    {
+        name: 'registerWithLocator',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'peerId', type: 'bytes32' },
+            { name: 'policyHash', type: 'bytes32' },
+            { name: 'locator', type: 'string' },
+        ],
+        outputs: [],
+    },
+    {
+        name: 'advertise',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [{ name: 'locator', type: 'string' }],
+        outputs: [],
+    },
+    {
+        name: 'selfDeactivate',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [],
+        outputs: [],
+    },
+    {
+        name: 'MAX_LOCATOR_BYTES',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    {
+        name: 'WorkerLocated',
+        type: 'event',
+        inputs: [
+            { name: 'wallet', type: 'address', indexed: true },
+            { name: 'peerId', type: 'bytes32', indexed: true },
+            { name: 'locator', type: 'string', indexed: false },
+            { name: 'updatedAt', type: 'uint64', indexed: false },
+        ],
+    },
+    {
+        name: 'WorkerDeactivated',
+        type: 'event',
+        inputs: [
+            { name: 'wallet', type: 'address', indexed: true },
+            { name: 'reason', type: 'string', indexed: false },
+        ],
+    },
+    {
+        name: 'workers',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: '', type: 'address' }],
+        outputs: [
+            { name: 'peerId', type: 'bytes32' },
+            { name: 'policyHash', type: 'bytes32' },
+            { name: 'registeredAt', type: 'uint64' },
+            { name: 'lastActiveAt', type: 'uint64' },
+            { name: 'active', type: 'bool' },
+        ],
+    },
+    {
+        name: 'isActive',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'wallet', type: 'address' }],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
+export const USDC_ABI = [{
+        name: 'approve',
+        type: 'function',
+        stateMutability: 'nonpayable',
+        inputs: [
+            { name: 'spender', type: 'address' },
+            { name: 'amount', type: 'uint256' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+    {
+        name: 'allowance',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'owner', type: 'address' },
+            { name: 'spender', type: 'address' },
+        ],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+    {
+        name: 'balanceOf',
+        type: 'function',
+        stateMutability: 'view',
+        inputs: [{ name: 'owner', type: 'address' }],
+        outputs: [{ name: '', type: 'uint256' }],
+    },
+];
+function viemChain(env) {
+    // P6 will add the mainnet chain object. Until then the ONLY wired chain is
+    // Base Sepolia — refusing keeps the chain type narrow for viem's contract
+    // typing and makes the mainnet write guard structural, not call-site.
+    if (env !== 'base-sepolia') {
+        throw new Error('[genkaku:chain] mainnet uses canonical USDC and a Safe treasury — locked for P6');
+    }
+    return baseSepolia;
+}
+/** Public reads. The transport is a failover list (P4.9b): a rate-limited or
+ *  dead endpoint rolls to the next one without surfacing anything to the user. */
+/** Explicit return type: viem's inferred client type points into its own
+ *  package-internal modules, which cannot be re-exported from a declaration. */
+export function publicClientFor(env) {
+    return createPublicClient({ chain: viemChain(env), transport: rpcTransport(env) });
+}
+/** Local-account wallet client — signs and pays gas itself. Writes go through
+ *  the same failover list, so a flaky endpoint cannot strand a registration. */
+/** Explicit return type, same reason as {@link publicClientFor}. */
+export function walletClientFor(env, key) {
+    return createWalletClient({
+        chain: viemChain(env),
+        transport: rpcTransport(env),
+        account: privateKeyToAccount(key),
+    });
+}
+// ── digests ────────────────────────────────────────────────────────────────
+/** The worker's settle co-sign digest: keccak256(abi.encodePacked(id,
+ *  receiptHash, spend)) — an EIP-191 signature over this is what settle's
+ *  `_verify` checks against the session's WORKER address. */
+export function settleDigest(escrowId, receiptHash, spend) {
+    // `spend` is a uint128 in JobEscrow, and abi.encodePacked uses the TYPE's
+    // width: packing it as uint256 shifted every byte after it, so the contract
+    // recovered a different signer (BadSignature) on every real settlement.
+    return toBytes(keccak256(encodePacked(['uint256', 'bytes32', 'uint128'], [escrowId, receiptHash, spend])));
+}
+/** The on-chain `receiptHash` argument: the digest of the worker-held max
+ *  cumulative receipt (bit-for-bit what both data-plane sides verify). */
+export function receiptHashFor(receipt) {
+    return digestForHex(receipt);
+}
+// ── read ───────────────────────────────────────────────────────────────────
+export async function readAccrued(publicC, env, worker) {
+    if (CONTRACTS[env].escrow === '') {
+        return 0n;
+    }
+    return await publicC.readContract({
+        address: CONTRACTS[env].escrow,
+        abi: ESCROW_ABI,
+        functionName: 'accrued',
+        args: [worker],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+        // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+        // it is ignored at runtime for non-EIP-7702 calls.
+        authorizationList: undefined,
+    });
+}
+/**
+ * Read the balances a user needs before opening an escrow: USDC to pay and ETH
+ * for gas. A chain without a deployed escrow still has canonical USDC.
+ * @param publicC - public client for the selected network.
+ * @param env - network whose USDC address is used.
+ * @param wallet - account to read.
+ * @returns gas and 6-decimal USDC balances.
+ */
+export async function readWalletBalances(publicC, env, wallet) {
+    const [eth, usdc] = await Promise.all([
+        publicC.getBalance({ address: wallet }),
+        publicC.readContract({
+            address: CONTRACTS[env].usdc,
+            abi: USDC_ABI,
+            functionName: 'balanceOf',
+            args: [wallet],
+            // Same viem 2.57 / TS 6.0 shape workaround as readAccrued above.
+            authorizationList: undefined,
+        }),
+    ]);
+    return { eth, usdc };
+}
+/** The worker account's own wallet address (P4.5 binds peerId ⇄ wallet via
+ *  WorkerRegistry; offers self-report it until then). */
+export function walletAddress(key) {
+    return privateKeyToAccount(key).address;
+}
+// ── writes ─────────────────────────────────────────────────────────────────
+/** Approve (only when the allowance is short) + open. The numeric escrow id
+ *  is parsed from SessionOpened's OWN log — never from a counter probe (a
+ *  concurrent open would desync the id). */
+export async function openEscrow(publicC, walletC, env, worker, amount) {
+    const escrow = CONTRACTS[env].escrow;
+    const usdc = CONTRACTS[env].usdc;
+    if (!escrow) {
+        throw new Error(`[genkaku:chain] no escrow deployed for ${env}`);
+    }
+    const allowance = await publicC.readContract({
+        address: usdc,
+        abi: USDC_ABI,
+        functionName: 'allowance',
+        args: [walletC.account.address, escrow],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+        // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+        // it is ignored at runtime for non-EIP-7702 calls.
+        authorizationList: undefined,
+    });
+    let approved = allowance;
+    if (allowance < amount) {
+        const approveHash = await walletC.writeContract({
+            address: usdc,
+            abi: USDC_ABI,
+            functionName: 'approve',
+            args: [escrow, maxUint256],
+            // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+            // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+            // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+            // it is ignored at runtime for non-EIP-7702 calls.
+            authorizationList: undefined,
+            chain: viemChain(env),
+            account: walletC.account,
+        });
+        await publicC.waitForTransactionReceipt({ hash: approveHash });
+        approved = maxUint256;
+    }
+    const openHash = await walletC.writeContract({
+        address: escrow,
+        abi: ESCROW_ABI,
+        functionName: 'openSession',
+        args: [worker, amount],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+        // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+        // it is ignored at runtime for non-EIP-7702 calls.
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+    const rc = await publicC.waitForTransactionReceipt({ hash: openHash });
+    const openLog = rc.logs.find(l => l.address.toLowerCase() === escrow.toLowerCase());
+    if (openLog == null) {
+        throw new Error('[genkaku:chain] open: no SessionOpened log in the open tx');
+    }
+    // TS6: viem's Log type drops `topics` (same TS6-only narrowing quirk as
+    // authorizationList). Bridge through unknown; the log is filtered to the
+    // escrow address above, and SessionOpened's args are runtime-guaranteed
+    // by the ABI.
+    const decoded = decodeEventLog({
+        abi: ESCROW_ABI,
+        data: openLog.data,
+        topics: openLog.topics,
+    });
+    if (decoded.eventName !== 'SessionOpened') {
+        throw new Error(`[genkaku:chain] open: unexpected event ${decoded.eventName}`);
+    }
+    const id = decoded.args.id;
+    if (id == null) {
+        throw new Error('[genkaku:chain] open: SessionOpened log without an id');
+    }
+    return { escrowId: id, approved };
+}
+export async function settleSession(walletC, env, args) {
+    return await walletC.writeContract({
+        address: CONTRACTS[env].escrow,
+        abi: ESCROW_ABI,
+        functionName: 'settle',
+        args: [args.escrowId, args.receiptHash, args.spend, args.workerSig],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+        // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+        // it is ignored at runtime for non-EIP-7702 calls.
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+}
+/** Reclaim an unsettled escrow. A short session can bill zero started minutes;
+ *  without this the funds would sit in the contract until the user found a
+ *  manual refund, which a non-technical user never will. */
+export async function refundSession(walletC, env, escrowId) {
+    return await walletC.writeContract({
+        address: CONTRACTS[env].escrow,
+        abi: ESCROW_ABI,
+        functionName: 'refund',
+        args: [escrowId],
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+}
+export async function claimAccrual(walletC, env) {
+    return await walletC.writeContract({
+        address: CONTRACTS[env].escrow,
+        abi: ESCROW_ABI,
+        functionName: 'claim',
+        args: [],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (TS5.9 keeps it optional — verified
+        // in /tmp/viem-typecheck). Explicit undefined restores the TS5 shape;
+        // it is ignored at runtime for non-EIP-7702 calls.
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+}
+// ── worker registry (P4.5: wallet ⇄ PeerId binding) ──────────────────────
+/** The chain view of one worker's registry record (null when never active). */
+export async function readWorker(publicC, env, wallet) {
+    if (CONTRACTS[env].registry === '') {
+        return null;
+    }
+    const w = await publicC.readContract({
+        address: CONTRACTS[env].registry,
+        abi: REGISTRY_ABI,
+        functionName: 'workers',
+        args: [wallet],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (see openEscrow's comment).
+        authorizationList: undefined,
+    });
+    // viem returns the struct as this tuple: peerId, policyHash, registeredAt,
+    // lastActiveAt, active.
+    const [peerId, policyHash, , , active] = w;
+    return active ? { active, peerId, policyHash } : null;
+}
+/** Register (or re-pin) the CALLER's wallet to its PeerId digest + policy.
+ *  The caller is the worker wallet itself (msg.sender == the binding) — the
+ *  desktop pays gas from the worker key. Testnet-only (viemChain refuses
+ *  mainnet until P6). */
+export async function registerWorker(walletC, env, args) {
+    if (CONTRACTS[env].registry === '') {
+        throw new Error(`[genkaku:chain] no registry deployed for ${env}`);
+    }
+    const txHash = await walletC.writeContract({
+        address: CONTRACTS[env].registry,
+        abi: REGISTRY_ABI,
+        functionName: 'register',
+        args: [args.peerIdDigest, args.policyHash],
+        // viem 2.57 types `authorizationList` as `any` but TypeScript 6.0.3
+        // promotes it to a REQUIRED position (see openEscrow's comment).
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+    await publicClientFor(env).waitForTransactionReceipt({ hash: txHash });
+    return { txHash };
+}
+/** First block that can hold a v0.2 directory entry (the scan floor). */
+export const REGISTRY_DEPLOY_BLOCK = {
+    'base-sepolia': 55900292n, // DeployRegistryV2, 2026-11-08
+    base: 0n, // set at mainnet launch
+};
+/** First block that can hold a v0.2 escrow session (same deployment batch). */
+export const ESCROW_DEPLOY_BLOCK = {
+    'base-sepolia': 55900292n,
+    base: 0n,
+};
+/** The contract's locator ceiling (mirrors MAX_LOCATOR_BYTES). */
+export const MAX_LOCATOR_BYTES = 256;
+/** Four addresses is enough for LAN + public + relay without paying for more. */
+export const MAX_LOCATOR_ADDRS = 4;
+/** Build the on-chain locator from the addresses libp2p actually announces.
+ *  Loopback is dropped (useless to a remote peer) and the list is capped so it
+ *  always fits MAX_LOCATOR_BYTES. Public addrs come first: a client that can
+ *  only use one should try the routable one. Separator is `;` — a multiaddr
+ *  never contains it, so parsing stays unambiguous. */
+export function locatorOf(addrs, maxBytes = MAX_LOCATOR_BYTES, maxCount = MAX_LOCATOR_ADDRS) {
+    const clean = [...new Set(addrs)]
+        .filter(a => a.startsWith('/'))
+        .filter(a => !a.startsWith('/ip4/127.') && !a.startsWith('/ip6/::1'))
+        .map(a => a.trim())
+        .filter(a => a.length > 0);
+    const rank = (a) => {
+        if (a.includes('/p2p-circuit/'))
+            return 2;
+        if (/^\/ip4\/(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(a))
+            return 1;
+        if (/^\/ip6\/(fc|fd|fe80)/.test(a))
+            return 1;
+        return 0;
+    };
+    const ordered = clean
+        .map((addr, index) => ({ addr, index, rank: rank(addr) }))
+        .sort((a, b) => a.rank - b.rank || a.index - b.index)
+        .map(x => x.addr);
+    const picked = [];
+    let bytes = 0;
+    for (const addr of ordered) {
+        if (picked.length >= maxCount)
+            break;
+        const extra = addr.length + (picked.length > 0 ? 1 : 0);
+        if (bytes + extra > maxBytes)
+            continue;
+        picked.push(addr);
+        bytes += extra;
+    }
+    return picked.join(';');
+}
+/** True when this address is reachable from the public internet. LAN, loopback,
+ *  link-local and CGNAT (100.64/10) ranges are local-only; a relay address is
+ *  signaling, not a data path (P4.9g). A user-supplied DNS name is trusted. */
+export function isPublicAddr(addr) {
+    if (!addr.startsWith('/'))
+        return false;
+    if (addr.includes('/p2p-circuit/'))
+        return false;
+    const v4 = /^\/ip4\/(\d+)\.(\d+)\.(\d+)\.(\d+)\//.exec(addr);
+    if (v4 != null) {
+        const a = Number(v4[1]);
+        const b = Number(v4[2]);
+        if (a === 0 || a === 10 || a === 127)
+            return false;
+        if (a === 172 && b >= 16 && b <= 31)
+            return false;
+        if (a === 192 && b === 168)
+            return false;
+        if (a === 169 && b === 254)
+            return false;
+        if (a === 100 && b >= 64 && b <= 127)
+            return false;
+        return true;
+    }
+    const v6 = /^\/ip6\/([0-9a-f:]+)\//i.exec(addr);
+    if (v6 != null) {
+        const host = v6[1].toLowerCase();
+        if (host === '::1')
+            return false;
+        if (host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80'))
+            return false;
+        return true;
+    }
+    return /^\/dns(4|6|addr)\//.test(addr);
+}
+/** Does this peer announce any address the global directory can use? Without
+ *  one, on-chain presence only advertises a dead end (P4.9g §39). */
+export function hasPublicAddr(addrs) {
+    return addrs.some(isPublicAddr);
+}
+/** Split a locator back into multiaddrs (tolerates `;`, newline, whitespace). */
+export function parseLocator(locator) {
+    return locator
+        .split(/[;\n]+/)
+        .map(s => s.trim())
+        .filter(s => s.startsWith('/'));
+}
+/** Register (or re-pin) AND publish the locator in one transaction. */
+export async function registerWorkerWithLocator(walletC, env, args) {
+    if (CONTRACTS[env].registry === '') {
+        throw new Error(`[genkaku:chain] no registry deployed for ${env}`);
+    }
+    const txHash = await walletC.writeContract({
+        address: CONTRACTS[env].registry,
+        abi: REGISTRY_ABI,
+        functionName: 'registerWithLocator',
+        args: [args.peerIdDigest, args.policyHash, args.locator],
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+    await publicClientFor(env).waitForTransactionReceipt({ hash: txHash });
+    return txHash;
+}
+/** Publish a new locator for an already-registered worker. Only call this when
+ *  the announced address set actually changed — each call is a chain write. */
+export async function advertiseWorker(walletC, env, locator) {
+    if (CONTRACTS[env].registry === '') {
+        throw new Error(`[genkaku:chain] no registry deployed for ${env}`);
+    }
+    const txHash = await walletC.writeContract({
+        address: CONTRACTS[env].registry,
+        abi: REGISTRY_ABI,
+        functionName: 'advertise',
+        args: [locator],
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+    await publicClientFor(env).waitForTransactionReceipt({ hash: txHash });
+    return txHash;
+}
+/** Remove this wallet from the live directory. Used when a worker loses the
+ *  public address it advertised — a stale entry is worse than none. */
+export async function deactivateWorker(walletC, env) {
+    if (CONTRACTS[env].registry === '') {
+        throw new Error(`[genkaku:chain] no registry deployed for ${env}`);
+    }
+    const txHash = await walletC.writeContract({
+        address: CONTRACTS[env].registry,
+        abi: REGISTRY_ABI,
+        functionName: 'selfDeactivate',
+        args: [],
+        authorizationList: undefined,
+        chain: viemChain(env),
+        account: walletC.account,
+    });
+    await publicClientFor(env).waitForTransactionReceipt({ hash: txHash });
+    return txHash;
+}
+function registryEvent(name) {
+    const found = REGISTRY_ABI.find(entry => entry.type === 'event' && entry.name === name);
+    if (found == null || found.type !== 'event') {
+        throw new Error('[genkaku:chain] registry ABI is missing event ' + name);
+    }
+    return found;
+}
+/** Walk a block range, halving it whenever the RPC refuses the span.
+ *  Public Base endpoints disagree wildly on `eth_getLogs` limits (some reject
+ *  even a single block), so the scan floor is discovered at runtime instead of
+ *  assumed. */
+export async function collectLogs(publicC, address, event, fromBlock, toBlock, args, depth = 0) {
+    try {
+        // viem's getLogs overloads narrow on the literal event object; the event
+        // here is chosen at runtime from REGISTRY_ABI, so the generic cannot be
+        // inferred and the call is widened once, here.
+        const client = publicC;
+        return await client.getLogs({ address, event, args, fromBlock, toBlock });
+    }
+    catch (error) {
+        if (fromBlock >= toBlock || depth > 24)
+            throw error;
+        const mid = fromBlock + (toBlock - fromBlock) / 2n;
+        const [left, right] = await Promise.all([
+            collectLogs(publicC, address, event, fromBlock, mid, args, depth + 1),
+            collectLogs(publicC, address, event, mid + 1n, toBlock, args, depth + 1),
+        ]);
+        return [...left, ...right];
+    }
+}
+/** Rebuild the worker directory from chain logs — the whole point of P4.9a.
+ *  Returns only entries still live: a wallet whose LAST directory-relevant
+ *  event is `WorkerDeactivated` is dropped (the tombstone stays in history,
+ *  which is exactly what an auditor needs). */
+export async function readWorkerLocators(publicC, env, opts = {}) {
+    const registry = CONTRACTS[env].registry;
+    if (CONTRACTS[env].registry === '')
+        return [];
+    const latest = opts.toBlock ?? (await publicC.getBlockNumber());
+    const floor = opts.fromBlock ?? REGISTRY_DEPLOY_BLOCK[env];
+    if (latest < floor)
+        return [];
+    const chunkSize = opts.chunkSize ?? 50000n;
+    const from = floor;
+    const to = latest;
+    const locatedEvent = registryEvent('WorkerLocated');
+    const deactivatedEvent = registryEvent('WorkerDeactivated');
+    const located = [];
+    const tombstone = new Map();
+    for (let start = from; start <= to; start += chunkSize) {
+        const end = start + chunkSize - 1n > to ? to : start + chunkSize - 1n;
+        const walletFilter = opts.wallet != null ? { wallet: opts.wallet } : undefined;
+        const [locatedLogs, deadLogs] = await Promise.all([
+            collectLogs(publicC, registry, locatedEvent, start, end, walletFilter),
+            collectLogs(publicC, registry, deactivatedEvent, start, end, walletFilter),
+        ]);
+        for (const log of locatedLogs) {
+            const a = log.args;
+            located.push({
+                wallet: a.wallet,
+                peerId: a.peerId,
+                locator: a.locator,
+                updatedAt: Number(a.updatedAt),
+                blockNumber: log.blockNumber ?? 0n,
+            });
+        }
+        for (const log of deadLogs) {
+            const a = log.args;
+            const key = a.wallet.toLowerCase();
+            const block = log.blockNumber ?? 0n;
+            const prev = tombstone.get(key);
+            if (prev == null || block > prev)
+                tombstone.set(key, block);
+        }
+    }
+    // newest locator per wallet, then drop wallets whose last event was a death
+    const newest = new Map();
+    for (const entry of located) {
+        const key = entry.wallet.toLowerCase();
+        const prev = newest.get(key);
+        if (prev == null || entry.blockNumber > prev.blockNumber
+            || (entry.blockNumber === prev.blockNumber && entry.updatedAt >= prev.updatedAt)) {
+            newest.set(key, entry);
+        }
+    }
+    const out = [];
+    for (const [key, entry] of newest) {
+        const deadAt = tombstone.get(key);
+        if (deadAt != null && deadAt > entry.blockNumber)
+            continue;
+        out.push({
+            wallet: entry.wallet,
+            peerId: entry.peerId,
+            locator: entry.locator,
+            addrs: parseLocator(entry.locator),
+            updatedAt: entry.updatedAt,
+            blockNumber: entry.blockNumber,
+        });
+    }
+    return out.sort((a, b) => (a.blockNumber === b.blockNumber ? 0 : a.blockNumber < b.blockNumber ? 1 : -1));
+}
+/** Wallets that tombstoned themselves in a block range. Incremental readers
+ *  need these separately: `readWorkerLocators` only reports live entries for
+ *  the range it scanned, so a cached entry must be evicted by a later death. */
+export async function readWorkerDeactivations(publicC, env, opts) {
+    const registry = CONTRACTS[env].registry;
+    if (CONTRACTS[env].registry === '')
+        return [];
+    const to = opts.toBlock ?? (await publicC.getBlockNumber());
+    const chunkSize = opts.chunkSize ?? 50000n;
+    const event = registryEvent('WorkerDeactivated');
+    const out = [];
+    for (let start = opts.fromBlock; start <= to; start += chunkSize) {
+        const end = start + chunkSize - 1n > to ? to : start + chunkSize - 1n;
+        const logs = await collectLogs(publicC, registry, event, start, end);
+        for (const log of logs) {
+            const a = log.args;
+            out.push({ wallet: a.wallet, blockNumber: log.blockNumber ?? 0n });
+        }
+    }
+    return out;
+}
+/** Receipt signing re-export (single crypto door for callers). */
+export async function signReceiptPayload(key, receipt) {
+    return await signDigest(key, toBytes(digestForHex(receipt)));
+}
+//# sourceMappingURL=chain.js.map