Separate "Withdrawable" Bucket for Fully-Thawed Delegation Tokens

AxiomaticAardvark · June 8, 2026, 7:45am

I proposed a fix 2 weeks ago but there’s been only radio silence. typical for e&n

github.com/graphprotocol/contracts

feat(horizon): add delegation withdrawable bucket (tokensWithdrawable) (#1340)

main ← cargopete:feat/delegation-withdrawable-bucket

opened 09:19AM - 26 May 26 UTC

cargopete

+209 -31

## Summary Implements the \"withdrawable bucket\" design proposed by PaulieB in… the Graph Forum ([Accurately Representing Delegated GRT in APR/APY Calculations](https://forum.thegraph.com/t/accurately-representing-delegated-grt-in-apr-apy-calculations/6924)), which addresses a distortion in delegation APR/APY metrics caused by thawed-but-not-yet-withdrawn tokens remaining in the delegation pool denominator. ### The Problem When a delegator calls `undelegate`, their tokens enter a 28-day thaw period. After the thaw completes, the tokens still sit in `pool.tokens` until `withdrawDelegated` is explicitly called. This means: - `pool.tokens` includes tokens that no longer earn rewards - APR/APY calculations that divide rewards by `pool.tokens` are systematically depressed - The longer withdrawals are delayed, the worse the distortion ### The Fix This PR introduces a **pool-level `tokensWithdrawable` bucket** — a running total of delegation that has completed thawing but hasn't been withdrawn yet. A new permissionless function `releaseThawedDelegation` allows anyone (bots, dashboards, delegators) to scan expired thaw requests and move them into this bucket without transferring tokens. The key formula change: ``` // Before getDelegatedTokensAvailable = pool.tokens - pool.tokensThawing // After getDelegatedTokensAvailable = pool.tokens - pool.tokensThawing - pool.tokensWithdrawable ``` This correctly reflects only the actively-earning delegation base for APR/APY and capacity calculations. ### Changes **`IHorizonStakingTypes.sol`** - `DelegationPool` (public struct): add `tokensWithdrawable` - `DelegationPoolInternal`: add `tokensWithdrawable` - `DelegationInternal`: add `tokensReleasedPendingWithdrawal` (per-delegator tally) **`IHorizonStakingMain.sol`** - New `DelegationThawReleased` event - New `releaseThawedDelegation(serviceProvider, verifier, delegator, nThawRequests)` external function **`IHorizonStakingBase.sol`** - Updated `getDelegatedTokensAvailable` NatSpec to document new formula - New `getDelegatedTokensWithdrawable` view getter **`HorizonStakingBase.sol`** - `getDelegationPool`: expose `tokensWithdrawable` in public return value - `getDelegatedTokensWithdrawable`: implemented - `_getDelegatedTokensAvailable`: updated formula **`HorizonStaking.sol`** - `_undelegate`: active-base fix — exclude `tokensWithdrawable` when computing share → token conversion - `_withdrawDelegated`: calls `_releaseThawedDelegation` first (handles the common case where delegators skip the explicit release step), then drains `delegation.tokensReleasedPendingWithdrawal` - New `releaseThawedDelegation` external function (permissionless wrapper) - New `_releaseThawedDelegation` private implementation ### Backward Compatibility - Existing delegators do not need to change their workflow — `withdrawDelegated` calls `_releaseThawedDelegation` internally as a lazy first step - `releaseThawedDelegation` is a pure value-add: bots or dashboards can call it to keep `tokensWithdrawable` accurate before APR/APY snapshots - No changes to existing function signatures ### Testing Checklist - [ ] `_releaseThawedDelegation` processes expired requests and skips unexpired ones - [ ] `pool.tokensWithdrawable` is correctly incremented/decremented across release → withdraw lifecycle - [ ] `pool.tokensThawing` / `sharesThawing` are correctly decremented on release - [ ] `delegation.tokensReleasedPendingWithdrawal` is zeroed after `withdrawDelegated` - [ ] `getDelegatedTokensAvailable` returns `tokens - tokensThawing - tokensWithdrawable` - [ ] `_undelegate` share-value calculation uses corrected active base - [ ] Stale (wrong nonce) thaw requests are removed from list but don't accrue tokens - [ ] `releaseThawedDelegation` is callable by any address (permissionless) - [ ] `withdrawDelegated` with no prior `releaseThawedDelegation` call still works end-to-end Ref: https://forum.thegraph.com/t/accurately-representing-delegated-grt-in-apr-apy-calculations/6924

Topic		Replies	Views
Delegators rewards should be withdrawable to a separate address Research & Development	41	6624	March 3, 2021
Implement a token burn on indexer rewards withdrawn to a separate address via GIP-0002 Research & Development	48	4045	March 22, 2021
GIP-0002: Rewards destination for indexer's indexing rewards Graph Improvement Proposals (GIP) protocol-gov	169	16165	March 30, 2021

Separate "Withdrawable" Bucket for Fully-Thawed Delegation Tokens

Related topics