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

package/dist/core/units.js

@@ -0,0 +1,122 @@
+import { concat, keccak256, toUtf8Bytes } from "ethers";
+import { accountRef, dataUriJcs, erc721Ref, jcs, keccakUtf8 } from "./canonical.js";
+import { eventArgs } from "./world.js";
+export function elementId(kind, ref) {
+    return keccak256(concat([toUtf8Bytes(kind), new Uint8Array([0x3a]), toUtf8Bytes(ref)]));
+}
+export function unitRefString(chainId, registry, unitId, version) {
+    return `auf:eip155:${chainId}:${registry.toLowerCase()}:${unitId}@${version}`;
+}
+/** The unit of a single cell: the agent element, its treasury position and the deliverable/funds ports. */
+export function cellUnitDefinition(p) {
+    const agent = { kind: "agent", ref: accountRef(p.chainId, p.cell), label: `${p.name} (cell account)` };
+    const treasury = { kind: "financial-position", ref: accountRef(p.chainId, p.cell), label: "cell account balance" };
+    return {
+        auf: "1.0",
+        kind: "unit-definition",
+        unit: { name: p.name, summary: p.summary ?? "A FOGA cell: one address acting under the ten-ERC stack", tags: ["foga", "cell"] },
+        elements: [agent, treasury],
+        relations: [
+            { type: "owns", from: "unit", to: elementId(agent.kind, agent.ref), exclusive: true, share: "1", basis: ["erc8434:anchor"] },
+            { type: "holds", from: "unit", to: elementId(treasury.kind, treasury.ref), quantity: { amount: "0", unit: "ETH" }, scope: "native balance of the cell account" },
+        ],
+        ports: [
+            { id: "deliverable-out", direction: "out", class: "deliverable", template: "auf:port:deliverable-out@1", conditions: "accepted fulfillments on ERC-8414 tenders" },
+            { id: "funds-in", direction: "in", class: "funds", template: "auf:port:funds-in@1", asset: `eip155:${p.chainId}/slip44:60`, account: accountRef(p.chainId, p.cell), conditions: "tender rewards and service fees" },
+            { id: "funds-out", direction: "out", class: "funds", template: "auf:port:funds-out@1", asset: `eip155:${p.chainId}/slip44:60`, account: accountRef(p.chainId, p.cell), conditions: "gas and purchased services" },
+        ],
+        authorities: { definitionController: accountRef(p.chainId, p.cell), settlementAccounts: [accountRef(p.chainId, p.cell)] },
+    };
+}
+/** The unit of a skill token held by a cell: a source element the cell licenses out. */
+export function skillUnitDefinition(p) {
+    const skill = { kind: "skill", ref: erc721Ref(p.chainId, p.skillToken, p.tokenId), label: p.name };
+    return {
+        auf: "1.0",
+        kind: "unit-definition",
+        unit: { name: p.name, summary: p.summary ?? "An ERC-8338 skill package as an economic source", tags: ["foga", "skill", "source"] },
+        elements: [skill],
+        relations: [{ type: "owns", from: "unit", to: elementId(skill.kind, skill.ref), exclusive: true, share: "1", basis: ["erc8338:owner"] }],
+        ports: [
+            { id: "calls-out", direction: "out", class: "deliverable", template: "auf:port:deliverable-out@1", conditions: "executions of the skill" },
+            { id: "fees-in", direction: "in", class: "funds", template: "auf:port:funds-in@1", asset: `eip155:${p.chainId}/slip44:60`, account: accountRef(p.chainId, p.holder), conditions: "per-call fees and tender rewards earned with the skill" },
+        ],
+        authorities: { definitionController: accountRef(p.chainId, p.holder), settlementAccounts: [accountRef(p.chainId, p.holder)] },
+    };
+}
+export class Units {
+    world;
+    constructor(world) {
+        this.world = world;
+    }
+    registry(runner) {
+        return this.world.contract("8454/AUFUnitRegistry", runner);
+    }
+    get registryAddress() {
+        return this.world.address("8454/AUFUnitRegistry");
+    }
+    boundaryHash(def) {
+        return keccakUtf8(jcs(def));
+    }
+    encodeRegisterUnit(controller, def, contains = []) {
+        return this.registry().interface.encodeFunctionData("registerUnit", [controller, this.boundaryHash(def), dataUriJcs(def), contains.map((c) => [c.unitId, c.version])]);
+    }
+    async registerUnit(signer, controller, def, contains = []) {
+        const planned = (await this.unitCount()) + 1n;
+        const tx = await this.registry(signer).registerUnit(controller, this.boundaryHash(def), dataUriJcs(def), contains.map((c) => [c.unitId, c.version]));
+        const receipt = await tx.wait();
+        return { unitId: planned, receipt };
+    }
+    unitIdFromReceipt(receipt) {
+        return BigInt(eventArgs(this.registry().interface, receipt, "UnitRegistered", this.registryAddress).unitId);
+    }
+    async unitCount() {
+        return BigInt(await this.registry().unitCount());
+    }
+    async controllerOf(unitId) {
+        return this.registry().controllerOf(unitId);
+    }
+    async latestVersion(unitId) {
+        return Number(await this.registry().latestVersion(unitId));
+    }
+    async versionOf(unitId, version) {
+        const v = await this.registry().versionOf(unitId, version);
+        return { boundaryHash: v.boundaryHash ?? v[0], descriptorURI: v.descriptorURI ?? v[1] };
+    }
+    // ---- the assertion registry (observations, valuations, descriptors) ----
+    assertions(runner) {
+        return this.world.contract("8454/AUFAssertionRegistry", runner);
+    }
+    get assertionRegistryAddress() {
+        return this.world.address("8454/AUFAssertionRegistry");
+    }
+    encodeRegisterDescriptor(descriptorHash, kind, uri) {
+        return this.assertions().interface.encodeFunctionData("registerDescriptor", [descriptorHash, kind, uri]);
+    }
+    encodeAssertStatement(input) {
+        return this.assertions().interface.encodeFunctionData("assertStatement", [input]);
+    }
+    assertionIdFromReceipt(receipt) {
+        return eventArgs(this.assertions().interface, receipt, "Asserted", this.assertionRegistryAddress).assertionId;
+    }
+    async descriptorOf(hash) {
+        try {
+            const d = await this.assertions().descriptorOf(hash);
+            return { publisher: d.publisher ?? d[0], kind: d.descriptorKind ?? d[1], registeredAt: Number(d.registeredAt ?? d[2]), uri: d.uri ?? d[3] };
+        }
+        catch {
+            return null;
+        }
+    }
+    async assertionOf(assertionId) {
+        const a = await this.assertions().assertionOf(assertionId);
+        return { kind: Number(a.kind), status: Number(a.status), byController: Boolean(a.byController), version: Number(a.version), asserter: a.asserter, unitId: BigInt(a.unitId), profileId: a.profileId, contentHash: a.contentHash, contentURI: a.contentURI, validFrom: Number(a.validFrom), validUntil: Number(a.validUntil) };
+    }
+    async observationOf(assertionId) {
+        const o = await this.assertions().observationCoreOf(assertionId);
+        return { snapshotHash: o.snapshotHash ?? o[0], windowStart: Number(o.windowStart ?? o[1]), windowEnd: Number(o.windowEnd ?? o[2]) };
+    }
+    async assertionCount(unitId, version) {
+        return Number(await this.assertions().assertionCount(unitId, version));
+    }
+}

package/dist/core/world.js

@@ -0,0 +1,104 @@
+import { Contract, Interface } from "ethers";
+import { PinnedProvider } from "../kernel/provider.js";
+import { loadBundle } from "../bundle/load.js";
+import { readJson } from "../util/fs.js";
+/**
+ * A handle on one world instance: the address book plus the ABIs of everything in it (from the bundle),
+ * so every module can open a typed ethers Contract by step id ("8414/TaskToken") without carrying ABIs
+ * around. Contracts FOGA deploys during a scenario (cell accounts, adapters) are registered on the handle
+ * with the bundle key they were built from.
+ */
+export class World {
+    file;
+    bundle;
+    provider;
+    extras;
+    dynamic = new Map();
+    constructor(file, bundle, provider) {
+        this.file = file;
+        this.bundle = bundle;
+        this.provider = provider;
+        this.extras = bundle.extras;
+    }
+    static load(worldPath, rpc, bundlePath) {
+        const file = readJson(worldPath);
+        if (file.schema !== "foga.world/1")
+            throw new Error(`${worldPath} is not a world file`);
+        const bundle = loadBundle(bundlePath);
+        const url = rpc ?? process.env.FOGA_RPC_URL ?? (file.network === "anvil" ? "http://127.0.0.1:8545" : undefined);
+        if (!url)
+            throw new Error("no RPC: pass --rpc or set FOGA_RPC_URL");
+        // Reads are pinned to the highest block the provider has seen (kernel/provider.ts): a public endpoint is a
+        // cluster whose nodes lag each other by a block, and the kernel reads what it has just written.
+        const provider = new PinnedProvider(url, undefined, { staticNetwork: true, cacheTimeout: -1 });
+        // A local node answers in microseconds and mines on demand; a public endpoint is shared, rate-limited and
+        // makes a block every 12 s, so it is asked a few times per block, not several times per second.
+        provider.pollingInterval = file.network === "anvil" ? 250 : 4_000;
+        return new World(file, bundle, provider);
+    }
+    get chainId() {
+        return this.file.chainId;
+    }
+    has(id) {
+        return Boolean(this.file.contracts[id] || this.dynamic.get(id));
+    }
+    address(id) {
+        const entry = this.file.contracts[id] ?? this.dynamic.get(id);
+        if (!entry)
+            throw new Error(`world ${this.file.worldId} has no contract ${id}`);
+        return entry.address;
+    }
+    bundleKeyOf(id) {
+        const entry = this.file.contracts[id] ?? this.dynamic.get(id);
+        if (!entry?.bundleKey)
+            throw new Error(`world contract ${id} has no bundle key`);
+        return entry.bundleKey;
+    }
+    artifact(bundleKey) {
+        const c = this.bundle.contracts[bundleKey];
+        if (!c)
+            throw new Error(`bundle has no contract ${bundleKey}`);
+        return c;
+    }
+    abi(id) {
+        return this.artifact(this.bundleKeyOf(id)).abi;
+    }
+    iface(id) {
+        return new Interface(this.abi(id));
+    }
+    ifaceOf(bundleKey) {
+        return new Interface(this.artifact(bundleKey).abi);
+    }
+    /** Open a world contract; pass a signer to send transactions. */
+    contract(id, runner) {
+        return new Contract(this.address(id), this.abi(id), runner ?? this.provider);
+    }
+    /** Open any address with the ABI of a bundle contract. */
+    at(bundleKey, address, runner) {
+        return new Contract(address, this.artifact(bundleKey).abi, runner ?? this.provider);
+    }
+    /** Register a scenario-deployed contract under a step id for later lookups. */
+    attach(id, address, bundleKey) {
+        this.dynamic.set(id, { address, bundleKey });
+    }
+    async blockTimestamp() {
+        const b = await this.provider.getBlock("latest");
+        return Number(b.timestamp);
+    }
+}
+/** Decode the first event of a given name from a receipt using an Interface. */
+export function eventArgs(iface, receipt, 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`);
+}

package/dist/demo/demander.js

@@ -0,0 +1,76 @@
+import { Wallet } from "ethers";
+import { join } from "node:path";
+import { dataUri, keccakJcs, sha256Hex } from "../core/canonical.js";
+import { hashlock, nativeTerms } from "../core/tenders.js";
+import { extractVerifyFile } from "../genesis/extract.js";
+import { runProbe } from "../genesis/probe.js";
+import { Kernel } from "../kernel/kernel.js";
+import { repoRoot } from "../util/fs.js";
+export const ALL_CASES = ["a", "b", "c", "d", "d2", "e", "f"];
+/** A small deterministic generator (mulberry32), so a seed reproduces the order and the probe block. */
+export function prng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function shuffle(items, rnd) {
+    const out = [...items];
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(rnd() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out;
+}
+const DAY = 86400;
+export async function mintCases(opts) {
+    const log = opts.log ?? (() => { });
+    const k = await Kernel.open({ worldPath: opts.worldPath, rpc: opts.rpc, storePath: opts.storePath, keys: { demander: opts.key } });
+    try {
+        const me = new Wallet(opts.key).address;
+        const rnd = prng(opts.seed);
+        const reward = opts.rewardWei ?? 1000000000000000n; // 0.001 ETH
+        const below = opts.belowFloorWei ?? 100000000000000n; // 0.0001 ETH
+        const root = repoRoot();
+        const head = await k.blockNumber();
+        const probeBlock = Math.max(1, head - Math.floor(rnd() * Math.min(head - 1, 50)));
+        const probeInput = { subject: opts.cell, block: probeBlock, lookback: 9000, kya: { schemeId: opts.schemeId, issuers: opts.issuers } };
+        const probeAnswer = (await runProbe(k.world, probeInput)).answer;
+        const fixture = join(root, "scenarios", "fixtures", "sample-filing.txt");
+        const extractAnswer = extractVerifyFile(fixture, join(root, "scenarios", "skills", "finch-extract-verify", "fields.json"), opts.packages["finch-extract-verify"]).canonical;
+        const specs = {
+            a: { skill: "foga-probe", packageHash: opts.packages["foga-probe"], input: probeInput, answer: probeAnswer, rewardWei: reward, submitIn: DAY, settleIn: 7 * DAY, expect: { outcome: "taken" }, note: `foga-probe of the cell at block ${probeBlock}` },
+            b: { skill: "finch-extract-verify", packageHash: opts.packages["finch-extract-verify"], input: { document: "sample-filing.txt" }, answer: extractAnswer, rewardWei: reward, submitIn: DAY, settleIn: 7 * DAY, expect: { outcome: "taken" }, note: "finch-extract-verify over the fixture named by file name" },
+            c: { skill: "foga-oracle", packageHash: "0x" + "ab".repeat(32), input: { question: "what is the price" }, answer: "unknown", rewardWei: reward, submitIn: DAY, settleIn: 7 * DAY, expect: { outcome: "refused", gate: "skill" }, note: "a skill the cell does not have" },
+            d: { skill: "foga-probe", packageHash: opts.packages["foga-probe"], input: probeInput, answer: probeAnswer, rewardWei: below, submitIn: DAY, settleIn: 7 * DAY, expect: { outcome: "refused", gate: "policy" }, note: "a reward below the policy floor" },
+            d2: { skill: "foga-probe", packageHash: opts.packages["foga-probe"], input: probeInput, answer: probeAnswer, rewardWei: reward, submitIn: 120, settleIn: 7 * DAY, expect: { outcome: "refused", gate: "policy" }, note: "a submit deadline too close" },
+            e: { skill: "foga-probe", packageHash: opts.packages["foga-probe"], input: probeInput, answer: null, rewardWei: reward, submitIn: DAY, settleIn: 7 * DAY, authority: me, expect: { outcome: "refused", gate: "verifier" }, note: "a judged tender with the demander as its authority" },
+            f: { skill: "foga-probe", packageHash: opts.packages["foga-probe"], input: probeInput, answer: probeAnswer, rewardWei: reward, submitIn: DAY, settleIn: 7 * DAY, expect: { outcome: "refused-then-taken", gate: "safety" }, note: "a tender like a, met during the guardian's suspension" },
+        };
+        const out = [];
+        for (const id of shuffle(opts.cases, rnd)) {
+            const p = specs[id];
+            const t0 = await k.blockTimestamp();
+            const answerHash = p.answer === null ? "0x" + "11".repeat(32) : hashlock.answerHash(p.answer);
+            const task = { schema: "foga.task/1", skill: p.skill, packageHash: p.packageHash, input: p.input, acceptance: { mode: "verifier", profile: "x-hashlock-v1", verifier: k.tenders.hashlockAddress, answerHash }, deliverable: `loop D case ${id}: ${p.note}` };
+            const terms = nativeTerms(p.rewardWei, { submitBy: BigInt(t0 + p.submitIn), settleBy: BigInt(t0 + p.settleIn) });
+            const key = `demand.${opts.seed}.${id}`;
+            const m = await k.call(`${key}.mint`, "demander", k.tenders.address, k.tenders.contract().interface, "mintTask", [me, me, p.authority ?? k.tenders.hashlockAddress, keccakJcs({ td: "foga.task/1", skill: p.skill }), sha256Hex(JSON.stringify(task)), dataUri(task), terms]);
+            const tokenId = k.tenders.tokenIdFromReceipt(m.receipt);
+            await k.call(`${key}.fund`, "demander", k.tenders.address, k.tenders.contract().interface, "fundTask", [tokenId, p.rewardWei], p.rewardWei);
+            if (!p.authority)
+                await k.call(`${key}.commit`, "demander", k.tenders.hashlockAddress, k.tenders.hashlockVerifier().interface, "commitAnswer", [k.tenders.address, tokenId, answerHash]);
+            out.push({ id, tokenId: tokenId.toString(), skill: p.skill, rewardWei: p.rewardWei.toString(), submitBy: t0 + p.submitIn, settleBy: t0 + p.settleIn, expect: p.expect, note: p.note, answer: p.answer, mintTx: m.txHash });
+            log(`demander: case ${id} is tender ${tokenId} (${p.note}; expect ${p.expect.outcome}${"gate" in p.expect ? ` at ${p.expect.gate}` : ""})`);
+        }
+        return { demander: me, cases: out };
+    }
+    finally {
+        k.close();
+        k.world.provider.destroy();
+    }
+}

package/dist/demo/evidence.js

@@ -0,0 +1 @@
+export {};