Skip to content

Home

Jump to bottom
Tcholas edited this page Jan 14, 2025 · 2 revisions

Futarchy Governance Protocol Documentation

1. Introduction

This repository holds a modular implementation of a futarchy-based governance protocol using Gnosis Conditional Tokens (CTF) and liquidity pools. The core idea is that we split "base" protocol-owned liquidity into "pass" and "fail" pools for a given proposal, then recombine them after the proposal's outcome is decided. This doc covers the high-level architecture, details of each contract, and how they interact.

2. Repository Overview

The src/ directory contains all production contracts:

  • pools/ for Balancer-based pooling (e.g., BalancerPoolWrapper.sol)
  • gnosis/ for Gnosis CTF integration (GnosisCTFAdapter.sol)
  • mocks/ for local testing stubs and prototypes
  • FAO/ (Futarchy Approval Oracle) for the logic around proposals, oracles, and settlement (FutarchyGovernor.sol, FutarchyOracle.sol, ProposalManager.sol)
  • combinatorial/ for advanced expression handling in more complex contexts
  • FutarchyPoolManager.sol is the central manager that orchestrates the creation of conditional pools and handles splitting/merging liquidity

The test/ directory includes Foundry-based tests that demonstrate the main flows:

  • Setting up a fork of Gnosis Chain (for real-world scenario tests)
  • Splitting collateral tokens into binary outcome tokens
  • Deploying mock or real Balancer pools and verifying liquidity operations

The script/ directory has deployment scripts such as DeployFutarchy.s.sol.

3. High-Level Architecture

Before diving into individual contracts, here's how the pieces fit together:

Base Liquidity

Initially, the protocol has a base pool (e.g., TOKEN/CURRENCY) managed by FutarchyPoolManager. When a proposal enters its evaluation phase, some of that liquidity is withdrawn into separate TOKEN and CURRENCY.

Split Tokens

Using GnosisCTFAdapter, the code splits TOKEN into (pTOKEN, fTOKEN) and CURRENCY into (pCURRENCY, fCURRENCY), referencing a Gnosis condition ID for binary outcomes (proposal pass/fail).

Create Condition Pools

The manager deploys two pools:

  • Pass Pool (pTOKEN/pCURRENCY)
  • Fail Pool (fTOKEN/fCURRENCY)

Market Trading

Traders "buy" or "sell" conditionally by interacting with those pass/fail pools. This way, they speculate on the proposal's effect while the proposal is pending.

Resolution

At the end, an oracle (e.g., FutarchyOracle) marks the proposal as pass or fail. The FutarchyPoolManager merges the relevant tokens back into the base pool.

Proposal Execution

If the proposal passes, further governance steps are triggered (e.g., in FutarchyGovernor).

4. Key Contracts

4.1. FutarchyPoolManager

Location: src/FutarchyPoolManager.sol
Purpose: Orchestrates the entire life cycle of a conditional pool for a given proposal:

  • Calls the Gnosis CTF adapter to split outcome tokens
  • Uses a Balancer pool wrapper to create and manage pass/fail liquidity pools
  • Merges everything back after resolution

4.2. GnosisCTFAdapter

Location: src/gnosis/GnosisCTFAdapter.sol
Purpose: Wraps the Gnosis Conditional Token Framework's split/redeem functions. It also integrates a Wrapped1155Factory so that each outcome token can appear as a standard ERC20, simplifying pool creation.

4.3. BalancerPoolWrapper

Location: src/pools/BalancerPoolWrapper.sol
Purpose: Interacts with Balancer vaults or a mock version to:

  • createPool(tokenA, tokenB, weight)
  • addLiquidity(...)
  • removeLiquidity(...)

4.4. Futarchy Oracle & Approval Mechanisms

Location: src/FAO/
Key Contracts:

  • FutarchyOracle.sol and FutarchyGovernor.sol: Provide a resolution flow
  • FutarchyProposerGuard.sol: Restricts who can propose or final-check a proposal
  • ProposalManager.sol: Manages minted proposal NFTs and auctions for them

4.5. Mocks

Location: src/mocks/
Purpose: Provides test-friendly contracts like MockERC20.sol, MockBalancerPoolWrapper.sol, and MockConditionalTokens.sol.

5. Tests

We rely on Foundry for testing. Major test scenarios include:

  • test/GnosisFork.t.sol uses a fork from the environment variable GNOSIS_RPC_URL
  • test/FutarchyPoolManager.t.sol walks through:
    • Creating a base pool
    • Splitting on a condition
    • Handling errors
    • Merging after settlement
  • test/GnosisCTFAdapter.t.sol covers splitting and redeeming for multiple outcomes, verifying revert conditions, etc.

6. Setting Up & Development

Install Foundry

If you haven't yet installed Foundry, visit Foundry's official docs.

Clone Repo & Configure

git clone https://github.com/YourOrg/futarchy.git
cd futarchy
cp .env.example .env
# Fill in env with any required keys or RPC endpoints

Build & Test

forge build
forge test

Deploy

A sample script DeployFutarchy.s.sol is under /script. Modify it for the correct constructor parameters (e.g., addresses for Gnosis CTF, Balancer Vault).

Then do:

forge script script/DeployFutarchy.s.sol --broadcast --verify

7. Contributing

  • Pull Requests: Please ensure your PR includes relevant tests
  • Security: The code deals with a variety of potentially large financial transactions. Let us know if you see any vulnerabilities.

8. Knowledge Management

Given that the protocol is quite large and the architecture can evolve quickly, consider "saving" this wiki (plus any relevant business context or deployment instructions) in a persistent knowledge base. It makes future dev cycles more efficient.

Clone this wiki locally