# Governance

### Introduction

This document provides an overview of the governance system implemented in OpenLedger, referencing the `OpenLedgerGovernor` smart contract and the associated governance test suite. It is intended for auditors and stakeholders who require insight into the protocol’s on-chain governance mechanisms, parameters, and security considerations.

***

### Governance Architecture

OpenLedger’s governance is based on the OpenZeppelin Governor framework, extended for advanced features and robust security. The core contract, `OpenLedgerGovernor`, manages proposal creation, voting, and execution, leveraging a timelock for secure and transparent upgrades.

#### Key Components

* **Governor Contract:** `OpenLedgerGovernor` (see `contracts/OpenLedgerGovernor.sol`)
* **Governance Token:** GOpen (GOPEN) — see `gOpen.md`
* **Timelock Controller:** Enforces execution delays for approved proposals
* **Voting Power:** Derived from GOpen token balances (ERC20Votes extension)
* **Test Suite:** Comprehensive tests in `test/governance/`

***

### Governance Process

#### 1. Proposal Creation

* Any address holding at least the **proposal threshold** of GOpen tokens can create a proposal.
* **Proposal Threshold:** 10,000 GOPEN
* Proposals specify actions to be executed by the protocol if approved.

#### 2. Voting

* **Voting Delay:** 1 day after proposal creation before voting starts.
* **Voting Period:** 1 weeks for token holders to cast votes.
* Each GOpen token equals one vote; voting power can be delegated.
* Votes are tracked and checkpointed for transparency.

#### 3. Quorum and Approval

* **Quorum:** 5% of total GOpen supply must participate for a proposal to be valid.
* Proposals pass if they receive more "For" than "Against" votes and meet quorum.

#### 4. Timelock and Execution

* **Timelock Delay:** 1 week after proposal approval before execution.
* Only proposals that pass all checks and delays are executed by the Timelock Controller.
* Timelock ensures time for review and potential intervention before changes are applied.

#### 5. Proposal States

Proposals transition through the following states:

* Pending
* Active
* Canceled
* Defeated
* Succeeded
* Queued
* Expired
* Executed

***

### Security Features

* **Battle-tested Modules:** Built on OpenZeppelin Governor, Timelock, and ERC20Votes.
* **Role-Based Access:** Timelock roles (Proposer, Executor, Admin) are strictly managed.
* **Reentrancy Protection:** Follows checks-effects-interactions pattern.
* **Test Coverage:** All governance logic is covered by automated tests (see `test/governance/`).

***

### Governance Parameters

| Parameter          | Value        | Description                                 |
| ------------------ | ------------ | ------------------------------------------- |
| Voting Period      | 1 weeks      | Duration for voting on proposals            |
| Voting Delay       | 1 day        | Delay before voting starts                  |
| Timelock Delay     | 1 week       | Delay before execution after approval       |
| Proposal Threshold | 10,000 GOPEN | Minimum tokens to create a proposal         |
| Quorum             | 5%           | Minimum participation for proposal validity |

***

### Commands: Install, Compile, Test, Coverage, and Deploy

To work with OpenLedger governance contracts, use the following commands from the project root:

```sh
# Install dependencies
npm install

# Compile contracts
npx hardhat compile

# Run tests
npx hardhat test test/governance/**/*.js

# Generate coverage report
npx hardhat coverage

# Deploy governance contracts (replace [network] with your target network)
npx hardhat ignition deploy ignition/modules/deployGovernor.js --network [network]
```

***

### Test Coverage

The `OpenLedgerGovernor.sol` contract, which implements the core governance logic, is covered by a comprehensive automated test suite. As of the latest coverage report:

* **Statements:** 100%
* **Branches:** 100%
* **Functions:** 100%
* **Lines:** 100%

This demonstrates rigorous testing of the proposal lifecycle, parameter changes, role management, and edge cases for the governance system.

***

### Testing and Auditability

The `test/governance/` directory contains comprehensive tests for:

* Proposal lifecycle (creation, voting, queuing, execution, cancellation)
* Parameter changes (voting period, delay, threshold)
* Social consensus proposals
* Timelock and role management
* Edge cases and failure scenarios

These tests ensure the correctness and resilience of the governance system.

***

### References

* `contracts/OpenLedgerGovernor.sol` — Core governance contract
* `test/governance/` — Governance test suite
* `docs/gOpen.md` — GOpen governance token details
* OpenZeppelin Governor documentation: <https://docs.openzeppelin.com/contracts/5.x/governance>

***

### Contact

For security concerns or audit questions, contact: **<security@openledger.xyz>**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://openledger.gitbook.io/openledger/contracts/governance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.