[Task] Withdrawal buffer for OS Vault (#2649)

* Enhance undelegateValidator: log vault assets and available balance after buffer calculation

* Added buffer option to sonicUndelegate
Set vault buffer to 0.5% for undelegating S from the validator

---------

Co-authored-by: Nicholas Addison <nick@addisonbrown.com.au>

Author: clement-ux

contracts/scripts/defender-actions/sonicRequestWithdrawal.js

@@ -15,7 +15,10 @@ const handler = async (event) => {
   const provider = new DefenderRelayProvider(event);
   const signer = new DefenderRelaySigner(event, provider, { speed: "fastest" });
 
-  await undelegateValidator({ signer });
+  // The vault buffer in basis points, so 100 = 1%
+  const bufferPct = 50;
+
+  await undelegateValidator({ signer, bufferPct });
 };
 
 module.exports = { handler };

contracts/tasks/tasks.js

@@ -1786,10 +1786,20 @@ subtask("sonicUndelegate", "Remove liquidity from a Sonic validator")
     undefined,
     types.float
   )
+  .addOptionalParam(
+    "buffer",
+    "Percentage of total assets to keep as buffer in basis points. 100 = 1%",
+    50,
+    types.float
+  )
   .setAction(async (taskArgs) => {
     const signer = await getSigner();
 
-    await undelegateValidator({ ...taskArgs, signer });
+    await undelegateValidator({
+      ...taskArgs,
+      bufferPct: taskArgs.buffer,
+      signer,
+    });
   });
 task("sonicUndelegate").setAction(async (_, __, runSuper) => {
   return runSuper();

contracts/utils/sonicActions.js

@@ -9,7 +9,13 @@ const { logTxDetails } = require("../utils/txLogger");
 
 const log = require("../utils/logger")("task:sonic");
 
-async function undelegateValidator({ id, amount, signer }) {
+/**
+ * @param {*} id Validator ID to undelegate from. If not provided, will use the default validator ID.
+ * @param {*} amount Amount of wS to undelegate. If not provided, it will be calculated based on available wS, pending withdrawals and the vault buffer.
+ * @param {*} bufferPct Percentage of total assets to keep as a buffer for the vault in basis points. 100 = 1%
+ * @returns
+ */
+async function undelegateValidator({ id, amount, signer, bufferPct = 0 }) {
   const sonicStakingStrategy = new ethers.Contract(
     addresses.sonic.SonicStakingStrategy,
     sonicStakingStrategyAbi,
@@ -25,29 +31,63 @@ async function undelegateValidator({ id, amount, signer }) {
   let amountBN;
   if (amount == undefined) {
     const wsBalance = await ws.balanceOf(addresses.sonic.OSonicVaultProxy);
-    const queue = await vault.withdrawalQueueMetadata();
-    const pendingWithdrawals = await sonicStakingStrategy.pendingWithdrawals();
+    log(`wS balance in vault           : ${formatUnits(wsBalance, 18)} wS`);
 
-    const available = wsBalance
-      .add(queue.claimed)
-      .sub(queue.queued)
-      .add(pendingWithdrawals);
+    const queue = await vault.withdrawalQueueMetadata();
+    const unclaimedWithdrawals = queue.queued.sub(queue.claimed);
+    log(
+      `Unclaimed vault withdrawals   : ${formatUnits(
+        unclaimedWithdrawals,
+        18
+      )} wS`
+    );
+    const wsAvailable = wsBalance.sub(unclaimedWithdrawals);
+    log(`Available wS in vault         : ${formatUnits(wsAvailable, 18)} wS`);
 
-    log(`Available balance: ${formatUnits(available, 18)} wS`);
+    const pendingWithdrawals = await sonicStakingStrategy.pendingWithdrawals();
+    log(
+      `Pending validator withdrawals : ${formatUnits(
+        pendingWithdrawals,
+        18
+      )} wS`
+    );
+
+    const wsWithValidatorWithdrawals = wsAvailable.add(pendingWithdrawals);
+    log(
+      `wS with validator withdrawals : ${formatUnits(
+        wsWithValidatorWithdrawals,
+        18
+      )} wS`
+    );
+
+    const vaultTotalAsset = await vault.totalValue();
+    log(
+      `Total vault assets            : ${formatUnits(vaultTotalAsset, 18)} wS`
+    );
+    const buffer = vaultTotalAsset.mul(bufferPct).div(10000);
+    log(
+      `Buffer (${bufferPct / 100}% of total assets) : ${formatUnits(
+        buffer,
+        18
+      )} wS`
+    );
+
+    const wsWithBuffer = wsWithValidatorWithdrawals.sub(buffer);
+    log(`wS target with buffer         : ${formatUnits(wsWithBuffer, 18)} wS`);
 
     // Threshold is negative 1000 wS
     const threshold = parseUnits("1000", 18).mul(-1);
-    if (available.gt(threshold)) {
+    if (wsWithBuffer.gt(threshold)) {
       log(
-        `No need to undelgate as available balance ${formatUnits(
-          available,
+        `No need to undelegate as target with buffer of ${formatUnits(
+          wsWithBuffer,
           18
         )} wS is above threshold.`
       );
       return;
     }
     // Convert back to a positive amount
-    amountBN = available.mul(-1);
+    amountBN = wsWithBuffer.mul(-1);
   } else {
     // Use amount passed in from Hardhat task
     amountBN = parseUnits(amount.toString(), 18);