GO — Healthy across the board

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

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

nearcore is the reference implementation of the NEAR Protocol, a Proof-of-Stake blockchain designed to enable scalable, decentralized applications with developer-friendly tools. It implements the consensus mechanism, smart contract runtime (via near-vm), sharding for horizontal scalability, and a complete node implementation that can validate transactions and execute contracts written in Rust or JavaScript. The core innovation is achieving Ethereum-scale functionality at Firebase-like costs through a focus on usability and horizontal scaling. Monorepo with workspace root at nearcore/; core logic split into chain/ (consensus, chunks, client, jsonrpc), core/ (primitives, crypto, storage), and runtime/ (near-vm for contract execution). chain/client is the main node orchestrator; chain/chunks handles data availability; runtime/near-vm is the WebAssembly VM. neard/ is the binary entry point. Integration tests in integration-tests/ use pytest (see .style.yapf, migrate-pytest skill). Config in .cargo/config.profiling.toml and Cargo.toml with workspace resolver v2.

Blockchain infrastructure engineers building or validating NEAR nodes, protocol researchers understanding PoS consensus and sharding mechanics, Rust developers contributing to the reference implementation, and platform users running validator nodes on the NEAR network. External smart contract developers rarely modify nearcore directly but depend on its runtime behavior.

Production-ready and actively maintained. This is the canonical implementation of a live blockchain protocol with real economic value; the codebase has sophisticated CI/CD (GitHub Actions with nayduck testing, fuzzing, benchmarking), comprehensive test coverage (integration-tests, unit tests throughout), and structured release processes (neard_release.yml, near_crates_publish.yml). Commits appear frequent, and the monorepo organization with 80+ member crates indicates mature engineering practices.

Low risk for deployed nodes (protocol stability is paramount), but high risk for contributors: the consensus and state machine logic are safety-critical, meaning changes risk network consensus failures or state divergence. Dependencies span cryptography (near/near-crypto), async runtimes, and custom VM implementations—vulnerabilities cascade widely. The monorepo structure (80+ interdependent crates) means version coordination is complex; see workspace.metadata.workspaces forcing non-semver versioning (0.x.* bumps). Breaking changes occur frequently per the semver disclaimer.

Active development on protocol upgrades (GitHub Actions show nayduck_ci pipelines for continuous testing), fuzzing infrastructure (master_fuzzer_binaries.yml), performance optimization (benchmarks/), and RPC expansion (chain/jsonrpc with openapi schema generation). Weekly digests (.github/weekly-digest.yml) and issue metrics tracking suggest organized project governance. DevContainer setup (.devcontainer/) indicates push toward local development standardization.

Clone the repo: git clone https://github.com/near/nearcore.git && cd nearcore. Install Rust 1.93.0+ (see rust-version in Cargo.toml). Run cargo build to compile all workspace members (or cargo build -p neard for just the node binary). For tests: cargo test runs unit tests; integration tests use pytest (initialize python venv via .devcontainer/init-pyvenv.sh if available). Use cargo nextest run (configured in .config/nextest.toml) for parallel test execution.

Daily commands: Dev build: cargo build. Run a local validator node: ./target/debug/neard --home ~/.near/testnet init --chain-id testnet && ./target/debug/neard --home ~/.near/testnet run. For faster iteration, use miri or clippy: cargo clippy and cargo miri test (subset). Run integration tests: cd integration-tests && python -m pytest (requires venv initialized). Profile: cargo build --profile profiling (uses .cargo/config.profiling.toml).

• Cargo.toml — Root workspace manifest defining all crates, dependencies, and version strategy for the NEAR Protocol reference client.
• README.md — Primary entry point explaining the NEAR Protocol reference implementation, build instructions, and contribution guidelines.
• CONTRIBUTING.md — Mandatory guide for all contributors covering development workflow, testing requirements, and pull request standards.
• .github/workflows/ci.yml — Master CI/CD pipeline orchestrating builds, tests, and validation for all pull requests and merges.
• CLAUDE.md — AI-specific documentation providing context and patterns for code generation and assistant tasks.
• .cargo/config.toml — Cargo configuration defining build profiles, compilation flags, and workspace-wide dependency resolution.
• Justfile — Task automation and development command shortcuts for common operations like building, testing, and linting.

• CI/CD Pipeline (.github/workflows/) (GitHub Actions, Rust cargo, Docker, Nayduck) — Validates all commits and PRs via build, unit tests, integration tests, and benchmarks
  • Failure mode: PR merge blocked; developer waits for fix; production releases prevented if main branch fails
• Benchmark Infrastructure (benchmarks/) (Criterion, Diesel ORM, custom Rust tooling) — Continuous performance tracking for database operations, RPC endpoints, and sharding throughput
  • Failure mode: Performance regressions undetected; silent protocol slowdowns ship to validators
• Cargo Workspace (Cargo.toml, .cargo/ — undefined

Add a new benchmark suite

1. Create a new Cargo crate in benchmarks/ directory with a Cargo.toml manifest (benchmarks/your-benchmark/Cargo.toml)
2. Implement benchmark code using criterion or built-in test infrastructure (benchmarks/your-benchmark/src/lib.rs)
3. Add workflow trigger in .github/workflows/benchmarks.yml to run your suite (.github/workflows/benchmarks.yml)

Modify CI pipeline and build steps

1. Edit the primary CI workflow to add new test jobs or build steps (.github/workflows/ci.yml)
2. Update Cargo workspace configuration if new dependencies are required (Cargo.toml)
3. Add task shortcuts in Justfile for local reproduction of CI steps (Justfile)

Release a new binary or version

1. Update version in Cargo.toml (managed by cargo-workspaces for synchronized releases) (Cargo.toml)
2. Trigger neard_release.yml workflow or configure build matrix in neard_nightly_binary.yml (.github/workflows/neard_release.yml)
3. Document changes in CHANGELOG.md (CHANGELOG.md)

Enhance development environment setup

1. Update devcontainer.json to add new development tools or VS Code extensions (.devcontainer/devcontainer.json)
2. Modify Dockerfile with additional system dependencies (.devcontainer/Dockerfile)
3. Update .python-version or Rust version in rust-version field of Cargo.toml (.cargo/config.toml)

• Rust 1.93.0 with Edition 2024 — Memory-safe systems programming for blockchain consensus and P2P networking without garbage collection; tight control over resource allocation for validator nodes
• Cargo workspace with unified versioning (0.20.1) — Monorepo structure allows atomic protocol-wide upgrades; cargo-workspaces automates version synchronization across 100+ crates
• GitHub Actions CI/CD — Integrates with repository; automatic PR validation, release automation, and multi-platform binary builds (Linux, macOS M1)
• Devcontainer + Docker — Reproducible development and deployment environments; eases onboarding and eliminates 'works on my machine' issues
• Nayduck integration testing — Custom orchestration framework for distributed test scenarios; essential for validating consensus and networking behavior

• Monorepo with cargo-workspaces for version management

  • Why: Simplifies protocol-wide breaking changes; single release coordination
  • Consequence: Requires careful backward-compatibility testing across many crates; PR review complexity increases

• Extensive GitHub Actions workflows (20+) for CI

  • Why: Enables on-demand, nightly, and continuous binary builds for multiple platforms
  • Consequence: Workflow maintenance overhead; long CI times during heavy build periods

• Separate benchmark tools in benchmarks/continuous/db and benchmarks/rpc-probe

  • Why: Decoupled performance measurement allows targeted optimization and trend tracking
  • Consequence: Added complexity in test infrastructure; requires discipline to maintain benchmark stability

• Not a wallet or user-facing client—this is the protocol validator/node implementation only
• Does not provide JavaScript/WASM SDKs—those are separate repositories (near-sdk-js, near-sdk-rs)
• Not cross-platform for Windows—CI targets Linux and macOS only
• Does not manage blockchain state queryability at indexer level—that is delegated to external indexing services

1. Rust 1.93.0+ required (strict MSRV in Cargo.toml)—older toolchains will fail silently. 2. Integration tests require Python 3.8+ with pytest; venv must be initialized (see .devcontainer/init-pyvenv.sh) or pip install pytest pytest-asyncio manually. 3. Database state is persistent; ~/.near/testnet holds node state; delete it to reset. 4. Workspace uses cargo-workspaces for version management—bumping version in one crate doesn't auto-bump others; see workspace.metadata.workspaces exclusions. 5. Fuzzing binaries (master_fuzzer_binaries.yml) require LLVM clang; not guaranteed in all CI runners. 6. Protocol upgrades are coordinated via hard forks; running outdated nearcore on live network will cause consensus failure.

• Proof of Stake (PoS) with Validator Rotation — nearcore's chain/epoch-manager implements NEAR's PoS mechanism where validators are selected each epoch based on stake; understanding epoch boundaries and validator seat assignments is essential to modifying consensus
• Sharding (Dynamic Resharding) — NEAR's scalability comes from shards—data partitioned by account ID—processed in parallel; chain/chunks handles shard assignment and chunk gossiping, central to throughput
• WebAssembly (WASM) Execution & Gas Metering — Smart contracts are WASM binaries executed by runtime/near-vm with per-instruction gas metering; modifying VM behavior affects contract semantics and security
• Finality & Doomslug (BFT Consensus) — nearcore uses Doomslug, a Byzantine Fault Tolerant consensus where blocks become final after 2/3+ validator signatures; chain/client orchestrates block production and finality
• Receipt-based Asynchronous Execution — Transactions generate receipts that are executed asynchronously (across blocks/shards); understanding receipt routing in chain/chunks is key to contract behavior and cross-shard calls
• Columnar RocksDB Storage Layout — nearcore's state (accounts, contracts, storage) is persisted in RocksDB with a custom columnar schema defined in core/store; schema migrations are critical and schema-checker validates them
• Token-weighted Voting & Stake Delegation — nearcore's epoch manager tracks stake delegations and computes validator sets; understanding StakingPoolContract interactions (via receipts) is necessary to modify validator economics

• near/near-sdk-rs — Official Rust SDK for writing smart contracts on NEAR; contracts compiled by developers are executed by the runtime in nearcore
• near/near-api-js — JavaScript client library for interacting with NEAR nodes via the JSON-RPC API exposed by chain/jsonrpc in nearcore
• near/near-sdk-js — JavaScript SDK for writing smart contracts that run in the near-vm runtime implemented in nearcore
• near/nomicon — Formal specification of the NEAR Protocol that nearcore implements; canonical reference for consensus rules and state machine semantics
• near/nearup — Deployment and node management tool that uses nearcore binaries to run validator nodes locally or in production

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 JSON-RPC adversarial primitives

The repo has a dedicated chain/jsonrpc-adversarial-primitives crate but no visible test coverage in the file structure. This crate is critical for testing protocol resilience against malformed RPC requests. Adding comprehensive integration tests would improve robustness and serve as documentation for expected adversarial behavior.

• [ ] Review chain/jsonrpc-adversarial-primitives/src to understand current primitives
• [ ] Create chain/jsonrpc-adversarial-primitives/tests/ directory with integration test module
• [ ] Add tests for malformed request handling, boundary conditions, and protocol violations
• [ ] Integrate tests into CI via existing .github/workflows/ci.yml
• [ ] Document test patterns in CONTRIBUTING.md for future adversarial test contributions

Create GitHub Actions workflow for schema-checker crate validation

The repo contains core/schema-checker/ with three related crates (core, macro, lib) but there's no dedicated CI workflow to validate schema changes. Adding a pre-commit workflow that runs schema-checker on relevant codebase changes would catch breaking schema modifications early.

• [ ] Create .github/workflows/schema-checker.yml workflow file
• [ ] Configure workflow to trigger on changes to core/schema-checker/ and runtime/ directories
• [ ] Add build and test steps for all three schema-checker crates
• [ ] Add schema validation step that runs schema-checker-lib against the codebase
• [ ] Document in CONTRIBUTING.md when schema changes require this workflow approval

Add documentation for benchmarking framework and add missing benchmark tests

The repo has benchmarks/continuous/db/ with a Justfile and README but lacks comprehensive test coverage and documentation. The benchmarks/rpc-probe and benchmarks/transactions-generator crates lack corresponding benchmark suites. Adding structured benchmarks for these critical paths would help maintainers track performance regressions.

• [ ] Review benchmarks/continuous/db/tool/Cargo.toml and existing benchmark patterns
• [ ] Create benchmarks/rpc-probe/benches/ directory with criterion benchmarks for RPC latency and throughput
• [ ] Create benchmarks/transactions-generator/benches/ directory with transaction generation performance tests
• [ ] Update .config/nextest.toml to include benchmark test configuration
• [ ] Add section to CONTRIBUTING.md documenting how to run and add benchmarks

• Add schema validation tests for core/schema-checker/schema-checker-lib against real RocksDB store snapshots. The infrastructure exists but has no test coverage for edge cases (missing columns, type mismatches). Start with a test file in core/schema-checker/ that deserializes saved schemas.
• Document the sharding protocol in chain/chunks/README.md with a worked example of how a chunk is produced, gossiped, and validated. The code is well-structured but lacks high-level narrative; use chain/chunks/src/lib.rs structure as the outline.
• Implement missing metrics in chain/telemetry/ for WebAssembly execution time per contract. The runtime (runtime/near-vm) tracks execution but doesn't emit telemetry; add a span or counter to runtime/near-vm/src/lib.rs and wire it to telemetry crate.

• High · Rust Edition 2024 - Unstable/Non-existent Edition — Cargo.toml - [workspace.package]. The Cargo.toml specifies edition = '2024', which does not exist in the Rust language specification. Valid editions are 2015, 2018, and 2021. This is likely a configuration error that could prevent the project from building correctly and may indicate a placeholder or misconfiguration. Fix: Change edition to a valid Rust edition (2021 is recommended for modern projects). Verify this is not a placeholder value that was accidentally committed.
• High · Unspecified make_target in Dockerfile Build — Dockerfile - RUN make command. The Dockerfile uses 'ARG make_target=' with no default value and then references it with '${make_target:?make_target not set}', which will fail if not provided at build time. This could lead to failed builds or unexpected behavior if the build argument is not properly supplied during image construction. Fix: Provide a sensible default value for make_target or document the required build arguments clearly. Example: 'ARG make_target=neard' to set a default target.
• Medium · Exposed Network Ports in Container — Dockerfile - EXPOSE 3030 24567. The Dockerfile exposes ports 3030 and 24567 without documentation of their security implications. Port 24567 appears to be a P2P network port, which could be accessible to untrusted networks if proper firewall rules are not implemented. Fix: Document the purpose of each exposed port and implement network segmentation. Consider using a reverse proxy with authentication for port 3030 if it's an RPC endpoint. Restrict port 24567 access to trusted peers only.
• Medium · Cache Directory with Sensitive Data — Dockerfile - RUN mount=type=cache. The Dockerfile uses mount caches for '/usr/local/cargo/registry' and '/tmp/target'. Cargo registries can contain credentials in config files, and target directories may contain compiled artifacts with debug information or temporary files. Fix: Ensure BuildKit secrets are used for sensitive data instead of caches. Consider separating build caches by security boundary. Audit what sensitive data might persist in these cached directories.
• Medium · Rust Version Pinning Without Justification — Cargo.toml - [workspace.package] rust-version. The workspace pins rust-version = '1.93.0', which is a future version (beyond current stable). This suggests either documentation is incorrect or the project is testing against nightly/unstable Rust. This can lead to compatibility issues and security concerns with unstable compiler features. Fix: Verify the actual Rust version requirements and update to match (likely 1.75.0 or similar stable version). If nightly features are needed, document why and use explicit feature gates.
• Medium · Base Image Outdated Package Cache — Dockerfile - RUN apt-get update && apt-get install. The Dockerfile runs 'apt-get update' but doesn't use '--no-cache' flag or implement layer caching best practices. This could lead to outdated packages being cached in Docker layers, creating potential security vulnerabilities in deployed images. Fix: Use single RUN commands with apt-get update and apt-get install together. Consider using multi-stage builds more explicitly to minimize final image size and reduce attack surface.
• Low · Missing Security Headers Documentation — chain/jsonrpc and chain/jsonrpc-primitives. The project handles RPC endpoints (jsonrpc) but no security headers or CORS policy documentation is visible. RPC endpoints are high-value targets for attackers. Fix: Implement and document security headers (X-Content-Type-Options, X-Frame-Options, etc.) for RPC endpoints. Implement strict CORS policies. Consider rate limiting on RPC endpoints.
• Low · No Visible Dependency Audit Configuration — .cargo/audit.toml and Cargo.lock. While '.cargo/audit.toml' exists, no 'Cargo.lock' content or dependency vulnerability audit results were provided. The workspace uses many external dependencies without visible security scanning. Fix: Regularly run 'cargo audit' in CI/CD pipelines. Keep audit.toml

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

What it runs against: a local clone of near/nearcore — 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 near/nearcore | 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 near/nearcore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/near/nearcore.git
#   cd nearcore
#
# 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 near/nearcore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "near/nearcore(\\.git)?\\b" \\
  && ok "origin remote is near/nearcore" \\
  || miss "origin remote is not near/nearcore (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 "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f ".github/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f "CLAUDE.md" \\
  && ok "CLAUDE.md" \\
  || miss "missing critical file: CLAUDE.md"

# 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/near/nearcore"
  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.