Delegated Voting and Vote Escrow Models

Detailed Instructions

Begin by architecturing the core Vote-Escrow (ve) token contract. This contract will manage the locking of a governance token (e.g., ERC20Votes) in exchange for a non-transferable veToken representing voting power. Define the primary data structures: a LockedBalance struct to store the locked amount and unlock timestamp, and a mapping from user addresses to their lock data.

• Sub-step 1: Inherit from OpenZeppelin's ERC20Votes and ERC20Permit for the base token. Create a new veToken contract that is ERC721 (non-transferable) or a custom non-transferable token standard.
• Sub-step 2: Implement the create_lock(uint256 _value, uint256 _unlock_time) function. It must transfer _value of the base token from the user to the contract and mint a veToken NFT.
• Sub-step 3: Calculate voting power. The standard formula is voting_power = locked_amount * (unlock_time - block.timestamp) / MAX_LOCK_TIME. Store this value for each user epoch.

solidityCopy
struct LockedBalance {
    uint256 amount;
    uint256 end;
}
mapping(address => LockedBalance) public locked;

function _votingPowerOf(address _user) internal view returns (uint256) {
    LockedBalance memory lock = locked[_user];
    if (lock.end <= block.timestamp) return 0;
    return (lock.amount * (lock.end - block.timestamp)) / MAX_LOCK_TIME;
}

Tip: Use a MAX_LOCK_TIME constant (e.g., 4 years in seconds) to normalize voting power, creating an incentive for longer lock durations.

Detailed Instructions

The core economic mechanism is time-weighted voting power. Unlike a simple locked balance, power must decay linearly to zero at the unlock time, preventing permanent influence. This requires calculating power on-the-fly based on the current block timestamp.

• Sub-step 1: Modify the balanceOf or getVotes function in your veToken contract to call the internal _votingPowerOf function. This ensures any external query gets the current, decayed power.
• Sub-step 2: For historical vote snapshots (e.g., for past proposals), you must checkpoint the voting power. Implement a checkpoint() function that records a user's power at the current block number. Store checkpoints in an array for each user.
• Sub-step 3: When a user increases their lock amount or extends their lock time (increase_amount, increase_unlock_time), you must create a new checkpoint. Calculate the new slope and bias for the linear decay function and update the global state.

solidityCopy
function getVotes(address account) public view override returns (uint256) {
    // Return the linearly decaying voting power at the current block
    return _votingPowerOf(account);
}

function checkpoint() public {
    // Write a new checkpoint for the msg.sender at block.number
    _writeCheckpoint(msg.sender, _votingPowerOf(msg.sender));
}

Tip: For gas efficiency in complex DeFi integrations, consider emitting a VotePowerChanged event on every lock modification so indexers can track power without constant contract calls.

Detailed Instructions

The veToken contract holds voting power; a separate Governor contract uses it to execute on-chain proposals. Use OpenZeppelin's Governor framework. The veToken must implement the IVotes interface, providing getVotes, getPastVotes, and delegate functions.

• Sub-step 1: Ensure your veToken contract inherits from OpenZeppelin's Votes abstract contract or manually implements the IVotes interface. The delegate function should allow users to delegate their decaying voting power to another address.
• Sub-step 2: Deploy a Governor contract (e.g., GovernorVotesQuorumFraction) that is initialized with the address of the veToken as the token parameter. This links governance power directly to the escrowed tokens.
• Sub-step 3: Configure governance parameters in the Governor contract: votingDelay (blocks before voting starts), votingPeriod (blocks voting is active), and quorumFraction (percentage of total veToken supply required to pass). For a ve system, a quorumFraction of 4% is a common starting point.

solidityCopy
import "@openzeppelin/contracts/governance/Governor.sol";
import "@openzeppelin/contracts/governance/extensions/GovernorVotes.sol";

contract VeGovernor is Governor, GovernorVotes {
    constructor(IVotes _token)
        Governor("VeGovernor")
        GovernorVotes(_token)
    {}
    // ... set votingDelay, votingPeriod, quorumNumerator
}

Tip: Use GovernorVotesQuorumFraction to easily set a quorum based on a fraction of the total historical veToken supply, which is more secure than using the current supply.

Detailed Instructions

A critical feature for adoption is fee distribution to veToken lockers, often in the form of protocol revenue (e.g., trading fees). This requires a FeeDistributor contract that calculates rewards proportionally to a user's time-weighted lock.

• Sub-step 1: Design a contract that accepts fee tokens (e.g., USDC, ETH) from the protocol. It should track the total veToken supply at each week using checkpoints, similar to the voting power logic.
• Sub-step 2: For each new fee deposit, calculate the amount per veToken for that time period. Accumulate unclaimed rewards for each user based on their lock amount and duration during that period.
• Sub-step 3: Implement a claim() function allowing users to withdraw their accrued rewards. To prevent gas-intensive loops, use a merkle drop mechanism or store a cumulative reward per token that users can subtract their already-claimed amount from.

solidityCopy
// Simplified reward accumulation
mapping(address => uint256) public userRewardPerTokenPaid;
mapping(address => uint256) public rewards;
uint256 public rewardPerTokenStored;

function _updateReward(address account) internal {
    rewardPerTokenStored = rewardPerToken();
    if (account != address(0)) {
        rewards[account] = earned(account);
        userRewardPerTokenPaid[account] = rewardPerTokenStored;
    }
}
function earned(address account) public view returns (uint256) {
    return (balanceOf(account) * (rewardPerToken() - userRewardPerTokenPaid[account])) / 1e18 + rewards[account];
}

Tip: For production, audit a proven implementation like Curve Finance's FeeDistributor.vy (Vyper) to understand the precise time-weighted math and gas optimizations.

Detailed Instructions

After development and testing, deploy the contract suite to a testnet and eventually mainnet. Use a structured deployment script to correctly initialize interdependent contracts and transfer ownership to the Governor.

• Sub-step 1: Write a deployment script (using Hardhat or Foundry) that deploys the base ERC20 token, the veToken contract, the Governor contract, and the FeeDistributor in the correct order. The veToken needs the base token address, and the Governor needs the veToken address.
• Sub-step 2: Verify all contracts on a block explorer like Etherscan. Use constructor arguments ABI encoding to ensure the verification passes and the contract interactions are transparent for users.
• Sub-step 3: Create the first governance proposal to bootstrap the system. This proposal should typically transfer control of the core protocol contracts (e.g., fee settings, admin functions) to the newly deployed Governor contract. Use the propose function on the Governor, specifying the target contracts, calldata, and description.

javascriptCopy
// Example Hardhat deployment snippet
async function main() {
  const Token = await ethers.getContractFactory("ERC20Votes");
  const token = await Token.deploy("Governance Token", "GT");
  await token.deployed();

  const VeToken = await ethers.getContractFactory("VoteEscrow");
  const veToken = await VeToken.deploy(token.address, "veGT", "veGT", "1");
  await veToken.deployed();

  const Governor = await ethers.getContractFactory("VeGovernor");
  const governor = await Governor.deploy(veToken.address);
  await governor.deployed();
}

Tip: Before the first proposal, ensure several trusted community members have created locks to establish an initial quorum. Consider a whitelisted proposal creation period initially to prevent spam.

Detailed Instructions

First, connect your Web3 wallet (e.g., MetaMask) to the protocol's governance interface, such as Tally or the protocol's native dApp. Navigate to the governance section, often labeled "Vote" or "Delegate." Your voting power is typically derived from your token balance. Check the interface to confirm your available voting weight, which may be displayed as a raw token amount or a normalized voting power value. This step is crucial for understanding your influence before delegation.

• Sub-step 1: Connect your wallet and ensure you are on the correct network (e.g., Ethereum Mainnet).
• Sub-step 2: Locate and review your current token balance and associated voting power.
• Sub-step 3: Verify the contract addresses for the governance token and staking contracts from official sources.

Tip: Bookmark the official governance portal URL to avoid phishing sites that could compromise your tokens.

Detailed Instructions

Decide whether to use a simple delegation model or a vote-escrow (veToken) model. In delegation, you assign your voting rights to another address (a delegate) without locking tokens; they can vote on proposals on your behalf. In veToken models, you must lock your tokens for a specified duration (e.g., 1-4 years) to receive non-transferable veTokens, which grant boosted voting power. The lock-up period is a time-weight multiplier; longer locks yield more power per token. Assess your goals: delegation offers flexibility, while escrow provides greater influence and often protocol fee rewards.

• Sub-step 1: Review the protocol's documentation to confirm which model(s) it supports.
• Sub-step 2: For veTokens, calculate potential voting power based on your intended lock duration.
• Sub-step 3: Identify trusted delegates by reviewing their voting history and statements if choosing delegation.

Tip: In veToken systems, your voting power decays over time as the lock expiration approaches, influencing long-term strategy.

Detailed Instructions

For delegation, call the delegate(address delegatee) function on the governance token contract, specifying the recipient's address. This is often a simple write transaction from your wallet. For vote escrow, the process involves a deposit and lock. You will call a function like create_lock(uint256 _value, uint256 _unlock_time) on the escrow contract (e.g., Curve's VotingEscrow). The _value is the token amount to lock, and _unlock_time is a future UNIX timestamp. This transaction mints veTokens to your address. Always verify gas estimates and ensure you have sufficient ETH for the transaction fee.

• Sub-step 1: For delegation, input the delegatee's ENS name or checksummed address.
• Sub-step 2: For escrow, use a tool to calculate the exact UNIX timestamp for your desired lock period.
• Sub-step 3: Review the transaction details in your wallet before signing, checking the contract interaction.

solidityCopy
// Example delegation call for an ERC20Votes-compatible token
IERC20Votes(tokenAddress).delegate(delegateeAddress);

Tip: Test with a small amount first if the interface allows, especially for locking transactions which are irreversible until maturity.

Detailed Instructions

After the transaction is confirmed, verify the new state on-chain. Use a block explorer like Etherscan to check the transaction logs. For delegation, look for a DelegateChanged event. Your token balance remains in your wallet, but voting power is assigned. For vote escrow, look for a Deposit or Supply event; your base tokens are now locked. Then, return to the governance interface or query the contract directly to confirm your updated voting weight. For veTokens, call the balanceOf(address addr) function on the escrow contract. For delegated power, call getVotes(address account) on the governance token contract at the current block.

• Sub-step 1: Paste your transaction hash into a block explorer and confirm its success status.
• Sub-step 2: On the governance UI, refresh the page and check if your voting power display has updated.
• Sub-step 3: Use a read function in a tool like Etherscan's "Read Contract" tab to query your voting power directly.

Tip: Voting power snapshots are often taken at a specific block per proposal; your power is based on your balance/delegation at that historical block, not necessarily the current state.

Detailed Instructions

Your initial choice is not permanent. For delegation, you can re-delegate to a different address at any time by submitting a new delegate transaction; the change is effective from the next block. For vote-escrow positions, management is more complex. You cannot withdraw tokens before the unlock time, but you may often increase the lock amount or extend the lock duration. Some protocols allow merging locks. To extend, call a function like increase_unlock_time(uint256 _unlock_time). To add more tokens, use increase_amount(uint256 _value). Always review the contract's specific functions, as early exit is typically impossible without community approval via governance.

• Sub-step 1: To change a delegate, simply execute a new delegation to the new address.
• Sub-step 2: To extend a veToken lock, calculate the new unlock timestamp and submit the transaction.
• Sub-step 3: Monitor your lock expiration and plan ahead for potential re-locking to maintain voting influence.

solidityCopy
// Example calls for a veToken contract (like Curve)
// Increase lock amount
VotingEscrow(escrowAddress).increase_amount(additionalTokenAmount);
// Extend lock time
VotingEscrow(escrowAddress).increase_unlock_time(newUnlockTimestamp);

Tip: In ve systems, the maximum voting power boost is achieved at the maximum lock duration (e.g., 4 years). Extending an existing lock resets the time-weight calculation.