@oracle-agent/oracle 0.1.0 → 0.2.1

package/src/protocol-templates/gate.mjs

@@ -0,0 +1,179 @@
+// Protocol template security gate.
+// Refuse prepare-deploy unless Foundry tests are green.
+// Static analysis (slither) is required when available; otherwise documented skip.
+// This is NOT a substitute for a paid Solidity firm audit.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+const PKG_ROOT = resolve(HERE, "../..");
+const TEMPLATES_ROOT = join(PKG_ROOT, "protocols", "templates");
+
+export const TEMPLATE_AUDIT_DISCLAIMER =
+  "Template + Foundry tests + optional static analysis. NOT a paid security-firm audit. Do not put mainnet TVL on forks without an independent Solidity audit.";
+
+export function listProtocolTemplates() {
+  if (!existsSync(TEMPLATES_ROOT)) return [];
+  return readdirSync(TEMPLATES_ROOT)
+    .filter((name) => statSync(join(TEMPLATES_ROOT, name)).isDirectory())
+    .map((id) => {
+      const dir = join(TEMPLATES_ROOT, id);
+      const security = join(dir, "SECURITY.md");
+      return {
+        id,
+        path: dir,
+        securityNotice: existsSync(security) ? readFileSync(security, "utf8").slice(0, 500) : null,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      };
+    });
+}
+
+function forgeBin() {
+  if (process.env.FORGE_BIN) return process.env.FORGE_BIN;
+  const home = process.env.HOME || "";
+  const candidates = ["forge", join(home, ".foundry/bin/forge")];
+  for (const c of candidates) {
+    const r = spawnSync(c, ["--version"], { encoding: "utf8" });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+function slitherBin() {
+  if (process.env.SLITHER_BIN) return process.env.SLITHER_BIN;
+  const r = spawnSync("slither", ["--version"], { encoding: "utf8" });
+  return r.status === 0 ? "slither" : null;
+}
+
+function run(cmd, args, cwd) {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, PATH: `${process.env.HOME || ""}/.foundry/bin:${process.env.PATH || ""}` },
+    timeout: 120_000,
+  });
+  return {
+    ok: r.status === 0,
+    status: r.status,
+    stdout: r.stdout || "",
+    stderr: r.stderr || "",
+  };
+}
+
+function hashTree(dir) {
+  const h = createHash("sha256");
+  function walk(p) {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      if (["lib", "out", "cache", ".git"].includes(p.split("/").pop())) return;
+      for (const name of readdirSync(p).sort()) walk(join(p, name));
+    } else if (st.isFile() && (p.endsWith(".sol") || p.endsWith(".toml") || p.endsWith(".md"))) {
+      h.update(p);
+      h.update(readFileSync(p));
+    }
+  }
+  walk(dir);
+  return h.digest("hex");
+}
+
+/**
+ * Run security gate on a template id.
+ * @param {string} templateId e.g. "safe-erc20"
+ * @param {{ allowSkipStatic?: boolean }} opts
+ */
+export function runProtocolTemplateGate(templateId, opts = {}) {
+  const allowSkipStatic = opts.allowSkipStatic !== false; // default allow skip if no slither
+  const dir = join(TEMPLATES_ROOT, templateId);
+  if (!existsSync(dir)) {
+    throw new Error(`protocol-templates: unknown template "${templateId}"`);
+  }
+
+  const forge = forgeBin();
+  if (!forge) {
+    throw new Error(
+      "protocol-templates: forge not found. Install Foundry (https://getfoundry.sh) then: cd protocols/templates/" +
+        templateId +
+        " && forge install && forge test"
+    );
+  }
+
+  // ensure libs (not vendored in git)
+  if (!existsSync(join(dir, "lib", "forge-std"))) {
+    const a = run(forge, ["install", "foundry-rs/forge-std", "--no-git"], dir);
+    if (!a.ok) throw new Error(`protocol-templates: forge install forge-std failed\n${a.stderr}`);
+  }
+  if (!existsSync(join(dir, "lib", "openzeppelin-contracts"))) {
+    const b = run(forge, ["install", "OpenZeppelin/openzeppelin-contracts@v5.0.2", "--no-git"], dir);
+    if (!b.ok) throw new Error(`protocol-templates: forge install openzeppelin failed\n${b.stderr}`);
+  }
+
+  const tests = run(forge, ["test", "-q"], dir);
+  if (!tests.ok) {
+    throw new Error(
+      `protocol-templates: forge test FAILED for ${templateId}\n${tests.stdout}\n${tests.stderr}`.slice(0, 2000)
+    );
+  }
+
+  let staticAnalysis = { tool: null, ok: true, skipped: true, reason: "slither not installed" };
+  const slither = slitherBin();
+  if (slither) {
+    const s = run(slither, [".", "--filter-paths", "lib", "--exclude-dependencies"], dir);
+    staticAnalysis = {
+      tool: "slither",
+      ok: s.ok,
+      skipped: false,
+      stdout: (s.stdout || "").slice(0, 1500),
+      stderr: (s.stderr || "").slice(0, 500),
+    };
+    if (!s.ok && !opts.allowStaticFail) {
+      throw new Error(`protocol-templates: slither FAILED for ${templateId}\n${s.stdout}\n${s.stderr}`.slice(0, 2000));
+    }
+  } else if (!allowSkipStatic) {
+    throw new Error("protocol-templates: slither required (allowSkipStatic=false) but not installed");
+  }
+
+  const sourceHash = hashTree(dir);
+  return {
+    ok: true,
+    templateId,
+    path: dir,
+    forgeTests: { ok: true, tool: "forge", summary: "forge test passed" },
+    staticAnalysis,
+    sourceHash,
+    disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+    firmAudit: false,
+  };
+}
+
+/**
+ * Build artifact after gate. Returns bytecode for unsigned deploy prepare.
+ */
+export function buildProtocolTemplate(templateId, opts = {}) {
+  const gate = runProtocolTemplateGate(templateId, opts);
+  const forge = forgeBin();
+  const dir = gate.path;
+  const build = run(forge, ["build", "-q"], dir);
+  if (!build.ok) {
+    throw new Error(`protocol-templates: forge build failed\n${build.stderr}`.slice(0, 1500));
+  }
+  // default contract name heuristic
+  const contractName = opts.contractName || (templateId === "safe-erc20" ? "SafeERC20" : null);
+  if (!contractName) throw new Error("protocol-templates: contractName required");
+  const artifactPath = join(dir, "out", `${contractName}.sol`, `${contractName}.json`);
+  if (!existsSync(artifactPath)) {
+    throw new Error(`protocol-templates: artifact missing at ${artifactPath}`);
+  }
+  const artifact = JSON.parse(readFileSync(artifactPath, "utf8"));
+  return {
+    gate,
+    contractName,
+    abi: artifact.abi,
+    bytecode: artifact.bytecode?.object || artifact.bytecode,
+    deployedBytecode: artifact.deployedBytecode?.object || artifact.deployedBytecode,
+    artifactPath,
+  };
+}

package/src/protocol-templates/prepare-deploy.mjs

@@ -0,0 +1,81 @@
+// Prepare unsigned deploy for a gated protocol template.
+// Never signs. Never broadcasts. Requires green forge tests first.
+
+import { ContractFactory, isAddress } from "ethers";
+import { stampPrepared } from "../prepare-envelope.mjs";
+import { buildProtocolTemplate, listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER } from "./gate.mjs";
+
+export { listProtocolTemplates, TEMPLATE_AUDIT_DISCLAIMER };
+
+/**
+ * @param {object} args
+ * @param {string} args.templateId - e.g. safe-erc20
+ * @param {number} args.chainId
+ * @param {string[]} [args.constructorArgs] - ABI-encoded via ethers from values
+ * @param {any[]} [args.args] - constructor JS values (preferred)
+ * @param {string} [args.contractName]
+ */
+export async function prepareTemplateDeploy(args = {}, opts = {}) {
+  const templateId = String(args.templateId || "").trim();
+  if (!templateId) throw new Error("prepareTemplateDeploy: templateId required");
+  const chainId = Number(args.chainId);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error("prepareTemplateDeploy: chainId required");
+  }
+
+  const built = buildProtocolTemplate(templateId, {
+    contractName: args.contractName,
+    allowSkipStatic: opts.allowSkipStatic !== false,
+    allowStaticFail: opts.allowStaticFail === true,
+  });
+
+  if (!built.bytecode || built.bytecode === "0x") {
+    throw new Error("prepareTemplateDeploy: empty bytecode");
+  }
+
+  const bc = built.bytecode.startsWith("0x") ? built.bytecode : `0x${built.bytecode}`;
+  const ctorArgs = args.args ?? args.constructorArgs ?? [];
+  const factory = new ContractFactory(built.abi, bc);
+  const deployTx = await factory.getDeployTransaction(...(Array.isArray(ctorArgs) ? ctorArgs : []));
+  const data = deployTx.data;
+
+  // validate SafeERC20 constructor shape if applicable
+  if (templateId === "safe-erc20" && Array.isArray(ctorArgs)) {
+    const [name, symbol, supply, holder, owner] = ctorArgs;
+    if (!name || !symbol) throw new Error("safe-erc20: name/symbol required");
+    if (supply == null || BigInt(supply) <= 0n) throw new Error("safe-erc20: supply must be > 0");
+    if (!isAddress(String(holder))) throw new Error("safe-erc20: initialHolder must be address");
+    if (!isAddress(String(owner))) throw new Error("safe-erc20: initialOwner must be address");
+  }
+
+  return stampPrepared(
+    {
+      provider: "protocol-templates",
+      kind: "template-deploy",
+      templateId,
+      contractName: built.contractName,
+      chainId,
+      transaction: {
+        chainId,
+        to: null, // creation
+        data,
+        value: "0x0",
+      },
+      abi: built.abi,
+      bytecodeHash: built.gate.sourceHash,
+      gate: {
+        forgeTests: built.gate.forgeTests,
+        staticAnalysis: {
+          tool: built.gate.staticAnalysis.tool,
+          ok: built.gate.staticAnalysis.ok,
+          skipped: built.gate.staticAnalysis.skipped,
+        },
+        firmAudit: false,
+        disclaimer: TEMPLATE_AUDIT_DISCLAIMER,
+      },
+      requiresUserSignature: true,
+      note: "Unsigned deploy. User wallet signs. Template tests passed; not a firm audit.",
+    },
+    { provider: "protocol-templates", kind: "template-deploy" }
+  );
+}

package/src/public-control/bundler-client.mjs

@@ -211,26 +211,11 @@ function toHexIfBigIntLike(value) {
  *   if it does not resolve to ENTRYPOINT_V07
  * @returns {Promise<string>} userOpHash returned by the bundler client
  */
-export async function submitUserOperation(params = {}) {
-  const { userOp, bundlerClient, entryPoint } = params;
-  requireSignedUserOp(userOp);
-  const resolvedEntryPoint = resolveEntryPoint(entryPoint);
-  requireClientMethod(bundlerClient, "sendUserOperation", "bundlerClient");
-
-  const payload = canonicalizeUserOpForSubmit(userOp);
-  assertNoSecretPayload(payload);
-
-  const userOpHash = await bundlerClient.sendUserOperation({
-    userOperation: payload,
-    entryPoint: resolvedEntryPoint,
-  });
-
-  if (typeof userOpHash !== "string" || !isHex(userOpHash)) {
-    fail("bundlerClient.sendUserOperation must resolve to a 0x-hex userOpHash");
-  }
-  return userOpHash;
+export async function submitUserOperation(_params = {}) {
+  throw new Error("bundler-client.submitUserOperation refused: @oracle-agent/oracle is prepare-only. Submit UserOps from the user wallet or local operator.");
 }
 
+
 /**
  * Fill gas fields on an UNSIGNED (pre-signature) UserOperation via an
  * injected bundler client's estimateUserOperationGas. Never submits