ichaingov-contract-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ana Ferreira 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# ichaingov-contract-generator
+
+DAO CLI — generates and deploys governance contracts for gateway-based interoperability systems from a single `config.json` file.
+
+This tool is part of the Master's thesis **IChainGov: Governance Protocols in Blockchain Interoperability Mechanisms**.
+
+---
+
+## Overview
+
+`ichaingov-contract-generator` automates the creation of a complete on-chain governance framework designed for gateway interoperability systems like those described in the Secure Asset Transfer Protocol (SATP). It produces all the necessary Solidity contracts, configuration, and deployment scripts, allowing a DAO to manage protocol parameters and gateway registration.
+
+The generated contracts use and extend OpenZeppelin's contracts, it implements multiple voting systems and an optional timelock.
+
+---
+
+## Generated Contracts
+
+The CLI creates the following smart contracts:
+
+| Contract | Description |
+|----------|-------------|
+| **Token** | ERC20 token with vote delegation (ERC20Votes). Used for governance voting power. |
+| **GovernanceTL** | Main governor contract inheriting `Governor`, `GovernorSettings`, `GovernorCountingSimple`, `GovernorVotes`, `GovernorVotesQuorumFraction`, and `GovernorTimelockControl`. Supports three voting systems: TokenBased, Quadratic, and WeightedReputation. |
+| **Timelock** | OpenZeppelin TimelockController that enforces a delay between proposal passing and execution. Optional — controlled by `config.json`. |
+| **GatewayRegistry** | Ownable contract storing on-chain identities of organizations and their gateways. |
+| **PolicyRegistry** | Simple key-value store for protocol parameters. Only the governor can modify it, ensuring all changes go through on-chain governance. |
+
+---
+
+## Quick Start
+
+```bash
+ichaingov-contract-generator
+```
+
+If no `config.json` is present in the current directory, a template will be copied automatically. Edit it to match your DAO's requirements and run the command again.
+
+## Configuration
+
+All settings are read from a `config.json` file. Below is a complete example:
+
+```json
+{
+  "name": "MyDAO",
+  "tokenomics": {
+    "name": "MyToken",
+    "symbol": "MTK",
+    "supply": 1000000,
+    "defaultMemberTokens": 1000
+  },
+  "organizations": [
+    {
+      "address": "0x...",
+      "name": "Org A",
+      "reputation": 0,
+      "gateways": ["0x..."]
+    }
+  ],
+  "governance": {
+    "votingDelay": 1,
+    "votingPeriod": 5,
+    "proposalThreshold": 0,
+    "quorumFraction": 0,
+    "votingSystem": "token-based"
+  },
+  "timelock": {
+    "enabled": true,
+    "minDelay": 0
+  },
+  "protocolParameters": [
+    { "key": "satp.version", "value": "v02" }
+  ]
+}
+```
+
+- `votingSystem` accepts: `token-based`, `quadratic`, `weighted-reputation`.
+
+---
+
+## Important Notes
+
+- **EVM target**: The generated Hardhat config uses `evmVersion: "cancun"`. This is required because OpenZeppelin v5.6+ uses the `mcopy` opcode. If you have an existing config, ensure the same EVM version is set.
+
+---
+
+## Thesis & Academic Context
+
+This CLI was developed as part of the Master's dissertation:
+
+**IChainGov: Governance Protocols in Blockchain Interoperability Mechanisms**  
+*Ana Catarina Ferreira de Sá*  
+Instituto Superior Técnico, Universidade de Lisboa  
+2025
+
+The thesis addresses governance challenges in gateway-based interoperability systems, proposing a decentralized governance framework for protocols like SATP. The smart contracts generated by this tool form the on-chain layer of that framework, while an external integration layer listens to DAO events to update gateway configurations automatically.
+
+For more details on the architecture, voting systems, and the integration with SATP, refer to the full thesis document.

package/bin/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+import { loadConfig }     from "../core/loadConfig.js";
+import { validateConfig } from "../core/validateConfig.js";
+import { generate }       from "../index/generator.js";
+import { generateDeploy } from "../index/generateDeploy.js";
+import { execSync }       from "child_process";
+import readline           from "readline/promises";
+import fs                 from "fs";
+import path               from "path";
+import { fileURLToPath }  from "url";
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+async function ask(q) {
+  return rl.question(q);
+}
+
+const args        = process.argv.slice(2);
+const shouldDeploy = args.includes("--deploy");
+const network      = args.find(a => a.startsWith("--network="))?.split("=")[1] ?? "localhost";
+
+const defaultHardhatConfig = `
+require("@nomicfoundation/hardhat-toolbox");
+module.exports = {
+  solidity: {
+    version: "0.8.28",
+    settings: {
+      evmVersion: "cancun",
+      optimizer: { enabled: true, runs: 200 },
+    },
+  },
+  networks: {
+    hardhat: {},
+    localhost: { url: "http://127.0.0.1:8545" },
+  },
+};
+`.trim();
+
+function isESMProject() {
+  const pkgPath = path.resolve(process.cwd(), "package.json");
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    return pkg.type === "module";
+  }
+  return false;
+}
+
+function ensureDeployScript() {
+  if (!isESMProject()) return;                                    
+  const js = path.resolve(process.cwd(), "scripts/deploy.js");
+  const cjs = path.resolve(process.cwd(), "scripts/deploy.cjs");
+  if (fs.existsSync(js)) {
+    const content = fs.readFileSync(js, "utf8");
+    if (content.includes("require(")) {
+      fs.writeFileSync(cjs, content);
+      fs.unlinkSync(js);
+      console.log("Renamed scripts/deploy.js → scripts/deploy.cjs (CommonJS required)");
+    }
+  }
+}
+
+function getDeployScriptName() {
+  const cjs = path.resolve(process.cwd(), "scripts/deploy.cjs");
+  if (fs.existsSync(cjs)) return "scripts/deploy.cjs";
+  const js = path.resolve(process.cwd(), "scripts/deploy.js");
+  if (fs.existsSync(js)) return "scripts/deploy.js";
+  return "scripts/deploy.js";
+}
+
+async function main() {
+  console.log("#################################");
+  console.log("# ichaingov:create-governance #");
+  console.log("#################################\n");
+
+
+  // ── Use template config if config.json is missing ──────────────────
+  const configFilePath = path.resolve(process.cwd(), "config.json");
+  if (!fs.existsSync(configFilePath)) {
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname  = path.dirname(__filename);
+    const templateConfigPath = path.resolve(__dirname, "..", "index/templates", "template-config.json");
+    if (!fs.existsSync(templateConfigPath)) {
+      console.error("Template config file not found. Please create a config.json manually.");
+      process.exit(1);
+    }
+    fs.copyFileSync(templateConfigPath, configFilePath);
+    console.log("No config.json found. A template has been created.");
+    console.log("You can edit config.json now, or continue with the defaults.\n");
+
+    const useTemplate = await ask("Proceed with the template values? (y/N) ");
+    if (useTemplate.trim().toLowerCase() !== "y" && useTemplate.trim().toLowerCase() !== "yes") {
+      console.log("Edit config.json and run again when ready.");
+      process.exit(0);
+    }
+    console.log("");
+  }
+
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    console.error("Could not load config.json:", err.message);
+    process.exit(1);
+  }
+  try {
+    validateConfig(config);
+  } catch (err) {
+    console.error("Invalid config.json:\n", err.message);
+    process.exit(1);
+  }
+
+  try {
+    await generate(config);
+    await generateDeploy(config);
+  } catch (err) {
+    console.error("Generation failed:", err.message);
+    process.exit(1);
+  }
+
+  ensureDeployScript();
+
+  if (shouldDeploy) {
+    const script = getDeployScriptName();
+    console.log(`\nDeploying to '${network}'...`);
+    try {
+      execSync(
+        `npx hardhat run ${script} --network ${network}`,
+        { stdio: "inherit" }
+      );
+    } catch {
+      console.error("Deployment failed. Check Hardhat output above.");
+      process.exit(1);
+    }
+    rl.close();
+    return;
+  }
+
+  console.log("\nGeneration complete. You can now deploy your contracts.");
+  const answer = (await ask("Deploy to local Hardhat network now? (y/N) ")).trim().toLowerCase();
+
+  if (answer === "y" || answer === "yes") {
+    const configPaths = [
+      path.resolve(process.cwd(), "hardhat.config.js"),
+      path.resolve(process.cwd(), "hardhat.config.ts"),
+      path.resolve(process.cwd(), "hardhat.config.cjs"),
+    ];
+    const existing = configPaths.find(p => fs.existsSync(p));
+    if (existing) {
+      console.log("Warning: Hardhat config already exists – it will not be modified.");
+      console.log("If deployment fails due to the 'mcopy' opcode, ensure your config uses evmVersion: 'cancun'.");
+    } else {
+      fs.writeFileSync(path.resolve(process.cwd(), "hardhat.config.cjs"), defaultHardhatConfig);
+      console.log("Created hardhat.config.cjs (Cancun‑ready).");
+    }
+
+    const script = getDeployScriptName();
+    console.log(`Deploying '${config.name}' to Hardhat's built‑in network...`);
+    try {
+      execSync(
+        `npx hardhat run ${script} --network hardhat`,
+        { stdio: "inherit" }
+      );
+    } catch {
+      console.error("Deployment failed. Check the output above and ensure all dependencies (npm install) are installed.");
+      process.exit(1);
+    }
+  } else {
+    console.log("Skipping deployment. You can deploy later.");
+  }
+
+  console.log("\nAvailable deployment commands:");
+  console.log("  npx create-governance --deploy                 (defaults to 'localhost')");
+  console.log("  npm run deploy                                 (same as above)");
+  console.log("\nTo use a different network, edit hardhat.config.js and add your RPC URL.");
+
+  rl.close();
+}
+
+main();

package/core/encodeParameter.js

@@ -0,0 +1,10 @@
+import { keccak256, toUtf8Bytes } from "ethers";
+
+export function encodeValue(value) {
+  if (typeof value === 'number' || (typeof value === 'string' && !isNaN(value) && value.trim() !== '')) {
+    return BigInt(value);
+  }
+  if (value === true || value === "true") return 1n;
+  if (value === false || value === "false") return 0n;
+  return BigInt(keccak256(toUtf8Bytes(value)));
+}

package/core/loadConfig.js

@@ -0,0 +1,21 @@
+import fs   from "fs";
+import path from "path";
+
+export function loadConfig(filePath = "config.json") {
+  const resolved = path.resolve(process.cwd(), filePath);
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(
+      `config.json not found at ${resolved}\n` +
+      "Create one based on config.example.json"
+    );
+  }
+
+  const raw = fs.readFileSync(resolved, "utf-8");
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`config.json is not valid JSON: ${err.message}`);
+  }
+}

package/core/validateConfig.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+
+
+const GatewaySchema = z.object({
+  publicKey: z.string().regex(/^0x[a-fA-F0-9]{64,128}$/, "Invalid public key hex"),
+  name: z.string().min(1)
+});
+
+const OrganizationSchema = z.object({
+  name: z.string().min(1),
+  address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address"),
+  reputation: z.number().int().min(0).default(0),
+  gateways: z.array(GatewaySchema).optional(),
+});
+
+const TokenomicsSchema = z.object({
+  treasury: z.boolean().optional().default(true),
+  name: z.string().min(1),
+  symbol: z.string().min(1).max(8),
+  supply: z.number().positive(),
+  defaultMemberTokens: z.number().positive().optional(),
+});
+
+const GovernanceSchema = z.object({
+  votingDelay:       z.number().int().min(0),
+  votingPeriod:      z.number().int().min(1),
+  proposalThreshold: z.number().int().min(0),
+  quorumFraction:    z.number().int().min(0).max(100),   // allow 0
+  votingSystem:      z.enum(["token-based", "quadratic", "weighted-reputation"]),
+});
+
+const TimelockSchema = z.object({
+  enabled:  z.boolean(),
+  minDelay: z.number().int().min(0),
+});
+
+const ProtocolParameterSchema = z.object({
+  key:   z.string().min(1),
+  value: z.union([z.string(), z.number(), z.boolean()]),
+});
+
+export const ConfigSchema = z.object({
+  name:               z.string().min(1),
+  tokenomics:         TokenomicsSchema,
+  governance:         GovernanceSchema,
+  timelock:           TimelockSchema,
+  organizations:      z.array(OrganizationSchema).min(1),
+  protocolParameters: z.array(ProtocolParameterSchema).optional().default([]),
+});
+
+export function validateConfig(config) {
+  const result = ConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    const messages = result.error.errors
+      .map(e => `  • ${e.path.join(".")} — ${e.message}`)
+      .join("\n");
+    throw new Error(`Config validation failed:\n${messages}`);
+  }
+
+  const { governance, tokenomics, organizations } = result.data;
+
+  if (
+    governance.votingSystem === "weighted-reputation" &&
+    (!organizations || organizations.length === 0)
+  ) {
+    throw new Error(
+      "governance.votingSystem 'weighted-reputation' requires at least one entry in organizations[]"
+    );
+  }
+
+  if (tokenomics.defaultMemberTokens) {
+    const totalForOrgs = tokenomics.defaultMemberTokens * organizations.length;
+    if (totalForOrgs >= tokenomics.supply) {
+      throw new Error(
+        `tokenomics.defaultMemberTokens (${tokenomics.defaultMemberTokens} × ${organizations.length} orgs = ${totalForOrgs}) ` +
+        `must be less than total supply (${tokenomics.supply}) to leave tokens for the treasury`
+      );
+    }
+  }
+
+  return result.data;
+}