From 4fba4071918ac6b1da4eba231fcb71226281a155 Mon Sep 17 00:00:00 2001 From: jayesh yadav Date: Tue, 16 Jun 2026 23:05:22 +0530 Subject: [PATCH] chore: remove spec cross-references from code comments The spec lives in a private, gitignored doc, so code comments that pointed at spec/section/phase numbers ("spec Section 8.4", "Phase 4 rebalancer", etc.) referenced something a public reader cannot see. Strip every such reference from src and test comments, keeping the technical substance of each comment so it stands on its own (e.g. "behind the Phase 5 timelock" becomes "behind the methodology-admin timelock"). Comment-only change; no behavior change. --- src/ComponentRegistry.sol | 4 ++-- src/IndexVault.sol | 9 +++------ src/interfaces/ISupplyOracle.sol | 2 +- src/libraries/WeightMath.sol | 4 ++-- src/methodology/MarketCapMethodology.sol | 14 +++++++------- src/oracle/ExcludedAddressRegistry.sol | 4 ++-- src/oracle/SupplyOracle.sol | 6 +++--- test/IndexVault.t.sol | 2 +- test/MarketCapMethodology.t.sol | 2 +- test/SupplyOracleIntegration.t.sol | 2 +- test/WeightMath.t.sol | 2 +- 11 files changed, 24 insertions(+), 27 deletions(-) diff --git a/src/ComponentRegistry.sol b/src/ComponentRegistry.sol index 93609d9..d1a7ecb 100644 --- a/src/ComponentRegistry.sol +++ b/src/ComponentRegistry.sol @@ -50,7 +50,7 @@ error ComponentRegistry_UsdcFeedNotSet(); * non-positive answer reverts so that price-sensitive vault operations * (mint, settle, rebalance) fail closed instead of transacting on bad data. * @dev Prices are normalized to 8 decimals regardless of feed decimals. - * Supply-oracle bindings and reconstitution metadata land here in Phase 3. + * Supply-oracle bindings and reconstitution metadata land here later. */ contract ComponentRegistry is Ownable2Step { struct Component { @@ -111,7 +111,7 @@ contract ComponentRegistry is Ownable2Step { /// @notice Removes a constituent from the registry. /// @dev The vault may still hold a balance of a removed token; removal only /// stops it being valued and traded. Deregistration policy (forced exit of - /// the position first) is enforced at the rebalancer layer in Phase 4. + /// the position first) is enforced at the rebalancer layer. function removeComponent(address token) external onlyOwner { if (_components[token].token == address(0)) revert ComponentRegistry_NotRegistered(token); diff --git a/src/IndexVault.sol b/src/IndexVault.sol index 2265e60..755ae8d 100644 --- a/src/IndexVault.sol +++ b/src/IndexVault.sol @@ -36,7 +36,7 @@ error IndexVault_SettleIntervalNotPassed(); error IndexVault_RequestBlockDelayNotPassed(); /// @notice Thrown when the idle buffer cannot cover the epoch's pending redemptions. -/// @dev Until the Phase 4 rebalancer can free USDC from the basket, settlement +/// @dev Until the rebalancer can free USDC from the basket, settlement /// requires the buffer to cover net outflows. error IndexVault_InsufficientSettlementLiquidity(uint256 required, uint256 available); @@ -72,10 +72,7 @@ error IndexVault_InvalidSettleParams(); * operations revert rather than transact on bad data. * * Pending redemptions are priced at settle time, not request time, which is - * fairer to remaining holders (spec Section 12, decision 1). - * - * Phase 1 scope: no methodology engine, no rebalancer, no fees. Target - * weights and basket deployment arrive in Phases 2 and 4. + * fairer to remaining holders. */ contract IndexVault is ERC4626, Ownable2Step, IERC7540 { using SafeERC20 for IERC20; @@ -536,7 +533,7 @@ contract IndexVault is ERC4626, Ownable2Step, IERC7540 { } /// @notice Sets the buffer band. Low and high gate the sync lanes; target - /// is the level the Phase 4 rebalancer tops the buffer back toward. + /// is the level the rebalancer tops the buffer back toward. function setBufferBand(uint16 lowBps, uint16 targetBps, uint16 highBps) external onlyOwner { if (lowBps == 0 || lowBps > targetBps || targetBps > highBps || highBps >= BPS) { revert IndexVault_InvalidBufferBand(); diff --git a/src/interfaces/ISupplyOracle.sol b/src/interfaces/ISupplyOracle.sol index f59dca5..94357e5 100644 --- a/src/interfaces/ISupplyOracle.sol +++ b/src/interfaces/ISupplyOracle.sol @@ -5,7 +5,7 @@ pragma solidity 0.8.28; * @title ISupplyOracle * @notice Source of float-adjusted circulating supply per constituent. The * methodology engine consumes an already-float-adjusted figure and does not - * itself decide float (spec Section 5.2). The implementation layers on-chain + * itself decide float. The implementation layers on-chain * derivation, a multi-source median with divergence freeze, and containment * guards behind this interface, so the methodology never needs to know how * the number was secured. diff --git a/src/libraries/WeightMath.sol b/src/libraries/WeightMath.sol index 676aaee..07d1df0 100644 --- a/src/libraries/WeightMath.sol +++ b/src/libraries/WeightMath.sol @@ -7,7 +7,7 @@ import { Math } from "@openzeppelin/contracts/utils/math/Math.sol"; * @title WeightMath * @notice Pure index-weighting math: iterative cap-and-redistribute, exact * renormalization, and the minimum-weight floor. This is the textbook capped - * market-cap methodology (spec Section 5.3): a hard per-asset cap with the + * market-cap methodology: a hard per-asset cap with the * overflow redistributed pro-rata to uncapped constituents, iterated because * redistribution can push a previously-uncapped name over the cap. * @@ -177,7 +177,7 @@ library WeightMath { } // ======================================================================== - // Reconstitution buffer rule (spec Section 5.4) + // Reconstitution buffer rule // ======================================================================== /** diff --git a/src/methodology/MarketCapMethodology.sol b/src/methodology/MarketCapMethodology.sol index a839195..90318d8 100644 --- a/src/methodology/MarketCapMethodology.sol +++ b/src/methodology/MarketCapMethodology.sol @@ -31,15 +31,15 @@ error MarketCapMethodology_InvalidParams(); /** * @title MarketCapMethodology * @notice Reference IMethodology implementation: float-adjusted market-cap - * weighting with a hard per-asset cap, iteratively redistributed (spec - * Section 5.3), and a minimum-weight floor that prunes dust positions. This - * is standard index-provider methodology (capped market-cap with float - * adjustment), which almost no on-chain index implements correctly. + * weighting with a hard per-asset cap, iteratively redistributed, and a + * minimum-weight floor that prunes dust positions. This is standard + * index-provider methodology (capped market-cap with float adjustment), + * which almost no on-chain index implements correctly. * * The cap does security work beyond diversification: large constituents are * pinned at the cap regardless of their exact supply, so supply-oracle * precision only matters for the mid and long tail, where the value at risk - * from manipulation is smaller (spec Section 8.4). + * from manipulation is smaller. */ contract MarketCapMethodology is IMethodology, Ownable2Step { using Math for uint256; @@ -55,7 +55,7 @@ contract MarketCapMethodology is IMethodology, Ownable2Step { /// supply arrived in native token decimals instead of whole tokens. uint256 public constant MARKET_CAP_SANITY_BOUND = 1e30; - /// @notice Hard per-asset weight cap in WAD. Default 25% (spec Section 12). + /// @notice Hard per-asset weight cap in WAD. Default 25%. uint256 public capWad = 0.25e18; /// @notice Minimum weight in WAD below which a constituent is pruned to @@ -102,7 +102,7 @@ contract MarketCapMethodology is IMethodology, Ownable2Step { } /// @notice Sets the per-asset cap and the minimum-weight floor. - /// @dev Methodology-admin lever; sits behind the Phase 5 timelock. + /// @dev Methodology-admin lever; sits behind the methodology-admin timelock. /// The cap must be feasible for the constituent set: getWeights reverts /// with WeightMath_CapInfeasible when the number of nonzero-market-cap /// constituents k satisfies k * capWad < 1e18 (a 25% cap needs at least diff --git a/src/oracle/ExcludedAddressRegistry.sol b/src/oracle/ExcludedAddressRegistry.sol index be5ada2..ccbcaca 100644 --- a/src/oracle/ExcludedAddressRegistry.sol +++ b/src/oracle/ExcludedAddressRegistry.sol @@ -31,7 +31,7 @@ error ExcludedRegistry_InvalidDelay(uint256 delay); /** * @title ExcludedAddressRegistry - * @notice Layer 1 of the supply oracle (spec Section 8.1): minimize the + * @notice Layer 1 of the supply oracle: minimize the * off-chain surface by deriving circulating supply on-chain wherever possible. * * Circulating supply is computed directly as @@ -107,7 +107,7 @@ contract ExcludedAddressRegistry is Ownable2Step { } /// @notice Cancels a pending change before it executes. The owner today, - /// the guardian once Phase 5 wires fast pause powers in. + /// the guardian once fast pause powers are wired in. function cancelChange(address token, address account, bool exclude) external onlyOwner { bytes32 id = changeId(token, account, exclude); if (!pendingChanges[id].exists) revert ExcludedRegistry_NoPendingChange(id); diff --git a/src/oracle/SupplyOracle.sol b/src/oracle/SupplyOracle.sol index 4dd5c2a..33b1918 100644 --- a/src/oracle/SupplyOracle.sol +++ b/src/oracle/SupplyOracle.sol @@ -48,7 +48,7 @@ error SupplyOracle_InvalidParams(); /** * @title SupplyOracle - * @notice Layers 2 and 3 of the supply-oracle design (spec Section 8), built + * @notice Layers 2 and 3 of the supply-oracle design, built * on the Layer 1 on-chain derivation in ExcludedAddressRegistry. * * Free-float supply is expressed as @@ -69,7 +69,7 @@ error SupplyOracle_InvalidParams(); * disagree, the commit reverts and the constituent freezes at its last-good * factor rather than acting on disputed data. This interface is shaped so an * optimistic oracle can later replace the reporter-median residual per - * constituent without the methodology engine noticing (spec Section 8.2). + * constituent without the methodology engine noticing. * * Layer 3, contain. The committed factor moves toward the median by at most * `maxFactorDeltaBps` per commit, and a `minCommitInterval` cooldown spreads @@ -102,7 +102,7 @@ contract SupplyOracle is ISupplyOracle, Ownable2Step { /// @notice Layer 1 on-chain circulating-supply source. ExcludedAddressRegistry public immutable EXCLUDED; - /// @notice Guardian with pause-only powers (spec Section 10). + /// @notice Guardian with pause-only powers. address public guardian; /// @notice When true, every read fails closed. diff --git a/test/IndexVault.t.sol b/test/IndexVault.t.sol index 374f430..996d126 100644 --- a/test/IndexVault.t.sol +++ b/test/IndexVault.t.sol @@ -66,7 +66,7 @@ contract IndexVaultTest is Test { } /// @dev Simulates a deployed basket: 1 WBTC ($100k) + 20 WETH ($100k) - /// held by the vault, as the Phase 4 rebalancer would leave it. + /// held by the vault, as the rebalancer would leave it. function _seedBasket() internal { wbtc.mint(address(vault), 1e8); weth.mint(address(vault), 20e18); diff --git a/test/MarketCapMethodology.t.sol b/test/MarketCapMethodology.t.sol index 806021a..a78e82f 100644 --- a/test/MarketCapMethodology.t.sol +++ b/test/MarketCapMethodology.t.sol @@ -100,7 +100,7 @@ contract MarketCapMethodologyTest is Test { } function test_GetWeights_CapDoesSecurityWork() public { - // Spec Section 8.4: a manipulated supply on a capped constituent must + // A manipulated supply on a capped constituent must // not move its weight. Double BTC's reported supply; BTC stays at cap. uint256[] memory before = methodology.getWeights(tokens); supplyOracle.setSupply(address(wbtc), 40_000_000); diff --git a/test/SupplyOracleIntegration.t.sol b/test/SupplyOracleIntegration.t.sol index 444409f..c52d99d 100644 --- a/test/SupplyOracleIntegration.t.sol +++ b/test/SupplyOracleIntegration.t.sol @@ -111,7 +111,7 @@ contract SupplyOracleIntegrationTest is Test { assertEq(sum, WAD); } - /// @notice Section 8.4: a capped constituent's weight is independent of its + /// @notice A capped constituent's weight is independent of its /// supply-oracle value. Move BTC's free-float factor through the full /// committed range and its weight never leaves the cap. function test_CapNeutralizesSupplyOracleOnLargeConstituent() public { diff --git a/test/WeightMath.t.sol b/test/WeightMath.t.sol index a243a76..5d70135 100644 --- a/test/WeightMath.t.sol +++ b/test/WeightMath.t.sol @@ -52,7 +52,7 @@ contract WeightMathTest is Test { } // ======================================================================== - // applyCap, property fuzz (spec Section 13 phase 2) + // applyCap, property fuzz // ======================================================================== /// @notice For any normalized weight vector and feasible cap: the output