fix: prevent stuck withdrawals when Election cap exhausts a group (#235)

* fix: prevent and recover stuck withdrawals (Election cap exhaustion)

Rebased onto releases/4 for release.

Root cause: Account.scheduleWithdrawals validated per-group capacity via
getCeloForGroup, which counts scheduledVotes.toVote even when the Election
numVotesReceivable cap permanently blocks it. Withdrawals scheduled against
that stale toVote could never be revoked, pinning a user's CELO to a group
with no recovery path (forum.celo.org/t/.../13333).

Fix:
- New Account.getRealisableCeloForGroup = max(0, revokable - toRevoke)
  + min(balance, toVote), minus existing toWithdraw once (withdraw is
  immediate-first, so a pending withdrawal costs one unit of combined
  capacity, not one per bucket).
- scheduleWithdrawals books each entry through _addBeneficiaryWithdrawal,
  which validates against realisable and threads a shared balance budget so
  a multi-group call cannot double-count the same unlocked CELO.
- DefaultStrategy / SpecificGroupStrategy withdrawal distribution cap each
  group by realisable (real withdrawals) and skip zero-capacity / already
  chosen groups, so distribution never pins to a group that cannot pay and
  never emits a group twice. Transfers (isTransfer) stay accounting-only.
- New permissionless Account.rescueScheduledWithdrawal re-routes an existing
  stuck pin to groups that can fulfill it, gated by _requireGroupInDeficit so
  it only fires when the group genuinely cannot pay the beneficiary now.

Versions bumped per the contract-compatibility check against releases/4:
Account 1.2.2.0 (minor: added view + rescue), DefaultStrategy 1.3.0.0
(major: generateWithdrawalVoteDistribution gained isTransfer),
SpecificGroupStrategy 1.1.1.1 and Manager 1.3.1.1 (patch).

Tests: account-realisable.test.ts (realisable + single-subtraction +
rescue), end-to-end-stuck-withdrawal.test.ts (real-contract prevention,
distribution, no-duplicate-group, rescue gating, shared balance budget),
plus scripts/verify-stuck-withdrawal-mainnet-fork.sh (anvil mainnet-fork
proof). Full suite green; compatibility check passes against releases/4.

* ci: run CI-Pipeline for release branches (releases/**), not just master

PR 235 targets releases/4; the workflow only triggered on PRs into master,
so retargeting left it without CI. Add releases/** to the push and
pull_request branch filters so release-targeted PRs get lint, test, and the
contract-compatibility check.

* fix: align contract versions with releases/4 compatibility baseline

The contract-compatibility CI job compares against a baseline one increment
below releases/4 source and requires getVersionNumber to land exactly on the
releases/4 source values (Account 1.2.1.0, DefaultStrategy 1.2.0.0,
SpecificGroupStrategy 1.1.1.0, Manager 1.3.1.0). An earlier local run read the
baseline one step higher (different toolchain) and over-bumped; revert to the
CI-mandated values.

* chore: add governance release script for stuck-withdrawal fix

Releases the 4 upgraded stCELO impls (Account, DefaultStrategy,
SpecificGroupStrategy, Manager) via a Celo Governance proposal. The proxies
are owned by the stCELO MultiSig, which exposes governanceProposeAndExecute
(onlyGovernance) - so a single CGP tx (Governance -> MultiSig
governanceProposeAndExecute([4 proxies],[0,0,0,0],[upgradeTo x4])) performs all
four upgrades, no owner timelock.

The script deploys the impls, builds the CGP calldata + JSON, and (default
fork-test mode) impersonates Celo Governance to execute it and assert: all 4
proxies repointed, pre-existing storage intact, new code live, versions at
release values. Storage layout verified unchanged vs releases/4 (solc layout
diff + CI compat + on-fork state-intact). --emit-only prints the CGP without
executing.

* chore: release script supports fork + mainnet, with explorer verification

- 'fork' (default): unchanged - fork mainnet, deploy ephemeral impls,
  impersonate Celo Governance, execute governanceProposeAndExecute, assert
  upgrades + storage intact + new code live.
- 'mainnet': real broadcast (needs DEPLOYER_PK, CELO_SCAN_API_KEY). Deploys
  the 4 impls + AddressSortedLinkedList library, verifies each on Celoscan
  (hardhat verify) AND Blockscout (forge verify-contract --verifier blockscout),
  then builds + prints the CGP tx/JSON with the real addresses. Does not
  execute the upgrade (Governance does, on vote pass).

DefaultStrategy verification passes the library link on both verifiers.
solc 0.8.11 / evm istanbul / optimizer disabled (matches hardhat.config).

* fix: correct DefaultStrategy library link + surface deploy errors

The library-link step reused norm() (strips leading zeros) to substitute the
deployed AddressSortedLinkedList address into DefaultStrategy's bytecode
placeholder. If the library address has a leading zero this produces a
wrong-length (malformed) link and the deploy fails - which is what happened on
the mainnet attempt. Preserve the full 40-hex address (0x stripped, lowercased,
leading zeros kept) and assert no unlinked placeholder remains.

Also: deploy() no longer swallows cast stderr - it prints the real error and
aborts, so a failed deploy (bad link, gas, or insufficient funds) is diagnosable
instead of an empty address.

* fix: explicit incrementing nonce for sequential deploys

forno's 'latest' nonce can lag the sequencer, so cast auto-nonce submitted a
stale value (nonce too low: next 28, tx 27). Anchor to the PENDING nonce once
and pass an explicit, caller-incremented --nonce for each of the 5 deploys so
they stay in lock-step with the sequencer. Nonce is incremented in the caller,
not inside the deploy function (it runs in a command-substitution subshell).

* fix: verify Celoscan via forge (avoid hardhat-etherscan solc-bin DNS dep)

hardhat verify failed with 'getaddrinfo ENOTFOUND solc-bin.ethereum.org' - the
@nomiclabs/hardhat-etherscan plugin fetches the solc version list from that host
before verifying. Switch the Celoscan step to forge verify-contract --chain celo
(same as Blockscout, which passed), which uses the local solc and has no
solc-bin dependency. Both explorers now verified through forge.

---------

Co-authored-by: Pavel Hornak <pavel.hornak@clabs.co>

Author: pahor167

.github/workflows/solidity.yml

@@ -1,11 +1,11 @@
 name: CI-Pipeline
 
 on:
-  # Triggers the workflow on push or pull request events but only for the main branch
+  # Triggers on push or pull request events for master and release branches.
   push:
-    branches: [master]
+    branches: [master, "releases/**"]
   pull_request:
-    branches: [master]
+    branches: [master, "releases/**"]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

contracts/Account.sol

@@ -187,6 +187,17 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
     /// @notice There's no amount of scheduled withdrawal for the given beneficiary and group.
     error NoScheduledWithdrawal(address beneficiary, address group);
 
+    /**
+     * @notice Thrown when `rescueScheduledWithdrawal` targets a group that can
+     * still pay the beneficiary's withdrawal - so no rescue is warranted.
+     */
+    error GroupNotInDeficit(
+        address beneficiary,
+        address group,
+        uint256 capacity,
+        uint256 userClaim
+    );
+
     /// @notice Voting for proposal was not successfull.
     error VotingNotSuccessful(uint256 proposalId);
 
@@ -325,19 +336,19 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
             revert GroupsAndVotesArrayLengthsMismatch();
         }
 
+        // Thread one balance budget across groups: balance is shared, so
+        // validating each group independently would double-count the same CELO.
+        uint256 balanceBudget = address(this).balance;
         uint256 totalWithdrawalsDelta;
 
         for (uint256 i = 0; i < withdrawals.length; i++) {
-            uint256 celoAvailableForGroup = getCeloForGroup(groups[i]);
-            if (celoAvailableForGroup < withdrawals[i]) {
-                revert WithdrawalAmountTooHigh(groups[i], celoAvailableForGroup, withdrawals[i]);
-            }
-
-            scheduledVotes[groups[i]].toWithdraw += withdrawals[i];
-            scheduledVotes[groups[i]].toWithdrawFor[beneficiary] += withdrawals[i];
+            balanceBudget = _addBeneficiaryWithdrawal(
+                beneficiary,
+                groups[i],
+                withdrawals[i],
+                balanceBudget
+            );
             totalWithdrawalsDelta += withdrawals[i];
-
-            emit CeloWithdrawalScheduled(beneficiary, groups[i], withdrawals[i]);
         }
 
         totalScheduledWithdrawals += totalWithdrawalsDelta;
@@ -580,6 +591,60 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
         }
     }
 
+    /**
+     * @notice Re-routes a beneficiary's pinned withdrawal onto groups that can
+     * fulfill it, freeing CELO stuck on a group whose Election votes fell below
+     * the pinned amount. Bookkeeping only; no CELO moves. Permissionless, but
+     * only when `fromGroup` truly cannot pay this beneficiary right now (see
+     * `_requireGroupInDeficit`). Funds can only ever reach `beneficiary` via
+     * `Account.withdraw`, so a caller can at worst route to slower groups -
+     * never steal or destroy CELO.
+     * @dev Net change to `totalScheduledWithdrawals` is zero, so it isn't
+     * touched. The source slot is cleared before the additions, so passing
+     * `fromGroup` inside `toGroups` re-adds onto a clean slot instead of
+     * zeroing the beneficiary's claim.
+     * @param beneficiary The beneficiary of the withdrawal.
+     * @param fromGroup The group the withdrawal is currently pinned to.
+     * @param toGroups Groups to re-route the withdrawal across.
+     * @param amounts Per-group CELO amounts. Sum must equal the pinned amount.
+     */
+    function rescueScheduledWithdrawal(
+        address beneficiary,
+        address fromGroup,
+        address[] calldata toGroups,
+        uint256[] calldata amounts
+    ) external onlyWhenNotPaused {
+        if (toGroups.length != amounts.length) {
+            revert GroupsAndVotesArrayLengthsMismatch();
+        }
+        uint256 original = scheduledVotes[fromGroup].toWithdrawFor[beneficiary];
+        if (original == 0) {
+            revert NoScheduledWithdrawal(beneficiary, fromGroup);
+        }
+        _requireGroupInDeficit(beneficiary, fromGroup, original);
+
+        // Clear source FIRST so a malformed `toGroups` containing
+        // `fromGroup` cannot trigger an "add-then-zero" sequence that
+        // would destroy the beneficiary's claim.
+        scheduledVotes[fromGroup].toWithdrawFor[beneficiary] = 0;
+        scheduledVotes[fromGroup].toWithdraw -= original;
+
+        uint256 balanceBudget = address(this).balance;
+        uint256 sum;
+        for (uint256 i = 0; i < toGroups.length; i++) {
+            balanceBudget = _addBeneficiaryWithdrawal(
+                beneficiary,
+                toGroups[i],
+                amounts[i],
+                balanceBudget
+            );
+            sum += amounts[i];
+        }
+        if (sum != original) {
+            revert TransferAmountMisalignment(original, sum);
+        }
+    }
+
     /**
      * @notice Gets the total amount of CELO this contract controls. This is the
      * unlocked CELO balance of the contract plus the amount of LockedGold for this contract,
@@ -762,6 +827,9 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
      * @notice Returns the total amount of CELO directed towards `group`. This is
      * the Unlocked CELO balance for `group` plus the combined amount in pending
      * and active votes made by this contract.
+     * @dev WARNING: includes `scheduledVotes.toVote` even when Election cap is
+     * exhausted and those votes can never be cast. For withdrawal-capacity
+     * decisions use `getRealisableCeloForGroup` instead.
      * @param group The address of the validator group.
      * @return The total amount of CELO directed towards `group`.
      */
@@ -777,6 +845,29 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
         return 0;
     }
 
+    /**
+     * @notice CELO for `group` that `Account.withdraw` can actually pay out now,
+     * unlike `getCeloForGroup` which counts `toVote` the Election cap may block.
+     * @dev Two buckets: revokable Election votes, and the `toVote` slice backed
+     * by current balance (withdraw pays that directly, no Election vote needed).
+     * Subtract queued `toRevoke` from the revoke bucket, and existing
+     * `toWithdraw` once from the total - withdraw is immediate-first, so a
+     * pending withdrawal costs one unit of total capacity, not one per bucket.
+     * @param group The address of the validator group.
+     * @return The realisable CELO for `group`.
+     */
+    function getRealisableCeloForGroup(address group) public view returns (uint256) {
+        uint256 revokable = getElection().getTotalVotesForGroupByAccount(group, address(this));
+        uint256 toRevoke = scheduledVotes[group].toRevoke;
+        uint256 revokableAvail = revokable > toRevoke ? revokable - toRevoke : 0;
+        uint256 toVote = scheduledVotes[group].toVote;
+        uint256 balance = address(this).balance;
+        uint256 immediateBucket = balance < toVote ? balance : toVote;
+        uint256 capacity = revokableAvail + immediateBucket;
+        uint256 toWithdraw = scheduledVotes[group].toWithdraw;
+        return capacity > toWithdraw ? capacity - toWithdraw : 0;
+    }
+
     /**
      * @notice Returns the total amount of CELO that's voted with for a group.
      * @param group The address of the validator group.
@@ -946,4 +1037,69 @@ contract Account is UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Managed, I
             emit RevocationScheduled(group, addToRevoke);
         }
     }
+
+    /**
+     * @notice Books a per-group withdrawal for `rescueScheduledWithdrawal`,
+     * reverting unless the group can realisably fulfill it. Returns the
+     * balance budget left after this pin's immediate draw.
+     */
+    function _addBeneficiaryWithdrawal(
+        address beneficiary,
+        address toGroup,
+        uint256 amount,
+        uint256 balanceBudget
+    ) private returns (uint256 newBalanceBudget) {
+        // Capacity = immediate bucket + revoke bucket, minus what existing
+        // pins on this group already claim (subtracted once - see
+        // getRealisableCeloForGroup). Charge the budget by this pin's immediate
+        // draw so a later group can't reuse the same balance.
+        uint256 immediate;
+        {
+            uint256 revokable = getElection().getTotalVotesForGroupByAccount(
+                toGroup,
+                address(this)
+            );
+            uint256 toRevoke = scheduledVotes[toGroup].toRevoke;
+            uint256 revokableAvail = revokable > toRevoke ? revokable - toRevoke : 0;
+            uint256 toVote = scheduledVotes[toGroup].toVote;
+            uint256 immediateBucket = balanceBudget < toVote ? balanceBudget : toVote;
+            uint256 capacity = revokableAvail + immediateBucket;
+            uint256 existingToWithdraw = scheduledVotes[toGroup].toWithdraw;
+            uint256 capacityForNew = capacity > existingToWithdraw
+                ? capacity - existingToWithdraw
+                : 0;
+            if (amount > capacityForNew) {
+                revert WithdrawalAmountTooHigh(toGroup, capacityForNew, amount);
+            }
+            immediate = amount < immediateBucket ? amount : immediateBucket;
+        }
+        scheduledVotes[toGroup].toWithdraw += amount;
+        scheduledVotes[toGroup].toWithdrawFor[beneficiary] += amount;
+        emit CeloWithdrawalScheduled(beneficiary, toGroup, amount);
+        return balanceBudget - immediate;
+    }
+
+    /**
+     * @notice Reverts unless `group` genuinely cannot pay `userClaim` to this
+     * beneficiary now - the gate that keeps `rescueScheduledWithdrawal`
+     * permissionless without letting anyone reroute a payable withdrawal.
+     * @dev Capacity is what `Account.withdraw(beneficiary, group)` could deliver
+     * for THIS claim: `min(balance, toVote) + revokable`. It deliberately
+     * ignores `toRevoke` and other beneficiaries' `toWithdraw` - withdraw isn't
+     * gated by those, so counting them could mark a payable group as deficient.
+     */
+    function _requireGroupInDeficit(
+        address beneficiary,
+        address group,
+        uint256 userClaim
+    ) private view {
+        uint256 revokable = getElection().getTotalVotesForGroupByAccount(group, address(this));
+        uint256 toVote = scheduledVotes[group].toVote;
+        uint256 balance = address(this).balance;
+        uint256 immediate = toVote < balance ? toVote : balance;
+        uint256 capacity = immediate + revokable;
+        if (capacity >= userClaim) {
+            revert GroupNotInDeficit(beneficiary, group, capacity, userClaim);
+        }
+    }
 }

contracts/DefaultStrategy.sol

@@ -412,7 +412,7 @@ contract DefaultStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausable {
      * @return finalGroups The groups that were chosen for subtraction.
      * @return finalVotes The votes of chosen finalGroups.
      */
-    function generateWithdrawalVoteDistribution(uint256 celoAmount)
+    function generateWithdrawalVoteDistribution(uint256 celoAmount, bool isTransfer)
         external
         managerOrStrategy
         returns (address[] memory finalGroups, uint256[] memory finalVotes)
@@ -430,14 +430,22 @@ contract DefaultStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausable {
         uint256 groupsIndex;
 
         while (groupsIndex < maxGroupCount && celoAmount != 0 && votedGroup != address(0)) {
-            votes[groupsIndex] = Math.min(
-                Math.min(
-                    account.getCeloForGroup(votedGroup),
-                    IManager(manager).toCelo(stCeloInGroup[votedGroup])
-                ),
-                celoAmount
-            );
+            // Real withdrawals cap by realisable CELO so we never pin to a
+            // group that can't pay. Transfers (isTransfer) are accounting-only
+            // and the caller discards the votes, so they skip that cap.
+            uint256 stCeloAsCelo = IManager(manager).toCelo(stCeloInGroup[votedGroup]);
+            uint256 capacity = isTransfer
+                ? stCeloAsCelo
+                : Math.min(account.getRealisableCeloForGroup(votedGroup), stCeloAsCelo);
+
+            if (capacity == 0) {
+                // Nothing to take here; move to the next-smaller group without
+                // using a slot. (Re-reading HEAD would loop on this group.)
+                (, votedGroup, ) = activeGroups.get(votedGroup);
+                continue;
+            }
 
+            votes[groupsIndex] = Math.min(capacity, celoAmount);
             groups[groupsIndex] = votedGroup;
             celoAmount -= votes[groupsIndex];
             _updateGroupStCelo(
@@ -447,13 +455,31 @@ contract DefaultStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausable {
             );
             trySort(votedGroup, stCeloInGroup[votedGroup], false);
 
+            address previous = votedGroup;
             if (sorted) {
                 votedGroup = activeGroups.getHead();
             } else {
-                (, votedGroup, ) = activeGroups.get(votedGroup);
+                (, votedGroup, ) = activeGroups.get(previous);
             }
 
             groupsIndex++;
+
+            // Skip groups already chosen this call: when realisable (not
+            // stCelo) is the binding cap, a group's stCelo barely drops and it
+            // can resurface as HEAD, and emitting it twice would make
+            // scheduleWithdrawals revert. Walking toward smaller groups never
+            // skips an unchosen one (HEAD-down order).
+            bool chosen = true;
+            while (votedGroup != address(0) && chosen) {
+                chosen = false;
+                for (uint256 j = 0; j < groupsIndex; j++) {
+                    if (groups[j] == votedGroup) {
+                        chosen = true;
+                        (, votedGroup, ) = activeGroups.get(votedGroup);
+                        break;
+                    }
+                }
+            }
         }
 
         if (celoAmount != 0) {

contracts/Manager.sol

@@ -671,7 +671,7 @@ contract Manager is Errors, UUPSOwnableUpgradeable, UsingRegistryUpgradeable, Pa
                 .generateWithdrawalVoteDistribution(strategy, celoAmount, stCeloAmount, isTransfer);
         } else {
             (groupsWithdrawn, withdrawalsPerGroup) = defaultStrategy
-                .generateWithdrawalVoteDistribution(celoAmount);
+                .generateWithdrawalVoteDistribution(celoAmount, isTransfer);
         }
 
         return (groupsWithdrawn, withdrawalsPerGroup);

contracts/SpecificGroupStrategy.sol

@@ -279,7 +279,7 @@ contract SpecificGroupStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausa
             celoWithdrawalAmount -= celoToBeMovedFromDefaultStrategy;
 
             (address[] memory overflowGroups, uint256[] memory overflowVotes) = defaultStrategy
-                .generateWithdrawalVoteDistribution(celoToBeMovedFromDefaultStrategy);
+                .generateWithdrawalVoteDistribution(celoToBeMovedFromDefaultStrategy, isTransfer);
 
             handleWithdrawalOverflowAndUnhealthyAccounting(
                 group,
@@ -294,7 +294,11 @@ contract SpecificGroupStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausa
                     groups[i] = overflowGroups[i];
                     votes[i] = overflowVotes[i];
                 }
-                if (!isTransfer && account.getCeloForGroup(group) < celoWithdrawalAmount) {
+                if (
+                    !isTransfer && account.getRealisableCeloForGroup(group) < celoWithdrawalAmount
+                ) {
+                    // Use realisable (not getCeloForGroup) so we don't pin to a
+                    // group whose votes the Election cap won't let us revoke.
                     revert GroupNotBalanced(group);
                 }
                 groups[overflowGroups.length] = group;
@@ -623,8 +627,9 @@ contract SpecificGroupStrategy is Errors, UUPSOwnableUpgradeable, Managed, Pausa
      */
     function transferFromDefaultStrategy(address group, uint256 stCeloToMove) private {
         uint256 toMoveCelo = IManager(manager).toCelo(stCeloToMove);
+        // isTransfer=true: accounting-only move, so DS skips the realisable cap.
         (address[] memory fromGroups, uint256[] memory fromVotes) = defaultStrategy
-            .generateWithdrawalVoteDistribution(toMoveCelo);
+            .generateWithdrawalVoteDistribution(toMoveCelo, true);
         address[] memory toGroups = new address[](1);
         uint256[] memory toVotes = new uint256[](1);
         toGroups[0] = group;

contracts/interfaces/IAccount.sol

@@ -29,6 +29,8 @@ interface IAccount {
 
     function getCeloForGroup(address) external view returns (uint256);
 
+    function getRealisableCeloForGroup(address group) external view returns (uint256);
+
     function scheduledVotesForGroup(address group) external view returns (uint256);
 
     function scheduledRevokeForGroup(address group) external view returns (uint256);

contracts/interfaces/IDefaultStrategy.sol

@@ -8,7 +8,7 @@ interface IDefaultStrategy {
         address depositGroupToIgnore
     ) external returns (address[] memory finalGroups, uint256[] memory finalVotes);
 
-    function generateWithdrawalVoteDistribution(uint256 celoAmount)
+    function generateWithdrawalVoteDistribution(uint256 celoAmount, bool isTransfer)
         external
         returns (address[] memory finalGroups, uint256[] memory finalVotes);