fix: 🛠️ Add Base Support (#43)

* feat: ✨ Added config file support

* tidy

* tidy

* lint

* refactor: ♻️ tidy

* ci: 💚 fix ci

* fix: 🐛 fix asset order

* fix: 🐛 fix oraclehelper issue

* fix

* refactor: ♻️ tidy

* fmt

* fix default overriding

* Refactor/big refactor (#39)

* refactor: ♻️ big refactor

* refactor: ♻️ Tidy

* docs: 📝 update readme

* refactor: ♻️ pr comments

* refactor: asset addresses constants as typed dicts (#38)

* feat: add validation for asset prices in total_assets calculation (#35)

* feat: add validation for asset prices in total_assets calculation

- Implemented checks for invalid prices (<= 0) in the calculate_total_assets function.
- Added error handling to raise ValueError with details of invalid prices.
- Introduced a new test to ensure that invalid prices trigger the appropriate exception.

* refactor: turn invalid prices computation into list comprehension

* feat: add price validation for price adapter (#36)

* fix: update WstETHAdapter and tests to set ETH base asset price to 1

- Changed the base asset price for ETH in WstETHAdapter from 0 to 1 to ensure accurate pricing.
- Updated related tests to verify that the ETH price is now correctly set to 1 instead of 0.
- Adjusted documentation to clarify the base asset pricing behavior.

* feat: add price validation to BasePriceAdapter

* refactor: change validate_prices method to synchronous in price adapters

- Updated the validate_prices method in BasePriceAdapter to be synchronous instead of asynchronous.
- Adjusted calls to validate_prices in ChainlinkAdapter, CowSwapAdapter, and WstETHAdapter accordingly.

* feat: add TypedDict for network addresses in constants.py

* feat: add NetworkAddresses instances

* refactor: rename NetworkAddresses to NetworkTokens and update address constants

* feat: add network configuration and asset retrieval to OracleCLIConfig

* refactor: update WstETHAdapter to use dynamic asset addresses from config

* refactor: enhance WstETHAdapter to enforce required ETH address and simplify checks

* refactor: update CowSwapAdapter to use dynamic asset addresses and improve network configuration

* refactor: update ChainlinkAdapter to use dynamic asset addresses from config and enforce required ETH address

* refactor: update IdleBalancesAdapter to use dynamic asset addresses from config and enforce required ETH and USDC addresses

* refactor: remove optional asset address attributes from Chainlink, CowSwap, and WstETH adapters

* refactor: enforce required USDC address in HyperliquidAdapter and update asset address retrieval from config

* refactor: update Chainlink test suite to use dynamic asset addresses from config

* refactor: update WstETHAdapter tests to utilize dynamic asset addresses from config

* refactor: enhance HyperliquidAdapter tests to utilize dynamic USDC addresses from config

* refactor: update tests to utilize dynamic asset addresses from config for improved consistency

* refactor: update Chainlink and CowSwap tests to utilize dynamic asset addresses from config for improved consistency

* refactor: update Chainlink tests to include dynamic ETH address in price fetching for USDT and USDS on testnet

* refactor: update import paths from config to settings in CowSwap and Hyperliquid test files

* test fix

* refactor: ♻️ pr comments

* pr comments

* Update constants.py

Co-authored-by: Copilot <[email protected]>

* Feat/improved docs checks (#40)

* docs

* docs

* Update src/tq_oracle/adapters/asset_adapters/idle_balances.py

Co-authored-by: Copilot <[email protected]>

* Update tq-oracle-example.toml

Co-authored-by: Copilot <[email protected]>

* Update README.md

Co-authored-by: Copilot <[email protected]>

* update cli opts

* fix: 🐛 working with base now

* rename l1->vault

* fix private key

* price fix

* fix tests

* update tests

* give steth disclaimer

* fmt

---------

Co-authored-by: Matías Ignacio González <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

ARCHITECTURE.md

@@ -82,6 +82,10 @@ Multi-stage pricing system with validation:
 1. **Price Fetching**: Queries multiple price sources sequentially
    - `CowSwapAdapter`: Primary DEX aggregator price source
    - `WstETHAdapter`: Specialized adapter for wrapped staked ETH
+     - **⚠️ Pricing Assumption**: Assumes 1:1 peg between stETH and ETH
+     - Calculates wstETH price by querying the stETH/wstETH exchange rate from the wstETH contract
+     - Does NOT fetch or validate the market price of stETH/ETH
+     - During stETH depeg events, wstETH will be mispriced relative to market value
    - `ChainlinkAdapter`: Not used in main pipeline, only for validation
 
 2. **Price Validation** (`checks/price_validators.py`):
@@ -198,7 +202,7 @@ TQ Oracle uses a three-tier configuration system with precedence:
 
 - `vault_address`: Target vault to report on
 - `oracle_helper_address`: OracleHelper contract for price normalization
-- `l1_rpc` / `hl_rpc`: RPC endpoints for different chains
+- `vault_rpc` / `hl_rpc`: RPC endpoints for different chains (vault network and Hyperliquid)
 - `safe_address`: Gnosis Safe for multi-sig submission
 - `private_key`: Signer key for proposing Safe transactions
 - `subvault_adapters`: Per-subvault adapter configuration

README.md

@@ -8,6 +8,13 @@ TQ Oracle performs read smart contract READ calls through a registry of protocol
 
 For detailed system architecture and integration with Mellow Finance flexible-vaults, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
+## Known Limitations & Assumptions
+
+> [!WARNING]
+> **stETH/ETH Peg Assumption**: The wstETH price adapter assumes a 1:1 peg between stETH and ETH when calculating wstETH prices. This assumption is **not validated** against market prices.
+>
+> **Impact**: During stETH depeg events (e.g., market stress, liquidity crises), the oracle will report inaccurate TVL for vaults holding wstETH. The reported value will reflect the stETH/wstETH exchange rate multiplied by an assumed 1:1 stETH/ETH rate, not the actual market value.
+
 ## Running without installing
 
 You can run this CLI without any git cloning, directly with `uv`
@@ -67,7 +74,7 @@ All configuration options can be set via CLI arguments, environment variables, o
 | `VAULT_ADDRESS` | - | `vault_address` | *required* | Vault contract address (positional argument) |
 | `--config` `-c` | - | - | Auto-detect | Path to TOML configuration file |
 | `--oracle-helper-address` `-h` | - | `oracle_helper_address` | Auto (mainnet/testnet) | OracleHelper contract address |
-| `--l1-rpc` | `L1_RPC` | `l1_rpc` | Auto (mainnet/testnet) | Ethereum L1 RPC endpoint |
+| `--vault-rpc` | `VAULT_RPC` | `vault_rpc` | Auto (mainnet/sepolia/base) | Vault network RPC endpoint |
 | `--hl-rpc` | `HL_EVM_RPC` | `hl_rpc` | Auto (mainnet/testnet) | Hyperliquid RPC endpoint |
 | `--l1-subvault-address` | `L1_SUBVAULT_ADDRESS` | `l1_subvault_address` | - | L1 subvault for CCTP monitoring |
 | `--hl-subvault-address` | `HL_SUBVAULT_ADDRESS` | `hl_subvault_address` | Vault address | Hyperliquid subvault address |

scripts/check_cctp_inflight.py

@@ -25,7 +25,7 @@ async def test_cctp_bridge(
     l1_subvault_address: str,
     hl_subvault_address: str,
     testnet: bool = False,
-    l1_rpc: str | None = None,
+    vault_rpc: str | None = None,
     hl_rpc: str | None = None,
 ) -> int:
     """Test CCTP bridge in-flight transaction detection.
@@ -34,21 +34,21 @@ async def test_cctp_bridge(
         l1_subvault_address: L1 subvault address to monitor
         hl_subvault_address: Hyperliquid subvault address to monitor
         testnet: Whether to use testnet (default: False for mainnet)
-        l1_rpc: Custom L1 RPC URL (optional, defaults based on testnet flag)
+        vault_rpc: Custom L1 RPC URL (optional, defaults based on testnet flag)
         hl_rpc: Custom Hyperliquid RPC URL (optional, defaults based on testnet flag)
     """
-    using_default_rpc = l1_rpc is None or hl_rpc is None
+    using_default_rpc = vault_rpc is None or hl_rpc is None
 
-    if l1_rpc is None:
-        l1_rpc = DEFAULT_SEPOLIA_RPC_URL if testnet else DEFAULT_MAINNET_RPC_URL
+    if vault_rpc is None:
+        vault_rpc = DEFAULT_SEPOLIA_RPC_URL if testnet else DEFAULT_MAINNET_RPC_URL
 
     if hl_rpc is None:
         hl_rpc = HL_TEST_EVM_RPC if testnet else HL_PROD_EVM_RPC
 
     config = OracleSettings(
         vault_address="",
         oracle_helper_address="",
-        l1_rpc=l1_rpc,
+        vault_rpc=vault_rpc,
         l1_subvault_address=l1_subvault_address,
         safe_address=None,
         hl_rpc=hl_rpc,
@@ -65,7 +65,7 @@ async def test_cctp_bridge(
     logger.info(f"L1 Subvault: {l1_subvault_address}")
     logger.info(f"HL Subvault: {hl_subvault_address}")
     logger.info(f"Network: {'Testnet' if testnet else 'Mainnet'}")
-    logger.info(f"L1 RPC: {l1_rpc}")
+    logger.info(f"Vault RPC: {vault_rpc}")
     logger.info(f"HL RPC: {hl_rpc}")
     logger.info("=" * 60)
 
@@ -116,7 +116,7 @@ def main() -> int:
                 l1_subvault_address=args.l1_subvault_address,
                 hl_subvault_address=args.hl_subvault_address,
                 testnet=args.testnet,
-                l1_rpc=args.l1_rpc,
+                vault_rpc=args.vault_rpc,
                 hl_rpc=args.hl_rpc,
             )
         )

src/tq_oracle/adapters/asset_adapters/base.py

@@ -9,7 +9,7 @@
 class AdapterChain(Enum):
     """Enum indicating which blockchain/RPC an adapter uses."""
 
-    L1 = "l1"  # Ethereum L1 (uses l1_rpc)
+    VAULT_CHAIN = "vault_chain"  # Main vault network (uses vault_rpc)
     HYPERLIQUID = "hyperliquid"  # Hyperliquid chain (uses hl_rpc)
 
 
@@ -24,12 +24,12 @@ class AssetData:
 class BaseAssetAdapter(ABC):
     """Abstract base class for asset adapters."""
 
-    def __init__(self, config: OracleSettings, chain: str = "l1"):
+    def __init__(self, config: OracleSettings, chain: str = "vault_chain"):
         """Initialize the adapter with configuration.
 
         Args:
             config: Oracle configuration
-            chain: Which chain to operate on - "l1" or "hyperliquid"
+            chain: Which chain to operate on - "vault_chain" or "hyperliquid"
         """
         self.config = config
         self._chain = chain

src/tq_oracle/adapters/asset_adapters/idle_balances.py

@@ -28,12 +28,12 @@ class IdleBalancesAdapter(BaseAssetAdapter):
     eth_address: str
     usdc_address: str
 
-    def __init__(self, config: OracleSettings, chain: str = "l1"):
+    def __init__(self, config: OracleSettings, chain: str = "vault_chain"):
         """Initialize the adapter.
 
         Args:
             config: Oracle configuration
-            chain: Which chain to query - "l1" or "hyperliquid"
+            chain: Which chain to query - "vault_chain" or "hyperliquid"
         """
         super().__init__(config, chain=chain)
 
@@ -42,9 +42,10 @@ def __init__(self, config: OracleSettings, chain: str = "l1"):
                 raise ValueError("hl_rpc must be configured to use hyperliquid chain")
             self.w3 = Web3(Web3.HTTPProvider(config.hl_rpc))
         else:
-            self.w3 = Web3(Web3.HTTPProvider(config.l1_rpc))
+            self.w3 = Web3(Web3.HTTPProvider(config.vault_rpc))
 
         assets = config.assets
+        logger.debug(f"Assets available: {assets}")
         eth_address = assets["ETH"]
         if eth_address is None:
             raise ValueError("ETH address is required for IdleBalances adapter")
@@ -80,7 +81,7 @@ def chain(self) -> AdapterChain:
         return (
             AdapterChain.HYPERLIQUID
             if self._chain == "hyperliquid"
-            else AdapterChain.L1
+            else AdapterChain.VAULT_CHAIN
         )
 
     async def fetch_assets(self, subvault_address: str) -> list[AssetData]:
@@ -221,7 +222,7 @@ async def _fetch_supported_assets(self) -> list[str]:
         """Get the supported assets for the given vault."""
         oracle_abi = load_oracle_abi()
         oracle_address = get_oracle_address_from_vault(
-            self.config.vault_address_required, self.config.l1_rpc_required
+            self.config.vault_address_required, self.config.vault_rpc_required
         )
         return await self._fetch_contract_list(
             contract_address=oracle_address,

src/tq_oracle/adapters/check_adapters/active_submit_report_proposal_check.py

@@ -6,6 +6,7 @@
 import logging
 from typing import TYPE_CHECKING
 
+import requests
 from eth_typing import URI
 from safe_eth.eth import EthereumClient, EthereumNetwork
 from safe_eth.safe.api import TransactionServiceApi
@@ -93,7 +94,7 @@ async def _get_active_submit_report_proposals(self) -> list[object]:
             List of active submitReport() proposals
         """
         network = EthereumNetwork(self._config.chain_id)
-        ethereum_client = EthereumClient(URI(self._config.l1_rpc_required))
+        ethereum_client = EthereumClient(URI(self._config.vault_rpc_required))
 
         api_key = (
             self._config.safe_txn_srvc_api_key.get_secret_value()
@@ -104,6 +105,12 @@ async def _get_active_submit_report_proposals(self) -> list[object]:
 
         safe_checksum = Web3.to_checksum_address(self._config.safe_address)
 
+        safe_api_url = f"{tx_service.base_url}/api/v1/safes/{safe_checksum}/"
+        safe_info_response = await asyncio.to_thread(requests.get, safe_api_url)
+        safe_info_response.raise_for_status()
+        safe_info_data = safe_info_response.json()
+        current_nonce = int(safe_info_data.get("nonce", 0))
+
         pending_txs = await asyncio.to_thread(
             tx_service.get_transactions,
             safe_checksum,
@@ -117,6 +124,10 @@ async def _get_active_submit_report_proposals(self) -> list[object]:
             if not tx.get("isExecuted", False):
                 tx_data = tx.get("data", "")
                 if tx_data and tx_data.startswith(SUBMIT_REPORTS_SELECTOR):
-                    active_submit_report_proposals.append(tx)
+                    # Filter out stale transactions (nonce < current_nonce)
+                    # These are rejected/superseded proposals that can never execute
+                    tx_nonce = tx.get("nonce")
+                    if tx_nonce is not None and int(tx_nonce) >= current_nonce:
+                        active_submit_report_proposals.append(tx)
 
         return active_submit_report_proposals

src/tq_oracle/adapters/check_adapters/cctp_bridge.py

@@ -125,8 +125,8 @@ async def run_check(self) -> CheckResult:
                     message="Skipping CCTP bridge checks - HL subvault address not configured",
                     retry_recommended=False,
                 )
-            logger.debug(f"Connecting to L1 RPC: {self._config.l1_rpc}")
-            l1_w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(self._config.l1_rpc))
+            logger.debug(f"Connecting to vault-chain RPC: {self._config.vault_rpc}")
+            l1_w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(self._config.vault_rpc))
             logger.debug(f"Connecting to HL RPC: {self._config.hl_rpc}")
             hl_w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(self._config.hl_rpc))
 

src/tq_oracle/adapters/check_adapters/timeout_check.py

@@ -59,7 +59,7 @@ async def run_check(self) -> CheckResult:
         """
         w3 = None
         try:
-            w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(self._config.l1_rpc))
+            w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(self._config.vault_rpc))
 
             oracle_address = self._config.oracle_address
             logger.debug(f"Using oracle address: {oracle_address}")

src/tq_oracle/adapters/price_adapters/chainlink.py

@@ -26,7 +26,7 @@ class ChainlinkAdapter(BasePriceAdapter):
 
     def __init__(self, config: OracleSettings):
         super().__init__(config)
-        self.l1_rpc = config.l1_rpc
+        self.vault_rpc = config.vault_rpc
         assets = config.assets
         eth_address = assets["ETH"]
         if eth_address is None:
@@ -83,7 +83,7 @@ async def fetch_prices(
         if not direct_feed_assets and not has_usds:
             return prices_accumulator
 
-        w3 = Web3(Web3.HTTPProvider(self.l1_rpc))
+        w3 = Web3(Web3.HTTPProvider(self.vault_rpc))
         aggregator_abi = load_aggregator_abi()
 
         for asset_address, price_feed in direct_feed_assets:

src/tq_oracle/adapters/price_adapters/wsteth.py

@@ -1,24 +1,51 @@
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING
 
 from web3 import Web3
 
 from ...abi import load_wsteth_abi
+from ...constants import DEFAULT_MAINNET_RPC_URL, ETH_MAINNET_ASSETS
+from ...settings import Network
 from .base import BasePriceAdapter, PriceData
 
 if TYPE_CHECKING:
     from ...settings import OracleSettings
 
+logger = logging.getLogger(__name__)
+
 
 class WstETHAdapter(BasePriceAdapter):
-    """Adapter for pricing ETH, WETH, and wstETH."""
+    """Adapter for pricing ETH, WETH, and wstETH.
+
+    WARNING: This adapter assumes a 1:1 peg between stETH and ETH when pricing wstETH.
+    The wstETH price is calculated by querying the wstETH contract's stETH/wstETH exchange
+    rate and treating that value as equivalent to ETH. During stETH depeg events (e.g.,
+    market stress, liquidity issues), this will result in inaccurate TVL reporting.
+
+    The adapter does NOT validate the stETH/ETH market price. Operators should monitor
+    stETH/ETH price deviation and be aware that reported wstETH values may not reflect
+    true market pricing during depeg scenarios.
+    """
 
     eth_address: str
 
     def __init__(self, config: OracleSettings):
         super().__init__(config)
-        self.l1_rpc = config.l1_rpc
+
+        if config.network == Network.MAINNET:
+            self.mainnet_rpc = config.vault_rpc
+        else:
+            # On L2s (Base, Sepolia, etc), use eth_mainnet_rpc or fall back to default
+            self.mainnet_rpc = config.eth_mainnet_rpc or DEFAULT_MAINNET_RPC_URL
+            if not config.eth_mainnet_rpc:
+                logger.warning(
+                    f"eth_mainnet_rpc not configured for {config.network.value}. "
+                    f"Using default public RPC ({DEFAULT_MAINNET_RPC_URL}) for wstETH pricing. "
+                    f"For production deployments, configure eth_mainnet_rpc in your settings."
+                )
+
         assets = config.assets
         eth_address = assets["ETH"]
         if eth_address is None:
@@ -54,12 +81,16 @@ async def fetch_prices(
         if prices_accumulator.base_asset != self.eth_address:
             raise ValueError("WstETH adapter only supports ETH as base asset")
 
-        has_eth = self.eth_address in asset_addresses
+        asset_addresses_lower = [addr.lower() for addr in asset_addresses]
+
+        has_eth = self.eth_address.lower() in asset_addresses_lower
         has_weth = (
-            self.weth_address is not None and self.weth_address in asset_addresses
+            self.weth_address is not None
+            and self.weth_address.lower() in asset_addresses_lower
         )
         has_wsteth = (
-            self.wsteth_address is not None and self.wsteth_address in asset_addresses
+            self.wsteth_address is not None
+            and self.wsteth_address.lower() in asset_addresses_lower
         )
 
         if has_eth:
@@ -71,15 +102,23 @@ async def fetch_prices(
 
         if has_wsteth:
             assert self.wsteth_address is not None
-            w3 = Web3(Web3.HTTPProvider(self.l1_rpc))
+            wsteth_addr_actual = next(
+                addr
+                for addr in asset_addresses
+                if addr.lower() == self.wsteth_address.lower()
+            )
+
+            w3 = Web3(Web3.HTTPProvider(self.mainnet_rpc))
             wsteth_abi = load_wsteth_abi()
+            mainnet_wsteth = ETH_MAINNET_ASSETS["WSTETH"]
+            assert mainnet_wsteth is not None
             wsteth_contract = w3.eth.contract(
-                address=w3.to_checksum_address(self.wsteth_address),
+                address=w3.to_checksum_address(mainnet_wsteth),
                 abi=wsteth_abi,
             )
 
             wsteth_price = wsteth_contract.functions.getStETHByWstETH(10**18).call()
-            prices_accumulator.prices[self.wsteth_address] = int(wsteth_price)
+            prices_accumulator.prices[wsteth_addr_actual] = int(wsteth_price)
 
         self.validate_prices(prices_accumulator)