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/stacks-network/stacks-core 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 the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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 stacks-network/stacks-core repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/stacks-network/stacks-core.

What it runs against: a local clone of stacks-network/stacks-core — 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 stacks-network/stacks-core | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of stacks-network/stacks-core. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/stacks-network/stacks-core.git
#   cd stacks-core
#
# 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 stacks-network/stacks-core and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "clarity/src/libclarity.rs" \\
  && ok "clarity/src/libclarity.rs" \\
  || miss "missing critical file: clarity/src/libclarity.rs"
test -f "stackslib/src" \\
  && ok "stackslib/src" \\
  || miss "missing critical file: stackslib/src"
test -f "clarity/src/vm/analysis/mod.rs" \\
  && ok "clarity/src/vm/analysis/mod.rs" \\
  || miss "missing critical file: clarity/src/vm/analysis/mod.rs"
test -f "clarity-types/src/lib.rs" \\
  && ok "clarity-types/src/lib.rs" \\
  || miss "missing critical file: clarity-types/src/lib.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/stacks-network/stacks-core"
  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).

stacks-core is the reference Rust implementation of the Stacks blockchain, a Layer 2 solution that anchors to Bitcoin for security and enables smart contracts via the Clarity language using Proof of Transfer (PoX) consensus. It allows decentralized apps to run on Bitcoin without modifying the base layer, with miners competing for blocks through Bitcoin-based leader election. Cargo monorepo with 10 core workspace members: stackslib (main blockchain implementation), stacks-common (shared utilities), clarity (smart contract interpreter), stacks-node (node binary), libsigner (signer infrastructure), stacks-signer (signing service), plus contrib binaries (stacks-inspect, clarity-cli, stacks-cli). Profile.dev optimizes at opt-level=1 with opt-level=3 for dependencies; release uses fat LTO with debug symbols; release-lite uses thin LTO for lower-RAM environments.

Blockchain developers building on or contributing to Stacks, Bitcoin DeFi protocol engineers, Clarity smart contract developers, and node operators running Stacks validators or miners. Also relevant for researchers studying alternative consensus mechanisms and Layer 2 scaling solutions.

Production-ready and actively maintained. The codebase is substantial (23M+ lines of Rust), has comprehensive CI/CD workflows (.github/workflows/ with bitcoin-tests, epoch-tests, p2p-tests, standalone-tests), uses cargo nextest for parallel testing, and follows standard Rust release practices with release-build and release-docker workflows. Regular releases are tracked in the repository.

Relatively low risk for a blockchain project at this maturity level. The dependency surface is controlled via workspace.dependencies with pinned versions (e.g., ed25519-dalek 2.1.1, rusqlite 0.31.0), and there's strict CI enforcement (clippy, rustfmt, changelog checks). Main risks: blockchain consensus changes require careful coordination, PoX mining economics are complex, and the large codebase makes code review critical—single breaking consensus bugs could fork the network.

Active development on PoX consensus refinements, Bitcoin integration tests (bitcoin-tests.yml), p2p networking improvements (p2p-tests.yml), Clarity language features, and signer infrastructure (separate stacks-signer crate). Multiple specialized test workflows suggest ongoing work on epoch mechanics, network testing, and potentially sBTC integration (sbtc-tests.yml visible in workflows).

git clone --depth=1 https://github.com/stacks-network/stacks-core.git
cd stacks-core
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
rustup component add rustfmt
rustup update
cargo build --release

Daily commands: Testnet follower (default): cargo run --bin stacks-node -- start --config ./sample/conf/testnet-follower-conf.toml. Unit tests: cargo test testnet -- --test-threads=1 (sequential) or cargo nextest run (parallel, faster). Release optimized: cargo build --release (fat LTO, ~1+ GB intermediate artifacts) or cargo build --profile release-lite (thin LTO for <16GB RAM systems).

• Cargo.toml — Workspace root configuration defining all member crates and shared dependencies; essential for understanding project structure and build requirements.
• clarity/src/libclarity.rs — Core Clarity VM entry point; primary interface for smart contract execution and analysis in the Stacks blockchain.
• stackslib/src — Main blockchain logic library (inferred from workspace); contains consensus, transaction processing, and PoX mining implementation.
• clarity/src/vm/analysis/mod.rs — Contract analysis and type checking module; critical for Clarity language semantic validation before execution.
• clarity-types/src/lib.rs — Type system definitions and serialization; foundational for all Clarity smart contract type safety across the codebase.
• .github/workflows/ci.yml — Primary CI pipeline definition; shows test expectations, build requirements, and integration test patterns contributors must maintain.
• README.md — Project overview explaining Stacks as a PoX-based Bitcoin L2 with Clarity smart contracts; context for all technical decisions.

Add a new Clarity analysis check

1. Create new analysis module in clarity/src/vm/analysis/ (clarity/src/vm/analysis/mod.rs)
2. Implement trait for new checker (e.g., arithmetic_checker pattern) (clarity/src/vm/analysis/arithmetic_checker/mod.rs)
3. Register checker in main analysis flow (clarity/src/vm/analysis/mod.rs)
4. Add test cases in checker module (clarity/src/vm/analysis/arithmetic_checker/tests.rs)

Add a new Clarity built-in function

1. Define function signature and cost in clarity-types type system (clarity-types/src/types/mod.rs)
2. Implement execution logic in clarity/src/vm/ (clarity/src/libclarity.rs)
3. Add type analysis rule for the new function (clarity/src/vm/analysis/mod.rs)
4. Add test in clarity test suite (in clarity/src/vm/tests/) (clarity/src/libclarity.rs)

Add a new blockchain validation rule

1. Define rule in stackslib consensus module (stackslib/Cargo.toml)
2. Implement validation in block/transaction processor (stackslib/Cargo.toml)
3. Update CI test harness to verify rule (.github/workflows/bitcoin-tests.yml)
4. Add integration test in test suite (.github/workflows/stacks-core-tests.yml)

Add a new PoX parameter or behavior

1. Update PoX locking logic and parameter handling (pox-locking/Cargo.toml)
2. Update reward distribution calculations (pox-locking/Cargo.toml)
3. Add Bitcoin integration test for new behavior (.github/workflows/bitcoin-tests.yml)
4. Document in CHANGELOG.md (CHANGELOG.md)

• Rust — Memory safety without GC; essential for blockchain security-critical code and performance-sensitive consensus operations
• Clarity Language — Designed specifically for Bitcoin-secured smart contracts; static analysis prevents entire classes of exploits (reentrancy, overflow)
• Proof of Transfer (PoX) — Bitcoin-backed consensus; leverages Bitcoin security without modifying Bitcoin, enabling STX mining via BTC lock-ups
• Ed25519-Dalek — High-performance, constant-time signature operations; critical for transaction validation in PoX consensus
• Docker multi-stage builds — Reproducible node deployments across Alpine, Debian, and specialized test environments (Bitcoin Core integration)

• Clarity as non-Turing-complete, linear type system

  • Why: Prevents infinite loops, reentrancy attacks, and unpredictable execution costs at analysis time
  • Consequence: More limited smart contract expressiveness than Solidity/EVM; some patterns require workarounds

• Anchor to Bitcoin for every Stacks block

  • Why: Inherits Bitcoin's 51% attack cost; Bitcoin finality applies directly to Stacks
  • Consequence: Stacks block time depends on Bitcoin (≈10 min); higher latency than pure L1 chains

• Separate Stacks blockchain from Bitcoin

  • Why: No Bitcoin protocol changes; full backwards compatibility; clean separation of concerns
  • Consequence: Requires bridge/relay infrastructure and increases operational complexity

• StackerDB for signer state distribution

  • Why: Decentralized coordination without additional consensus; Byzantine fault tolerance
  • Consequence: Requires careful quorum and liveness assumptions; eventual consistency model

• Stacks Core does not implement EVM compatibility—Clarity is the sole smart contract language
• Does not modify Bitcoin consensus rules or transaction format
• Does not provide exchange rate oracle—relies on external price feeds
• Not a general-purpose data availability layer—only for Stacks contract state
• Does not implement light client protocol for SPV (full node validation required)

Windows testing: Many tests fail on Windows due to parallelism; run tests individually (--test-threads=1) or use WSL2. RAM requirements: Release builds with fat LTO need >16 GB RAM; use --profile release-lite or opt-level=1 for dev builds if constrained. Bitcoin dependency: Integration tests (bitcoin-tests.yml) require a Bitcoin regtest node running; local testing needs bitcoind configuration. Testnet config: sample/conf/testnet-follower-conf.toml is provided, but custom networks require understanding PoX payout addresses and Bitcoin anchor block heights. Nix builds: Experimental .github/nix-check.yml workflow suggests flake.nix may exist but isn't shown—check if building on NixOS. Consensus forks: Epoch-based protocol upgrades (visible in epoch-tests.yml) mean older binaries may not validate newer blocks—always keep nodes updated.

• Proof of Transfer (PoX) — stacks-core's core consensus mechanism—miners commit Bitcoin to earn STX rewards instead of burning energy, directly anchoring Stacks security to Bitcoin's hashpower
• Clarity Smart Contract Language — The only smart contract language on Stacks with formal verification properties; understanding Clarity execution is essential for protocol safety and feature changes
• Layer 2 Blockchain Anchoring — stacks-core commits block headers and state roots to Bitcoin (vs. separate consensus)—this architecture enables security inheritance while maintaining fast settlement
• Bitcoin Regtest (Regression Test Mode) — Local Bitcoin network used in bitcoin-tests.yml for consensus testing without hitting mainnet—developers must understand regtest block generation and timing for integration work
• Epoch-based Protocol Upgrades — stacks-core coordinates consensus-rule changes via activation epochs (visible in epoch-tests.yml)—critical for hard/soft fork coordination across all nodes and miners
• Memory-mapped SQLite & Jemalloc — stacks-core uses rusqlite with jemalloc allocator for persistent state and performance tuning—understanding block state persistence and memory layout matters for scalability optimization
• PoX Stacking & STX Locking — Core economic incentive: STX holders lock tokens to earn Bitcoin; stacks-core validates locking contracts and calculates payout schedules—visible in pox-locking crate

• stacks-network/stacks — Original reference specification for Stacks protocol—stacks-core is its canonical Rust implementation
• bitcoin/bitcoin — Base layer security anchor; Stacks miners write blocks secured by Bitcoin's consensus—integration tests likely hook into Bitcoin regtest
• hirosystems/clarinet — Clarity development toolkit and testing framework—developers use this alongside stacks-core to write and test smart contracts
• stacks-network/sbtc — sBTC (Stacks Bitcoin) bridge protocol; visible in sbtc-tests.yml workflow—enables Bitcoin assets on Stacks
• hirosystems/stacks-js — JavaScript/TypeScript SDK for interacting with Stacks blockchain—mirrors functionality of stacks-core RPC endpoints

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 clarity-types error handling across all error modules

The clarity-types crate has error modules (analysis.rs, ast.rs, cost.rs, lexer.rs) but lacks comprehensive integration tests. These errors are critical for the Clarity language compiler frontend. Adding tests would catch regressions in error reporting and improve contributor confidence when modifying error handling paths.

• [ ] Create clarity-types/src/errors/tests.rs with test cases for each error type in analysis.rs, ast.rs, cost.rs, and lexer.rs
• [ ] Add round-trip serialization tests for error types with serde (already in workspace dependencies)
• [ ] Create fixture-based tests for realistic error scenarios (e.g., malformed expressions, type mismatches)
• [ ] Update clarity-types/Cargo.toml to enable test features if needed, and add to CI workflow .github/workflows/stacks-core-tests.yml

Add GitHub Actions workflow for clarity-types and clarity crate isolation testing

The repo has many workflows (.github/workflows/*.yml) but no dedicated workflow for testing the clarity-types and clarity crates in isolation. Since these are foundational crates used across the workspace, a focused CI job would catch dependency or API breakage early and speed up feedback for language changes.

• [ ] Create .github/workflows/clarity-tests.yml that runs 'cargo test --workspace --exclude stacks-node' for clarity and clarity-types
• [ ] Add clippy and rustfmt checks specific to these crates to catch style issues early
• [ ] Include a 'cargo check --all-features' step for both crates to validate feature combinations
• [ ] Set it to trigger on changes to clarity/, clarity-types/ and Cargo.toml files

Document and add tests for workspace dependency pinning rationale in Cargo.toml

The Cargo.toml pins several critical dependencies (ed25519-dalek, rusqlite, slog, etc.) in [workspace.dependencies] but lacks documentation explaining why each version is pinned or what constraints exist. This is especially important for security-critical deps like ed25519-dalek and rusqlite. Adding documentation and MSRV (minimum supported Rust version) validation tests would help contributors understand upgrade risks.

• [ ] Create DEPENDENCY_VERSIONS.md documenting the reason each [workspace.dependencies] entry is pinned (security, API stability, MSRV compatibility, etc.)
• [ ] Add a GitHub Actions workflow .github/workflows/dependency-audit.yml that runs 'cargo audit' and 'cargo update --dry-run' to flag outdated or vulnerable deps
• [ ] Add a build script in build.rs or CI to verify MSRV (Rust version) compatibility for all workspace members
• [ ] Reference this new documentation in CONTRIBUTING.md for dependency upgrade guidelines

• Add documentation examples for libsigner API in libsigner/README.md showing how to sign transactions and participate in consensus—currently no high-level developer guide visible in the file list.
• Write integration test harness for stacks-inspect tool in contrib/stacks-inspect/tests/ demonstrating how to inspect block state without running a full node—useful for debugging and education.
• Create TypeScript bindings generator from clarity/types to reduce duplication between clarity-types crate and TypeScript tooling (~797K TS LOC suggests significant manual porting)—could be a procedural macro in clarity crate.

The Stacks Core codebase demonstrates reasonable security practices with Rust's type safety, proper use of established cryptographic libraries (ed25519-dalek), and a defined security disclosure process through ImmuneFi. However, several medium-severity issues exist: JSON parsing with unbounded depth features could enable DoS attacks, SQLite bundling requires diligent version management, and database tracing could leak sensitive information. Docker configuration follows best practices with multi-stage builds and slim base images but lacks explicit security scanning. The incomplete SECURITY.md documentation should be expanded. No hardcoded secrets were detected in the provided file structure. Overall security posture is solid but would benefit from stricter dependency hardening and enhanced monitoring/logging controls.

• Medium · Bundled SQLite in Production Dependencies — Cargo.toml - workspace.dependencies.rusqlite. The Cargo.toml specifies rusqlite with the 'bundled' feature enabled in workspace dependencies. This means SQLite is compiled from source during the build process rather than using system libraries. While this improves portability, it can lead to outdated SQLite versions if dependencies are not regularly updated, potentially exposing the application to known SQLite vulnerabilities. Fix: Regularly update rusqlite to the latest version. Consider implementing a dependency audit process using cargo-audit in CI/CD pipelines. Alternatively, evaluate using system-provided SQLite libraries where appropriate for your deployment environment.
• Medium · Arbitrary Precision JSON Parsing Enabled — Cargo.toml - workspace.dependencies.serde_json. The serde_json dependency is configured with 'arbitrary_precision' and 'unbounded_depth' features. The 'arbitrary_precision' feature can lead to performance degradation and potential DoS vulnerabilities through large number parsing. The 'unbounded_depth' feature removes limits on JSON nesting depth, which could enable stack overflow attacks through deeply nested JSON structures. Fix: Implement input validation and size limits for JSON payloads. Consider removing 'unbounded_depth' feature and setting reasonable depth limits. If arbitrary precision is required, add rate limiting and request size constraints at the API layer.
• Medium · Missing Input Validation Framework Visibility — Cargo.toml - rusqlite trace feature. The codebase includes database operations (rusqlite with trace feature) and network handling (stacks-node), but the file structure does not clearly indicate input validation or sanitization patterns. While Rust's type system provides some protection, the trace feature on rusqlite could expose sensitive query information in logs. Fix: Ensure that database connection traces are not logged to production environments or logs are properly secured. Implement comprehensive input validation at all API boundaries. Consider disabling the 'trace' feature in release builds or ensuring trace output is properly sanitized.
• Low · Docker Base Image Without Security Scanning — Dockerfile - multi-stage build. The Dockerfile uses 'debian:bookworm-slim' as the base image for the final stage. While slim variants are preferred, there's no explicit indication of image scanning or vulnerability remediation in the build pipeline. Fix: Implement container image scanning in CI/CD (e.g., using tools like Trivy, Snyk, or similar). Pin base image tags to specific SHA digests rather than tags. Regularly rebuild images to incorporate security patches from the base OS.
• Low · Incomplete Security Policy Documentation — SECURITY.md. The SECURITY.md file appears to be truncated and lacks complete vulnerability disclosure guidelines, including response timelines, acknowledgment procedures, and detailed scope information. Fix: Complete the security policy documentation with: specific response time commitments, acknowledgment procedures, scope of in-scope vs out-of-scope components, and clear steps for researchers to verify vulnerability fixes before public disclosure.
• Low · Potential Information Disclosure in Release Builds — Cargo.toml - [profile.release]. The release profile includes debug = true, which means debug symbols are included in release binaries. This can potentially expose sensitive information during crash dumps or memory analysis in production environments. Fix: For production deployments, consider creating a separate 'profile.release-prod' with debug = false. Implement proper error handling to avoid exposing debug information to end users. Ensure debug symbols are stripped from distributed binaries or stored separately for developers only.

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.