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

package/dist/genesis/roles.js

@@ -0,0 +1,96 @@
+import { readFileSync } from "node:fs";
+import { HDNodeWallet, Mnemonic, Wallet, randomBytes } from "ethers";
+/**
+ * The accounts of the genesis scenario (design memo, section 3.1). Keys are signer names in the kernel.
+ *
+ *   W            world operator: deploys / attaches the world, registers schemes and specifications, issues
+ *                the attested standing assertions, funds the other roles and the cells
+ *   G            guardian: the intervener named in every cell's safety binding
+ *   owner.<X>    cold principal of cell X (deploys the account, administers it)
+ *   operator.<X> hot signer of cell X (acts through the account's execute)
+ *   E            evaluator (ERC-8454 measurement receipts, Phase 2b)
+ *   J1..J3       judges of the FOGA-Council policy (Phase 2a-2)
+ *
+ * Every key is derived from one BIP-39 phrase at the standard Ethereum path, role i at m/44'/60'/0'/0/i in the
+ * order below. On anvil the phrase is anvil's well-known one, so every local run uses the same addresses. On any
+ * other chain the phrase comes from FOGA_MNEMONIC (the words) or FOGA_MNEMONIC_FILE (a file holding them), and
+ * FOGA_KEY_<ROLE> ("." as "_", upper case) overrides the key of one role — W = the key that already holds the
+ * chain's gas token, for instance. `foga keys new` writes a fresh phrase; `foga keys show` lists the addresses.
+ */
+export const CELLS = ["A", "B", "C"];
+export const ROLE_ORDER = ["W", "G", "owner.A", "owner.B", "owner.C", "operator.A", "operator.B", "operator.C", "E", "J1", "J2", "J3"];
+export const ANVIL_MNEMONIC = "test test test test test test test test test test test junk";
+/** Roles that must be funded by W on a local chain because anvil only pre-funds its first ten accounts. */
+export const DERIVED_BEYOND_ANVIL_DEFAULTS = ["J1", "J2", "J3"];
+export function rolePath(index) {
+    return `m/44'/60'/0'/0/${index}`;
+}
+export function envNameOf(role) {
+    return `FOGA_KEY_${role.replace(".", "_").toUpperCase()}`;
+}
+/** Every role's key from one phrase, role i at the i-th standard Ethereum path. */
+export function mnemonicKeys(phrase) {
+    const m = Mnemonic.fromPhrase(phrase.trim().split(/\s+/).join(" "));
+    const out = {};
+    ROLE_ORDER.forEach((role, i) => {
+        out[role] = HDNodeWallet.fromMnemonic(m, rolePath(i)).privateKey;
+    });
+    return out;
+}
+export function anvilKeys() {
+    return mnemonicKeys(ANVIL_MNEMONIC);
+}
+/** A new 12-word phrase from 128 bits of the platform's randomness. */
+export function newMnemonic() {
+    return Mnemonic.fromEntropy(randomBytes(16)).phrase;
+}
+/** The phrase the environment names, if any: FOGA_MNEMONIC (the words) or FOGA_MNEMONIC_FILE (a file holding them). */
+export function envMnemonic() {
+    const inline = process.env.FOGA_MNEMONIC?.trim();
+    if (inline)
+        return inline;
+    const file = process.env.FOGA_MNEMONIC_FILE;
+    if (file)
+        return readFileSync(file, "utf8").trim();
+    return undefined;
+}
+/**
+ * The keys of a non-anvil chain: the phrase's derivation, each role overridable by FOGA_KEY_<ROLE>. Without a
+ * phrase every required role needs its own variable.
+ */
+export function envKeys(required) {
+    const phrase = envMnemonic();
+    const derived = phrase ? mnemonicKeys(phrase) : null;
+    const out = {};
+    const missing = [];
+    for (const role of required) {
+        const override = process.env[envNameOf(role)];
+        if (override)
+            out[role] = override;
+        else if (derived)
+            out[role] = derived[role];
+        else
+            missing.push(envNameOf(role));
+    }
+    if (missing.length)
+        throw new Error(`missing keys for this world: set FOGA_MNEMONIC (or FOGA_MNEMONIC_FILE) for all roles, or ${missing.join(", ")}`);
+    return out;
+}
+/** The keys a genesis run needs for a world: anvil's derived set, or the environment on other chains. */
+export function roleKeys(world, required = ROLE_ORDER) {
+    if (world.network === "anvil") {
+        const all = anvilKeys();
+        return Object.fromEntries(required.map((r) => [r, all[r]]));
+    }
+    return envKeys(required);
+}
+/** The address of every role for a key set. */
+export function roleAddresses(keys) {
+    return Object.fromEntries(Object.entries(keys).map(([role, pk]) => [role, new Wallet(pk).address]));
+}
+export function ownerRole(cell) {
+    return `owner.${cell}`;
+}
+export function operatorRole(cell) {
+    return `operator.${cell}`;
+}

package/dist/genesis/run.js

@@ -0,0 +1,71 @@
+import { basename, join, relative, resolve } from "node:path";
+import { readJson, repoRoot, writeJson } from "../util/fs.js";
+import { log } from "../util/log.js";
+import { Genesis, STEPS } from "./scenario.js";
+/** `foga genesis run`: open the kernel on a deployed world, run T0..until, write the evidence file. */
+export async function runGenesis(opts) {
+    const root = repoRoot();
+    const worldPath = resolve(opts.worldPath);
+    const world = readJson(worldPath);
+    if (world.schema !== "foga.world/1")
+        throw new Error(`${worldPath} is not a deployed world file (run foga world deploy first)`);
+    const name = basename(worldPath).replace(/\.json$/, "");
+    const rpc = opts.rpc ?? process.env.FOGA_RPC_URL ?? (world.network === "anvil" ? "http://127.0.0.1:8545" : undefined);
+    if (!rpc)
+        throw new Error("no RPC: pass --rpc or set FOGA_RPC_URL");
+    const storePath = resolve(opts.storePath ?? join(root, "deployments", `${name}.genesis.sqlite`));
+    const evidencePath = resolve(opts.evidencePath ?? join(root, "deployments", `${name}.genesis.json`));
+    const skillsDir = resolve(opts.skillsDir ?? join(root, "scenarios", "skills"));
+    const fixturesDir = resolve(opts.fixturesDir ?? join(root, "scenarios", "fixtures"));
+    const until = opts.until ?? "T9";
+    if (!STEPS.includes(until))
+        throw new Error(`--until must be one of ${STEPS.join(", ")}`);
+    const say = opts.quiet ? () => { } : (line) => log.step(line);
+    const g = await Genesis.open({ worldPath, rpc, bundlePath: opts.bundlePath, storePath, skillsDir, fixturesDir, zk: opts.zk ?? "auto", crashBeforeBroadcast: opts.crashBeforeBroadcast, crashAfterBroadcast: opts.crashAfterBroadcast, log: say });
+    log.info(`genesis on world ${world.worldId} (chain ${world.chainId}) via ${rpc}; store ${storePath}`);
+    const before = g.kernel.store.summary();
+    if (before.ops.confirmed + before.ops.sent + before.ops.failed > 0)
+        log.info(`resuming: store holds ${before.ops.confirmed} confirmed, ${before.ops.sent} sent, ${before.ops.failed} failed operations`);
+    const startSeq = g.kernel.store.journalEntries().at(-1)?.seq ?? 0;
+    let runError = null;
+    try {
+        await g.run(until);
+    }
+    catch (e) {
+        runError = e;
+    }
+    const journal = g.kernel.store.journalEntries();
+    const thisRun = journal.filter((j) => j.seq > startSeq);
+    const ops = g.kernel.store.summary().ops;
+    const failed = g.checks.filter((c) => !c.pass).length;
+    const evidence = {
+        schema: "foga.genesis-evidence/1",
+        worldId: world.worldId,
+        chainId: world.chainId,
+        world: relative(root, worldPath),
+        store: relative(root, storePath),
+        ranAt: new Date().toISOString(),
+        until,
+        checks: g.checks,
+        summary: {
+            checks: g.checks.length,
+            passed: g.checks.length - failed,
+            failed,
+            operations: ops,
+            sent: thisRun.filter((j) => j.event === "sent").length,
+            replayed: thisRun.filter((j) => j.event === "replayed").length,
+            recovered: thisRun.filter((j) => j.event === "recovered-receipt" || j.event === "recovered-pending").length,
+            resent: thisRun.filter((j) => j.event === "resend").length,
+            replaced: thisRun.filter((j) => j.event === "replaced").length,
+        },
+        facts: g.kernel.store.facts(),
+        evidence: g.kernel.evidenceRecords(),
+        journal,
+    };
+    writeJson(evidencePath, evidence);
+    g.close();
+    if (runError)
+        throw runError;
+    log.info(`genesis ${until}: ${evidence.summary.passed}/${evidence.summary.checks} checks passed; ${ops.confirmed} operations confirmed in the store; this run: ${evidence.summary.sent} sent, ${evidence.summary.replayed} replayed, ${evidence.summary.recovered} recovered, ${evidence.summary.resent} re-sent, ${evidence.summary.replaced} fee-replaced -> ${evidencePath}`);
+    return { evidence, failed };
+}