Votemarket Hooks

Your Incentives, Your Rules

Overview

Hooks automatically handle undistributed incentives at the end of campaign periods. When a campaign's max price per vote caps the reward-per-vote, or when a gauge receives no votes, the surplus rewards are sent to the hook contract for custom processing.

How Leftovers Occur

Leftover rewards are generated in two scenarios:

1. Max price cap reached — The campaign allocates more rewards per period than what the max price per vote allows given the actual votes received. The excess becomes leftover.
2. No votes received — The entire period allocation becomes leftover since no voters are eligible.

Hook Lifecycle

When an epoch closes with leftover rewards, Votemarket transfers the tokens to the hook contract and calls doSomething(). The hook then processes the rewards according to its own logic.

The IHook Interface

All hook contracts must implement the following interface:

interface IHook {
    function doSomething(
        uint256 campaignId,
        uint256 chainId,
        address rewardToken,
        uint256 epoch,
        uint256 amount,
        bytes calldata hookData
    ) external;
}

Available Hooks

Votemarket ships three hooks covering the most common leftover management strategies. Each hook is whitelisted per Votemarket instance by governance.

Liquidity Mining

The Liquidity Mining hook captures surplus rewards and redirects them to liquidity providers. Leftover rewards are bridged from Arbitrum to Ethereum via LaPoste, then distributed through a Merkle-tree based distribution system to holders of the strategy (the vault share token representing LP positions) that corresponds to the campaign's gauge.

1. When an epoch closes with leftover rewards, Votemarket calls doSomething(). The hook validates the reward token against LaPoste's TokenFactory and stages the incentive data (campaign, token, amount, gauge) in storage.
2. Once incentives are staged, anyone can call bridgeIncentives() to batch them and bridge via LaPoste (Chainlink CCIP) to Ethereum. This call is permissionless but requires ETH for bridging fees.
3. On Ethereum, the CampaignRewardsDistributor (0xd4898a378ea555595c4e7dbde722b134a3f346d1) receives the tokens and distributes them through a Merkle-tree based distribution system over a configurable duration to holders of the strategy corresponding to the campaign's gauge.

Once rewards land in the CampaignRewardsDistributor, an off-chain pipeline handles the actual distribution to strategy holders.

1. Incentive registration — When rewards arrive (via bridge or direct deposit), the CampaignRewardsDistributor stores the incentive and emits an IncentiveAdded event with the gauge, token, amount, duration, and manager.
2. Incentive detection — An automated off-chain script (merkl-toolkit) runs every ~6 hours. It polls the contract for new incentives via nbIncentives() and incentives(i), then matches each gauge to its corresponding Stake DAO strategy (Curve v2, Balancer v2, or Pendle).
3. TWAB calculation — For each active incentive, the script computes a Time-Weighted Average Balance (TWAB) of all vault share holders over the incentive window. It replays every Transfer event on the vault token to reconstruct balances over time, ensuring rewards are proportional to how long and how much each user held.
4. Wrapper expansion — If a vault share holder is a wrapper contract (e.g. a Morpho vault), the script discovers the underlying depositors and runs a sub-TWAB on the wrapper's deposit/withdrawal events. The wrapper's allocation is redistributed proportionally to its depositors.
5. Merkle tree generation — A cumulative Merkle tree is built: each new root includes all prior rewards plus the new distribution. Leaves are double-hashed (keccak256(keccak256(abi.encode(user, token, amount)))) for second preimage protection.
6. Verification — Before publishing, the script checks that the contract balance covers all pending claims (solvency check) and simulates every claim() call on-chain to ensure no claim would revert.
7. Root publication — The new Merkle root is set on-chain via setRoot(). Strategy holders can then claim their accumulated rewards at any time using Merkle proofs.

The CampaignRewardsDistributor also accepts direct incentives deposited on Ethereum, without going through the Votemarket hook flow. Anyone can call addIncentive() to deposit reward tokens directly for a specific gauge.

The addIncentive() function is permissionless — any address can deposit incentives for any gauge. Each incentive specifies:

The depositor must approve the CampaignRewardsDistributor for the reward token before calling addIncentive(). Distribution starts immediately at the current block timestamp.

IncentiveGaugeHook (L2)

CampaignRewardsDistributor (Ethereum)

Leftover Distribution

The simplest hook — sends unspent rewards directly to a designated recipient. Useful when a campaign manager wants leftover rewards forwarded to a specific address (e.g., a treasury, a DAO multisig, or another contract).

1. When doSomething() is called with leftover rewards, the hook looks up a custom recipient for that specific campaign.
2. If no custom recipient is set, it falls back to the campaign's manager address.
3. If neither is found, the transaction reverts.
4. Tokens are transferred directly to the resolved recipient in a single step.

Governance can also override any recipient via overrideLeftOverRecipient().

Rollover & Refund

The Rollover & Refund hook intelligently routes leftover rewards based on campaign timing. During active periods, leftovers are rolled over back into the campaign to increase its budget. At the last period(s), leftovers are refunded to the campaign manager.

1. When doSomething() is called with leftover rewards, the hook cannot call back into Votemarket in the same transaction due to Votemarket's nonReentrant guard. Instead, it queues the leftover data in pendingRollovers.
2. Anyone can then call executeRollovers() permissionlessly to process the queued rollovers in a separate transaction.
3. During execution, the hook checks the campaign's remaining periods against a configurable threshold:
   • Above threshold (active periods remain): leftovers are rolled over into the campaign via increaseTotalRewardAmount(), increasing the budget for future epochs.
   • At or below threshold (last period): leftovers are refunded directly to the campaign manager.

Comparison

Deployments

All hooks are deployed at the same address across every supported chain.

See the Contract Addresses page for the full registry.

Security

• Whitelisted access: Only Votemarket instances explicitly whitelisted by governance can call a hook's doSomething() function. Unauthorized contracts cannot trigger hooks.
• Governance model: All hooks use a two-step governance transfer pattern (transferGovernance() → acceptGovernance()) to prevent accidental ownership changes.
• NonReentrant safety: Votemarket's nonReentrant modifier prevents hooks from calling back into the Votemarket contract during doSomething(). The RolloverRefundHook handles this with a queue-and-execute pattern.
• Rescue function: All hooks include a rescueERC20() governance function for emergency token recovery.