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.

GO — Healthy across all four use cases

• 16 active contributors
• Distributed ownership (top contributor 28% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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 ≤ 824 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 824 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~794d)"
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).

Artemis is a Rust framework for building MEV (Maximal Extractable Value) bots that process blockchain events through a three-stage pipeline: Collectors ingest external events (pending transactions, blocks, marketplace orders), Strategies analyze them for opportunities, and Executors submit the resulting transactions or orders. It's designed for high-performance sandwich attacks, NFT arbitrage, and cross-exchange trading. Monorepo with workspace root at Cargo.toml: crates/artemis-core/ contains the event engine and base collectors/executors, bin/artemis/ is the main binary, crates/strategies// contains pluggable strategies (e.g., opensea-sudo-arb), and crates/clients/ wrap external services (Chainbound Fiber, MEV-Share). Each crate is independently versioned but shares workspace dependencies.

Blockchain developers and trading engineers building MEV strategies who need a modular, fast framework to prototype and deploy bots against Ethereum. Specifically developers comfortable with Rust who want to avoid rewriting event pipelines and blockchain interaction code for each new strategy.

Actively developed with a solid foundation: includes CI/CD via GitHub Actions (rust.yml, contracts.yml), test suite in crates/artemis-core/tests/, working example strategies (opensea-sudo-arb), and Docker support. However, it appears to be a framework still in active feature development rather than a stable 1.0+ release—the codebase is organized but relatively young.

Moderate risk: depends heavily on ethers-rs 2.x for Ethereum interaction (a known moving target), requires external services (Infura/Alchemy for RPC, Flashbots for execution, OpenSea API), and MEV strategies are inherently adversarial (regulatory and technical risks). The monorepo has multiple strategy crates that may not be equally maintained.

The repo structure suggests active development on strategy implementations (OpenSea/Sudoswap NFT arb) and collector diversity (mempool, blocks, logs, MEV-Share, OpenSea marketplace orders visible in crates/artemis-core/src/collectors/). GitHub Actions workflows indicate CI is running on all commits; specific commit recency not available but the breadth of collectors suggests ongoing iteration.

git clone https://github.com/paradigmxyz/artemis
cd artemis
cargo test --all
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>

Note: Requires Anvil installed for testing (foundry-rs/foundry).

Daily commands: For the main opensea-sudoswap strategy: cargo run --bin artemis -- --wss <WSS_URL> --opensea-api-key <KEY> --private-key <HEX> --arb-contract-address <0x...> --bid-percentage <PERCENT>. For tests: cargo test --all. For CLI (separate binary): cargo run --bin cli -- <args>.

• crates/artemis-core/src/engine.rs — Core event processing pipeline engine that orchestrates collectors, strategies, and executors—the architectural heart of the framework.
• crates/artemis-core/src/types.rs — Defines fundamental types (Event, Action, etc.) that all components must understand and implement.
• crates/artemis-core/src/collectors/mod.rs — Collector trait and registry—defines the interface all data sources must implement to feed events into the pipeline.
• crates/artemis-core/src/lib.rs — Public API surface; defines what users and extensions import when building bots on Artemis.
• bin/artemis/src/main.rs — Reference implementation and entry point showing how to assemble collectors, strategies, and executors into a working bot.
• Cargo.toml — Workspace configuration defining all member crates and shared dependencies; essential for understanding project structure.
• crates/generator/src/lib.rs — Code generation tooling that bootstraps new strategies and crates following framework conventions.

Add a New Collector (Event Source)

1. Define your collector struct in a new file under crates/artemis-core/src/collectors/ (crates/artemis-core/src/collectors/your_collector.rs)
2. Implement the Collector trait from types.rs, mapping external events to internal Event types (crates/artemis-core/src/collectors/your_collector.rs)
3. Register your collector in the mod.rs exports and the collector registry in engine.rs (crates/artemis-core/src/collectors/mod.rs)
4. Instantiate and add your collector in the engine setup within bin/artemis/src/main.rs (bin/artemis/src/main.rs)

Add a New Strategy

1. Use the generator CLI to scaffold: cargo run --bin cli -- generate strategy --name my_strategy (bin/cli/src/main.rs)
2. Implement the Strategy trait in crates/strategies/my_strategy/, listening to Event types and producing Actions (crates/strategies/my_strategy/src/lib.rs)
3. Reference the example arbitrage strategy for pattern: crates/strategies/mev-share-uni-arb (crates/strategies/mev-share-uni-arb/src/lib.rs)
4. Register and instantiate your strategy in the engine within bin/artemis/src/main.rs (bin/artemis/src/main.rs)

Add a New Executor (Action Submission)

1. Create a new executor file in crates/artemis-core/src/executors/ (crates/artemis-core/src/executors/my_executor.rs)
2. Implement the Executor trait, converting Actions to domain-specific submissions (txs, bundles, orders, etc.) (crates/artemis-core/src/executors/my_executor.rs)
3. Export and register in crates/artemis-core/src/executors/mod.rs (crates/artemis-core/src/executors/mod.rs)
4. Initialize in the engine pipeline and pass to the orchestrator in bin/artemis/src/main.rs (bin/artemis/src/main.rs)

Add a New External Service Client

1. Create a new crate under crates/clients/my_service/ with Cargo.toml and src/lib.rs (crates/clients/my_service/Cargo.toml)
2. Implement the HTTP client and type definitions following the OpenSea client pattern (crates/clients/my_service/src/client.rs)
3. Export public API in src/lib.rs and document in README.md (crates/clients/my_service/src/lib.rs)
4. Add to workspace members in root Cargo.toml and depend on it from collectors or executors (Cargo.toml)

• Rust — Type safety and performance critical for MEV bots handling high-frequency events and large financial transactions; compile-time guarantees prevent memory bugs.
• ethers-rs — Ethereum client library providing RPC interaction, transaction signing, and contract ABIs; industry standard for Rust Ethereum development.
• Event-driven async pipeline — MEV opportunities are time-sensitive; async/await allows handling thousands of pending txs and block events concurrently without blocking.
• Modular collector/strategy/executor architecture — Decouples data sources, opportunity logic, and submission domains; allows mixing strategies (e.g., run 3 arbs + 2 liquidations in parallel).
• Flashbots, MEV-Share integration — Enables MEV sharing and bundle privacy; allows bots to participate in permissioned MEV extraction without naively leaking to public mempool.

• Single-threaded event loop (engine.rs) rather than multi-threaded strategy execution

  • Why: Simplifies ordering guarantees and state consistency across strategies operating on the same event stream.
  • Consequence: CPU-bound strategies may slow other strategies; users must shard if ultra-high throughput needed.

• Trait-based plugin architecture (Collector, Strategy, Executor traits) instead of macro-based configuration

  • Why: Provides full Rust language ergonomics and type checking; users write normal structs/impls rather than DSLs.
  • Consequence: Slightly more boilerplate per component, but better IDE support and compile-time safety.

• Event types are enum-based (internal representation) rather than duck-typed dynamic dispatch

  • Why: Ensures type safety and pattern matching for all event handling code.
  • Consequence: Adding new event types requires changes to types.rs; not infinitely extensible without enum variants.

• Separate executor for each domain (mempool, Flashbots, MEV-Share) rather than a unified executor

  • Why: Each domain has different submission protocols and semantics; cleaner separation of concerns.
  • Consequence: Bot code must know which

1. Requires external keys: WSS endpoint (Infura/Alchemy), OpenSea API key (if using that strategy), private key with ETH for gas—bot will fail silently if these are missing or incorrect. 2. Anvil required for tests: cargo test will fail if foundry-rs/Anvil is not installed; see README. 3. Strategy-specific contract deployment: opensea-sudo-arb requires you to deploy SudoOpenseaArb.sol and pass its address via CLI; addresses are not hardcoded. 4. ethers 2.x breaking changes: if upgrading or adding ethers crates, ensure all workspace members use same version to avoid resolver conflicts. 5. Async runtime assumption: no explicit main setup visible—likely using tokio::main macro, so runtime initialization is hidden.

• MEV (Maximal Extractable Value) — Core motivation for Artemis; understanding what MEV is (reordering, sandwich attacks, liquidations, arbitrage) explains why the event pipeline is designed this way and what opportunities strategies hunt for
• Event-Driven Architecture / Reactive Streams — Artemis organizes as Collector → Strategy → Executor; each stage is event-driven (new block arrives, trigger strategy, emit action). Rust's async/await and trait-based design make this pattern explicit.
• Flashbots Bundles & MEV Relay — crates/artemis-core/src/executors/flashbots_executor.rs submits bundles privately to Flashbots relay instead of mempool; critical to understand for avoiding front-running and sandwich attacks in MEV bot execution
• RLP Encoding & Transaction Serialization — Collectors parse raw Ethereum transactions (mempool, blocks); Executors must serialize them for relay/mempool. ethers handles this but understanding RLP (Recursive Length Prefix) helps debug transaction edge cases.
• State Override (Eth RPC eth_call) — crates/artemis-core/src/utilities/state_override_middleware.rs wraps RPC calls with state overrides to simulate strategy execution before submitting onchain; critical for avoiding loss-making transactions
• WebSocket vs HTTP RPC Streaming — Collectors use WebSocket subscriptions (ws feature in ethers) for real-time block/log streaming; slower HTTP would miss MEV opportunities. Artemis requires WSS endpoints (Infura, Alchemy) for this reason.
• Atomic Swaps & Cross-Market Arbitrage — opensea-sudo-arb strategy (only full example) finds price discrepancies between NFT markets and executes atomic swaps; concept of sandwich-free execution via contract logic, not RPC ordering, is non-obvious in MEV bots

• libevm/subway — Original MEV sandwich framework Artemis is inspired by; shows earlier Rust approach to MEV bot architecture
• refcell/subway-rs — Direct Rust predecessor; helps understand Artemis's design decisions and borrowed patterns for event processing
• 0xKitsune/cfmms-rs — Companion library for AMM state tracking and swap simulation; commonly used with Artemis strategies for DeFi opportunities
• paradigmxyz/reth — Paradigm's Ethereum execution client; provides deeper integration points for state queries and MEV insights that Artemis strategies rely on
• onbjerg/ethers-flashbots — Flashbots Rust SDK that Artemis wraps via crates/artemis-core/src/executors/flashbots_executor.rs for bundle submission

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-executor pipeline in artemis-core

The crates/artemis-core/tests/main.rs file exists but is likely minimal. There are no visible unit tests for individual collectors (block_collector.rs, log_collector.rs, mempool_collector.rs, mevshare_collector.rs, opensea_order_collector.rs) or executors (flashbots_executor.rs, mempool_executor.rs, mev_share_executor.rs). Adding comprehensive tests would improve reliability of core pipeline components and serve as reference implementations for strategy developers.

• [ ] Create test cases in crates/artemis-core/tests/main.rs for each collector in src/collectors/
• [ ] Add unit tests verifying event transformation logic in each collector module
• [ ] Create integration tests for executor modules, including error handling paths
• [ ] Add tests for the engine.rs event loop with mock collectors and executors
• [ ] Document expected behavior in test comments for contributor reference

Add GitHub Actions workflow for contract compilation and type generation

The .github/workflows/contracts.yml file exists but there's no corresponding CI for contract compilation or ABI type generation. Given that MEV bots depend heavily on contract interactions and the ethers crate generates Rust bindings, a dedicated workflow would catch ABI changes, validate contract compilation, and ensure generated types don't break downstream bot code.

• [ ] Create or enhance .github/workflows/contracts.yml with solc compilation step
• [ ] Add ethers-contract-abigen step to regenerate Rust bindings from ABIs
• [ ] Configure workflow to fail if generated types differ from committed versions
• [ ] Add step to validate all strategy crates compile against generated types
• [ ] Document ABI update process in README.md or CONTRIBUTING guide

Implement configuration schema validation and example configs for core strategies

The crate-template/src/lib.rs and individual strategy directories (e.g., crates/strategies/mev-share-uni-arb/) lack documented configuration schemas and example config files. New contributors cannot easily understand required vs optional parameters for collectors, strategies, and executors. Adding validated configuration structures with example TOML/JSON files would lower the barrier to entry.

• [ ] Create a new crates/artemis-core/src/config.rs module with serde-based config structs
• [ ] Add configuration validation logic for each collector type in src/collectors/
• [ ] Add configuration validation logic for each executor type in src/executors/
• [ ] Create example config files: examples/config.example.toml and examples/config.example.json
• [ ] Update crate-template/src/lib.rs with sample configuration usage and validation
• [ ] Add schema documentation in a new CONFIGURATION.md file with field descriptions

• Add unit tests for crates/artemis-core/src/utilities/state_override_middleware.rs—file exists but no corresponding test file visible; would benefit from tests covering state override edge cases (missing account, storage slot conflicts, etc.).
• Implement a block_collector integration test in crates/artemis-core/tests/main.rs—currently sparse; add test demonstrating collector receives Anvil-mined blocks and converts to internal Event type.
• Add Collector and Executor trait documentation examples to crates/artemis-core/src/collectors/mod.rs and src/executors/mod.rs—patterns are inferred from impl examples (flashbots_executor.rs) but not explicitly documented; add doc-comment examples showing minimal trait impl.

The Artemis MEV bot framework has moderate security posture with several areas requiring attention. The primary concerns are: (1) use of outdated Ubuntu 20.04 base image with known vulnerabilities; (2) loose dependency version pinning allowing un

• High · Outdated Base Image with Known Vulnerabilities — Dockerfile (runtime stage). The Dockerfile uses ubuntu:20.04 as the runtime base image, which is EOL (End of Life) and contains multiple known CVEs. Ubuntu 20.04 reached standard support end on April 2025, and using outdated base images introduces security risks including unpatched vulnerabilities in system libraries. Fix: Upgrade to a more recent and actively maintained Ubuntu LTS version (e.g., ubuntu:24.04 or ubuntu:22.04). Alternatively, consider using distroless images for minimal attack surface.
• High · Missing pinned dependency versions — Cargo.toml (workspace.dependencies). The Cargo.toml uses flexible version specifications for critical dependencies (e.g., ethers = "2"). This allows automatic updates to minor and patch versions, which could introduce breaking changes or security issues without explicit review. The workspace dependencies lack specific version pinning. Fix: Pin all dependencies to specific versions using exact version syntax (e.g., ethers = "2.0.14") or use = operator. Implement a dependency audit process and regular security updates through controlled mechanisms.
• Medium · Missing security headers and isolation in Docker build — Dockerfile (builder stage). The Dockerfile runs apt-get operations without security options like --no-install-recommends, which increases image size and attack surface. Additionally, there's no explicit cleanup of apt cache, and the builder image is not explicitly set to a hardened base. Fix: Add --no-install-recommends to apt-get install, clean apt cache with 'apt-get clean && rm -rf /var/lib/apt/lists/*', and consider using a hardened base image or implementing multi-stage builds with proper layer cleanup.
• Medium · No explicit security context or runtime user in Docker — Dockerfile (runtime stage). The runtime stage does not specify a non-root user for executing the binary. Running containerized applications as root increases the impact of potential code execution vulnerabilities. Fix: Create a non-root user and specify it with USER directive before ENTRYPOINT. Example: 'RUN useradd -m -u 1000 appuser && USER appuser'
• Medium · Missing HEALTHCHECK directive — Dockerfile. The Dockerfile lacks a HEALTHCHECK instruction, which could allow the container to continue running even if the application crashes or becomes unresponsive. Fix: Add a HEALTHCHECK directive to monitor the application's health status. Example: 'HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:8080/health || exit 1' (adjust based on actual health endpoint).
• Low · Potential hardcoded configuration in template crate — crate-template/src/lib.rs. The crate-template directory structure suggests template generation for new crates. If templates contain hardcoded secrets, credentials, or insecure defaults, they could propagate vulnerabilities to generated projects. Fix: Review template files to ensure they don't contain any hardcoded secrets, API keys, or insecure defaults. Use placeholder values and clear documentation for configuration.
• Low · No explicit dependency audit mechanism — Repository configuration (GitHub Actions, Cargo.toml). The repository lacks visible evidence of automated dependency auditing (e.g., cargo-audit, dependabot configuration). This could allow vulnerable transitive dependencies to slip through. Fix: Implement automated dependency scanning with 'cargo audit' in CI/CD pipeline and enable GitHub Dependabot or similar tools for continuous vulnerability monitoring.
• Low · Missing source code integrity verification — Cargo.lock, Dockerfile builder stage. The Cargo.lock file is present but there's no evidence of signature verification or checksums for downloaded dependencies in the build process. Fix: Ensure Cargo.lock is committed to the repository and use cargo verify-data to validate package integrity. Consider implementing supply chain security best practices.

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

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

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