feat: Enhance safety guard and external API manager with oracle feed support

- Added a bypass for balance checks in SafetyGuard for testing purposes.
- Refactored ExternalAPIManager to support multiple oracle feeds by chain.
- Implemented loading of configured oracle feeds from settings.
- Enhanced price fetching logic to fall back on oracle prices when no providers are available.
- Improved transaction processing in TxPoolScanner with comprehensive MEV analysis and logging.
- Added normalization for transaction hashes and support for Uniswap V3 multi-hop paths.
- Updated error recovery mechanisms in ErrorRecoveryManager for better handling of Web3 reconnections and transaction retries.
- Enhanced test coverage for new features, including oracle feed normalization and transaction manager profit analysis.

Author: John0n1

.env.example

@@ -1,9 +1,7 @@
-# Application Settings (required)
-TESTNET=0
+# Application / Logging
 RUN_LIVE_API_TESTS=0
 LOG_LEVEL=INFO
-DEBUG=true
-SIMULATE_ONLY=0
+DEBUG=false
 
 # Wallet (required)
 WALLET_KEY=
@@ -13,45 +11,60 @@ PROFIT_RECEIVER_ADDRESS=
 # WALLET_KEY_1=
 # WALLET_ADDRESS_1=
 
-# Chain and node endpoints (required) Publicnode for testing only.
+# Chain and node endpoints (required)
 CHAINS="1"
-POA_CHAINS="56,5"
+POA_CHAINS=""
 RPC_URL_1="https://ethereum-rpc.publicnode.com"
 WEBSOCKET_URL_1="wss://ethereum-rpc.publicnode.com"
-
+# PublicNode RPCs (EVM networks)
+# RPC_URL_10="https://optimism-rpc.publicnode.com"
+# WEBSOCKET_URL_10="wss://optimism-rpc.publicnode.com"
+# RPC_URL_56="https://bsc-rpc.publicnode.com"
+# WEBSOCKET_URL_56="wss://bsc-rpc.publicnode.com"
+# RPC_URL_137="https://polygon-bor-rpc.publicnode.com"
+# WEBSOCKET_URL_137="wss://polygon-bor-rpc.publicnode.com"
+# RPC_URL_42161="https://arbitrum-one-rpc.publicnode.com"
+# WEBSOCKET_URL_42161="wss://arbitrum-one-rpc.publicnode.com"
+# RPC_URL_43114="https://avalanche-c-chain-rpc.publicnode.com"
+# WEBSOCKET_URL_43114="wss://avalanche-c-chain-rpc.publicnode.com"
+# RPC_URL_8453="https://base-rpc.publicnode.com"
+# WEBSOCKET_URL_8453="wss://base-rpc.publicnode.com"
 
 # Transaction & Gas (required)
-TRANSACTION_RETRY_COUNT=0
-TRANSACTION_RETRY_DELAY=0
+TRANSACTION_RETRY_COUNT=3
+TRANSACTION_RETRY_DELAY=2.0
 MAX_GAS_PRICE_GWEI=200
-GAS_PRICE_MULTIPLIER=1.25
+GAS_PRICE_MULTIPLIER=1.1
 DEFAULT_GAS_LIMIT=500000
 FALLBACK_GAS_PRICE_GWEI=50
 DYNAMIC_GAS_PRICING=1
 GAS_PRICE_PERCENTILE=75
 MAX_GAS_FEE_PERCENTAGE=10.0
-MIN_WALLET_BALANCE=0.01
+MIN_WALLET_BALANCE=0.05
 
 # Simulation & Submission (optional)
 ALLOW_UNSIMULATED_TRADES=0
 SIMULATION_BACKEND=eth_call
 SIMULATION_CONCURRENCY=5
 SUBMISSION_MODE=public
 PRIVATE_RPC_URL=
+TENDERLY_BASE_URL="https://api.tenderly.co/api/v1"
+TENDERLY_ACCOUNT_SLUG=
+TENDERLY_PROJECT_SLUG=
+TENDERLY_ACCESS_TOKEN=
 BUNDLE_RELAY_URL=
 BUNDLE_RELAY_AUTH_TOKEN=
 BUNDLE_SIGNER_KEY=
-BUNDLE_SIGNER_KEY_PATH=
+BUNDLE_SIGNER_KEY_PATH=~/.on1builder/bundle_signer.key
 BUNDLE_TARGET_BLOCK_OFFSET=1
 BUNDLE_TIMEOUT_SECONDS=30
-TENDERLY_BASE_URL="https://api.tenderly.co/api/v1"
-TENDERLY_ACCOUNT_SLUG=
-TENDERLY_PROJECT_SLUG=
-TENDERLY_ACCESS_TOKEN=
+ALLOW_INSUFFICIENT_FUNDS_TESTS=0
+STARTUP_TEST_TRANSACTION=0
 
 # Strategy & Profit (required)
-MIN_PROFIT_ETH=0.01
+MIN_PROFIT_ETH=0.005
 MIN_PROFIT_PERCENTAGE=0.1
+PROFIT_ANALYSIS_ENABLED=0
 DYNAMIC_PROFIT_SCALING=1
 BALANCE_RISK_RATIO=0.3
 SLIPPAGE_TOLERANCE=0.5
@@ -73,69 +86,63 @@ FRONT_RUNNING_ENABLED=1
 BACK_RUNNING_ENABLED=1
 SANDWICH_ATTACKS_ENABLED=0
 
-# Cross-chain (optional)
+# ML Strategy (optional)
+ML_ENABLED=1
+ML_LEARNING_RATE=0.01
+ML_EXPLORATION_RATE=0.1
+ML_DECAY_RATE=0.995
+ML_UPDATE_FREQUENCY=100
+
+# Market Sentiment (optional)
+USE_MARKET_SENTIMENT=1
+SENTIMENT_WEIGHT=0.3
+
+# Cross-chain & Arbitrage (optional)
 CROSS_CHAIN_ENABLED=1
 BRIDGE_MONITORING_ENABLED=1
 ARBITRAGE_SCAN_INTERVAL=15
 
 # Contracts (mainnet)
 UNISWAP_V2_ROUTER_ADDRESSES='{"1": "0x1234567890abcdef1234567890abcdef1234567"}'
-UNISWAP_V2_FACTORY_ADDRESSES=
-UNISWAP_V3_ROUTER_ADDRESSES=
-UNISWAP_V3_FACTORY_ADDRESSES=
-UNISWAP_V3_POSITION_MANAGER_ADDRESSES=
-UNISWAP_V3_QUOTER_ADDRESSES=
-SUSHISWAP_ROUTER_ADDRESSES=
-AAVE_V3_POOL_ADDRESSES=
+UNISWAP_V3_ROUTER_ADDRESSES='{}'
+SUSHISWAP_ROUTER_ADDRESSES='{}'
+AAVE_V3_POOL_ADDRESSES='{}'
 
 # Your deployed flashloan contract addresses per chain (if any)
-SIMPLE_FLASHLOAN_CONTRACT_ADDRESSES=
+SIMPLE_FLASHLOAN_CONTRACT_ADDRESSES='{}'
 
 # External APIs (optional)
-ETHERSCAN_API_KEY=123456apikey654321
+ETHERSCAN_API_KEY=
 COINGECKO_API_KEY=
 COINMARKETCAP_API_KEY=
 CRYPTOCOMPARE_API_KEY=
-BINANCE_API_KEY=
 INFURA_PROJECT_ID=
 
+# Oracle feeds (optional, chain_id -> symbol -> feed address)
+# ORACLE_FEEDS='{"1": {"ETH": "0x..."} }'
+ORACLE_FEEDS='{"10": {"ETH": "0x13e3Ee699D1909E989722E753853AE30b17e08c5", "OP": "0x0D276FC14719f9292D5C1eA2198673d1f4269246"}, "137": {"ETH": "0xF9680D99D6C9589e2a93a78A04A279e509205945", "MATIC": "0xAB594600376Ec9fD91F8e885dADF0CE036862dE0", "USDC": "0xfE4A8cc5b5B2366C1B58Bea3858e81843581b2F7"}, "42161": {"ARB": "0xb2A824043730FE05F3DA2efaFa1CBbe83fa548D6", "BTC": "0x6ce185860a4963106506C203335A2910413708e9", "ETH": "0x639Fe6ab55C921f74e7fac1ee960C0B6293ba612"}, "56": {"BNB": "0x0567F2323251f0Aab15c8dFb1967E4e8A7D42aeE", "BTC": "0x264990fbd0A4796A3E3d8E37C4d5F87a3aCa5Ebf", "ETH": "0x9ef1B8c0E4F7dc8bF5719Ea496883DC6401d5b2e"}, "8453": {"ETH": "0x71041dddad3595F9CEd3DcCFBe3D1F4b0a16Bb70"}}'
+ORACLE_STALE_SECONDS=3600
+
 # System & Performance (required)
 MEMORY_CHECK_INTERVAL=300
-HEARTBEAT_INTERVAL=90
+HEARTBEAT_INTERVAL=30
 CONNECTION_RETRY_COUNT=5
 CONNECTION_RETRY_DELAY=5.0
+PERFORMANCE_REPORT_INTERVAL=3600
 
 # Database (required)
 DATABASE_URL="sqlite+aiosqlite:///on1builder_data.db"
 
 # Notifications (optional)
-NOTIFICATION_CHANNELS=discord,slack,email
-MIN_NOTIFICATION_LEVEL=
+# NOTIFICATION_CHANNELS=discord,slack,email
+NOTIFICATION_CHANNELS=
+MIN_NOTIFICATION_LEVEL=INFO
 SLACK_WEBHOOK_URL=
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
 DISCORD_WEBHOOK_URL=
 SMTP_SERVER=
-SMTP_PORT=
+SMTP_PORT=587
 SMTP_USERNAME=
 SMTP_PASSWORD=
 ALERT_EMAIL=
-
-#######################################
-# Testnet related settings
-STARTUP_TEST_SWAP=0
-STARTUP_TEST_SWAP_AMOUNT_ETH=0
-STARTUP_TEST_SWAP_PATH=
-STARTUP_TEST_SWAP_DEX=
-STARTUP_TEST_SWAP_FEE=
-STARTUP_TEST_SWAP_DELAY=
-TESTNET_ARB_ENABLED=
-TESTNET_ARB_INTERVAL=
-TESTNET_ARB_AMOUNT_ETH=
-TESTNET_ARB_PATH=
-TESTNET_ARB_V3_FEE=
-TESTNET_ARB_MIN_PROFIT_ETH=
-TESTNET_ARB_GAS_LIMIT=
-TESTNET_ARB_INITIAL_DELAY=
-RPC_URL_11155111=
-WEBSOCKET_URL_11155111=

README.md

@@ -96,9 +96,16 @@ python -m on1builder run start
 | `SIMULATION_BACKEND` | `eth_call`, `anvil`, or `tenderly` |
 | `SIMULATION_CONCURRENCY` | Max concurrent simulations |
 | `NOTIFICATION_CHANNELS` | `slack,telegram,discord,email` (blank = off) |
+| `ORACLE_FEEDS` | JSON map of chain_id → symbol → Chainlink feed address |
+| `ORACLE_STALE_SECONDS` | Max age (seconds) before oracle price is treated as stale |
+| `STARTUP_TEST_TRANSACTION` | Run a diagnostic self-tx on startup (requires `ALLOW_INSUFFICIENT_FUNDS_TESTS`) |
+| `ALLOW_INSUFFICIENT_FUNDS_TESTS` | Bypass local balance checks for test sends (debug only) |
 
 Full list lives in `.env.example`.
 
+PublicNode endpoints can be used for EVM chains listed in `.env.example`. Non-EVM endpoints
+(Sui, Aptos, Osmosis, Avalanche P/X, Polygon Heimdall) are not supported by ON1Builder.
+
 ## Running & Monitoring
 
 ```bash
@@ -127,6 +134,17 @@ black src tests && flake8 src tests && mypy src
 
 Pre-commit hooks are configured in `.pre-commit-config.yaml`.
 
+## Optional Utilities
+
+ON1Builder ships a few utilities that are not required for core execution but can be
+integrated in advanced deployments:
+
+- `src/on1builder/utils/error_recovery.py`: Retry/circuit-breaker helpers and a recovery
+  manager. The TransactionManager now reports failures to this manager for tracking and
+  optional recovery strategies, but most strategies are placeholders by default.
+- `src/on1builder/utils/container.py`: A lightweight DI container for advanced lifecycle
+  management. The core runtime does not use it yet; opt in if you want centralized wiring.
+
 ## Flashloan setup
 You need to deploy your own flashloan provider contract or use an existing one. Make sure to configure the flashloan provider address in your strategy settings.
 

src/on1builder/config/loaders.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from pathlib import Path
 from typing import Dict, Any, Optional
@@ -91,11 +92,18 @@ class _EnvSettings(BaseSettings):
     )
     bundle_target_block_offset: int = 1
     bundle_timeout_seconds: int = 30
+    allow_insufficient_funds_tests: bool = Field(
+        False, alias="ALLOW_INSUFFICIENT_FUNDS_TESTS"
+    )
+    startup_test_transaction: bool = Field(
+        False, alias="STARTUP_TEST_TRANSACTION"
+    )
 
     # Balance and profit settings
     min_wallet_balance: float = 0.05
     min_profit_eth: float = 0.005
     min_profit_percentage: float = 0.1
+    profit_analysis_enabled: bool = False
     dynamic_profit_scaling: bool = True
     balance_risk_ratio: float = 0.3
     slippage_tolerance: float = 0.5
@@ -187,6 +195,25 @@ class _EnvSettings(BaseSettings):
         "sqlite+aiosqlite:///on1builder_data.db", alias="DATABASE_URL"
     )
 
+    oracle_feeds: str = Field("{}", alias="ORACLE_FEEDS")
+    oracle_stale_seconds: int = Field(3600, alias="ORACLE_STALE_SECONDS")
+
+
+def _parse_json_env(value: Any, default: Any) -> Any:
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return default
+        if stripped.startswith("{"):
+            try:
+                return json.loads(stripped)
+            except json.JSONDecodeError:
+                logger.warning("Invalid JSON for ORACLE_FEEDS; using defaults.")
+                return default
+    return default
+
 
 def _gather_dynamic_env_vars() -> Dict[str, Any]:
     """
@@ -282,6 +309,9 @@ def load_settings(env_path: Optional[Path] = None) -> GlobalSettings:
     # Gather all static and dynamic data
     final_config_data = env_settings.model_dump()
     final_config_data.update(_gather_dynamic_env_vars())
+    final_config_data["oracle_feeds"] = _parse_json_env(
+        env_settings.oracle_feeds, {}
+    )
 
     # Populate nested models
     final_config_data["api"] = api_settings

src/on1builder/config/settings.py

@@ -75,7 +75,7 @@ def normalize_level(cls, v):
     @field_validator("channels", mode="before")
     def split_str(cls, v):
         if isinstance(v, str):
-            return [item.strip() for item in v.split(",")]
+            return [item.strip() for item in v.split(",") if item.strip()]
         return v
 
 
@@ -290,12 +290,24 @@ def validate_complete_settings(self):
     )
     fallback_gas_price_gwei: int = Field(default=50, gt=0)
     min_wallet_balance: float = Field(default=0.05, ge=0)
+    allow_insufficient_funds_tests: bool = Field(
+        default=False,
+        description="Bypass local balance checks for startup test transactions.",
+    )
+    startup_test_transaction: bool = Field(
+        default=False,
+        description="Attempt a startup test transaction for diagnostics.",
+    )
 
     # Strategy & Profit - ON1Builder with dynamic thresholds
     min_profit_eth: float = Field(default=0.005, ge=0)
     min_profit_percentage: float = Field(
         default=0.1, ge=0
     )  # Minimum profit as % of investment
+    profit_analysis_enabled: bool = Field(
+        default=False,
+        description="Enable detailed post-trade profit analysis (extra RPC/API calls).",
+    )
     dynamic_profit_scaling: bool = Field(
         default=True
     )  # Scale profit requirements based on balance
@@ -385,6 +397,14 @@ def validate_complete_settings(self):
     cross_chain_enabled: bool = Field(default=True)
     bridge_monitoring_enabled: bool = Field(default=True)
 
+    # Oracle feeds (chain_id -> symbol -> feed address)
+    oracle_feeds: Dict[str, Dict[str, str]] = Field(default_factory=dict)
+    oracle_stale_seconds: int = Field(
+        default=3600,
+        gt=0,
+        description="Max age in seconds for oracle prices before treating as stale.",
+    )
+
     # Nested Settings Models
     api: APISettings = Field(default_factory=APISettings)
     contracts: ContractAddressSettings = Field(default_factory=ContractAddressSettings)

src/on1builder/config/validation.py

@@ -27,6 +27,7 @@ class ConfigValidator:
         10: "Optimism",
         56: "BSC",
         43114: "Avalanche",
+        8453: "Base",
         250: "Fantom",
         # Add test networks
         5: "Goerli",