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

package/prover/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "foga-prover",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Proving-side dependencies of the ERC-8419 credential-pattern ZK path (kya-public-v1), kept apart from the kernel's own dependencies",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "circomlibjs": "0.1.7",
+    "snarkjs": "0.7.6"
+  },
+  "devDependencies": {
+    "circom2": "^0.2.23",
+    "circomlib": "^2.0.5"
+  }
+}

package/prover/run.cjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// Bridge between the kernel and the upstream prover of kya-standard (companions/zk-kya-groth16/prover.js):
+// reads one JSON job on stdin, writes one JSON result on stdout. The upstream module and its dependencies
+// (snarkjs, circomlibjs, ethers) are resolved from this directory's node_modules, which `npm run zk:install`
+// populates; the kernel's own dependency tree stays free of them.
+//
+// Jobs:
+//   { "op": "root",   "attestors": [<32-byte hex private key>, ...] }
+//        -> { "root": bytes32, "attestors": [{ "pub": [hex, hex], "leaf": hex }] }
+//   { "op": "commit", "secret": <hex> }
+//        -> { "commitment": hex }                        Poseidon(secret): what the attestor signs
+//   { "op": "attest", "attestor": <hex prv>, "claim": {...}, "commitment": <hex> }
+//        -> { "sig": { "R8x", "R8y", "S" } }              the attestor never sees the secret
+//   { "op": "prove",  "issuerPubs": [[hex, hex], ...], "attestorPub": [hex, hex], "claim": {...}, "secret": <hex>,
+//                     "sig": {...}, "epoch": <decimal string>, "admissionDomain": bytes32 }
+//        -> { "publicInputs": hex, "proof": hex, "nullifier": bytes32, "publicSignals": [...] }
+//        the prover holds the secret and public material only; no attestor private key is involved
+// claim = { subjectKey, schemeId, level, claimDigest, expiresAt }.
+//
+// Predicate-pattern jobs (FOGA's own circuit zk/circuits/kya_predicate_count_v1.circom, built by
+// prover/build-predicate.mjs into zk/build; FOGA_ZK_PREDICATE_DIR overrides the build directory):
+//   { "op": "record.sign", "source": <hex prv>, "record": { "subjectKey": bytes32, "taskRef": <hex, 128-bit>,
+//                          "status": <number>, "timestamp": <number> } }
+//        -> { "sig": { "R8x", "R8y", "S" }, "pub": [hex, hex], "message": hex }
+//        a source signs one task-completion record about a subject; the same `root` job gives the source set
+//   { "op": "predicate.prove", "sourcePubs": [[hex, hex], ...], "sourcePub": [hex, hex], "subjectKey": bytes32,
+//                              "records": [{ "taskRef", "status", "timestamp", "sig" }], "challenge": bytes32,
+//                              "t0", "t1", "k": <number>, "schemeId": bytes32, "epoch": <decimal string>,
+//                              "admissionDomain": bytes32, "secret": <hex> }
+//        -> { "publicInputs": hex, "proof": hex, "nullifier": bytes32, "result": 0|1, "count": n,
+//             "publicSignals": [...], "verified": bool }
+//        records are sorted by taskRef (which must be distinct) and padded to the circuit's N slots
+"use strict";
+const path = require("node:path");
+const Module = require("node:module");
+
+const root = __dirname;
+process.env.NODE_PATH = path.join(root, "node_modules") + (process.env.NODE_PATH ? path.delimiter + process.env.NODE_PATH : "");
+Module._initPaths();
+
+const upstream = process.env.FOGA_ZK_PROVER || path.join(root, "..", "vendor", "kya-standard", "companions", "zk-kya-groth16", "prover.js");
+const predicateDir = process.env.FOGA_ZK_PREDICATE_DIR || path.join(root, "..", "zk", "build");
+const PREDICATE = { name: "kya_predicate_count_v1", slots: 8, depth: 16 };
+const MASK128 = (1n << 128n) - 1n;
+const split128 = (hex) => {
+  const v = BigInt(hex);
+  return [v >> 128n, v & MASK128];
+};
+
+function toBig(hex) {
+  return BigInt(hex);
+}
+
+function attestorFromPrv(zk, prvHex) {
+  const prv = Buffer.from(prvHex.replace(/^0x/, ""), "hex");
+  if (prv.length !== 32) throw new Error("attestor private key must be 32 bytes");
+  const pubP = zk.eddsa.prv2pub(prv);
+  const pub = [zk.F.toObject(pubP[0]), zk.F.toObject(pubP[1])];
+  return { prv, pub, leaf: zk.H(pub[0], pub[1]) };
+}
+
+/** The signed message, as the circuit recomputes it, from the secret's Poseidon commitment. */
+function messageFromCommitment(zk, claim, commitment) {
+  const split = (hex) => {
+    const v = BigInt(hex);
+    return [v >> 128n, v & ((1n << 128n) - 1n)];
+  };
+  const [skHi, skLo] = split(claim.subjectKey);
+  const [siHi, siLo] = split(claim.schemeId);
+  const [cdHi, cdLo] = split(claim.claimDigest);
+  return zk.H(skHi, skLo, siHi, siLo, BigInt(claim.level), cdHi, cdLo, BigInt(claim.expiresAt), toBig(commitment));
+}
+
+/** Poseidon(5) over a task-completion record, as the predicate circuit recomputes it. */
+function recordMessage(zk, subjectKey, record) {
+  const [skHi, skLo] = split128(subjectKey);
+  const taskRef = BigInt(record.taskRef);
+  if (taskRef < 0n || taskRef > MASK128) throw new Error("taskRef must be a 128-bit value");
+  return zk.H(skHi, skLo, taskRef, BigInt(record.status), BigInt(record.timestamp));
+}
+
+async function provePredicate(zk, job) {
+  // ethers v6 from the repository root (this sub-package's own tree holds the v5 that circomlibjs depends on)
+  const { ethers } = require(require.resolve("ethers", { paths: [path.join(root, "..")] }));
+  const snarkjs = require("snarkjs");
+  const coder = ethers.AbiCoder.defaultAbiCoder();
+  const wasm = path.join(predicateDir, `${PREDICATE.name}_js`, `${PREDICATE.name}.wasm`);
+  const zkey = path.join(predicateDir, `${PREDICATE.name}_final.zkey`);
+  const vkeyPath = path.join(predicateDir, "verification_key.json");
+  for (const f of [wasm, zkey]) if (!require("node:fs").existsSync(f)) throw new Error(`predicate proving material missing: ${f} (run: node prover/build-predicate.mjs)`);
+
+  const pubs = job.sourcePubs.map(([x, y]) => [toBig(x), toBig(y)]);
+  const set = zk.issuerSet(pubs); // the source set: the same Poseidon Merkle tree (depth 16) as the issuer set
+  const sourcePub = [toBig(job.sourcePub[0]), toBig(job.sourcePub[1])];
+  const leaf = zk.H(sourcePub[0], sourcePub[1]);
+  const idx = set.leaves.indexOf(leaf);
+  if (idx < 0) throw new Error("source not in the source set");
+  const { pathElements, pathIndices } = set.proofFor(idx);
+
+  const records = job.records.map((r) => ({ taskRef: BigInt(r.taskRef), status: BigInt(r.status), timestamp: BigInt(r.timestamp), sig: r.sig }));
+  records.sort((a, b) => (a.taskRef < b.taskRef ? -1 : a.taskRef > b.taskRef ? 1 : 0));
+  for (let i = 1; i < records.length; i++) if (records[i].taskRef === records[i - 1].taskRef) throw new Error("records must have distinct taskRefs");
+  if (records.length > PREDICATE.slots) throw new Error(`at most ${PREDICATE.slots} records per proof`);
+  const n = PREDICATE.slots;
+  const slot = (f, pad) => Array.from({ length: n }, (_, i) => (i < records.length ? f(records[i]) : pad));
+
+  const [skHi, skLo] = split128(job.subjectKey);
+  const [chHi, chLo] = split128(job.challenge);
+  const [rtHi, rtLo] = split128(set.rootHex);
+  const [siHi, siLo] = split128(job.schemeId);
+  const [adHi, adLo] = split128(job.admissionDomain);
+  const t0 = BigInt(job.t0);
+  const t1 = BigInt(job.t1);
+  const k = BigInt(job.k);
+  const epoch = BigInt(job.epoch);
+  const input = {
+    subjectKeyHi: skHi, subjectKeyLo: skLo, challengeHi: chHi, challengeLo: chLo, t0, t1, k,
+    sourceSetRootHi: rtHi, sourceSetRootLo: rtLo, schemeIdHi: siHi, schemeIdLo: siLo, epoch,
+    admissionDomainHi: adHi, admissionDomainLo: adLo,
+    secret: toBig(job.secret), Ax: sourcePub[0], Ay: sourcePub[1], pathElements, pathIndices,
+    present: slot(() => 1n, 0n),
+    taskRef: slot((r) => r.taskRef, 0n),
+    status: slot((r) => r.status, 0n),
+    timestamp: slot((r) => r.timestamp, 0n),
+    S: slot((r) => BigInt(r.sig.S), 0n),
+    R8x: slot((r) => toBig(r.sig.R8x), 0n),
+    R8y: slot((r) => toBig(r.sig.R8y), 0n),
+  };
+  const { proof, publicSignals } = await snarkjs.groth16.fullProve(input, wasm, zkey);
+  const nullifier = ethers.toBeHex((BigInt(publicSignals[0]) << 128n) | BigInt(publicSignals[1]), 32);
+  const result = Number(publicSignals[2]);
+  const count = records.filter((r) => r.status === 1n && r.timestamp >= t0 && r.timestamp <= t1).length;
+  const publicInputs = coder.encode(
+    ["bytes32", "bytes32", "bytes32", "uint64", "uint64", "uint16", "bytes32", "uint64", "uint8"],
+    [job.subjectKey, nullifier, job.challenge, t0, t1, k, set.rootHex, epoch, result],
+  );
+  const proofBytes = coder.encode(
+    ["uint256[2]", "uint256[2][2]", "uint256[2]"],
+    [[proof.pi_a[0], proof.pi_a[1]], [[proof.pi_b[0][1], proof.pi_b[0][0]], [proof.pi_b[1][1], proof.pi_b[1][0]]], [proof.pi_c[0], proof.pi_c[1]]],
+  );
+  let verified = null;
+  if (require("node:fs").existsSync(vkeyPath)) verified = await snarkjs.groth16.verify(JSON.parse(require("node:fs").readFileSync(vkeyPath, "utf8")), publicSignals, proof);
+  return { publicInputs, proof: proofBytes, nullifier, result, count, publicSignals: publicSignals.map(String), verified };
+}
+
+async function main() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(Buffer.from(c));
+  const job = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  const { ZK } = require(upstream);
+  const zk = await ZK.create();
+  const hex32 = (v) => "0x" + BigInt(v).toString(16).padStart(64, "0");
+
+  let out;
+  if (job.op === "root") {
+    const atts = job.attestors.map((p) => attestorFromPrv(zk, p));
+    const set = zk.issuerSet(atts.map((a) => a.pub));
+    out = { root: set.rootHex, attestors: atts.map((a) => ({ pub: [hex32(a.pub[0]), hex32(a.pub[1])], leaf: hex32(a.leaf) })) };
+  } else if (job.op === "commit") {
+    out = { commitment: hex32(zk.H(toBig(job.secret))) };
+  } else if (job.op === "attest") {
+    const attestor = attestorFromPrv(zk, job.attestor);
+    const m = zk.F.e(messageFromCommitment(zk, job.claim, job.commitment));
+    const s = zk.eddsa.signPoseidon(attestor.prv, m);
+    out = { sig: { R8x: hex32(zk.F.toObject(s.R8[0])), R8y: hex32(zk.F.toObject(s.R8[1])), S: s.S.toString() } };
+  } else if (job.op === "prove") {
+    const pubs = job.issuerPubs.map(([x, y]) => [toBig(x), toBig(y)]);
+    const set = zk.issuerSet(pubs);
+    const pub = [toBig(job.attestorPub[0]), toBig(job.attestorPub[1])];
+    const attestor = { pub, leaf: zk.H(pub[0], pub[1]) };
+    const sig = { R8x: toBig(job.sig.R8x), R8y: toBig(job.sig.R8y), S: BigInt(job.sig.S) };
+    const r = await zk.prove({
+      ...job.claim,
+      epoch: BigInt(job.epoch),
+      admissionDomain: job.admissionDomain,
+      secret: toBig(job.secret),
+      attestor,
+      sig,
+      set,
+    });
+    out = { publicInputs: r.publicInputs, proof: r.proof, nullifier: r.nullifier, publicSignals: r.publicSignals.map(String) };
+  } else if (job.op === "record.sign") {
+    const source = attestorFromPrv(zk, job.source);
+    const m = recordMessage(zk, job.record.subjectKey, job.record);
+    const sg = zk.eddsa.signPoseidon(source.prv, zk.F.e(m));
+    out = { sig: { R8x: hex32(zk.F.toObject(sg.R8[0])), R8y: hex32(zk.F.toObject(sg.R8[1])), S: sg.S.toString() }, pub: [hex32(source.pub[0]), hex32(source.pub[1])], message: hex32(m) };
+  } else if (job.op === "predicate.prove") {
+    out = await provePredicate(zk, job);
+  } else {
+    throw new Error(`unknown op ${job.op}`);
+  }
+  process.stdout.write(JSON.stringify(out));
+  process.exit(0);
+}
+
+main().catch((e) => {
+  process.stderr.write(String(e && e.stack ? e.stack : e));
+  process.exit(1);
+});

package/scenarios/fixtures/sample-filing.txt

@@ -0,0 +1,16 @@
+EXAMPLE HOLDINGS LTD
+Condensed interim financial statement (synthetic fixture for the FOGA genesis; no real company)
+
+Document date: 2026-08-15
+Issuer: Example Holdings Ltd
+Period end: 2026-06-30
+Reporting currency: USD thousands
+
+BALANCE SHEET
+Total assets: 1,250
+Total liabilities: 800
+Total equity: 450
+
+NOTES
+1. The figures above are invented for a software test and carry no financial meaning.
+2. Total equity equals total assets less total liabilities by construction.

package/scenarios/skills/finch-extract-verify/LICENSE

@@ -0,0 +1,2 @@
+Apache License 2.0. This skill package is part of the Finch OG Agent repository; the full license text is the
+repository's LICENSE file.

package/scenarios/skills/finch-extract-verify/SKILL.md

@@ -0,0 +1,34 @@
+# finch-extract-verify
+
+Extract named fields from a fixed-version public document and verify their mutual consistency.
+
+## What the skill does
+
+The input is one document pinned by content hash (a filing, a published report, a specification) and a field
+list (`fields.json`). The skill extracts each field as it appears in the document, records where it was found,
+checks the consistency rules the field list declares (totals that must add up, dates that must be ordered,
+identifiers that must match across sections) and produces a deliverable with the extracted values, the
+evidence spans and the verdict of every rule.
+
+This is the first business task of a FOGA cell: structured extraction plus consistency checking over a fixed
+version of public material, with the output judged by a reader or by a council (ERC-8436), not by a hash.
+
+## Inputs
+
+| name        | type   | meaning                                                                    |
+|-------------|--------|----------------------------------------------------------------------------|
+| document    | bytes  | the pinned document; its sha256 must equal `documentDigest`                |
+| documentDigest | string | `sha256:<hex>` of the document                                          |
+| fields      | object | the field list and rules (`fields.json` by default)                        |
+
+## Output
+
+A JSON deliverable: `{ "schema": "finch.extract-verify/1", "documentDigest", "fields": { name: { "value",
+"evidence": [{ "page", "quote" }] } }, "rules": [{ "id", "verdict": "pass" | "fail" | "unknown", "note" }] }`.
+
+## Rules
+
+1. Values are copied, never computed, unless a rule says a derived value is expected.
+2. Every value carries at least one evidence span.
+3. A field that cannot be found yields `null` and the rules that depend on it yield `unknown`.
+4. The deliverable states the document digest it was produced from.

package/scenarios/skills/finch-extract-verify/fields.json

@@ -0,0 +1,56 @@
+{
+  "schema": "finch.extract-verify.fields/1",
+  "fields": [
+    {
+      "name": "issuer",
+      "kind": "text",
+      "label": "Issuer",
+      "where": "cover page"
+    },
+    {
+      "name": "documentDate",
+      "kind": "date",
+      "label": "Document date",
+      "where": "cover page"
+    },
+    {
+      "name": "periodEnd",
+      "kind": "date",
+      "label": "Period end",
+      "where": "cover page"
+    },
+    {
+      "name": "totalAssets",
+      "kind": "amount",
+      "label": "Total assets",
+      "where": "balance sheet"
+    },
+    {
+      "name": "totalLiabilities",
+      "kind": "amount",
+      "label": "Total liabilities",
+      "where": "balance sheet"
+    },
+    {
+      "name": "totalEquity",
+      "kind": "amount",
+      "label": "Total equity",
+      "where": "balance sheet"
+    }
+  ],
+  "rules": [
+    {
+      "id": "balance",
+      "check": "totalAssets == totalLiabilities + totalEquity",
+      "tolerance": "1"
+    },
+    {
+      "id": "period",
+      "check": "periodEnd is a calendar date not after documentDate"
+    }
+  ],
+  "extraction": {
+    "method": "line-label",
+    "description": "A field's value is the text after `<label>:` on the first line that starts with the label; amounts drop thousands separators; dates are ISO 8601."
+  }
+}

package/scenarios/skills/finch-extract-verify/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0",
+  "name": "finch-extract-verify",
+  "skillVersion": "1.0.0",
+  "summary": "Extract named fields from a fixed-version public document and verify their mutual consistency",
+  "entrypoint": "SKILL.md",
+  "skillType": "business",
+  "scopes": ["read:document"],
+  "standard": "ERC-8338",
+  "x-entry-profile": "llm-markdown-v1",
+  "x-foga": {
+    "runner": "foga.kernel.llm/1",
+    "deterministic": false,
+    "fields": "fields.json"
+  }
+}

package/scenarios/skills/foga-probe/LICENSE

@@ -0,0 +1,2 @@
+Apache License 2.0. This skill package is part of the Finch OG Agent repository; the full license text is the
+repository's LICENSE file.

package/scenarios/skills/foga-probe/SKILL.md

@@ -0,0 +1,35 @@
+# foga-probe
+
+Probe one address against the ten-ERC agent stack at one block and produce a canonical report.
+
+## What the skill does
+
+Given a subject address, a block number and the world's address book, read — at that block and only through
+view calls — what each of the ten registries says about the subject, and emit one JSON document in RFC 8785
+canonical form. The report is deterministic: two independent runs against the same chain, block and inputs
+produce byte-identical output. That is what makes it usable as the known answer of a hashlock tender
+(ERC-8414, profile x-hashlock-v1): the demander runs it first and commits `sha256(report)`; a fulfiller runs it
+again and settles by revealing the same bytes.
+
+## Inputs
+
+| name      | type                 | meaning                                                             |
+|-----------|----------------------|---------------------------------------------------------------------|
+| subject   | address              | the account to probe                                                |
+| block     | integer              | the block at which every read is made                               |
+| lookback  | integer (optional)   | how many blocks before `block` the log-based sections scan (from `block - lookback`, at least 0); absent, from the chain's first block. Public endpoints cap the range of a log query, so a task on such a chain names one |
+| kya       | object               | `{ "schemeId": bytes32, "issuers": [address] }` — the standing scheme and the issuers the report trusts |
+| world     | string               | the world id (address book) the probe reads                         |
+
+## Output
+
+`foga.probe/1` — see `probe.schema.json`. Sections, one per standard: erc8004, erc8434, erc8419, erc8468,
+erc8444, erc8454, erc8338, erc8414, erc8447, erc8436, erc8471. Every number is a decimal string, every address
+is lower-case, the block hash is included so a report is bound to one chain history.
+
+## Rules
+
+1. Read at `block`; never at `latest`. Logs are read from `block - lookback` to `block`.
+2. Never write. The skill has no transaction.
+3. No clocks, no randomness, no environment-dependent values in the report.
+4. A registry that reverts or is absent for the subject yields `null` for that section, never an omission.

package/scenarios/skills/foga-probe/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": "1.0",
+  "name": "foga-probe",
+  "skillVersion": "1.1.0",
+  "summary": "Probe one address against the ten-ERC agent stack at one block and produce a canonical report",
+  "entrypoint": "SKILL.md",
+  "skillType": "protocol",
+  "scopes": ["read:chain"],
+  "standard": "ERC-8338",
+  "x-entry-profile": "llm-markdown-v1",
+  "x-foga": {
+    "runner": "foga.kernel.probe/1",
+    "deterministic": true,
+    "outputSchema": "probe.schema.json"
+  }
+}

package/scenarios/skills/foga-probe/probe.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://foga.local/schemas/probe.schema.json",
+  "title": "foga.probe/1 report",
+  "type": "object",
+  "required": ["schema", "skill", "world", "subject", "checks"],
+  "properties": {
+    "schema": { "const": "foga.probe/1" },
+    "skill": { "const": "foga-probe" },
+    "world": {
+      "type": "object",
+      "required": ["worldId", "chainId", "block", "blockHash"],
+      "properties": {
+        "worldId": { "type": "string" },
+        "chainId": { "type": "integer" },
+        "block": { "type": "integer" },
+        "blockHash": { "type": "string" }
+      }
+    },
+    "subject": { "type": "string", "description": "CAIP-10 account reference, lower-case" },
+    "checks": {
+      "type": "object",
+      "required": ["erc8004", "erc8434", "erc8419", "erc8468", "erc8444", "erc8454", "erc8338", "erc8414", "erc8447", "erc8436", "erc8471"],
+      "additionalProperties": false,
+      "properties": {
+        "erc8004": { "type": ["object", "null"] },
+        "erc8434": { "type": ["object", "null"] },
+        "erc8419": { "type": ["object", "null"] },
+        "erc8468": { "type": ["object", "null"] },
+        "erc8444": { "type": ["object", "null"] },
+        "erc8454": { "type": ["object", "null"] },
+        "erc8338": { "type": ["object", "null"] },
+        "erc8414": { "type": ["object", "null"] },
+        "erc8447": { "type": ["object", "null"] },
+        "erc8436": { "type": ["object", "null"] },
+        "erc8471": { "type": ["object", "null"] }
+      }
+    }
+  }
+}

package/server.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.garyyang-finchip/foga",
+  "title": "FOGA node",
+  "description": "A Finch OG Agent cell as an MCP server: read the world, dry-run and take ERC-8414 tenders by policy.",
+  "repository": {
+    "url": "https://github.com/garyyang-finchip/foga",
+    "source": "github"
+  },
+  "websiteUrl": "https://foga.finchip.ai",
+  "version": "0.6.0-alpha.4",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@finchip.ai/foga",
+      "version": "0.6.0-alpha.4",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "node",
+          "description": "the node command group"
+        },
+        {
+          "type": "positional",
+          "value": "mcp",
+          "description": "MCP over stdio"
+        },
+        {
+          "type": "named",
+          "name": "--config",
+          "valueHint": "cell.config.json",
+          "format": "filepath",
+          "isRequired": true,
+          "description": "the cell's configuration file (written by foga cell new and foga cell init)"
+        },
+        {
+          "type": "named",
+          "name": "--rpc",
+          "valueHint": "https://...",
+          "isRequired": false,
+          "description": "the JSON-RPC endpoint of the world's chain, when the configuration names none"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "FOGA_OPERATOR_KEY_FILE",
+          "format": "filepath",
+          "isRequired": false,
+          "isSecret": false,
+          "description": "a file (mode 0600) holding the operator key: with it the server acts for the cell; without it, reads, dry runs and builds only"
+        },
+        {
+          "name": "FOGA_RPC_URL",
+          "isRequired": false,
+          "description": "the JSON-RPC endpoint when neither the configuration nor --rpc names one"
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://foga.finchip.ai/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "isRequired": false,
+          "isSecret": true,
+          "description": "Bearer <api key> for a caller the node's operator granted; without it the public reads and builds"
+        }
+      ]
+    }
+  ]
+}

package/vendor/LOCK.json

@@ -0,0 +1,107 @@
+{
+  "schema": "foga.vendor-lock/1",
+  "lockedAt": "2026-10-30",
+  "note": "Reference implementations of the ten ERCs, pinned by commit. `foga vendor sync` materializes each source tree under vendor/<repo>/ at exactly this commit; the committed artifacts/bundle.json is built from these commits and CI rebuilds it to prove the hash. Spec references are recorded separately from implementation commits: a Sepolia deployment may predate the implementation commit (see docs/version-lock.md).",
+  "sources": [
+    {
+      "erc": 8338,
+      "title": "Token-Bound Executable Skills",
+      "repo": "skill-token-standard",
+      "url": "https://github.com/garyyang-finchip/skill-token-standard.git",
+      "commit": "359ad64aa698c7c206bee9329a9a5ec05f12a685",
+      "contractsRoot": "contracts",
+      "upstreamToolchain": "foundry (solc 0.8.24, optimizer on, default runs)",
+      "spec": { "status": "Draft", "where": "ethereum/ERCs PR #1879 (not in this repository)", "discussion": "https://ethereum-magicians.org/t/29005" }
+    },
+    {
+      "erc": 8414,
+      "title": "Token-Bound Task Tenders",
+      "repo": "task-token-standard",
+      "url": "https://github.com/garyyang-finchip/task-token-standard.git",
+      "commit": "b3da62e761b00ef0921860f353d7eed24c6c85ae",
+      "contractsRoot": "contracts",
+      "upstreamToolchain": "foundry (solc 0.8.24, optimizer runs 1)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-9999.md in this repository (placeholder file name); ethereum/ERCs PR #2005", "discussion": "https://ethereum-magicians.org/t/29597" }
+    },
+    {
+      "erc": 8419,
+      "title": "Know-Your-Agent (KYA) Framework",
+      "repo": "kya-standard",
+      "url": "https://github.com/garyyang-finchip/kya-standard.git",
+      "commit": "f204f2ec2115bd8d1a96de60e0e844dee31cfe1b",
+      "contractsRoot": "assets/erc-kya/contracts",
+      "upstreamToolchain": "solc-js via tools/compile.js (solc 0.8.28, optimizer runs 200, evm cancun)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-kya.md in this repository; ethereum/ERCs PR #2012", "discussion": "https://ethereum-magicians.org/t/29735" }
+    },
+    {
+      "erc": 8434,
+      "title": "Agent Identity (AID)",
+      "repo": "aid-standard",
+      "url": "https://github.com/garyyang-finchip/aid-standard.git",
+      "commit": "1ff7215505af0f4699d437744402bd1e1b4dd043",
+      "contractsRoot": "assets/erc-aid/contracts",
+      "upstreamToolchain": "solc-js via scripts/compile.js (solc 0.8.28, optimizer runs 200, evm cancun)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-aid.md in this repository; ethereum/ERCs PR #2044", "discussion": "https://ethereum-magicians.org/t/29805" }
+    },
+    {
+      "erc": 8436,
+      "title": "Agent Collective Decision Framework (ACDF)",
+      "repo": "acd-framework",
+      "url": "https://github.com/garyyang-finchip/acd-framework.git",
+      "commit": "f8204fb9c38d47d619b9d8bc81441dfe9e8e7f91",
+      "contractsRoot": "assets/erc-acdf/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.24, optimizer runs 1, via-IR)",
+      "spec": { "status": "Draft (merged into ethereum/ERCs 2026-10-14)", "where": "https://eips.ethereum.org/EIPS/eip-8436", "discussion": "https://ethereum-magicians.org/t/29850" }
+    },
+    {
+      "erc": 8444,
+      "title": "Agentic Resource Discovery (ARD) Onchain",
+      "repo": "ard-onchain-framework",
+      "url": "https://github.com/garyyang-finchip/ard-onchain-framework.git",
+      "commit": "26416854e489564fc32c4a69cf9c176b703dc089",
+      "contractsRoot": "assets/erc-8444/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.24, optimizer runs 200)",
+      "spec": { "status": "Draft (merged into ethereum/ERCs 2026-10-15)", "where": "https://eips.ethereum.org/ERCS/erc-8444", "discussion": "https://ethereum-magicians.org/t/29963" }
+    },
+    {
+      "erc": 8447,
+      "title": "Swarm AI Framework (SAI)",
+      "repo": "swarm-ai-framework",
+      "url": "https://github.com/garyyang-finchip/swarm-ai-framework.git",
+      "commit": "de5bc291ab93bca0163bec47caa66136d1cf3f6a",
+      "contractsRoot": "assets/erc-8447/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.24, optimizer runs 1, via-IR, external libraries)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-8447.md in this repository; ethereum/ERCs PR #2081", "discussion": "https://ethereum-magicians.org/t/29998" }
+    },
+    {
+      "erc": 8454,
+      "title": "AIFi Unit Framework (AUF)",
+      "repo": "aifi-unit-framework",
+      "url": "https://github.com/garyyang-finchip/aifi-unit-framework.git",
+      "commit": "1be1da69811875bae0a6fd7b10152b4831e5538f",
+      "contractsRoot": "assets/erc-auf/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.30, optimizer runs 200, evm cancun, bytecode_hash none)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-auf.md in this repository; ethereum/ERCs PR #2095", "discussion": "https://ethereum-magicians.org/t/30040" }
+    },
+    {
+      "erc": 8468,
+      "title": "Agent Safety Framework (ASF)",
+      "repo": "agent-safety-framework",
+      "url": "https://github.com/garyyang-finchip/agent-safety-framework.git",
+      "commit": "a76071c0e0ab76c296a0eb878dee1365ce5a78bc",
+      "contractsRoot": "assets/erc-asf/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.30, optimizer runs 200, via-IR, evm cancun, bytecode_hash none, external libraries)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-asf.md in this repository; ethereum/ERCs PR #2113", "discussion": "https://ethereum-magicians.org/t/30073" }
+    },
+    {
+      "erc": 8471,
+      "title": "AI Dispute Resolution Framework (ADRF)",
+      "repo": "ai-dispute-resolution",
+      "url": "https://github.com/garyyang-finchip/ai-dispute-resolution.git",
+      "commit": "cd5a3e076d648ff5c29d87ab023b22398e0ab17a",
+      "contractsRoot": "assets/erc-adrf/contracts",
+      "upstreamToolchain": "foundry (solc 0.8.30, optimizer runs 200, via-IR, evm cancun, bytecode_hash none)",
+      "spec": { "status": "Draft", "where": "ERCS/erc-adrf.md in this repository; ethereum/ERCs PR #2123", "discussion": "https://ethereum-magicians.org/t/30121" }
+    }
+  ]
+}

package/vendor/README.md

@@ -0,0 +1,13 @@
+# vendor/
+
+This directory holds the pinned upstream sources of the ten reference implementations.
+Only `LOCK.json` is committed. Run `npm run vendor:sync` (or `foga vendor sync`) to
+materialize `vendor/<repo>/` at exactly the locked commits; the directories are
+gitignored so the FOGA repository itself stays small and uploadable by hand.
+
+The sources are needed only to (re)build `artifacts/bundle.json`. Deploying a world,
+running the doctor and (later) running cells all work from the committed bundle.
+
+The upstream repositories are CC0-1.0 (with Apache-2.0 vendored ARD material inside
+ard-onchain-framework). FOGA does not modify them; changes it needs go back upstream as
+separate pull requests.