feat: added withdrawal output with asset in for oracles [SUP-15736] (#822)

supervaulter · 0xTimepunk · web-flow · commit 71ae51d08144 · 2025-10-27T15:29:54.000+01:00
Co-authored-by: 0xTimepunk &lt;45543880+0xTimepunk@users.noreply.github.com&gt;
diff --git a/SECURITY.md b/SECURITY.md
@@ -39,4 +39,7 @@ The destination executor supports only one leaf per destination in the Merkle ro
 The protocol allows signatures with no expiration. While convenient, these signatures can pose risks in certain operational contexts and should be used carefully.
 
 #### 11. Multiple valid execution paths
-Once an intent is signed, there are several valid methods to execute it, even in cases where the associated bridge transaction has not completed successfully. This provides flexibility but requires careful handling by integrators to avoid unintended consequences.
+Once an intent is signed, there are several valid methods to execute it, even in cases where the associated bridge transaction has not completed successfully. This provides flexibility but requires careful handling by integrators to avoid unintended consequences.
+
+#### 12. Token decimals
+Superform's yield sources and oracle calculations are designed with ERC-20 assets that use up to 18 decimals of precision in mind. Yield source assets with more than 18 decimals are considered non-standard and unsupported.
diff --git a/src/accounting/oracles/AbstractYieldSourceOracle.sol b/src/accounting/oracles/AbstractYieldSourceOracle.sol
@@ -48,6 +48,17 @@ abstract contract AbstractYieldSourceOracle is IYieldSourceOracle {
         virtual
         returns (uint256);
 
+    /// @inheritdoc IYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address yieldSourceAddress,
+        address assetIn,
+        uint256 assetsIn
+    )
+        external
+        view
+        virtual
+        returns (uint256);
+
     /// @inheritdoc IYieldSourceOracle
     function getAssetOutput(
         address yieldSourceAddress,
diff --git a/src/accounting/oracles/ERC4626YieldSourceOracle.sol b/src/accounting/oracles/ERC4626YieldSourceOracle.sol
@@ -36,6 +36,20 @@ contract ERC4626YieldSourceOracle is AbstractYieldSourceOracle {
         return IERC4626(yieldSourceAddress).previewDeposit(assetsIn);
     }
 
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address yieldSourceAddress,
+        address,
+        uint256 assetsIn
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        return IERC4626(yieldSourceAddress).previewWithdraw(assetsIn);
+    }
+
     /// @inheritdoc AbstractYieldSourceOracle
     function getAssetOutput(
         address yieldSourceAddress,
diff --git a/src/accounting/oracles/ERC5115YieldSourceOracle.sol b/src/accounting/oracles/ERC5115YieldSourceOracle.sol
@@ -17,8 +17,28 @@ contract ERC5115YieldSourceOracle is AbstractYieldSourceOracle {
     /*//////////////////////////////////////////////////////////////
                             EXTERNAL FUNCTIONS
     //////////////////////////////////////////////////////////////*/
-    /// @inheritdoc AbstractYieldSourceOracle
-    function decimals(address /*yieldSourceAddress*/ ) public pure override returns (uint8) {
+    /// exchangeRate() returns price scaled to 1e18 precision, independent of SY token or asset decimals.
+    /// This ensures correct normalization in mulDiv operations.
+    /// See https://eips.ethereum.org/EIPS/eip-5115#methods -> exchangeRate()
+    /// The name decimals() here is ambiguous because it is a function used in other areas of the code for scaling (but
+    /// it doesn't refer to the SY decimals) 
+    /// Calculation Examples in the Oracle:
+    /// - In getTVL: Math.mulDiv(totalShares, yieldSource.exchangeRate(), 1e18). Here, totalShares is in SY decimals
+    /// (D), exchangeRate is (totalAssets * 1e18) / totalShares (per EIP, with totalAssets in asset decimals A). This
+    /// simplifies to totalAssets, correctly outputting the asset amount regardless of D or A.
+    /// - In getWithdrawalShareOutput: previewRedeem(assetIn, 1e18) gets assets for 1e18 SY share units, then
+    /// mulDiv(assetsIn, 1e18, assetsPerShare, Ceil) computes the required share units. The 1e18 acts as a precision
+    /// scaler (matching EIP), not an assumption about D. For example, with a 6-decimal SY (like Pendle's SY-syrupUSDC)
+    /// and initial 1:1 rate, it correctly computes shares without issues.
+    /// - This pattern holds for other functions like getAssetOutput (direct previewRedeem without scaling assumptions).
+    function decimals(
+        address /*yieldSourceAddress*/
+    )
+        public
+        pure
+        override
+        returns (uint8)
+    {
         return 18;
     }
 
@@ -36,6 +56,22 @@ contract ERC5115YieldSourceOracle is AbstractYieldSourceOracle {
         return IStandardizedYield(yieldSourceAddress).previewDeposit(assetIn, assetsIn);
     }
 
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address yieldSourceAddress,
+        address assetIn,
+        uint256 assetsIn
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        uint256 assetsPerShare = IStandardizedYield(yieldSourceAddress).previewRedeem(assetIn, 1e18);
+        if (assetsPerShare == 0) return 0;
+        return Math.mulDiv(assetsIn, 1e18, assetsPerShare, Math.Rounding.Ceil);
+    }
+
     /// @inheritdoc AbstractYieldSourceOracle
     function getAssetOutput(
         address yieldSourceAddress,
diff --git a/src/accounting/oracles/ERC7540YieldSourceOracle.sol b/src/accounting/oracles/ERC7540YieldSourceOracle.sol
@@ -5,6 +5,7 @@ pragma solidity 0.8.30;
 import { IERC20Metadata } from "@openzeppelin/contracts/interfaces/IERC20Metadata.sol";
 import { IERC7540 } from "../../vendor/vaults/7540/IERC7540.sol";
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
 
 // Superform
 import { AbstractYieldSourceOracle } from "./AbstractYieldSourceOracle.sol";
@@ -38,6 +39,22 @@ contract ERC7540YieldSourceOracle is AbstractYieldSourceOracle {
         return IERC7540(yieldSourceAddress).convertToShares(assetsIn);
     }
 
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address yieldSourceAddress,
+        address,
+        uint256 assetsIn
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        uint256 assetsPerShare = IERC7540(yieldSourceAddress).convertToAssets(1e18);
+        if (assetsPerShare == 0) return 0;
+        return Math.mulDiv(assetsIn, 1e18, assetsPerShare, Math.Rounding.Ceil);
+    }
+
     /// @inheritdoc AbstractYieldSourceOracle
     function getAssetOutput(
         address yieldSourceAddress,
@@ -91,4 +108,5 @@ contract ERC7540YieldSourceOracle is AbstractYieldSourceOracle {
     function getTVL(address yieldSourceAddress) public view override returns (uint256) {
         return IERC7540(yieldSourceAddress).totalAssets();
     }
+
 }
diff --git a/src/accounting/oracles/PendlePTYieldSourceOracle.sol b/src/accounting/oracles/PendlePTYieldSourceOracle.sol
@@ -115,7 +115,37 @@ contract PendlePTYieldSourceOracle is AbstractYieldSourceOracle {
             // Scale down if assetDecimals < 18
             // Avoids underflow in 10**(PRICE_DECIMALS - assetDecimals) which happens in the division below
             assetsOut = Math.mulDiv(assetsOut18, 1, 10 ** (PRICE_DECIMALS - assetDecimals));
+        }    
+    }
+
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address market,
+        address,
+        uint256 assetsIn
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        uint256 pricePerShare = getPricePerShare(market); // PT / Asset in 1e18
+        if (pricePerShare == 0) return 0;
+
+        IStandardizedYield sY = IStandardizedYield(_sy(market));
+        (,, uint8 assetDecimals) = _getAssetInfo(sY);
+        uint8 ptDecimals = IERC20Metadata(_pt(market)).decimals();
+
+        // First scale assetsIn into 1e18 terms
+        uint256 assetsIn18;
+        if (assetDecimals <= PRICE_DECIMALS) {
+            assetsIn18 = assetsIn * (10 ** (PRICE_DECIMALS - assetDecimals));
+        } else {
+            assetsIn18 = Math.mulDiv(assetsIn, 1, 10 ** (assetDecimals - PRICE_DECIMALS));
         }
+
+        // Compute how many PT shares are needed: shares = assetsIn18 * 10^ptDecimals / pricePerShare
+        return Math.mulDiv(assetsIn18, 10 ** uint256(ptDecimals), pricePerShare, Math.Rounding.Ceil);
     }
 
     /// @inheritdoc IYieldSourceOracle
diff --git a/src/accounting/oracles/SpectraPTYieldSourceOracle.sol b/src/accounting/oracles/SpectraPTYieldSourceOracle.sol
@@ -3,6 +3,7 @@ pragma solidity 0.8.30;
 
 // external
 import { IERC20Metadata } from "@openzeppelin/contracts/interfaces/IERC20Metadata.sol";
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
 
 import { IPrincipalToken } from "../../vendor/spectra/IPrincipalToken.sol";
 // Superform
@@ -25,10 +26,26 @@ contract SpectraPTYieldSourceOracle is AbstractYieldSourceOracle {
 
     /// @inheritdoc AbstractYieldSourceOracle
     function getShareOutput(address ptAddress, address, uint256 assetsIn) external view override returns (uint256) {
-        // Use convertToPrincipal to get shares (PTs) for assets
         return IPrincipalToken(ptAddress).convertToPrincipal(assetsIn);
     }
 
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address ptAddress,
+        address,
+        uint256 assetsIn
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        uint8 _dec = _decimals(ptAddress);
+        uint256 underlyingPerShare = IPrincipalToken(ptAddress).convertToUnderlying(10 ** _dec);
+        if (underlyingPerShare == 0) return 0;
+        return Math.mulDiv(assetsIn, 10 ** _dec, underlyingPerShare, Math.Rounding.Ceil);
+    } 
+
     /// @inheritdoc AbstractYieldSourceOracle
     function getAssetOutput(
         address ptAddress,
@@ -40,7 +57,6 @@ contract SpectraPTYieldSourceOracle is AbstractYieldSourceOracle {
         override
         returns (uint256)
     {
-        // Use convertToUnderlying to get assets for shares (PTs)
         return IPrincipalToken(ptAddress).convertToUnderlying(sharesIn);
     }
 
diff --git a/src/accounting/oracles/StakingYieldSourceOracle.sol b/src/accounting/oracles/StakingYieldSourceOracle.sol
@@ -3,6 +3,7 @@ pragma solidity 0.8.30;
 
 // external
 import { IERC20 } from "@openzeppelin/contracts/interfaces/IERC20.sol";
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
 
 // Superform
 import { AbstractYieldSourceOracle } from "./AbstractYieldSourceOracle.sol";
@@ -32,6 +33,20 @@ contract StakingYieldSourceOracle is AbstractYieldSourceOracle {
         return assetsIn;
     }
 
+    /// @inheritdoc AbstractYieldSourceOracle
+    function getWithdrawalShareOutput(
+        address,
+        address,
+        uint256 assetsIn
+    )
+        external
+        pure
+        override
+        returns (uint256)
+    {
+        return assetsIn;
+    } 
+
     /// @inheritdoc AbstractYieldSourceOracle
     function getAssetOutput(address, address, uint256 sharesIn) public pure override returns (uint256) {
         return sharesIn;
diff --git a/src/interfaces/accounting/IYieldSourceOracle.sol b/src/interfaces/accounting/IYieldSourceOracle.sol
@@ -73,6 +73,21 @@ interface IYieldSourceOracle {
         view
         returns (uint256);
 
+    /// @notice Calculates the amount of shares that would be burnt when withdrawing a given amount of assets
+    /// @dev Used by oracles to simulate withdrawals and to derive the current exchange rate
+    /// @param yieldSourceAddress The address of the yield-bearing token (e.g., aUSDC, cDAI)
+    /// @param assetIn The address of the underlying asset to be withdrawn (e.g., USDC, DAI)
+    /// @param assetsIn The amount of underlying assets to withdraw, denominated in the asset’s native units
+    /// @return shares The amount of yield-bearing shares that would be burnt after withdrawal
+    function getWithdrawalShareOutput(
+        address yieldSourceAddress,
+        address assetIn,
+        uint256 assetsIn
+    )
+        external
+        view
+        returns (uint256);
+
     /// @notice Calculates the number of underlying assets that would be received for a given amount of shares
     /// @dev Used for withdrawal simulations and to calculate current yield
     /// @param yieldSourceAddress The yield-bearing token address (e.g., aUSDC, cDAI)
diff --git a/test/mocks/MockYieldSourceOracle.sol b/test/mocks/MockYieldSourceOracle.sol
@@ -46,6 +46,10 @@ contract MockYieldSourceOracle is IYieldSourceOracle {
         return assetsIn;
     }
 
+    function getWithdrawalShareOutput(address, address, uint256 assetsIn) external pure override returns (uint256) {
+        return assetsIn;
+    }
+
     function getAssetOutput(address, address, uint256 sharesIn) public pure returns (uint256) {
         return sharesIn;
     }
diff --git a/test/unit/accounting/AbstractYieldSourceOracleTest.t.sol b/test/unit/accounting/AbstractYieldSourceOracleTest.t.sol
@@ -24,6 +24,10 @@ contract MockYieldSourceOracle is AbstractYieldSourceOracle {
         return assetsIn;
     }
 
+    function getWithdrawalShareOutput(address, address, uint256 assetsIn) external pure override returns (uint256) {
+        return assetsIn;
+    }
+
     function getAssetOutput(address, address, uint256 sharesIn) public pure override returns (uint256) {
         return sharesIn;
     }
diff --git a/test/unit/accounting/YieldSourceOracles.t.sol b/test/unit/accounting/YieldSourceOracles.t.sol
@@ -10,6 +10,7 @@ import { Mock5115Vault } from "../../mocks/Mock5115Vault.sol";
 
 import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { Math } from "@openzeppelin/contracts/utils/math/Math.sol";
 import { IStakingVault } from "../../../src/vendor/staking/IStakingVault.sol";
 
 import { ERC4626YieldSourceOracle } from "../../../src/accounting/oracles/ERC4626YieldSourceOracle.sol";
@@ -131,6 +132,42 @@ contract YieldSourceOraclesTest is Helpers {
         assertEq(actualShares, assetsIn); // For staking vaults, shares = assets
     }
 
+    /*//////////////////////////////////////////////////////////////
+                    WITHDRAWAL SHARE OUTPUT TESTS
+    //////////////////////////////////////////////////////////////*/
+    function test_ERC4626_getWithdrawalShareOutput() public view {
+        uint256 assetsIn = 1e18;
+        uint256 expectedShares = erc4626.previewWithdraw(assetsIn);
+        uint256 actualShares = erc4626YieldSourceOracle.getWithdrawalShareOutput(address(erc4626), address(0), assetsIn);
+        assertEq(actualShares, expectedShares);
+    }
+
+    function test_ERC7540_getWithdrawalShareOutput() public view {
+        uint256 assetsIn = 1e18;
+        // For ERC7540: calculate shares needed to withdraw assetsIn
+        uint256 assetsPerShare = erc7540.convertToAssets(1e18);
+        uint256 expectedShares = Math.mulDiv(assetsIn, 1e18, assetsPerShare, Math.Rounding.Ceil);
+        uint256 actualShares = erc7540YieldSourceOracle.getWithdrawalShareOutput(address(erc7540), address(0), assetsIn);
+        assertEq(actualShares, expectedShares);
+    }
+
+    function test_ERC5115_getWithdrawalShareOutput() public view {
+        uint256 assetsIn = 1e18;
+        // For ERC5115: calculate shares needed to withdraw assetsIn
+        uint256 assetsPerShare = erc5115.previewRedeem(address(asset), 1e18);
+        uint256 expectedShares = Math.mulDiv(assetsIn, 1e18, assetsPerShare, Math.Rounding.Ceil);
+        uint256 actualShares =
+            erc5115YieldSourceOracle.getWithdrawalShareOutput(address(erc5115), address(asset), assetsIn);
+        assertEq(actualShares, expectedShares);
+    }
+
+    function test_Staking_getWithdrawalShareOutput() public view {
+        uint256 assetsIn = 1e18;
+        uint256 actualShares =
+            stakingYieldSourceOracle.getWithdrawalShareOutput(address(stakingVault), address(0), assetsIn);
+        assertEq(actualShares, assetsIn); // For staking vaults, shares needed = assets (1:1 ratio)
+    }
+
     /*//////////////////////////////////////////////////////////////
                           ASSET OUTPUT TESTS
     //////////////////////////////////////////////////////////////*/
@@ -151,7 +188,7 @@ contract YieldSourceOraclesTest is Helpers {
     function test_ERC5115_getAssetOutput() public view {
         uint256 sharesIn = 1e18;
         uint256 expectedAssets = erc5115.previewRedeem(address(asset), sharesIn);
-        uint256 actualAssets = erc5115YieldSourceOracle.getAssetOutput(address(erc5115), address(0), sharesIn);
+        uint256 actualAssets = erc5115YieldSourceOracle.getAssetOutput(address(erc5115), address(asset), sharesIn);
         assertEq(actualAssets, expectedAssets);
     }
 

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,10 @@ contract MockYieldSourceOracle is IYieldSourceOracle {`
`46`	`46`	`return assetsIn;`
`47`	`47`	`}`
`48`	`48`
	`49`	`+ function getWithdrawalShareOutput(address, address, uint256 assetsIn) external pure override returns (uint256) {`
	`50`	`+ return assetsIn;`
	`51`	`+ }`
	`52`	`+`
`49`	`53`	`function getAssetOutput(address, address, uint256 sharesIn) public pure returns (uint256) {`
`50`	`54`	`return sharesIn;`
`51`	`55`	`}`