Merge remote-tracking branch 'origin/proxy-deploy-scripts' into docs

Author: acenolaza

.eslintrc.js

@@ -1,7 +1,8 @@
 module.exports = {
   extends: ['plugin:@api3/eslint-plugin-commons/universal', 'plugin:@api3/eslint-plugin-commons/jest'],
   parserOptions: {
-    project: ['./tsconfig.json'],
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname,
   },
   rules: {
     camelcase: 'off',
@@ -26,4 +27,5 @@ module.exports = {
     '@typescript-eslint/no-unsafe-call': 'off',
     '@typescript-eslint/require-await': 'off',
   },
+  ignorePatterns: ['typechain-types/*'],
 };

.husky/pre-push

@@ -0,0 +1 @@
+pnpm check:deployment-addresses

contracts/NormalizedApi3ReaderProxyV1.sol

@@ -2,41 +2,58 @@
 pragma solidity ^0.8.27;
 
 import "./interfaces/INormalizedApi3ReaderProxyV1.sol";
-import "./ProxyUtils.sol";
 
 /// @title An immutable proxy contract that converts a Chainlink
 /// AggregatorV2V3Interface feed output to 18 decimals to conform with
-/// IApi3ReaderProxy decimal standard
+/// IApi3ReaderProxy decimal convention
 /// @dev This contract implements the AggregatorV2V3Interface to be compatible
 /// with Chainlink aggregators. This allows the contract to be used as a drop-in
 /// replacement for Chainlink aggregators in existing dApps.
 /// Refer to https://github.com/api3dao/migrate-from-chainlink-to-api3 for more
 /// information about the Chainlink interface implementation.
 contract NormalizedApi3ReaderProxyV1 is INormalizedApi3ReaderProxyV1 {
-    using ProxyUtils for int256;
-
     /// @notice Chainlink AggregatorV2V3Interface contract address
     address public immutable override feed;
 
-    uint8 internal immutable feedDecimals;
+    /// @notice Pre-calculated factor for scaling the feed's value to 18
+    /// decimals.
+    int256 public immutable scalingFactor;
+
+    /// @notice True if upscaling (multiply by `scalingFactor`), false if
+    /// downscaling (divide by `scalingFactor`), to normalize to 18 decimals.
+    bool public immutable isUpscaling;
 
     /// @param feed_ The address of the Chainlink AggregatorV2V3Interface feed
     constructor(address feed_) {
         if (feed_ == address(0)) {
             revert ZeroProxyAddress();
         }
-
         uint8 feedDecimals_ = AggregatorV2V3Interface(feed_).decimals();
         if (feedDecimals_ == 0 || feedDecimals_ > 36) {
             revert UnsupportedFeedDecimals();
         }
+        if (feedDecimals_ == 18) {
+            revert NoNormalizationNeeded();
+        }
         feed = feed_;
-        feedDecimals = feedDecimals_;
+        uint8 delta = feedDecimals_ > 18
+            ? feedDecimals_ - 18
+            : 18 - feedDecimals_;
+        scalingFactor = int256(10 ** uint256(delta));
+        isUpscaling = feedDecimals_ < 18;
     }
 
     /// @notice Returns the price of the underlying Chainlink feed normalized to
-    /// 18 decimals
-    /// of underlying Chainlink feed
+    /// 18 decimals.
+    /// @dev Fetches an `int256` answer from the Chainlink feed and scales it
+    /// to 18 decimals using pre-calculated factors. The result is cast to
+    /// `int224` to conform to the `IApi3ReaderProxy` interface.
+    /// IMPORTANT: If the normalized `int256` value is outside the `int224`
+    /// range, this cast causes silent truncation and data loss. Deployers
+    /// must verify that the source feed's characteristics (value magnitude
+    /// and original decimals) ensure the 18-decimal normalized value fits
+    /// `int224`. Scaling arithmetic (prior to cast) reverts on `int256`
+    /// overflow.
     /// @return value The normalized signed fixed-point value with 18 decimals
     /// @return timestamp The updatedAt timestamp of the feed
     function read()
@@ -48,7 +65,9 @@ contract NormalizedApi3ReaderProxyV1 is INormalizedApi3ReaderProxyV1 {
         (, int256 answer, , uint256 updatedAt, ) = AggregatorV2V3Interface(feed)
             .latestRoundData();
 
-        value = int224(answer.scaleValue(feedDecimals, 18));
+        value = isUpscaling
+            ? int224(answer * scalingFactor)
+            : int224(answer / scalingFactor);
         timestamp = uint32(updatedAt);
     }
 

contracts/ProxyUtils.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import "@api3/contracts/interfaces/IApi3ReaderProxy.sol";
+import "./interfaces/IWstETH.sol";
+
+/// @title An immutable proxy contract that reads the stETH per wstETH ratio
+/// directly from the WstETH contract on Ethereum.
+/// @dev This contract implements only the IApi3ReaderProxy interface and not the
+/// AggregatorV2V3Interface which is usually implemented by Api3 proxies. The
+/// user of this contract needs to be aware of this limitation and only use this
+/// contract where the IApi3ReaderProxy interface is expected.
+contract WstETHApi3ReaderProxyV1 is IApi3ReaderProxy {
+    /// @notice The address of the wstETH contract on Ethereum mainnet.
+    address public constant WST_ETH =
+        0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0;
+
+    /// @inheritdoc IApi3ReaderProxy
+    /// @dev Returns the stETH/wstETH exchange rate with 18 decimals precision.
+    /// The timestamp returned is the current block timestamp.
+    function read()
+        public
+        view
+        override
+        returns (int224 value, uint32 timestamp)
+    {
+        uint256 stEthPerToken = IWstETH(WST_ETH).stEthPerToken();
+
+        value = int224(int256(stEthPerToken)); // stEthPerToken value has 18 decimals.
+        timestamp = uint32(block.timestamp);
+    }
+}

contracts/WstETHApi3ReaderProxyV1.sol

@@ -2,7 +2,6 @@
 pragma solidity ^0.8.27;
 
 import "@api3/contracts/interfaces/IApi3ReaderProxy.sol";
-import "../ProxyUtils.sol";
 import "./interfaces/IScaledApi3FeedProxyV1.sol";
 
 /// @title An immutable Chainlink AggregatorV2V3Interface feed contract that
@@ -11,13 +10,20 @@ import "./interfaces/IScaledApi3FeedProxyV1.sol";
 /// @dev This contract assumes the source proxy always returns values with
 /// 18 decimals (as all IApi3ReaderProxy-compatible proxies do)
 contract ScaledApi3FeedProxyV1 is IScaledApi3FeedProxyV1 {
-    using ProxyUtils for int256;
-
     /// @notice IApi3ReaderProxy contract address
     address public immutable override proxy;
 
+    /// @dev Target decimals for the scaled value.
     uint8 private immutable targetDecimals;
 
+    /// @notice Pre-calculated factor for scaling the proxy's 18-decimal value
+    /// to `targetDecimals`.
+    int256 public immutable scalingFactor;
+
+    /// @notice True if upscaling (multiply by `scalingFactor`), false if
+    /// downscaling (divide by `scalingFactor`), to scale to `targetDecimals`.
+    bool public immutable isUpscaling;
+
     /// @param proxy_ IApi3ReaderProxy contract address
     /// @param targetDecimals_ Decimals used to scale the IApi3ReaderProxy value
     constructor(address proxy_, uint8 targetDecimals_) {
@@ -27,9 +33,16 @@ contract ScaledApi3FeedProxyV1 is IScaledApi3FeedProxyV1 {
         if (targetDecimals_ == 0 || targetDecimals_ > 36) {
             revert InvalidDecimals();
         }
-
+        if (targetDecimals_ == 18) {
+            revert NoScalingNeeded();
+        }
         proxy = proxy_;
         targetDecimals = targetDecimals_;
+        uint8 delta = targetDecimals_ > 18
+            ? targetDecimals_ - 18
+            : 18 - targetDecimals_;
+        scalingFactor = int256(10 ** uint256(delta));
+        isUpscaling = targetDecimals_ > 18;
     }
 
     /// @dev AggregatorV2V3Interface users are already responsible with
@@ -118,19 +131,26 @@ contract ScaledApi3FeedProxyV1 is IScaledApi3FeedProxyV1 {
         updatedAt = startedAt;
     }
 
-    /// @notice Reads from the IApi3ReaderProxy value and scales it to target
-    /// decimals
-    /// @dev Casting the scaled value to int224 might cause an overflow but this
-    /// is preferable to checking the value for overflows in every read due to
-    /// gas overhead
-    function _read()
-        internal
-        view
-        returns (int256 scaledValue, uint32 timestamp)
-    {
-        (int256 value, uint32 proxyTimestamp) = IApi3ReaderProxy(proxy).read();
-
-        scaledValue = int224(value.scaleValue(18, targetDecimals));
+    /// @notice Reads a value from the underlying `IApi3ReaderProxy` and
+    /// scales it to `targetDecimals`.
+    /// @dev Reads an `int224` value (assumed to be 18 decimals) from the
+    /// underlying `IApi3ReaderProxy`. This value is then scaled to
+    /// `targetDecimals` using pre-calculated factors. The scaling arithmetic
+    /// (e.g., `proxyValue * scalingFactor`) involves an `int224` (`proxyValue`)
+    /// and an `int256` (`scalingFactor`). `proxyValue` is implicitly promoted
+    /// to `int256` for this operation, resulting in an `int256` value.
+    /// This allows the scaled result to exceed the `int224` range, provided
+    /// it fits within `int256`. Arithmetic operations will revert on `int256`
+    /// overflow. The function returns the scaled value as an `int256`.
+    /// @return value The scaled signed fixed-point value with `targetDecimals`.
+    /// @return timestamp The timestamp from the underlying proxy.
+    function _read() internal view returns (int256 value, uint32 timestamp) {
+        (int224 proxyValue, uint32 proxyTimestamp) = IApi3ReaderProxy(proxy)
+            .read();
+
+        value = isUpscaling
+            ? proxyValue * scalingFactor
+            : proxyValue / scalingFactor;
         timestamp = proxyTimestamp;
     }
 }

contracts/adapters/ScaledApi3FeedProxyV1.sol

@@ -8,7 +8,13 @@ interface IScaledApi3FeedProxyV1 is AggregatorV2V3Interface {
 
     error InvalidDecimals();
 
+    error NoScalingNeeded();
+
     error FunctionIsNotSupported();
 
     function proxy() external view returns (address proxy);
+
+    function scalingFactor() external view returns (int256);
+
+    function isUpscaling() external view returns (bool);
 }

contracts/adapters/interfaces/IScaledApi3FeedProxyV1.sol

@@ -12,7 +12,13 @@ interface INormalizedApi3ReaderProxyV1 is
 
     error UnsupportedFeedDecimals();
 
+    error NoNormalizationNeeded();
+
     error FunctionIsNotSupported();
 
     function feed() external view returns (address feed);
+
+    function scalingFactor() external view returns (int256);
+
+    function isUpscaling() external view returns (bool);
 }

contracts/interfaces/INormalizedApi3ReaderProxyV1.sol

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+/// @title A minimal interface for the wstETH contract on Ethereum
+/// @dev This interface only includes the stEthPerToken function needed to read
+/// the exchange rate between stETH and wstETH.
+interface IWstETH {
+    /// @notice Returns the amount of stETH that corresponds to 1 wstETH
+    /// @return The stETH/wstETH exchange rate with 18 decimals precision
+    function stEthPerToken() external view returns (uint256);
+}

contracts/interfaces/IWstETH.sol

@@ -0,0 +1,58 @@
+import type { HardhatRuntimeEnvironment } from 'hardhat/types';
+
+import { getDeploymentName } from '../src';
+
+export const CONTRACT_NAME = 'InverseApi3ReaderProxyV1';
+
+module.exports = async (hre: HardhatRuntimeEnvironment) => {
+  const { getUnnamedAccounts, deployments, ethers, network, run } = hre;
+  const { deploy, log } = deployments;
+
+  const [deployerAddress] = await getUnnamedAccounts();
+  if (!deployerAddress) {
+    throw new Error('No deployer address found.');
+  }
+  log(`Deployer address: ${deployerAddress}`);
+
+  const proxyAddress = process.env.PROXY;
+  if (!proxyAddress) {
+    throw new Error('PROXY environment variable not set. Please provide the address of the proxy contract.');
+  }
+  if (!ethers.isAddress(proxyAddress)) {
+    throw new Error(`Invalid address provided for PROXY: ${proxyAddress}`);
+  }
+  log(`Proxy address: ${proxyAddress}`);
+
+  const isLocalNetwork = network.name === 'hardhat' || network.name === 'localhost';
+
+  const confirmations = isLocalNetwork ? 1 : 5;
+  log(`Deployment confirmations: ${confirmations}`);
+
+  const constructorArgs = [proxyAddress];
+  const constructorArgTypes = ['address'];
+
+  const deploymentName = getDeploymentName(CONTRACT_NAME, constructorArgTypes, constructorArgs);
+  log(`Generated deterministic deployment name for this instance: ${deploymentName}`);
+
+  const deployment = await deploy(deploymentName, {
+    contract: CONTRACT_NAME,
+    from: deployerAddress,
+    args: constructorArgs,
+    log: true,
+    waitConfirmations: confirmations,
+  });
+
+  if (isLocalNetwork) {
+    log('Skipping verification on local network.');
+    return;
+  }
+
+  log(
+    `Attempting verification of ${deploymentName} (contract type ${CONTRACT_NAME}) at ${deployment.address} (already waited for confirmations)...`
+  );
+  await run('verify:verify', {
+    address: deployment.address,
+    constructorArguments: deployment.args,
+  });
+};
+module.exports.tags = [CONTRACT_NAME];