recon-registry 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# recon-registry
+
+A community catalog of **single self-contained fuzzing harnesses and mocks**, deployable **by
+name** into the [Recon operator](https://github.com/Recon-Fuzz/recon-fuzzer). Package a whole
+protocol (or a standalone tester like an ERC-4626 vault or a weird ERC-20) into **one
+self-contained contract** whose constructor stands the project up — then anyone can fuzz it.
+
+```
+operator (Rust)                 recon-registry (this repo)              you (a Foundry project)
+  deploy_from_registry(name) ──▶  entries/<name>.json  ◀── PR ──  npx recon-registry pack/publish
+```
+
+## Use an entry (consumer)
+From the operator: `deploy_from_registry("ERC4626Tester", as_actor: true)` — fetches the entry
+and stands the project up at a deterministic address. Browse: `npx recon-registry list`.
+
+## Contribute an entry (author)
+In your Foundry project:
+```
+npx recon-registry init       # scaffold recon-registry.toml + registry/Harness.sol + Rvm.sol
+# write your harness (its constructor news+wires the whole project; see registry/Harness.sol)
+npx recon-registry pack       # forge build + extract → recon-registry-out/<name>.json
+npx recon-registry publish    # write token → auto-PR; else opens a prefilled issue (one Ctrl+V)
+```
+
+## Model (intentionally simple)
+- **One entry = one contract.** A "project" is a single self-contained Setup-style harness whose
+  creation bytecode embeds and deploys its deps. No multi-contract manifests, no dependency
+  ordering.
+- **Entry schema** (`schema/entry.schema.json`): `name, description, tags, abi, creationBytecode,
+  source, solc`. Source is inlined (humans + the LLM read behavior); no heavy provenance.
+- **Formats:** manifest = TOML (`recon-registry.toml`, human-edited); entries = JSON
+  (`entries/*.json`, machine-generated). Same split as `foundry.toml` ↔ `out/*.json`.
+
+## Trust = reproducibility, enforced in CI
+On every PR, CI recompiles the entry's `source` with its `solc` and asserts the **bytecode
+matches**, validates the schema, and smoke-deploys. On merge to `main`, `registry.json` is
+rebuilt and the entry is immediately available to the operator (merge = publish).
+
+## Layout
+```
+entries/*.json   published entries (machine-generated)
+src/*.sol        the harness/mock sources (for browsing + CI recompile)
+schema/          the entry JSON schema
+registry.json    the catalog index (CI-generated on merge)
+```
+
+See `CONTRIBUTING.md` for the full author guide.

package/bin/recon-registry.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// recon-registry — package a Foundry harness/mock into a registry entry and publish it.
+//
+//   npx recon-registry init      scaffold manifest + harness template (run in a Foundry project)
+//   npx recon-registry pack      forge build + extract a schema-valid entry JSON
+//   npx recon-registry publish   open a PR to the registry repo with the entry
+//   npx recon-registry list      list published entries
+//
+// Zero runtime deps: Node builtins + shelling out to `forge` and `gh`.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const __dir = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = resolve(__dir, "..", "templates");
+const DEFAULT_REGISTRY = "Recon-Fuzz/recon-registry";
+
+const die = (m) => { console.error(`recon-registry: ${m}`); process.exit(1); };
+const ok = (m) => console.log(`✓ ${m}`);
+
+// --- tiny flat-TOML reader (enough for recon-registry.toml: [section] key = "..." | [..]) ---
+function readToml(path) {
+  const out = {};
+  let section = "";
+  for (const raw of readFileSync(path, "utf8").split("\n")) {
+    const line = raw.replace(/#.*$/, "").trim();
+    if (!line) continue;
+    const sec = line.match(/^\[(.+)\]$/);
+    if (sec) { section = sec[1]; out[section] = out[section] || {}; continue; }
+    const kv = line.match(/^([A-Za-z0-9_]+)\s*=\s*(.+)$/);
+    if (!kv) continue;
+    let [, k, v] = kv;
+    v = v.trim();
+    let val;
+    if (v.startsWith("[")) val = v.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    else val = v.replace(/^["']|["']$/g, "");
+    (section ? out[section] : out)[k] = val;
+  }
+  return out;
+}
+
+function sh(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], ...opts });
+}
+
+// --- cross-platform helpers (macOS / Linux / Windows) ---
+function copyToClipboard(text) {
+  const p = process.platform;
+  const cands =
+    p === "darwin" ? [["pbcopy", []]]
+    : p === "win32" ? [["clip", []]]
+    : [["xclip", ["-selection", "clipboard"]], ["wl-copy", []], ["xsel", ["--clipboard", "--input"]]];
+  for (const [cmd, args] of cands) {
+    try { execFileSync(cmd, args, { input: text, shell: p === "win32" }); return true; } catch {}
+  }
+  return false;
+}
+function openUrl(url) {
+  const p = process.platform;
+  try {
+    if (p === "darwin") execFileSync("open", [url], { stdio: "ignore" });
+    else if (p === "win32") execFileSync("cmd", ["/c", "start", "", url], { stdio: "ignore" });
+    else execFileSync("xdg-open", [url], { stdio: "ignore" });
+  } catch {}
+}
+// Reveal a file in the OS file manager, selected/highlighted so it's ready to drag.
+function revealFile(p) {
+  const plat = process.platform;
+  try {
+    if (plat === "darwin") execFileSync("open", ["-R", p], { stdio: "ignore" });
+    else if (plat === "win32") execFileSync("explorer", [`/select,${p}`], { stdio: "ignore" });
+    else execFileSync("xdg-open", [dirname(p)], { stdio: "ignore" }); // most Linux FMs lack --select
+  } catch {}
+}
+
+// ---------------------------------------------------------------- init
+function init() {
+  if (!existsSync("foundry.toml")) die("run inside a Foundry project (no foundry.toml found)");
+  mkdirSync("registry", { recursive: true });
+  const files = [
+    ["recon-registry.toml", "recon-registry.toml"],
+    [join("registry", "Harness.sol"), "Harness.sol"],
+    [join("registry", "Rvm.sol"), "Rvm.sol"],
+    [join("registry", "README.md"), "registry-README.md"],
+  ];
+  for (const [dst, tpl] of files) {
+    if (existsSync(dst)) { console.log(`· skip ${dst} (exists)`); continue; }
+    copyFileSync(join(TEMPLATES, tpl), dst);
+    ok(`created ${dst}`);
+  }
+  // Best-effort: prefill author from git config (only replaces the untouched placeholder).
+  try {
+    const n = sh("git", ["config", "user.name"]).trim();
+    const e = sh("git", ["config", "user.email"]).trim();
+    const a = n ? (e ? `${n} <${e}>` : n) : "";
+    const t = existsSync("recon-registry.toml") ? readFileSync("recon-registry.toml", "utf8") : "";
+    if (a && t.includes("Your Name <you@example.com>")) {
+      writeFileSync("recon-registry.toml", t.replace("Your Name <you@example.com>", a));
+      ok(`author = ${a}`);
+    }
+  } catch {}
+
+  console.log("\nNext: edit recon-registry.toml + registry/Harness.sol, then `npx recon-registry pack`.");
+}
+
+// ---------------------------------------------------------------- pack
+function pack() {
+  if (!existsSync("recon-registry.toml")) die("no recon-registry.toml — run `npx recon-registry init` first");
+  const m = readToml("recon-registry.toml");
+  const name = m.entry?.name || die("recon-registry.toml: [entry].name required");
+  const harness = m.entry?.harness || die("recon-registry.toml: [entry].harness required");
+  const skip = (m.build?.skip || []).flatMap((s) => ["--skip", s]);
+
+  console.log(`Building (forge build ${skip.join(" ")}) ...`);
+  sh("forge", ["build", ...skip], { stdio: ["ignore", "inherit", "inherit"] });
+
+  // Locate the concrete artifact for the harness contract.
+  const artifact = findArtifact("out", harness) || die(`artifact for ${harness} not found under out/`);
+  const a = JSON.parse(readFileSync(artifact, "utf8"));
+  const bytecode = a.bytecode?.object || "";
+  if (bytecode.replace(/^0x/, "").length === 0)
+    die(`${harness} has empty bytecode (abstract contract or basename collision — check [build].skip)`);
+  if (bytecode.includes("__$")) die(`${harness} has unlinked libraries — link them before packing`);
+
+  // Inline the FLATTENED source — self-contained (full dependency tree in one file), so CI can
+  // recompile it standalone to verify the bytecode, and humans/LLM see everything.
+  const sourcePath = m.entry?.source || guessSource(harness);
+  let source = "";
+  if (sourcePath && existsSync(sourcePath)) {
+    try { source = sh("forge", ["flatten", sourcePath]); }
+    catch { source = readFileSync(sourcePath, "utf8"); }
+  }
+
+  const entry = {
+    name,
+    description: m.entry?.description || "",
+    author: m.entry?.author || "",
+    tags: m.entry?.tags || [],
+    abi: a.abi,
+    creationBytecode: bytecode,
+    source,
+    solc: m.build?.solc || readToml("foundry.toml").profile?.default?.solc || detectSolc(),
+  };
+  mkdirSync("recon-registry-out", { recursive: true });
+  const out = join("recon-registry-out", `${name}.json`);
+  writeFileSync(out, JSON.stringify(entry, null, 1));
+  ok(`packed ${out} (${(bytecode.length / 2) | 0} bytes bytecode, ${entry.abi.length} abi items)`);
+  if (!source) console.log("· note: no source inlined — set [entry].source in the manifest for transparency");
+}
+
+// ---------------------------------------------------------------- publish
+// Two tiers, no `gh`/`git`, cross-platform:
+//   1. If a write token is available (GH_TOKEN/GITHUB_TOKEN), fire a `repository_dispatch` →
+//      the registry Action validates + opens the PR fully automatically (no UI step).
+//   2. Otherwise, copy the entry JSON to the clipboard and open the prefilled "Submit a
+//      registry entry" issue — the user clicks the field, Ctrl/Cmd+V, Submit; the Action
+//      turns the issue into a PR.
+async function publish() {
+  const built = existsSync("recon-registry-out") && readdirSync("recon-registry-out").find((f) => f.endsWith(".json"));
+  if (!built) die("nothing packed — run `npx recon-registry pack` first");
+  const m = existsSync("recon-registry.toml") ? readToml("recon-registry.toml") : {};
+  const repo = m.registry?.repo || DEFAULT_REGISTRY;
+  const name = built.replace(/\.json$/, "");
+  const file = join("recon-registry-out", built);
+  const jsonText = readFileSync(file, "utf8");
+  const token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN;
+
+  // Tier 1: repository_dispatch (needs write access).
+  if (token) {
+    const res = await fetch(`https://api.github.com/repos/${repo}/dispatches`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "User-Agent": "recon-registry",
+      },
+      body: JSON.stringify({ event_type: "submit-entry", client_payload: { entry: JSON.parse(jsonText) } }),
+    });
+    if (res.status === 204) {
+      ok(`dispatched '${name}' — the registry Action will validate it and open a PR.`);
+      return;
+    }
+    console.log(`· repository_dispatch not permitted (HTTP ${res.status}); falling back to the issue flow.`);
+  }
+
+  // Tier 2: open the markdown issue page AND reveal the entry file in the file manager so the
+  // user just drags it into the issue body and submits. The Action downloads + parses the
+  // attached file (drag-dropped .json works) and opens the PR. No clipboard/token/gh needed.
+  const url = `https://github.com/${repo}/issues/new?template=submit-entry.md&title=${encodeURIComponent(`[entry] ${name}`)}`;
+  const abs = resolve(file);
+  console.log(`\nSubmit '${name}':`);
+  console.log(`  1. Opening the issue page + your file manager (the entry file is highlighted).`);
+  console.log(`  2. Drag this file into the issue body, then click "Submit new issue":`);
+  console.log(`       ${abs}`);
+  console.log(`  3. A bot downloads it, validates it, and opens the PR.\n`);
+  openUrl(url);
+  revealFile(abs);
+}
+
+// ---------------------------------------------------------------- list
+async function list() {
+  const m = existsSync("recon-registry.toml") ? readToml("recon-registry.toml") : {};
+  const repo = m.registry?.repo || DEFAULT_REGISTRY;
+  const url = `https://raw.githubusercontent.com/${repo}/main/registry.json`;
+  const res = await fetch(url, { headers: { "User-Agent": "recon-registry" } });
+  if (!res.ok) die(`could not fetch ${url} (HTTP ${res.status})`);
+  const { entries = [] } = await res.json();
+  if (!entries.length) return console.log("(registry is empty)");
+  for (const e of entries) console.log(`${e.name}\t[${(e.tags || []).join(", ")}]\t${e.description || ""}`);
+}
+
+// ---------------------------------------------------------------- helpers
+function findArtifact(root, contract) {
+  if (!existsSync(root)) return null;
+  for (const d of readdirSync(root, { withFileTypes: true })) {
+    const p = join(root, d.name);
+    if (d.isDirectory()) { const r = findArtifact(p, contract); if (r) return r; }
+    else if (d.name === `${contract}.json`) return p;
+  }
+  return null;
+}
+function guessSource(contract) {
+  for (const root of ["registry", "src", "test"]) {
+    const r = findArtifact.call(null, root, contract); // reuse: look for <contract>.sol
+    if (existsSync(join(root, `${contract}.sol`))) return join(root, `${contract}.sol`);
+  }
+  return null;
+}
+function detectSolc() {
+  try { return (sh("forge", ["--version"]).match(/solc\s+([0-9.]+)/) || [])[1] || ""; } catch { return ""; }
+}
+
+const [, , cmd] = process.argv;
+const fn = { init, pack, publish, list }[cmd];
+if (!fn) die(`unknown command '${cmd ?? ""}'. usage: recon-registry <init|pack|publish|list>`);
+await fn();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "recon-registry",
+  "version": "0.1.0",
+  "description": "Package a Foundry project into a single self-contained fuzzing harness/mock and publish it to the Recon contract registry, deployable by name from the operator.",
+  "type": "module",
+  "bin": {
+    "recon-registry": "bin/recon-registry.mjs"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "schema/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ethereum",
+    "foundry",
+    "forge",
+    "fuzzing",
+    "invariant-testing",
+    "recon",
+    "registry"
+  ],
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Recon-Fuzz/recon-registry.git" },
+  "homepage": "https://github.com/Recon-Fuzz/recon-registry#readme",
+  "bugs": { "url": "https://github.com/Recon-Fuzz/recon-registry/issues" }
+}

package/schema/entry.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Recon-Fuzz/recon-registry/schema/entry.schema.json",
+  "title": "Recon registry entry",
+  "description": "One self-contained deployable contract (a project harness or a standalone mock). Single contract only — a project is one self-contained Setup-style harness, never a multi-contract manifest.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description", "tags", "abi", "creationBytecode", "source", "solc"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+$",
+      "description": "Unique entry name (also the file name and the deploy-by-name key)."
+    },
+    "description": { "type": "string", "description": "One-line summary of what it stands up / does." },
+    "author": { "type": "string", "description": "Optional attribution, e.g. \"Jane Doe <jane@example.com>\" (name required, email optional)." },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Discovery tags, e.g. erc4626, vault, lending, oracle, harness, mock."
+    },
+    "abi": {
+      "type": "array",
+      "description": "Standard Solidity ABI (JSON). Needed to encode constructor args and interact."
+    },
+    "creationBytecode": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]*$",
+      "description": "Linked creation (init) bytecode. Self-contained — embeds any `new`'d deps. Must be non-empty and fully library-linked (no __$ placeholders)."
+    },
+    "source": {
+      "type": "string",
+      "description": "Inlined Solidity source so humans and the LLM operator can see exactly what the contract does."
+    },
+    "solc": {
+      "type": "string",
+      "description": "solc version the bytecode was built with. CI recompiles `source` with this and asserts the bytecode matches (reproducibility = trust; no per-entry provenance)."
+    }
+  }
+}

package/templates/Harness.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {rvm} from "./Rvm.sol";
+
+// import {YourProtocol} from "src/YourProtocol.sol";
+// import {MockToken}    from "src/mocks/MockToken.sol";
+
+/// A registry harness packages an ENTIRE project into ONE self-contained contract: its
+/// constructor `new`s and wires the whole protocol, funds the operator's actors, and sets up
+/// initial state. Deploying this one artifact (the operator does so with `as_actor: true`)
+/// stands the project up — `new`'d contracts are embedded in this harness's creation bytecode.
+///
+/// After deploy, you attach handlers / properties / ghosts at runtime; this harness is just the
+/// SUT setup. Expose addresses via public getters so those can wire to them.
+contract MyHarness {
+    // YourProtocol public protocol;
+    // MockToken public token;
+
+    constructor() {
+        // The operator's actor set (includes this harness when deployed as_actor).
+        address[] memory actors = rvm.getActors();
+
+        // 1. Deploy + wire your protocol and mocks here:
+        // token = new MockToken("Test", "TST", 18);
+        // protocol = new YourProtocol(address(token));
+
+        // 2. Fund / approve every actor (no hardcoded users):
+        for (uint256 i; i < actors.length; i++) {
+            address a = actors[i];
+            // token.mint(a, type(uint128).max);
+            // rvm.prank(a); token.approve(address(protocol), type(uint256).max);
+            a; // remove once used
+        }
+    }
+
+    // function protocolAddr() external view returns (address) { return address(protocol); }
+}

package/templates/Rvm.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {Vm} from "forge-std/Vm.sol";
+
+/// Recon extended VM — inherits ALL Foundry cheatcodes (via `is Vm`) and adds the operator's
+/// actor / asset / ghost / generic-registry extensions, served at the canonical cheatcode
+/// address. The handle is named `rvm` so it never collides with forge-std's `vm`.
+interface IRvm is Vm {
+    // --- actors (the operator's actor set; includes the harness/deployer when deployed as_actor) ---
+    function getActor() external view returns (address);
+    function getActor(uint256 index) external view returns (address);
+    function getActors() external view returns (address[] memory);
+    function addActor() external returns (address);
+    function addActor(address actor) external;
+    function removeActor(address actor) external;
+    function switchActor(uint256 entropy) external;
+
+    // --- assets (operator-managed mock-token registry) ---
+    function getAsset() external view returns (address);
+    function getAssets() external view returns (address[] memory);
+    function newAsset(uint8 decimals) external returns (address);
+    function addAsset(address token) external;
+    function switchAsset(uint256 entropy) external;
+
+    // --- ghosts ---
+    function ghosts() external view returns (address[] memory);
+    function ghostGet(string calldata key) external view returns (bytes memory);
+    function ghostSet(string calldata key, bytes calldata value) external;
+
+    // --- generic named registry ---
+    function push(string calldata name, bytes calldata item) external;
+    function pop(string calldata name) external returns (bytes memory);
+    function removeAt(string calldata name, uint256 index) external;
+    function store(string calldata name, uint256 index, bytes calldata item) external;
+    function pick(string calldata name, uint256 entropy) external returns (bytes memory);
+    function current(string calldata name) external view returns (bytes memory);
+    function at(string calldata name, uint256 index) external view returns (bytes memory);
+    function all(string calldata name) external view returns (bytes[] memory);
+    function count(string calldata name) external view returns (uint256);
+}
+
+/// Recon VM handle. `rvm.*` — distinct from forge-std's `vm`.
+IRvm constant rvm = IRvm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);

package/templates/recon-registry.toml

@@ -0,0 +1,16 @@
+# recon-registry entry manifest. Edit, then `npx recon-registry pack && npx recon-registry publish`.
+
+[entry]
+name        = "MyHarness"          # unique entry name (also the published file name)
+description = "One-line description of what this harness/mock stands up"
+author      = "Your Name <you@example.com>"
+tags        = ["protocol", "harness"]
+harness     = "MyHarness"          # the contract `pack` extracts (single self-contained harness)
+# source    = "registry/Harness.sol"  # optional: defaults to the harness's .sol; inlined into the entry
+
+[build]
+solc = "0.8.24"                    # stamped into the entry; CI recompiles with this to verify bytecode
+skip = ["test/recon/**"]           # collision guard: skip dirs with clashing basenames
+
+[registry]
+repo = "Recon-Fuzz/recon-registry" # PR target

package/templates/registry-README.md

@@ -0,0 +1,16 @@
+# registry/ — your fuzzing harness entry
+
+This folder was scaffolded by `npx recon-registry init`. It packages your project into a single
+self-contained harness for the [recon-registry](https://github.com/Recon-Fuzz/recon-registry),
+deployable by name from the Recon operator.
+
+- `Harness.sol` — your harness: its constructor stands up the whole project (see the TODOs).
+- `Rvm.sol` — the `rvm` cheatcode interface the harness uses (`getActors`, `prank`, …).
+- `../recon-registry.toml` — the entry manifest (name, description, tags, harness, solc).
+
+## Flow
+```
+# edit Harness.sol + recon-registry.toml
+npx recon-registry pack       # forge build + extract entry → recon-registry-out/<name>.json
+npx recon-registry publish    # open a PR to the registry  →  merge = live for everyone
+```