@finchip.ai/foga 0.0.0-stage → 0.6.0-alpha.4

package/dist/kernel/kernel.js

@@ -0,0 +1,251 @@
+import { Interface, Wallet, getCreateAddress } from "ethers";
+import { ACDF } from "../core/acdf.js";
+import { ADRF } from "../core/adrf.js";
+import { AID } from "../core/aid.js";
+import { ARD } from "../core/ard.js";
+import { ASF } from "../core/asf.js";
+import { ERC8004_ABI, Identity8004 } from "../core/erc8004.js";
+import { KYA } from "../core/kya.js";
+import { Skills } from "../core/skills.js";
+import { Swarms } from "../core/swarm.js";
+import { Tenders } from "../core/tenders.js";
+import { Units } from "../core/units.js";
+import { World } from "../core/world.js";
+import { OperationStore } from "./store.js";
+import { TxManager } from "./tx.js";
+/**
+ * The kernel: one world, one operation store, the signers the node holds, and the ten protocol modules opened on
+ * that world. Everything that changes chain state goes through `tx` (idempotent by key); everything a later step
+ * or a resumed run needs is a fact in the store; everything a reviewer needs is evidence.
+ */
+export class Kernel {
+    world;
+    store;
+    options;
+    tx;
+    signers;
+    kya;
+    aid;
+    asf;
+    ard;
+    units;
+    skills;
+    tenders;
+    identity;
+    acdf;
+    adrf;
+    swarms;
+    evidenceList = [];
+    constructor(world, store, keys, options) {
+        this.world = world;
+        this.store = store;
+        this.options = options;
+        this.signers = Object.fromEntries(Object.entries(keys).map(([name, pk]) => [name, new Wallet(pk, world.provider)]));
+        // a public endpoint is usually a cluster: after a receipt, wait until the cluster answers from that block before reading
+        this.tx = new TxManager(world.provider, store, this.signers, { awaitVisibility: world.file.network !== "anvil", ...options });
+        // reads are pinned to the last seen block (kernel/provider.ts); a read that had to give the pin up is part of the record
+        const pinned = world.provider;
+        if ("pin" in world.provider)
+            pinned.onLag = (e) => {
+                store.journal("pinned-read", e);
+                options.log?.(`  rpc: ${e.method} at block ${e.block} refused ${e.attempts} time(s) by the endpoint (${e.nodeError}); ${e.outcome === "re-pinned" ? "read at the head the endpoint reports instead" : "giving up: the run stops here and resumes from its store"}`);
+            };
+        this.kya = new KYA(world);
+        this.aid = new AID(world);
+        this.asf = new ASF(world);
+        this.ard = new ARD(world);
+        this.units = new Units(world);
+        this.skills = new Skills(world);
+        this.tenders = new Tenders(world);
+        this.identity = new Identity8004(world);
+        this.acdf = new ACDF(world);
+        this.adrf = new ADRF(world);
+        this.swarms = new Swarms(world);
+        for (const id of Object.keys(world.file.contracts)) {
+            if (id === "identity8004")
+                continue;
+            try {
+                this.tx.decoder.add(world.iface(id), id);
+            }
+            catch {
+                /* no ABI for this entry */
+            }
+        }
+        this.tx.decoder.add(world.ifaceOf("foga:FogaCellAccount"), "foga:FogaCellAccount");
+        for (const key of ["swarm-ai-framework:SwarmAccount", "swarm-ai-framework:SwarmDecisionAdapter", "swarm-ai-framework:CompositeEligibility", "swarm-ai-framework:AssertionLevelEligibility", "acd-framework:ACDFTaskTenderAdapter", "kya-standard:Groth16KYAVerifierAdapter", "foga:Groth16PredicateKYAVerifierAdapter", "ai-dispute-resolution:ADRFErrors", "ai-dispute-resolution:IADRFDisputeRegistry", "ai-dispute-resolution:ADRFACDFBridge"]) {
+            try {
+                this.tx.decoder.add(world.ifaceOf(key), key);
+            }
+            catch {
+                /* not in this bundle */
+            }
+        }
+        this.tx.decoder.add(new Interface(ERC8004_ABI), "erc8004");
+    }
+    static async open(opts) {
+        const world = World.load(opts.worldPath, opts.rpc, opts.bundlePath);
+        const store = OperationStore.open(opts.storePath);
+        const net = await world.provider.getNetwork();
+        if (Number(net.chainId) !== world.chainId)
+            throw new Error(`RPC chain ${net.chainId} is not the world's chain ${world.chainId}`);
+        // Seed the read pin with the chain's head (kernel/provider.ts). A replayed run sees only the receipts of its old
+        // operations, whose blocks must not become the pin: reads are about the chain as it is now, not as it was then.
+        await world.provider.getBlockNumber();
+        // A store belongs to one chain instance and one world: the hash of block 0 tells a restarted local chain from
+        // a resumed one; the world id and chain id tell a store opened against the wrong world file.
+        const genesis = (await world.provider.getBlock(0))?.hash ?? "unknown";
+        const known = store.getMeta("genesisBlockHash");
+        if (known && known !== genesis) {
+            throw new Error(`operation store ${opts.storePath} belongs to a chain whose block 0 is ${known}; this RPC's block 0 is ${genesis}. The chain was reset: delete the store (or pass a fresh --store) to start over.`);
+        }
+        const knownWorld = store.getMeta("worldId");
+        if (knownWorld && knownWorld !== world.file.worldId) {
+            throw new Error(`operation store ${opts.storePath} belongs to world ${knownWorld}, not to ${world.file.worldId} (${opts.worldPath}). Point it at its own world file or start a fresh store.`);
+        }
+        const knownChain = store.getMeta("chainId");
+        if (knownChain && knownChain !== String(world.chainId)) {
+            throw new Error(`operation store ${opts.storePath} belongs to chain ${knownChain}, not to chain ${world.chainId}.`);
+        }
+        if (!known)
+            store.setMeta("genesisBlockHash", genesis);
+        if (!knownChain)
+            store.setMeta("chainId", String(world.chainId));
+        if (!knownWorld)
+            store.setMeta("worldId", world.file.worldId);
+        const { worldPath: _w, rpc: _r, bundlePath: _b, storePath: _s, keys, ...txOptions } = opts;
+        return new Kernel(world, store, keys, txOptions);
+    }
+    close() {
+        this.store.close();
+    }
+    get chainId() {
+        return this.world.chainId;
+    }
+    signer(name) {
+        return this.tx.signer(name);
+    }
+    address(signerName) {
+        return this.signer(signerName).address;
+    }
+    // ---------------------------------------------------------------------------- sending
+    /**
+     * Call a function on a contract as an EOA signer. `gasLimit` overrides the estimate for calls whose outcome
+     * depends on the gas left (a registry that treats a module's `false` with little gas left as unevaluable).
+     */
+    async call(key, signer, target, iface, fn, args, value = 0n, kind = "call", gasLimit) {
+        return this.tx.send({ key, signer, kind, build: () => ({ to: target, data: iface.encodeFunctionData(fn, args), value, ...(gasLimit ? { gasLimit } : {}) }) });
+    }
+    /** Deploy a bundle contract as an EOA signer. The predicted address is derived from the signer's nonce. */
+    async deploy(key, signer, bundleKey, args = [], onPredict) {
+        const artifact = this.world.artifact(bundleKey);
+        if (!artifact.deployable)
+            throw new Error(`${bundleKey} is not deployable`);
+        if (Object.keys(artifact.linkReferences ?? {}).length)
+            throw new Error(`${bundleKey} needs library linking; not supported by Kernel.deploy`);
+        const iface = new Interface(artifact.abi);
+        const confirmed = await this.tx.send({
+            key,
+            signer,
+            kind: "deploy",
+            build: ({ nonce, from }) => {
+                const predicted = getCreateAddress({ from, nonce });
+                const finalArgs = (onPredict && onPredict(predicted)) || args;
+                const ctor = iface.deploy;
+                const data = artifact.bytecode + (ctor.inputs.length ? iface.encodeDeploy(finalArgs).slice(2) : "");
+                return { data };
+            },
+        });
+        const address = confirmed.receipt.contractAddress;
+        if (!address)
+            throw new Error(`deployment ${key} has no contract address in its receipt`);
+        return { address, confirmed };
+    }
+    async transfer(key, signer, to, value) {
+        return this.tx.send({ key, signer, kind: "transfer", build: () => ({ to, value }) });
+    }
+    // ---------------------------------------------------------------------------- facts and evidence
+    fact(key) {
+        return this.store.getFact(key);
+    }
+    requireFact(key) {
+        return this.store.requireFact(key);
+    }
+    setFact(key, value) {
+        this.store.setFact(key, value);
+    }
+    /**
+     * A value fixed the first time it is computed and read back on every later run. Anything that enters a
+     * transaction and depends on the clock or on chain state at run time (deadlines, block numbers) goes through
+     * here, so a resumed run rebuilds exactly the inputs the recorded transactions were made from.
+     */
+    async memo(key, compute) {
+        const have = this.store.getFact(key);
+        if (have !== undefined)
+            return have;
+        const value = await compute();
+        this.store.setFact(key, value);
+        return value;
+    }
+    /** Record what a reviewer needs to check a step; kept in the store and in the run's evidence file. */
+    evidence(step, label, values) {
+        const rec = { step, label, values, at: new Date().toISOString() };
+        this.evidenceList.push(rec);
+        this.store.setFact(`evidence.${step}.${label}`, values);
+    }
+    evidenceRecords() {
+        return [...this.evidenceList];
+    }
+    // ---------------------------------------------------------------------------- views
+    contract(id, runner) {
+        return this.world.contract(id, runner);
+    }
+    async balance(address) {
+        return this.world.provider.getBalance(address);
+    }
+    async blockNumber() {
+        return this.world.provider.getBlockNumber();
+    }
+    async blockTimestamp() {
+        return this.world.blockTimestamp();
+    }
+    /** True for a local development chain whose clock the kernel may move. */
+    get isLocalChain() {
+        return this.world.file.network === "anvil";
+    }
+    /**
+     * Let `seconds` of chain time pass. On anvil the clock is moved and a block mined (recorded in the journal:
+     * a skipped interval is part of the evidence); on any other chain the kernel waits for real time.
+     */
+    async advanceTime(seconds, why) {
+        const before = await this.blockTimestamp();
+        if (this.isLocalChain) {
+            await this.world.provider.send("evm_increaseTime", [seconds]);
+            await this.world.provider.send("evm_mine", []);
+            const after = await this.blockTimestamp();
+            this.store.journal("time-skipped", { seconds, from: before, to: after, why });
+            return;
+        }
+        const target = before + seconds;
+        this.store.journal("time-waited", { seconds, from: before, until: target, why });
+        this.options.log?.(`  wait: ${seconds} s of chain time (${why}); until ${new Date(target * 1000).toISOString()}`);
+        while ((await this.blockTimestamp()) < target)
+            await new Promise((r) => setTimeout(r, 5_000));
+        this.options.log?.(`  wait: over (${why})`);
+    }
+    /** Decode the first event `name` from a receipt with the ABI of world contract `id` (or any interface). */
+    event(receipt, iface, name, address) {
+        for (const log of receipt.logs) {
+            if (address && log.address.toLowerCase() !== address.toLowerCase())
+                continue;
+            try {
+                const parsed = iface.parseLog({ topics: [...log.topics], data: log.data });
+                if (parsed && parsed.name === name)
+                    return parsed.args;
+            }
+            catch {
+                /* not ours */
+            }
+        }
+        throw new Error(`event ${name} not found in receipt ${receipt.hash}`);
+    }
+}

package/dist/kernel/provider.js

@@ -0,0 +1,125 @@
+import { JsonRpcProvider, toQuantity } from "ethers";
+/**
+ * A JSON-RPC provider that reads what it has written. A public RPC URL usually fronts a cluster whose nodes import a
+ * block at slightly different times; a read or a gas estimate made right after a receipt can reach a node that has not
+ * seen the block yet and answer from the state before it (on Sepolia the roster of a swarm read as not met one second
+ * after its third join confirmed; a call opened in one block was "unknown" to the estimate of its delivery in the next).
+ *
+ * The provider keeps a pin: the highest block it has seen in a receipt, a block header or a block number. Every state
+ * read at "latest" (eth_call, eth_estimateGas, eth_getBalance, eth_getCode, eth_getStorageAt, eth_getTransactionCount at
+ * "latest") is sent at that block instead, so a node behind the pin answers with an error rather than with stale state,
+ * and the request is retried until a node that has the block answers. Explicit block tags, "pending" and everything that
+ * is not a state read pass through unchanged. On a single local node the pin is always the node's own tip.
+ *
+ * The pin must start at the chain's head (the kernel reads the block number when it opens): the receipts a replayed
+ * run reads back are old, and a pin seeded from them would make every read a read of the past — a document read as
+ * its earlier version, a swarm read as still active — which is what the first Sepolia replays did.
+ */
+const BLOCK_PARAM = { eth_call: 1, eth_estimateGas: 1, eth_getBalance: 1, eth_getCode: 1, eth_getTransactionCount: 1, eth_getStorageAt: 2 };
+// what the clients of a public cluster say when asked about a block they do not (yet) have the state of: geth ("header
+// not found", "missing trie node"), erigon and reth ("block not found"), nethermind ("historical state ... is not
+// available", which it also says for a block one behind its own head), besu ("Block not found"), and a few gateways
+const BEHIND = /header not found|unknown block|block not found|missing trie node|cannot query|beyond|out of range|unknown header|no state|historical state|state (is )?not available|not available|pruned|too old|invalid block|resource not found/i;
+export class PinnedProvider extends JsonRpcProvider {
+    /** The highest block seen; reads are made no earlier than this. */
+    pin = 0;
+    /** Milliseconds to keep retrying a read that a lagging node refused before re-sampling the head and, failing that, raising. */
+    settleMs = 60_000;
+    /** Told when a pinned read ran out of retries (the kernel journals it). */
+    onLag;
+    constructor(url, network, options) {
+        super(url, network, options);
+    }
+    async send(method, params) {
+        const idx = BLOCK_PARAM[method];
+        const tag = idx === undefined ? undefined : params[idx];
+        const pinnable = idx !== undefined && this.pin > 0 && (tag === undefined || tag === null || tag === "latest");
+        if (!pinnable) {
+            const result = await super.send(method, params);
+            this.observe(method, params, result);
+            return result;
+        }
+        const pinned = [...params];
+        while (pinned.length <= idx)
+            pinned.push("latest");
+        const block = this.pin;
+        pinned[idx] = toQuantity(block);
+        const deadline = Date.now() + this.settleMs;
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await super.send(method, pinned);
+            }
+            catch (e) {
+                // ethers wraps a node's error (a call's as CALL_EXCEPTION, "missing revert data"); the node's own words are in info.error
+                const text = [e?.info?.error?.message, e?.error?.message, e?.shortMessage, e?.message].filter(Boolean).join(" | ");
+                // a contract's revert is an answer, not a lag: it is never retried
+                const reverted = /execution reverted/i.test(text) || Boolean(e?.data) || Boolean(e?.revert);
+                if (reverted)
+                    throw e;
+                const behind = BEHIND.test(text);
+                if (behind && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, Math.min(2_000, 250 * attempt)));
+                    continue;
+                }
+                // The lag outlasted the retries, or the refusal is one we do not recognize. A read at "latest" is not an
+                // option: the node that refuses an explicit block may be the one that is hours behind, and a stale answer is
+                // worse than no answer (it fails checks that hold on chain). Instead the head is sampled again: when the pin
+                // came from a node ahead of the rest, it is lowered to what the endpoint reports now and the read made there,
+                // once; otherwise the error is raised with the node's own words, and the run resumes from its store.
+                const head = await this.sampleHead();
+                if (head > 0 && head < block && pinned[idx] !== toQuantity(head)) {
+                    this.pin = head;
+                    pinned[idx] = toQuantity(head);
+                    try {
+                        const result = await super.send(method, pinned);
+                        this.onLag?.({ method, block, attempts: attempt, nodeError: text, outcome: "re-pinned" });
+                        return result;
+                    }
+                    catch (e2) {
+                        this.raise(e2, method, block, attempt, text);
+                    }
+                }
+                this.raise(e, method, block, attempt, text);
+            }
+        }
+    }
+    /** The highest block number three consecutive samples of the endpoint report (an outlier ahead is not followed twice). */
+    async sampleHead() {
+        const seen = [];
+        for (let i = 0; i < 3; i++) {
+            try {
+                seen.push(parseInt(await super.send("eth_blockNumber", []), 16));
+            }
+            catch {
+                /* a sample that fails is left out */
+            }
+            if (i < 2)
+                await new Promise((r) => setTimeout(r, 300));
+        }
+        seen.sort((a, b) => a - b);
+        return seen.length ? seen[Math.floor(seen.length / 2)] : 0;
+    }
+    raise(e, method, block, attempts, text) {
+        this.onLag?.({ method, block, attempts, nodeError: text, outcome: "raised" });
+        if (e && typeof e === "object" && typeof e.message === "string")
+            e.message += ` [read at block ${block} refused ${attempts} time${attempts === 1 ? "" : "s"} by the endpoint: ${text}]`;
+        throw e;
+    }
+    /** Move the pin forward from what the chain tells us. */
+    observe(method, params, result) {
+        let n = null;
+        if (method === "eth_blockNumber" && typeof result === "string")
+            n = parseInt(result, 16);
+        else if (method === "eth_getTransactionReceipt" && result?.blockNumber)
+            n = parseInt(result.blockNumber, 16);
+        else if (method === "eth_getBlockByNumber" && result?.number && (params[0] === "latest" || params[0] === "pending"))
+            n = parseInt(result.number, 16);
+        if (n !== null && Number.isFinite(n) && n > this.pin)
+            this.pin = n;
+    }
+    /** The kernel confirms a receipt: nothing is read before its block from now on. */
+    advanceTo(block) {
+        if (block > this.pin)
+            this.pin = block;
+    }
+}