# nearcore: the reference client behind NEAR Protocol

> nearcore is the Rust reference implementation of NEAR Protocol, and the binary it builds, neard, is what validators, RPC operators and indexers actually run. Here is what it does, how to build it, and where it stops being the right tool.

**near/nearcore** — Reference client for NEAR Protocol

- Repository: https://github.com/near/nearcore
- Website: https://near.org
- Stars: 2,620 · Forks: 795
- Language: Rust
- License: GPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/near-nearcore

## What nearcore is, and who ends up running it

nearcore is the reference client for NEAR Protocol: a Rust workspace that implements the protocol and compiles to a node binary called neard. The README states this plainly, and the repository layout backs it up. The workspace members listed in Cargo.toml read like the inside of a blockchain node rather than a library: chain/chain, chain/chunks, chain/client, chain/epoch-manager, chain/network, chain/jsonrpc, chain/pool, chain/rosetta-rpc, chain/telemetry, plus core/crypto, core/store and core/primitives. There is also a runtime/ directory and a neard/ directory, which is where the binary crate lives.

The audience follows from that. The README's only direct instruction for operators is a pointer to near-nodes.io for validator staking and delegation. Application developers are sent elsewhere: the JS client library near-api-js, the Rust SDK near-sdk-rs, the JavaScript/TypeScript SDK near-sdk-js, examples under near-examples, and documentation at docs.near.org. If your goal is to deploy a smart contract, nearcore is not the repository you are looking for. If your goal is to run infrastructure that other people's contracts execute on, it is the only repository that matters.

## The workspace layout as an architecture map

The crate names in Cargo.toml describe the data flow better than any diagram would. Incoming peer traffic is handled by chain/network. Blocks and chunks are validated and assembled in chain/chunks and chain/chain, with chain/epoch-manager deciding validator assignment per epoch. State lives behind core/store, while core/primitives and core/primitives-core hold the types shared across all of them. External clients reach the node through chain/jsonrpc, and chain/indexer exists for consumers that want to read the chain rather than participate in it. chain/rosetta-rpc exposes the Rosetta interface, and chain/telemetry handles reporting.

Two details in the workspace metadata deserve attention. The workspace declares edition 2024 and rust-version 1.95.0, so the toolchain floor is explicit rather than implied. And the metadata comment states that most crates are deliberately not stable: maintaining API compatibility is described as a significant developer time expense, and the note says only bump 0.x to 0.(x+1).0 on any nearcore release because nearcore does not guarantee semver compatibility. In other words, the internal crates are not a public API. If you vendor them, you own the breakage.

## Building neard with make and cargo

The Makefile is the shortest path to a working binary. The default target is release, which builds neard-release and then sandbox-release. The neard target builds the release binary and prints where it landed. From the repository root, the documented sequence is:

```bash
cargo build -p neard --release
```

The Makefile wraps this as neard-release, so `make neard` does the same thing and then echoes that the binary is ready in ./target/release/neard. Expect a long compile: this is a full node, and the Dockerfile installs git, cmake, g++, pkg-config, libssl-dev, curl, llvm, clang and libclang-dev before it even starts on Rust. The Dockerfile also sets PORTABLE=ON for the build, which is worth copying if you build outside Docker on an unfamiliar machine.

If you would rather not build at all, the Makefile defines three image targets: docker-nearcore with tag nearcore, docker-nearcore-sandbox with tag nearcore-sandbox, and docker-nearcore-nightly with tag nearcore-nightly. Each passes a different make_target build argument to the Dockerfile. The resulting image exposes ports 3030 and 24567 and runs scripts/run_docker.sh as its entrypoint.

## The first real use: a node, not a contract

The honest first use of nearcore is starting a node and letting it sync, and the README does not walk you through it. It points validators at near-nodes.io and stops there. What the repository does give you is the build, so the practical sequence is: build the binary, then check what the binary itself offers before assuming a flag. The Makefile shows the build commands but not the runtime commands, and the README does not list neard subcommands, configuration keys or genesis handling.

```bash
make neard
./target/release/neard --help
```

The binary is written to ./target/release/neard. Reading its own help output is the reliable way to learn the available subcommands for the version you built, because the repository files here do not document them. For anything beyond that, the chain/ directory is the reference: chain/client, chain/jsonrpc and chain/epoch-manager are where the behaviour you are configuring is actually implemented. Treat the source as the specification, since the README is not one.

## What nearcore is not: the SDKs live in other repositories

The most common wrong turn with this repository is trying to use it as a development toolkit. It is not. NEAR's developer-facing surface is deliberately split across separate projects, and the README names them: near-api-js for connecting to the protocol from an application, near-sdk-rs and near-sdk-js for writing contracts, near-examples for sample code, and docs.near.org for tutorials and API documentation. Protocol changes go through the NEPs repository rather than a pull request here.

That split has a cost. A nearcore release does not automatically mean your contract toolchain changed, and an SDK release does not mean your node needs upgrading. The two move on different clocks. The workspace metadata reinforces this from the other direction: the internal crates are explicitly not stable, so depending on them directly is a worse idea than depending on the SDKs, which exist for that purpose. If you find yourself adding a path dependency on chain/chain to build an application, you have picked the wrong layer.

## Limitations and the cases where it is the wrong tool

The README is thin in a way that matters for operators. It documents how to join the network by pointing at an external site, and it documents how to contribute, but it does not document node configuration, data directory layout, migration between versions, or rollback. For a piece of software whose users run long-lived stateful processes, that is a real gap, and it means the documentation you rely on is near-nodes.io and the source tree, not this repository.

The versioning policy is the second constraint. The workspace metadata says nearcore does not guarantee semver compatibility, and the recent release tags include two release candidates, 2.14.0-rc.2 and 2.14.0-rc.1, alongside the stable 2.13.4. Running a release candidate on a validator is a choice with consequences, and nothing in the repository files here describes a rollback path if a candidate misbehaves. The third constraint is simply scale: the Dockerfile pulls in a full LLVM and clang toolchain, and the workspace is large enough that the Dockerfile uses cargo registry cache mounts to avoid rebuilding dependencies from scratch. Building this on a laptop is possible but not pleasant.

Where it is the wrong tool is straightforward. If you want to read chain data for an application, an indexer or an RPC provider is less work than running a node. If you want to write and deploy contracts, you need the SDKs. If you want to understand the protocol without operating it, the formal specification at nomicon.io is the better starting point.

## Alternatives and how they differ in approach

The closest thing to an alternative mentioned in the README is the set of client libraries, and the difference is not one of quality but of layer. near-api-js connects an application to a NEAR node over RPC; nearcore is the node. Choosing near-api-js means you depend on somebody else's RPC endpoint and inherit their availability and rate limits. Choosing nearcore means you own the endpoint, the disk, the bandwidth and the upgrade cycle. For most applications the first is correct and the second is overkill.

For contract development, near-sdk-rs and near-sdk-js are the alternatives, and they differ in the same way: they compile to WebAssembly that runs inside the runtime that nearcore provides, rather than replacing any part of it. A third option sits inside this repository: chain/indexer and chain/rosetta-rpc are workspace members aimed at consumers who want chain data in a different shape. Using those still means building and running nearcore, but the interface you program against is not the node's internal crates. The distinction to hold onto is whether you are producing blocks, serving them, or consuming them.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-24, four days before this writing. The recent release history shows 2.14.0-rc.2 on 2026-09-17, 2.14.0-rc.1 on 2026-09-16 and 2.13.4 on 2026-09-03. The pattern is a stable line with release candidates ahead of it, which is what you would expect from a protocol client where upgrades are coordinated across a network rather than adopted at will.

Upgrade cost is the part the repository files do not answer. The README does not document rollback, and it does not describe a migration procedure between versions. What it does tell you is where to look for operational guidance: near-nodes.io for validators, and the Zulip instance at near.zulipchat.com for semi-synchronous technical discussion, with gov.near.org for non-technical direction. There is a CHANGELOG.md at the top level and a CONTRIBUTING.md and SECURITY.md, so the contribution path is documented even where the operator path is not.

On licensing, the picture is split and worth reading carefully. The repository is listed under GPL-3.0, while the workspace Cargo.toml declares license = "MIT OR Apache-2.0" for the crates. There is also a licenses/ directory and an ATTRIBUTIONS.md at the top level. That combination means the terms that apply to you depend on whether you are distributing the node binary or linking against workspace crates, and the repository files here do not resolve that question. Ask your own counsel rather than treating this paragraph as an answer.

## Conclusion

Adopt nearcore if you are operating a NEAR validator, an RPC endpoint or an indexer and you need the protocol itself rather than an SDK. Do not adopt it if you want to build an application: the README points application developers at near-api-js and the Rust and JavaScript contract SDKs, and none of those live in this repository. Before you commit, verify two things for yourself: which release tag your node needs, since the recent tags are 2.14.0-rc.2, 2.14.0-rc.1 and 2.13.4, and what the current neard subcommands are, because the README does not document them and the Makefile only shows how the binary is built.

## FAQ

### Is NEAR Protocol a good crypto to invest in?

That question is about the NEAR token, not about this software, and nothing in the repository files addresses token value. nearcore is a protocol client, and the README describes it as infrastructure for smart contracts and server-less applications.

### Does NEAR coin have a future?

The repository files make no forward-looking claims. What they show is a protocol client that is not archived, with a last push on 2026-09-24 and releases 2.14.0-rc.2, 2.14.0-rc.1 and 2.13.4 in September 2026.

### Is NEAR Protocol an AI coin?

The README describes NEAR as a developer platform for apps and smart contracts, and nearcore as the reference implementation of that protocol. Nothing in the repository files describes the protocol or this client as an AI system.

### What is the latest news on NEAR Protocol (NEAR)?

The repository files here carry no news feed. The most recent facts they contain are the last push on 2026-09-24 and the releases 2.14.0-rc.2 on 2026-09-17, 2.14.0-rc.1 on 2026-09-16 and 2.13.4 on 2026-09-03.

## Sources

- [License: GPL-3.0](https://github.com/near/nearcore/blob/master/LICENSE)
- [near/nearcore on GitHub](https://github.com/near/nearcore)
- [Project website](https://near.org)
- [README](https://github.com/near/nearcore/blob/master/README.md)
- [Releases](https://github.com/near/nearcore/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/near-nearcore