TAM: Introduction to Tokenized Allocation Mechanisms

Tokenized Allocation Mechanisms generalize a proven Yearn V3 pattern to governance and funding. The mechanism itself is an ERC‑20‑like share ledger with strict transfer rules; its lifecycle is fixed by the shared implementation, while hooks let you swap in different voting rules (e.g., Quadratic Funding vs. simple linear voting).

Who this is for

• Protocol teams building repeatable, auditable funding rounds.
• DAO operators who want permissionless queuing with a safety net (timelocks, grace periods).
• Researchers experimenting with voting functions under an invariant‑checked framework.

The model in one paragraph

Voters register (optionally depositing assets to gain voting power), proposers open proposals, and voters cast W votes at W² cost (“quadratic cost”) for the QF implementation. After the window closes, the owner finalizes tallies; then anyone can queue successful proposals. Recipients receive shares (redeemable only during a global window) or funds via a custom distribution hook that also keeps accounting correct. Shares are non‑transferable before redemption starts.

💡Delegatecall: runs code from another contract using the caller’s storage—here, the proxy holds state, the implementation supplies behavior. *

Hook: “your override point”; these are internal functions exposed via safe wrappers that only the implementation can call (the onlySelf pattern).

Timelock: delays execution and the grace period is the window where recipients can redeem; sweep is a post‑grace recovery of unclaimed funds.

Why TAM (developer motivations)

The design targets three outcomes: (1) modularity with a single audited core and small, policy‑only mechanisms; (2) permissionless execution at the right step (queuing) without giving up policy control (use the hook to constrain distribution); and (3) operational clarity through explicit windows, proposal states, and EIP‑712 signatures for gasless UX.

Key concepts (compact glossary)

These terms appear throughout the code and spec; understanding them avoids surprises during integration.

• TokenizedAllocationMechanism (implementation). Shared logic: registration, proposals, voting, tally finalization, queuing, redemption; ERC‑20‑style share ledger with transfer restrictions; EIP‑712 signatures. Storage lives in the proxy via delegatecall.
• BaseAllocationMechanism (proxy). Minimal delegator exposing onlySelf‑gated hook wrappers; all unknown calls fall back to the implementation. This ensures hooks are unreachable from userland.
• QuadraticVotingMechanism (mechanism base). Quadratic cost rules and α‑weighted funding (F_j = α(∑√c)^2 + (1−α)∑c), plus helpers for optimal α selection.
• ProperQF (math utilities). Incremental state for ∑√c and linear sums so per‑vote updates are O(1) yet exactly match full recomputation.

What users should expect

• Voters: One vote per proposal, quadratic pricing of weight, and visible tallies and states.
• Recipients: Either minted shares (redeemable only during the window) or a direct transfer applied by custom distribution.
• Operators: Clear gates: voting window, finalization, timelock, redemption window, then sweep.

Lifecycles at a glance

Round (direct participation)

1. Register → voting power. Voter calls signup(deposit) (or signature variant); power accrues deterministically by hook logic.
2. Propose. Authorized proposer (keeper/management by default) calls propose(recipient, description).
3. Vote. Voter calls castVote(pid, choice, weight, expectedRecipient); quadratic cost enforced; one vote per proposal.
4. Finalize tally (owner). After the window, owner calls finalizeVoteTally().
5. Queue (anyone). queueProposal(pid) checks quorum and converts votes to shares via hook; either mints shares or performs a custom distribution while keeping totalAssets consistent.
6. Redeem. Recipient redeems during the global redemption window; outside that window, 0 limit and later sweep by owner.

Responsibilities for mechanism authors

• Implement the hooks precisely and deterministically. When working with _processVoteHook, ensure it conserves power and properly enforces quadratic cost, always returning the new remaining power. For _convertVotesToShares, you must respect budget constraints and handle rounding appropriately; specifically for Quadratic Funding implementations, use the α‑blend and incremental state calculations from ProperQF. If you implement permissionless queuing, be sure to enforce any additional policies within the _requestCustomDistributionHook and always return the exact assetsTransferred value to maintain accurate accounting.