┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                           LUX GOVERNANCE ARCHITECTURE                                    │
├─────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                          │
│  VOTING POWER                                                                            │
│  ┌─────────────────────────────────────────────────────────────────────────────────┐    │
│  │  vLUX (Voting Power) = xLUX (LiquidLUX shares) + DLUX (Governance Token)        │    │
│  │                                                                                  │    │
│  │  • xLUX: Yield-bearing liquid staked LUX (earns protocol fees)                  │    │
│  │  • DLUX: OHM-style governance token (vote-only, no yield)                       │    │
│  │  • vLUX: Non-transferable aggregated voting power                               │    │
│  └─────────────────────────────────────────────────────────────────────────────────┘    │
│                                        │                                                 │
│  ┌─────────────────────────────────────┼─────────────────────────────────────────────┐  │
│  │                                     ▼                                              │  │
│  │  ┌─────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐        │  │
│  │  │ GaugeController │    │      Governor       │    │     Timelock        │        │  │
│  │  │                 │    │                     │    │                     │        │  │
│  │  │ Fee allocation  │    │ Proposal lifecycle  │    │ Execution delay     │        │  │
│  │  │ voting          │    │ management          │    │ for security        │        │  │
│  │  └────────┬────────┘    └──────────┬──────────┘    └──────────┬──────────┘        │  │
│  │           │                        │                          │                    │  │
│  │           ▼                        ▼                          ▼                    │  │
│  │  ┌─────────────────────────────────────────────────────────────────────────────┐  │  │
│  │  │                         Gnosis Safe (Treasury)                               │  │  │
│  │  │              Multi-sig + threshold signatures + modules                      │  │  │
│  │  └─────────────────────────────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────────────────┘

vLUX = xLUX + DLUX

VLUX = DLUX × f(K) × time_multiplier

where:
  f(K) = sqrt(K / 100)     // Karma scaling (1.0x - 3.16x)
  time_multiplier = 1 + (lock_months × 0.1)  // Max 4.0x at 30 months

import "@luxfi/contracts/governance/Karma.sol";

Karma karma = Karma(KARMA_ADDRESS);

// Get Karma balance (applies MIN_VERIFIED_KARMA floor if verified)
uint256 k = karma.karmaOf(account);

// Get comprehensive activity status
(
    uint256 karmaBalance,
    bool verified,
    bool activeThisMonth,
    bool activeLastMonth,
    uint256 currentDecayRate,
    bool hasKarmaFloor
) = karma.getActivityStatus(account);

import "@luxfi/contracts/governance/VotingLUX.sol";

VotingLUX votingLux = VotingLUX(VOTING_LUX_ADDRESS);

// Get total voting power
uint256 votingPower = votingLux.balanceOf(account);

// Get breakdown
(uint256 xLuxBalance, uint256 dLuxBalance, uint256 total) =
    votingLux.getVotingPowerBreakdown(account);

// Get past voting power (for proposals)
uint256 pastVotes = votingLux.getPastVotes(account, blockNumber);

import "@luxfi/contracts/governance/Governor.sol";
import "@luxfi/contracts/governance/base/Transaction.sol";

Governor governor = Governor(GOVERNOR_ADDRESS);

// Define transactions
Transaction[] memory txs = new Transaction[](1);
txs[0] = Transaction({
    to: targetContract,
    value: 0,
    data: abi.encodeCall(ITarget.updateParameter, (newValue)),
    operation: Enum.Operation.Call
});

// Submit proposal
governor.submitProposal(
    txs,
    "LIP-001: Update protocol parameter",
    proposerAdapter,
    proposerAdapterData
);

// Check proposal state
Governor.ProposalState state = governor.proposalState(proposalId);
require(state == Governor.ProposalState.EXECUTABLE, "Not executable");

// Execute
governor.executeProposal(proposalId, transactions);

import "@luxfi/contracts/governance/GaugeController.sol";

GaugeController gaugeController = GaugeController(GAUGE_CONTROLLER_ADDRESS);

// Vote for a single gauge (50% of your voting power)
gaugeController.vote(gaugeId, 5000);  // 5000 BPS = 50%

// Vote for multiple gauges at once
uint256[] memory gaugeIds = new uint256[](3);
uint256[] memory weights = new uint256[](3);
gaugeIds[0] = 1; weights[0] = 5000;  // 50% to gauge 1
gaugeIds[1] = 2; weights[1] = 3000;  // 30% to gauge 2
gaugeIds[2] = 3; weights[2] = 2000;  // 20% to gauge 3

gaugeController.voteMultiple(gaugeIds, weights);

// Get current gauge weights
uint256 burnWeight = gaugeController.getGaugeWeightBPS(burnGaugeId);

// Anyone can call to apply pending weight changes (after 1 week)
gaugeController.updateWeights();

import "@luxfi/contracts/governance/Timelock.sol";

Timelock timelock = Timelock(TIMELOCK_ADDRESS);

// Schedule transaction
bytes32 id = timelock.schedule(
    target,
    value,
    data,
    predecessor,
    salt,
    delay
);

// Execute after delay
timelock.execute(target, value, data, predecessor, salt);

// 1. Deploy VotesToken (for voting power)
VotesToken votesToken = new VotesToken("Lux Governance", "DLUX");

// 2. Deploy Timelock
address[] memory proposers = new address[](0);
address[] memory executors = new address[](1);
executors[0] = address(0);  // Anyone can execute
Timelock timelock = new Timelock(2 days, proposers, executors, admin);

// 3. Deploy Strategy
Strategy strategy = new Strategy();

// 4. Deploy Governor
Governor implementation = new Governor();
ERC1967Proxy proxy = new ERC1967Proxy(
    address(implementation),
    abi.encodeCall(Governor.initialize, (
        admin,
        safeAddress,      // vault
        safeAddress,      // target
        address(strategy),
        2 days,           // timelockPeriod
        7 days            // executionPeriod
    ))
);
Governor governor = Governor(address(proxy));

// 5. Deploy GaugeController
GaugeController gaugeController = new GaugeController(address(vLux));

// 6. Add gauges
gaugeController.addGauge(burnAddress, "Burn", 0);
gaugeController.addGauge(validatorVault, "Validators", 0);
gaugeController.addGauge(daoTreasury, "DAO", 0);

import "@luxfi/contracts/liquid/LiquidLUX.sol";
import "@luxfi/contracts/governance/VotingLUX.sol";

// Deposit to LiquidLUX to get xLUX
wlux.approve(address(liquidLux), amount);
uint256 shares = liquidLux.deposit(amount, msg.sender);

// xLUX automatically contributes to vLUX voting power
uint256 votingPower = votingLux.balanceOf(msg.sender);