create-governance

DAO scaffolding 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

create-governance automates the creation of a complete on-chain governance framework designed for gateway interoperability ecosystems 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. Includes a reputation checkpointing system (inspired by ERC20Votes) for historical queries and manipulation resistance.
PolicyRegistry	Simple key-value store for protocol parameters (e.g. fee percentages, epoch durations). Only the governor can modify it, ensuring all changes go through on-chain governance.

---

Quick Start

npx create-governance

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.

# Generate contracts and deploy to Hardhat's local network
npx create-governance --deploy --network hardhat

The interactive mode will guide you through deploying directly after generation.

---

Configuration

All settings are read from a config.json file. Below is a complete example:

{
  "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.
• Gateways can be specified as plain addresses

---

Commands

Command	Description
npx create-governance	Generate contracts from config.json. Offers interactive deployment.
npx create-governance --deploy	Generate and deploy to localhost (requires a running Hardhat node).
npm run deploy	Alias for the above (if using the package scripts).

---

Deployment Process

After generation, you can choose to deploy immediately. The CLI will:

1. Create a hardhat.config.cjs (Cancun-ready) if none exists.
2. Execute the deployment script in the following order:
   • Deploy the Token.
   • Optionally deploy the Timelock.
   • Deploy the GatewayRegistry and PolicyRegistry.
   • Register all organizations, transfer initial tokens, and register their gateways.
   • Add protocol parameters to the PolicyRegistry.
   • Transfer remaining token supply to the timelock (if enabled).
   • Deploy the GovernanceTL contract, passing all configured parameters.
   • Grant timelock roles to the governor, transfer registry ownership to the timelock, and revoke the deployer's admin rights.

A summary of all deployed addresses is printed at the end.

---

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.