From de708203374b21cc6940d4840561b8ed0e3dc6d6 Mon Sep 17 00:00:00 2001 From: "A.L." Date: Wed, 13 Nov 2024 14:45:06 +0800 Subject: [PATCH] docs: improvements * docs: enhance docs for `QueryProcessor` * docs: enhance docs for `ReservoirPriceOracle` --- src/ReservoirPriceOracle.sol | 10 +++++----- src/libraries/QueryProcessor.sol | 11 ++++------- 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/src/ReservoirPriceOracle.sol b/src/ReservoirPriceOracle.sol index fd70bdc..ac6bc00 100644 --- a/src/ReservoirPriceOracle.sol +++ b/src/ReservoirPriceOracle.sol @@ -238,9 +238,9 @@ contract ReservoirPriceOracle is IPriceOracle, Owned(msg.sender), ReentrancyGuar } } - /// @return rRoute The route to determine the price between aToken0 and aToken1 - /// @return rDecimalDiff The result of token1.decimals() - token0.decimals() if it's a simple route. 0 otherwise - /// @return rPrice The price of aToken0/aToken1 if it's a simple route (i.e. rRoute.length == 2). 0 otherwise + /// @return rRoute The route to determine the price between aToken0 and aToken1. Returns an empty array if there is no route. + /// @return rDecimalDiff The result of token1.decimals() - token0.decimals() if it's a simple route. 0 otherwise. + /// @return rPrice The price of aToken0/aToken1 if it's a simple route (i.e. rRoute.length == 2). 0 otherwise. /// @return rRewardThreshold The number of basis points of difference in price at and beyond which a reward is applicable for a price update. function _getRouteDecimalDifferencePrice(address aToken0, address aToken1) private @@ -292,8 +292,8 @@ contract ReservoirPriceOracle is IPriceOracle, Owned(msg.sender), ReentrancyGuar } } - /// Calculate the storage slot for this intermediate segment and read it to see if there is an existing - /// route. If there isn't an existing route, we write it as well. + // Calculate the storage slot for this intermediate segment and read it to see if there is an existing + // route. If there isn't an existing route, we create one as well. function _checkAndPopulateIntermediateRoute(address aTokenA, address aTokenB, uint16 aBpMaxReward) private { (address lToken0, address lToken1) = Utils.sortTokens(aTokenA, aTokenB); diff --git a/src/libraries/QueryProcessor.sol b/src/libraries/QueryProcessor.sol index 487d5c2..795200a 100644 --- a/src/libraries/QueryProcessor.sol +++ b/src/libraries/QueryProcessor.sol @@ -21,10 +21,8 @@ import { OracleErrors } from "src/libraries/OracleErrors.sol"; import { Samples, PriceType } from "src/libraries/Samples.sol"; /** - * @dev Auxiliary library for PoolPriceOracle, offloading most of the query code to reduce bytecode size by using this - * as a linked library. The downside is an extra DELEGATECALL is added (2600 gas as of the Berlin hardfork), but the - * bytecode size gains are so big (specially of the oracle contract does not use `LogCompression.fromLowResLog`) that - * it is worth it. + * @dev Auxiliary library for ReservoirPriceOracle, + * forked from Balancer implementation at https://github.com/balancer/balancer-v2-monorepo/blob/903d34e491a5e9c5d59dabf512c7addf1ccf9bbd/pkg/pool-utils/contracts/oracle/QueryProcessor.sol */ library QueryProcessor { using Buffer for uint16; @@ -80,9 +78,8 @@ library QueryProcessor { * If requesting information for a timestamp later than the latest one, it is extrapolated using the latest * available data. * - * When no exact information is available for the requested past timestamp (as usually happens, since at most one - * timestamp is stored every two minutes), it is estimated by performing linear interpolation using the closest - * values. This process is guaranteed to complete performing at most 11 storage reads. + * When no exact information is available for the requested past timestamp, it is estimated by performing linear interpolation using the closest values. + * This process is guaranteed to complete performing at most log2(Buffer.SIZE) storage reads. */ function getPastAccumulator(ReservoirPair pair, PriceType priceType, uint16 latestIndex, uint256 ago) internal