# Upgrade stCELO Contracts: Precise Withdrawal Accounting and Distribution
## Summary
This proposal upgrades the four core stCELO implementation contracts to improve how withdrawals are accounted for and distributed across validator groups, and to add a permissionless safeguard for re-routing a withdrawal if a group’s available capacity changes. Storage layouts are unchanged and the upgrade is non-breaking for users.
## Motivation
stCELO withdrawals are served from a mix of a group’s revocable Election votes and the unlocked CELO backing its scheduled votes. The previous accounting measured a group’s available capacity in a way that could include votes that aren’t currently realisable, which made withdrawal distribution less precise than it should be. This upgrade makes capacity accounting reflect what can actually be delivered at withdrawal time, so withdrawals are spread across groups that can fulfil them and the experience is more predictable.
## What changes
- **More precise withdrawal capacity (`Account`)** — introduces `getRealisableCeloForGroup`, which counts only the CELO a withdrawal can actually draw right now: revocable Election votes plus the balance-backed portion of scheduled votes, net of amounts already earmarked. Withdrawal scheduling validates against this figure.
- **Better distribution (`DefaultStrategy`, `SpecificGroupStrategy`)** — withdrawal vote distribution caps each group by its realisable capacity and spreads across healthy groups instead of concentrating on the largest one, skipping groups that cannot currently contribute.
- **Permissionless safeguard (`Account.rescueScheduledWithdrawal`)** — if a group’s realisable capacity falls below a beneficiary’s scheduled amount, anyone can re-route that scheduled withdrawal onto groups that can fulfil it. Funds can only ever flow to the original beneficiary, so this cannot be used to redirect or seize anyone’s CELO.
- **`Manager`** — threads the distribution context through to the strategies for the above.
## Technical details
New implementations (deployed and source-verified on **Celoscan** and **Blockscout**):
| Contract | Proxy (unchanged) | New implementation |
|—|—|—|
| Account | `0x4aAD04D41FD7fd495503731C5a2579e19054C432` | `0x3a81b5bd5c719cd57d9122d34a093119d61c8117` |
| Manager | `0x0239b96D10a434a56CC9E09383077A0490cF9398` | `0xbc465bbf2e2d71c62eda1b24061916877f6ae15e` |
| DefaultStrategy | `0x3A3ed74B1cC543D5EB323f70ac2F19977a0eA088` | `0xac294abf757dd2890c65751dcc095152c27b3416` |
| SpecificGroupStrategy | `0xb88af6EAc9cd146D8b03b66708EF76beBD937871` | `0x9cbbb5b84dc3dec31daea36c53bdfe145cb40e9d` |
| AddressSortedLinkedList (library) | — | `0x1f2030b177ea2d1ef457e4311d4ace5a920381a1` |
**Upgrade safety**
- Storage layouts are **identical** to the current implementations (verified by per-slot layout diff and on-fork upgrade with live state preserved). No new state variables, no reordering.
- Deployed bytecode matches the published source byte-for-byte (aside from the standard per-deployment immutable addresses).
- Validated end-to-end on a fork of current mainnet: the upgrade applies, existing protocol state is preserved, and withdrawals continue to function.
## On-chain action
This upgrade will be submitted as an on-chain **Celo Governance proposal** and follow the standard governance lifecycle (referendum vote, then execution by Celo Governance). It is not executed directly by the stCELO MultiSig — the MultiSig only serves as the proxies’ owner contract, and its `governanceProposeAndExecute` function is callable exclusively by Celo Governance for exactly this purpose.
The proposal contains a single transaction, which performs all four `upgradeTo` calls atomically:
- **To:** `0x78DaA21FcE4D30E74fF745Da3204764a0ad40179` (stCELO MultiSig)
- **Value:** `0`
- **Function:** `governanceProposeAndExecute(address[],uint256[],bytes[])`
- destinations: `[Account, DefaultStrategy, SpecificGroupStrategy, Manager]` proxies
- values: `[0, 0, 0, 0]`
- payloads: `upgradeTo(newImpl)` for each, in that order
If the proposal passes referendum, execution by Celo Governance triggers the MultiSig to apply all four upgrades in one transaction.
## Risk
Low. Implementations only; proxy addresses, ownership, and all balances are untouched. Storage layout is unchanged and the change is backward-compatible for existing stCELO holders. The new safeguard is permissionless but cannot move funds to anyone other than the original beneficiary.
## Vote
- **Yes** — adopt the withdrawal-flow improvements.
- **No** — keep the current implementations.