{"id":26909842,"url":"https://github.com/john0n1/on1builder","last_synced_at":"2026-04-12T06:06:56.862Z","repository":{"id":273662229,"uuid":"920018690","full_name":"John0n1/ON1Builder","owner":"John0n1","description":"High-performance, multi-chain blockchain transaction framework.","archived":false,"fork":false,"pushed_at":"2026-01-12T00:30:04.000Z","size":2520,"stargazers_count":33,"open_issues_count":2,"forks_count":10,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-12T04:43:48.231Z","etag":null,"topics":["aave-v3","arbitrage","back-running","blockchain","blockchain-framework","ethereum","flash-loan","machine-learning","maximal-extraction-value-bot","mempool-monitoring","mev-bots","smart-contracts","trading-automation","trading-strategies","tradingbot","web3py"],"latest_commit_sha":null,"homepage":"https://john0n1.github.io/ON1Builder/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/John0n1.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"John0n1"}},"created_at":"2025-01-21T12:26:22.000Z","updated_at":"2026-01-12T00:30:08.000Z","dependencies_parsed_at":"2025-02-22T12:18:31.724Z","dependency_job_id":"f29c4271-0b46-4473-86ad-bc9b376bcada","html_url":"https://github.com/John0n1/ON1Builder","commit_stats":null,"previous_names":["john0n1/0xbuilder","john0n1/on1builder"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/John0n1/ON1Builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John0n1%2FON1Builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John0n1%2FON1Builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John0n1%2FON1Builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John0n1%2FON1Builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/John0n1","download_url":"https://codeload.github.com/John0n1/ON1Builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/John0n1%2FON1Builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28480828,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aave-v3","arbitrage","back-running","blockchain","blockchain-framework","ethereum","flash-loan","machine-learning","maximal-extraction-value-bot","mempool-monitoring","mev-bots","smart-contracts","trading-automation","trading-strategies","tradingbot","web3py"],"created_at":"2025-04-01T13:29:44.455Z","updated_at":"2026-04-12T06:06:56.847Z","avatar_url":"https://github.com/John0n1.png","language":"Python","funding_links":["https://github.com/sponsors/John0n1"],"categories":[],"sub_categories":[],"readme":"# ON1Builder\n\n[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![CI](https://github.com/John0n1/ON1Builder/actions/workflows/ci.yml/badge.svg)](https://github.com/John0n1/ON1Builder/actions/workflows/ci.yml)\n\n```bash\npip install -e .\n```\n\nAsync, multi-chain MEV/arbitrage engine with safety rails, flashloan support, and live telemetry. Highly customizable via config.\n\n## Overview\nON1Builder is a modular MEV searcher framework designed for building and deploying arbitrage, front-running, and back-running strategies across multiple EVM-compatible blockchains. It emphasizes safety, configurability, and observability, making it suitable for both development and production environments.\n\n---\n\n## Key Features\n- **Multi-Chain Support**: Easily connect to any EVM-compatible chain with configurable RPC and WebSocket endpoints (prefers Nethermind, Geth nodes).\n- **MEV Strategies**: Built-in support for common MEV strategies including arbitrage, front-running, back-running, and flashloan-based trades.\n- **Safety Mechanisms**: Configurable slippage caps, gas price ceilings, and balance tiers to minimize risk.\n- **Flashloan Integration**: Seamless integration with popular flashloan providers for capital-efficient trading.\n- **Simulation Backends**: Supports multiple simulation backends (eth_call, Anvil, Tenderly) for pre-execution validation.\n- **Telemetry \u0026 Monitoring**: Heartbeats, performance summaries, structured logging, and notification channels (Slack, Telegram, Discord, Email) for real-time monitoring.\n- **Extensible Architecture**: Modular design allows for easy addition of new strategies, chains, and features.\n\n## Quick Snapshot\n\n| Track | Summary |\n| ----- | ------- |\n| Core Focus | MEV searcher: arbitrage, back/front-run, flashloans |\n| Chains | Ethereum ready (public RPC OK); multi-chain capable |\n| Safety | Slippage caps, gas ceilings, balance tiers, emergency stop |\n| Telemetry | Heartbeats, perf summaries, structured logs, notifications |\n\n## Feature Highlights\n\n\u003cimg width=\"9867\" height=\"2500\" alt=\"Dia\" src=\"https://github.com/user-attachments/assets/9acc0ac1-c5f3-45f1-a8c9-bf6bf1f3b232\" /\u003e\n\n## Quick Start\n\n### 1. Clone \u0026 env\n```bash\ngit clone https://github.com/John0n1/ON1Builder.git\ncd ON1Builder\n```\n- Windows\n```bash\npython -m venv .venv\n. .venv/Scripts/activate\npip install -r requirements.txt\npip install -e .\n```\n- Linux/MacOS\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\npip install -e .\n```\n\n### 2. Configure (minimum)\n```bash\ncopy .env.example .env\n# edit:\n#   WALLET_KEY, WALLET_ADDRESS\n#   RPC_URL_1=\"https://ethereum-rpc.publicnode.com\"\n#   WEBSOCKET_URL_1=\"wss://ethereum-rpc.publicnode.com\"   # public WS is auto-skipped for txpool\n#   ETHERSCAN_API_KEY=...\n```\n\n### 3. Run\n```bash\npython -m on1builder status check\npython -m on1builder run start\n```\n\n\n\u003e With public RPC/WS, txpool scanning is disabled on purpose (unreliable pending tx support). Provide a private WS endpoint if you want pending tx monitoring.\n\n## Architecture\n\n\u003cimg width=\"6265\" height=\"4722\" alt=\"Arch\" src=\"https://github.com/user-attachments/assets/934d3aaa-fae0-49c2-b28d-e740bedf0e2f\" /\u003e\n\n### Module Dependency Graph\n\n```\ncli/               → config/, core/\ncore/              → config/, engines/, integrations/, monitoring/, persistence/, utils/\nengines/           → config/, integrations/, utils/\nintegrations/      → config/, utils/\nmonitoring/        → config/, integrations/, utils/\npersistence/       → config/, utils/\nutils/             → (standalone, no internal deps except config.loaders)\n```\n\n### Key Design Patterns\n\n| Pattern | Where | Purpose |\n| ------- | ----- | ------- |\n| Singleton | `ExternalAPIManager`, `NonceManager`, `DatabaseInterface`, `NotificationService` | Shared state, connection pooling |\n| Circuit Breaker | `error_recovery.py` | Protect against cascading failures |\n| Async Context Manager | `DatabaseInterface`, `NotificationService` | Guaranteed resource cleanup |\n| Strategy | `StrategyExecutor` | Pluggable MEV strategies |\n| Observer | `TxPoolScanner` → `StrategyExecutor` | Decouple mempool monitoring from execution |\n\n## Configuration Cheat Sheet\n\n| Setting | Description |\n| ------- | ----------- |\n| `WALLET_KEY`, `WALLET_ADDRESS` | Required for signing/monitoring |\n| `RPC_URL_1` | HTTP RPC endpoint (public OK) |\n| `WEBSOCKET_URL_1` | WS endpoint; use private if you want txpool scanning |\n| `ETHERSCAN_API_KEY` | Optional but recommended for ABI/tx metadata |\n| `MIN_PROFIT_ETH` | Profit floor per trade (ETH) |\n| `MAX_GAS_PRICE_GWEI` | Hard gas ceiling |\n| `SUBMISSION_MODE` | `public`, `private`, or `bundle` (relay submission) |\n| `PRIVATE_RPC_URL` | Private RPC endpoint (Flashbots Protect, etc.) |\n| `BUNDLE_RELAY_URL` | Bundle relay endpoint (MEV-Boost/Flashbots) |\n| `SIMULATION_BACKEND` | `eth_call`, `anvil`, or `tenderly` |\n| `SIMULATION_CONCURRENCY` | Max concurrent simulations |\n| `NOTIFICATION_CHANNELS` | `slack,telegram,discord,email` (blank = off) |\n| `ORACLE_FEEDS` | JSON map of chain_id → symbol → Chainlink feed address |\n| `ORACLE_STALE_SECONDS` | Max age (seconds) before oracle price is treated as stale |\n| `MARKET_PRICE_PERSIST_INTERVAL` | Persist price snapshots to DB every N seconds (0 disables) |\n| `STARTUP_TEST_TRANSACTION` | Run a diagnostic self-tx on startup (requires `ALLOW_INSUFFICIENT_FUNDS_TESTS`) |\n| `ALLOW_INSUFFICIENT_FUNDS_TESTS` | Bypass local balance checks for test sends (debug only) |\n\nFull list lives in `.env.example`.\n\nPublicNode endpoints can be used for EVM chains listed in `.env.example`. Non-EVM endpoints\n(Sui, Aptos, Osmosis, Avalanche P/X, Polygon Heimdall) are not supported by ON1Builder.\n\n## Running \u0026 Monitoring\n\n```bash\n# Validate config\npython -m on1builder status check\n\n# Start bot\npython -m on1builder run start\n\n# View logs\ntail -f logs/on1builder.log          # *nix\nGet-Content logs\\\\on1builder.log -Wait  # Windows\n```\n\nHeartbeats report balance tier, pending tx count (0 if txpool scanner is disabled), and memory usage.\n\n## Testing\n\n```bash\n# Run all tests (fast, no external deps)\npython -m pytest tests/ -q\n\n# Run with verbose output\npython -m pytest tests/ -v --tb=short\n\n# Run with coverage report\npython -m pytest tests/ --cov=on1builder --cov-report=html\n\n# Run a specific test file\npython -m pytest tests/test_edge_cases.py -v\n\n# Run live API tests (requires network access)\nRUN_LIVE_API_TESTS=1 python -m pytest tests/test_external_api_integration.py\n```\n\n### Test Categories\n\n| Category | Files | Focus |\n| -------- | ----- | ----- |\n| Smoke | `test_smoke.py` | Package imports, version consistency, resource files |\n| Core Logic | `test_balance_manager.py`, `test_nonce_manager_logic.py`, `test_transaction_manager_logic.py` | Balance tiers, nonce management, TX building |\n| Engines | `test_safety_and_gas_guardrails.py`, `test_logic_behaviors.py` | Safety guards, strategy execution |\n| Monitoring | `test_txpool_end_to_end.py`, `test_market_data_feed_logic.py`, `test_websocket_*.py` | Mempool scanning, market data, WS resilience |\n| API | `test_external_api_logic.py`, `test_external_api_integration.py` | Price feeds, oracle integration |\n| Config | `test_config_manager.py`, `test_validation.py`, `test_cli_commands.py` | Settings loading, validation, CLI |\n| Utils | `test_utils.py`, `test_error_handling.py`, `test_path_helpers.py`, `test_logging_config.py` | Utilities, error handling, DI container |\n| Edge Cases | `test_edge_cases.py` | Boundary values, error paths, constants sanity |\n\n## Development\n\n\u003cimg width=\"15082\" height=\"7425\" alt=\"flow\" src=\"https://github.com/user-attachments/assets/c7838b3d-65f1-4856-ae90-34bb55d82e3e\" /\u003e\n\n```bash\n# Lint and format\nblack --target-version py312 src tests\npython -m compileall -q src tests\n\n# Run full test suite\npython -m pytest tests/ -q\n```\n\nPre-commit hooks are configured in `.pre-commit-config.yaml`.\n\n## Troubleshooting\n\n| Problem | Cause | Solution |\n| ------- | ----- | -------- |\n| `parsimonious` version conflict | `eth-abi` requires `\u003c0.11.0` | Use `parsimonious\u003e=0.10.0,\u003c0.11.0` (already pinned) |\n| txpool scanning silent | Public WS endpoint | Use a private node (Alchemy, Infura, self-hosted) |\n| `ConfigurationError` on start | Missing `.env` values | Run `python -m on1builder status check` to diagnose |\n| Gas estimation fails | Network congestion / bad RPC | Falls back to `default_gas_limit`; check RPC health |\n| Notifications not sending | Channels not configured | Set `NOTIFICATION_CHANNELS` in `.env` |\n| Tests fail with singleton state | Stale singleton between tests | Each test file resets singletons via fixtures |\n\n## Optional Utilities\n\nON1Builder ships a few utilities that are not required for core execution but can be\nintegrated in advanced deployments:\n\n- `src/on1builder/utils/error_recovery.py`: Retry/circuit-breaker helpers and a recovery\n  manager. The TransactionManager now reports failures to this manager for tracking and\n  optional recovery strategies, but most strategies are placeholders by default.\n- `src/on1builder/utils/container.py`: A lightweight DI container for advanced lifecycle\n  management. The core runtime does not use it yet; opt in if you want centralized wiring.\n- `src/on1builder/utils/memory_optimizer.py`: Memory monitoring and GC management for\n  long-running deployments. Tracks process memory and triggers cleanup when thresholds\n  are exceeded.\n\n## Flashloan setup\nYou 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.\n\nTo learn about deploying a flashloan contract, refer to the documentation of the flashloan provider you intend to use (e.g., Aave, dYdX) we recommend  [Aave](https://docs.aave.com/developers/guides/flash-loans)\n\nHere's a basic outline of the steps involved:\n\n1. Choose a Flashloan Provider: Decide which flashloan provider you want to use (e.g., Aave, dYdX).\n2. We recommend using Remix IDE for deploying smart contracts. Open Remix IDE in your web browser.\n3. Create a New File: In Remix, create a new Solidity file (e.g., FlashloanProvider.sol) and write or paste the flashloan contract code.\n4. Compile the Contract: Use the Solidity compiler in Remix to compile your flashloan contract.\n5. Deploy the Contract:\n   - Select the appropriate environment (e.g., Injected Web3 for MetaMask).\n   - Choose the contract you want to deploy.\n   - Click the \"Deploy\" button and confirm the transaction in your wallet.\n6. Note the Contract Address: After deployment, copy the contract address. You'll need to configure this address in .env\n\n## API Keys\n\nThe bot is able to function without API keys, but some features are limited. It's recommended to set up the following free API keys for best experience:\n\n- **Etherscan API Key**: For fetching contract ABIs and transaction metadata. Sign up at [Etherscan](https://etherscan.io/apis).\n- **Tenderly Account**: For advanced simulation backend. Sign up at [Tenderly](https://tenderly.co/).\n- **CoinGecko API Key**: Optional, for additional price data. Sign up at [CoinGecko](https://www.coingecko.com/en/api).\n\n\n## Safety Notes\n\n- Public WS endpoints are auto-skipped for txpool scanning to avoid noisy failures.\n- Price lookups are limited to a small, well-known token set; repeated failures are silenced after blacklisting.\n- Emergency balance tiers keep the bot idle when funds are low.\n- Gas estimation includes a 20% buffer with a hard cap at 30M (Ethereum block gas limit).\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n\n## Disclaimer\n\nUse at your own risk. No warranty. MEV strategies can be volatile and may incur losses. Keep keys safe; never use production keys on public demos.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn0n1%2Fon1builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohn0n1%2Fon1builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohn0n1%2Fon1builder/lists"}