docs: EigenPod Manager slashing updates (#1005)

* docs: complete EigenPodManager for slashing

* docs: add in _beaconChainSlashingFactor state variable note

* docs: finish epm docs

* chore: make bindings

---------

Co-authored-by: wadealexc <[email protected]>

src/contracts/interfaces/IEigenPodManager.sol

@@ -104,10 +104,12 @@ interface IEigenPodManager is
     function stake(bytes calldata pubkey, bytes calldata signature, bytes32 depositDataRoot) external payable;
 
     /**
-     * @notice Changes the `podOwner`'s shares by `sharesDelta` and performs a call to the DelegationManager
-     * to ensure that delegated shares are also tracked correctly
+     * @notice Adds any positive share delta to the pod owner's deposit shares, and delegates them to the pod
+     * owner's operator (if applicable). A negative share delta does NOT impact the pod owner's deposit shares,
+     * but will reduce their beacon chain slashing factor and delegated shares accordingly.
      * @param podOwner is the pod owner whose balance is being updated.
-     * @param prevRestakedBalanceWei is the total amount restaked through the pod before the balance update
+     * @param prevRestakedBalanceWei is the total amount restaked through the pod before the balance update, including
+     * any amount currently in the withdrawal queue.
      * @param balanceDeltaWei is the amount the balance changed
      * @dev Callable only by the podOwner's EigenPod contract.
      * @dev Reverts if `sharesDelta` is not a whole Gwei amount

src/contracts/pods/EigenPodManager.sol

@@ -150,9 +150,8 @@ contract EigenPodManager is
     }
 
     /**
-     * @notice Increases the `podOwner`'s shares by `shares`, paying off deficit if possible.
+     * @notice Increases the `podOwner`'s shares by `shares`, paying off negative shares if needed.
      * Used by the DelegationManager to award a pod owner shares on exiting the withdrawal queue
-     * @dev Reverts if `shares` is not a whole Gwei amount
      * @return existingDepositShares the pod owner's shares prior to any additions. Returns 0 if negative
      * @return addedShares the number of shares added to the staker's balance above 0. This means that if,
      * after shares are added, the staker's balance is non-positive, this will return 0.
@@ -168,9 +167,8 @@ contract EigenPodManager is
     }
 
     /**
-     * @notice Used by the DelegationManager to complete a withdrawal, sending tokens to some destination address
+     * @notice Used by the DelegationManager to complete a withdrawal, sending tokens to the pod owner
      * @dev Prioritizes decreasing the podOwner's share deficit, if they have one
-     * @dev Reverts if `shares` is not a whole Gwei amount
      * @dev This function assumes that `removeShares` has already been called by the delegationManager, hence why
      *      we do not need to update the podOwnerDepositShares if `currentpodOwnerDepositShares` is positive
      */

src/contracts/pods/EigenPodManagerStorage.sol

@@ -62,20 +62,30 @@ abstract contract EigenPodManagerStorage is IEigenPodManager {
 
     // BEGIN STORAGE VARIABLES ADDED AFTER MAINNET DEPLOYMENT -- DO NOT SUGGEST REORDERING TO CONVENTIONAL ORDER
     /**
-     * // TODO: Update this comment
-     * @notice Mapping from Pod owner owner to the number of deposit shares they have in the virtual beacon chain ETH strategy.
-     * @dev The deposit share amount can become negative. This is necessary to accommodate the fact that a pod owner's virtual beacon chain ETH shares can
-     * decrease between the pod owner queuing and completing a withdrawal.
-     * When the pod owner's shares would otherwise increase, this "deficit" is decreased first _instead_.
-     * Likewise, when a withdrawal is completed, this "deficit" is decreased and the withdrawal amount is decreased; We can think of this
-     * as the withdrawal "paying off the deficit".
+     * @notice mapping from pod owner to the deposit shares they have in the virtual beacon chain ETH strategy
+     *
+     * @dev When an EigenPod registers a balance increase, deposit shares are increased. When registering a balance
+     * decrease, however, deposit shares are NOT decreased. Instead, the pod owner's beacon chain slashing factor
+     * is decreased proportional to the balance decrease. This impacts the number of shares that will be withdrawn
+     * when the deposit shares are queued for withdrawal in the DelegationManager.
+     *
+     * Note that prior to the slashing release, deposit shares were decreased when balance decreases occurred.
+     * In certain cases, a combination of queueing a withdrawal plus registering a balance decrease could result
+     * in a staker having negative deposit shares in this mapping. This negative value would be corrected when the
+     * staker completes a withdrawal (as tokens or as shares).
+     *
+     * With the slashing release, negative shares are no longer possible. However, a staker can still have negative
+     * shares if they met the conditions for them before the slashing release. If this is the case, that staker
+     * should complete any outstanding queued withdrawal in the DelegationManager ("as shares"). This will correct
+     * the negative share count and allow the staker to continue using their pod as normal.
      */
     mapping(address podOwner => int256 shares) public podOwnerDepositShares;
 
     uint64 internal __deprecated_denebForkTimestamp;
 
     /// @notice Returns the slashing factor applied to the `staker` for the `beaconChainETHStrategy`
-    /// Note: this is specifically updated when the staker's beacon chain balance decreases
+    /// Note: this value starts at 1 WAD (1e18) for all stakers, and is updated when a staker's pod registers
+    /// a balance decrease.
     mapping(address staker => BeaconChainSlashingFactor) internal _beaconChainSlashingFactor;
 
     /// @notice Returns the amount of `shares` that have been slashed on EigenLayer but not burned yet.