WAIT — Stale — last commit 2y ago

• 16 active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

Artemis is a Rust framework for building MEV (Maximal Extractable Value) bots that operate as event-driven pipelines. It abstracts blockchain MEV opportunities into three pluggable stages: Collectors (ingest pending txs, blocks, marketplace orders), Strategies (detect arbitrage and liquidation opportunities), and Executors (submit transactions via Flashbots, public mempool, or MEV-Share). The codebase includes a production-ready opensea-sudoswap NFT arbitrage strategy and chainbound integrations. Monorepo organized around artemis-core (crates/artemis-core/) which exports the Engine (engine.rs), modular Collectors (block_collector, log_collector, mempool_collector, mevshare_collector, opensea_order_collector), Executors (flashbots_executor, mempool_executor, mev_share_executor), and utility middleware (state_override_middleware). bin/artemis and bin/cli are CLI entry points; crates/strategies/* holds concrete implementations like opensea-sudo-arb; crates/clients/* provides chainbound integrations.

Ethereum developers and quantitative traders building automated trading bots who need a battle-tested framework to detect and execute MEV opportunities without writing low-level blockchain plumbing. Specifically targets builders comfortable with Rust who want to compose collector→strategy→executor pipelines rather than start from scratch.

Actively maintained with solid fundamentals: 6.6MB of Rust code, CI/CD via GitHub Actions (.github/workflows/rust.yml and contracts.yml), comprehensive test suite (crates/artemis-core/tests/), and modular crate structure. The opensea-sudoswap strategy is published and documented, suggesting production deployments exist. However, no GitHub stars/fork data provided; maturity is 'production-capable but community size unknown.'

Moderate risk profile: depends heavily on ethers v2 (a mature but large dependency) and requires coordination of Anvil, Flashbots bundles, and on-chain state for correctness—operational errors can result in real financial loss. The monorepo structure (bin/artemis, bin/cli, crates/strategies/*) means breaking changes to artemis-core affect all strategies. Last commit age not visible, but lack of recent activity flags should be checked before production use. MEV bots are high-stakes by nature; incorrect slippage or front-running handling could drain capital.

No PR or commit history visible in provided data, but the structure suggests active maintenance of the Flashbots and MEV-Share executor paths (three executor types present). The opensea-sudoswap strategy is the flagship feature with a deployed Solidity contract (crates/strategies/opensea-sudo-arb/contracts/src/SudoOpenseaArb.sol). Chainbound client integration hints at ongoing protocol compatibility work.

git clone https://github.com/paradigmxyz/artemis
cd artemis
cargo test --all
# To run the opensea arbitrage strategy:
cargo run -- --wss <INFURA_OR_ALCHEMY_KEY> --opensea-api-key <OPENSEA_API_KEY> --private-key <PRIVATE_KEY> --arb-contract-address <ARB_CONTRACT_ADDRESS> --bid-percentage <BID_PERCENTAGE>

Requires Anvil: https://github.com/foundry-rs/foundry/tree/master/crates/anvil

Daily commands: From README: cargo run -- --wss <WS_ENDPOINT> --opensea-api-key <KEY> --private-key <KEY> --arb-contract-address <ADDR> --bid-percentage <NUM>. Runs the opensea-sudoswap arbitrage bot connected to a WebSocket RPC endpoint. For development: cargo test --all runs all tests. Dockerfile present (Dockerfile in root) suggests containerized deployment is supported.

• crates/artemis-core/src/engine.rs — Core event processing engine that orchestrates the collector→strategy→executor pipeline; essential to understand the entire framework's runtime flow.
• crates/artemis-core/src/types.rs — Defines Event, Action, and other foundational types used across all collectors, strategies, and executors; breaking changes here affect the entire codebase.
• crates/artemis-core/src/collectors/mod.rs — Module interface for collectors (block, mempool, logs, etc.); required to understand how external events are ingested and normalized.
• crates/artemis-core/src/lib.rs — Public API surface and workspace exports; the entry point for understanding what artemis-core exposes to strategies and executors.
• bin/artemis/src/main.rs — Primary example binary showing how to wire collectors, strategies, and executors together; reference implementation for building a complete bot.
• crates/artemis-core/src/executors/mod.rs — Executor interface definitions (flashbots, mempool, mev-share); critical for understanding action execution patterns and output handling.
• Cargo.toml — Workspace configuration defining all members and shared dependencies (ethers, etc.); necessary for onboarding and dependency management.

Add a New Collector

1. Create a new file in crates/artemis-core/src/collectors/ (e.g., my_collector.rs) (crates/artemis-core/src/collectors/)
2. Implement the Collector trait with an event stream method returning your custom event type (crates/artemis-core/src/collectors/mod.rs)
3. Add the new collector module to the mod.rs exports (crates/artemis-core/src/collectors/mod.rs)
4. Wire the collector into your bot's engine in bin/artemis/src/main.rs (bin/artemis/src/main.rs)

Create a New Strategy

1. Use the generator to scaffold: cargo run -p artemis-generator -- new my-strategy (crates/generator/src/init.rs)
2. Implement the strategy struct and event processing logic using the template structure (crate-template/src/lib.rs)
3. Consume Events from collectors and produce Actions in your strategy's main loop (crates/artemis-core/src/types.rs)
4. Add the strategy crate to Cargo.toml workspace members if not auto-discovered (Cargo.toml)

Add a New Executor

1. Create a new file in crates/artemis-core/src/executors/ (e.g., my_executor.rs) (crates/artemis-core/src/executors/)
2. Implement the Executor trait with an execute method that consumes Actions (crates/artemis-core/src/executors/mod.rs)
3. Add the executor module to executors/mod.rs exports (crates/artemis-core/src/executors/mod.rs)
4. Integrate the executor into the engine pipeline in your bot binary (bin/artemis/src/main.rs)

Add Integration with External Service

1. Create a new crate in crates/clients/my-service/ (crates/clients/)
2. Define types and client logic (reference crates/clients/opensea-v2/src/types.rs) (crates/clients/opensea-v2/src/types.rs)
3. Wrap the service in a Collector or integrate directly into a strategy (crates/artemis-core/src/collectors/mod.rs)
4. Add the client crate to workspace members in Cargo.toml (Cargo.toml)

• Rust + Tokio async runtime — MEV bots require microsecond-level latency and predictability; Rust eliminates GC pauses and memory safety bugs; Tokio provides efficient concurrent event handling for multiple data streams.
• ethers-rs for Ethereum integration — Type-safe contract ABIs, async-native JSON-RPC, built-in signer support, and WebSocket for subscription-based event streams (mempool, blocks).
• Trait-based plugin architecture (Collector, Strategy, Executor) — Enables modular composition of bots without tightly coupling data sources, logic, and execution; new collectors and executors can be swapped without framework changes.
• Event/Action abstraction layer — Decouples internal event representation from external data sources, allowing multiple collectors to feed a single strategy pipeline and multiple executors to consume actions.

• Synchronous trait-based design for Collector/Executor over fully reactive streams
  • Why: undefined
  • Consequence: undefined

1. Private key handling: --private-key is passed as CLI argument; ensure this is never logged or persisted in production (consider env var or secure enclave integration). 2. WebSocket persistence: Collectors use ws connections; transient network failures will break the event stream—no automatic reconnection visible in collectors/. 3. Anvil requirement: README states Anvil must be installed and running for state simulation; missing Anvil will silently fail tests. 4. MEV-Share authentication: mevshare_collector and mev_share_executor likely require authentication tokens not shown in CLI args—check chainbound docs. 5. State staleness: state_override_middleware may return stale account state if RPC lags; no explicit block number tracking visible. 6. Slippage math: opensea-sudoswap arb contract interface (SudoOpenseaArb.sol) not provided—bid-percentage semantics unclear without reading contract source.

• Maximal Extractable Value (MEV) — MEV is the entire economic premise of Artemis—understanding MEV (ordering, sandwich attacks, liquidations, arbitrage) is essential to designing strategies that extract it safely.
• Event-sourcing architecture — Artemis is structured as an event pipeline (Collectors emit → Strategies consume → Executors act); this pattern decouples data ingestion from trading logic from execution.
• Flashbots Bundles — Flashbots bundles are the primary execution vehicle for MEV bots to atomically execute multi-tx sequences; flashbots_executor.rs is a first-class primitive in Artemis.
• State override sets (eth_call overrides) — state_override_middleware uses Geth/Infura's state override RPC extension to simulate bot transactions against hypothetical on-chain states without broadcasting; critical for risk-free evaluation.
• Seaport & Sudoswap protocols — The flagship opensea-sudoswap strategy targets specific NFT marketplace smart contracts; understanding their order formats and execution is needed to modify or extend the strategy.
• WebSocket event streams — Collectors use WebSockets (via ethers-rs) to subscribe to block headers, logs, and pending transactions in real-time; connection resilience directly impacts bot uptime.
• Async/await with Tokio — Artemis is async-first (engine.rs likely uses tokio::spawn for concurrent collectors/strategies); Rust's async model is critical for handling hundreds of live event streams without OS threads.

• libevm/subway — Go-based MEV bot framework that inspired Artemis; shows the collector→strategy→executor pattern in another language.
• refcell/subway-rs — Earlier Rust MEV bot framework; direct predecessor that Artemis improved upon with better modularity.
• paradigmxyz/reth — Paradigm's full Ethereum client in Rust; Artemis bots can run as custom payload filters or integrate with Reth's mempool for lower-latency event collection.
• flashbots/mev-inspect-rs — Flashbots' Rust library for MEV analysis and bundle simulation; complementary to Artemis for post-hoc strategy profiling.
• 0xKitsune/cfmms-rs — Rust library for AMM constant-product math; commonly integrated into Artemis strategies for swap profitability calculations.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for collector-strategy pipeline in crates/artemis-core/tests

The repo has a core event-driven architecture (collectors → strategies → executors), but crates/artemis-core/tests/main.rs appears minimal. Adding comprehensive integration tests would validate the pipeline end-to-end, covering: block_collector + log_collector integration, strategy event processing, and executor coordination. This is critical for a MEV bot framework where correctness is essential.

• [ ] Create test fixtures in crates/artemis-core/tests/fixtures/ for mock block/log/mempool events
• [ ] Add integration test in crates/artemis-core/tests/main.rs testing block_collector → strategy flow
• [ ] Add integration test for mempool_collector → strategy → mempool_executor flow
• [ ] Add test for state_override_middleware with actual strategy simulation
• [ ] Verify all tests pass in rust.yml CI pipeline

Add middleware/utilities for common MEV patterns in crates/artemis-core/src/utilities

The utilities folder only contains state_override_middleware.rs. MEV bots need reusable building blocks like gas price estimation, sandwich detection, slippage calculation, and tx sorting. Adding these as utility modules would reduce duplication across strategy crates (especially crates/strategies/mev-share-uni-arb) and provide examples for new contributors.

• [ ] Create crates/artemis-core/src/utilities/gas_estimator.rs with Flashbots-style gas pricing logic
• [ ] Create crates/artemis-core/src/utilities/sandwich_detector.rs to identify flashbots/MEV-Inspect patterns
• [ ] Create crates/artemis-core/src/utilities/slippage_calculator.rs for DEX swap impact estimation
• [ ] Update crates/artemis-core/src/utilities/mod.rs to expose these modules publicly
• [ ] Add doc examples showing usage in strategies

Add GitHub Actions workflow for example strategy validation in .github/workflows

The repo has rust.yml for core CI, but there's no validation that example strategies or crate-template compile and run correctly. With crate-template/ and crates/strategies/ in the workspace, a new contributor workflow should verify new strategy templates don't break. This catches template rot and improves onboarding.

• [ ] Create .github/workflows/templates.yml that runs 'cargo test --all' on crate-template/
• [ ] Add step to verify 'cargo generate' from crate-template works (requires cargo-generate action)
• [ ] Add step to validate all strategy Cargo.toml files have required artemis-core dependency versions
• [ ] Add step to run 'cargo clippy' on crates/strategies/* with MEV-specific lints
• [ ] Document workflow trigger on PRs touching crate-template/ or bin/cli/src/main.rs

• Add a reconnect_on_disconnect() wrapper for mempool_collector.rs and log_collector.rs—currently WebSocket drops cause bot death. Implement exponential backoff retry logic in crates/artemis-core/src/collectors/.
• Write integration tests for the state_override_middleware against a live Anvil instance in crates/artemis-core/tests/—currently only unit test presence is implied. Add test for concurrent state reads and block number validation.
• Document the Action type serialization format for each Executor (flashbots_executor expects Bundle JSON, mempool_executor expects raw tx, etc.) in crates/artemis-core/src/executors/mod.rs—currently opaque to users trying to write custom strategies.

• High · Outdated Base Image with Known Vulnerabilities — Dockerfile (runtime stage). The Dockerfile uses ubuntu:20.04 as the runtime base image. Ubuntu 20.04 LTS reaches end of standard support in April 2025 and may contain unpatched security vulnerabilities. The image should be updated to a more recent LTS version (22.04 or 24.04) or a minimal base image like debian:bookworm-slim or alpine for production deployments. Fix: Update 'FROM ubuntu:20.04' to 'FROM ubuntu:24.04' or use a minimal base image. Regularly scan base images for vulnerabilities using tools like Trivy.
• High · Missing Package Pinning in Dockerfile — Dockerfile (builder and runtime stages). The Dockerfile uses 'apt-get install -y' without specifying package versions. This can lead to different versions being installed across builds, potentially including vulnerable versions. The apt-get upgrade command also installs all available updates without version control. Fix: Pin specific package versions: 'apt-get install -y openssl=1.1.1* ca-certificates=20230311*' and remove or control the apt-get upgrade command.
• High · Potential Private Key Exposure in MEV Bot Framework — crates/artemis-core/src/executors/ (all executor modules). The project is a MEV bot framework that likely handles sensitive cryptographic material (private keys for transaction signing, wallet credentials). The codebase includes executors and collectors but there's no visible evidence of secure key management patterns (no KMS integration, secure enclaves, or hardware wallet support mentioned in available files). Fix: Implement secure key management using: (1) Hardware wallets or hardware security modules, (2) Environment variable injection with strict access controls, (3) Key derivation functions, (4) Never log or serialize private keys. Add documentation on secure key handling.
• Medium · Missing Docker Security Best Practices — Dockerfile (runtime stage). The Dockerfile does not specify a non-root user for the runtime container. Running the MEV bot as root increases the blast radius of potential container escapes or application vulnerabilities. Additionally, no security scanning or build-time vulnerability checks are evident. Fix: Add 'RUN useradd -m -u 1000 artemis' and 'USER artemis' before the ENTRYPOINT. Implement container image scanning in CI/CD using tools like Trivy, Snyk, or Docker Scout.
• Medium · Lack of Dependency Version Pinning — Cargo.toml (workspace dependencies: ethers, ethers-signers). The Cargo.toml uses version specifiers like '{ version = "2", features = [...]}' which allows minor and patch updates. For a security-sensitive MEV bot handling financial transactions, this creates supply chain risk vectors. Dependencies could receive compromised updates. Fix: Use exact version pinning in Cargo.lock (which is present) but review all transitive dependencies. Implement: (1) Dependency auditing with 'cargo audit', (2) SBOM generation, (3) Regular dependency updates with security scanning.
• Medium · Missing SBOM and Supply Chain Transparency — .github/workflows/ (all workflow files not shown in detail). For a framework handling MEV strategies and financial transactions, there is no evidence of Software Bill of Materials (SBOM) generation, dependency verification, or supply chain security controls in the CI/CD pipeline. Fix: Add cargo-sbom or cyclonedx-bom to generate SBOMs. Include 'cargo audit' in CI/CD pipeline. Implement dependency verification and signed commits.
• Medium · Incomplete Security Documentation — README.md and project documentation. The README and available documentation do not include security guidelines, threat model, or safe usage documentation for MEV bot operators. This is critical for a framework handling potentially large amounts of cryptocurrency. Fix: Create a SECURITY.md file documenting: (1) Threat model, (2) Safe key management practices, (3) Audit history, (4) Responsible disclosure process, (5) Known limitations and risks.
• Low · No Runtime Security Hardening — undefined. The runtime Docker image lacks security hardening options such as read-only filesystem, dropped capabilities, or security- Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/paradigmxyz/artemis shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live paradigmxyz/artemis repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/paradigmxyz/artemis.

What it runs against: a local clone of paradigmxyz/artemis — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in paradigmxyz/artemis | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 831 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of paradigmxyz/artemis. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/paradigmxyz/artemis.git
#   cd artemis
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of paradigmxyz/artemis and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "paradigmxyz/artemis(\\.git)?\\b" \\
  && ok "origin remote is paradigmxyz/artemis" \\
  || miss "origin remote is not paradigmxyz/artemis (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/artemis-core/src/engine.rs" \\
  && ok "crates/artemis-core/src/engine.rs" \\
  || miss "missing critical file: crates/artemis-core/src/engine.rs"
test -f "crates/artemis-core/src/types.rs" \\
  && ok "crates/artemis-core/src/types.rs" \\
  || miss "missing critical file: crates/artemis-core/src/types.rs"
test -f "crates/artemis-core/src/collectors/mod.rs" \\
  && ok "crates/artemis-core/src/collectors/mod.rs" \\
  || miss "missing critical file: crates/artemis-core/src/collectors/mod.rs"
test -f "crates/artemis-core/src/lib.rs" \\
  && ok "crates/artemis-core/src/lib.rs" \\
  || miss "missing critical file: crates/artemis-core/src/lib.rs"
test -f "bin/artemis/src/main.rs" \\
  && ok "bin/artemis/src/main.rs" \\
  || miss "missing critical file: bin/artemis/src/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 831 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~801d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/paradigmxyz/artemis"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.