A developer's guide to NEAR Protocol's core infrastructure
If you've ever wondered what powers one of the most scalable blockchain networks in operation today, the answer lies in a single Rust-based repository: nearcore. As the reference client for NEAR Protocol, nearcore is the backbone that enables thousands of decentralized applications to run seamlessly across a global network of validators.
But nearcore isn't just another blockchain node implementation. It represents a fundamentally different approach to building distributed systems—one designed from the ground up for scalability, developer experience, and real-world usability.
What sets nearcore apart is its clean architectural separation of concerns. At its heart, the system is organized into five major components that work together like a well-orchestrated symphony:
Every interaction with NEAR begins here. The JSON RPC layer serves as the HTTP interface that enables external communication with the network. When you submit a transaction or query the blockchain state, this is your entry point. It's designed to feel familiar to developers accustomed to modern APIs—clean, predictable, and well-documented.
The network layer handles all communication between nodes using protobuf-encoded messages over TCP connections. Two key actors orchestrate this dance: the PeerManagerActor, which manages all network-to-component communications, and individual Peer connections that maintain the gossip protocol essential for distributed consensus.
Here's where things get interesting. The Client represents the "logical state of the blockchain" and is thoughtfully split into two subsystems:
-
Chain: Determines transaction ordering through block and chunk production. It handles consensus mechanisms, validator selection, and builds the blockchain data structure—but critically, it doesn't execute transactions.
-
Runtime: This is where state changes actually happen. The runtime executes transactions deterministically against the current state, handling everything from simple token transfers to complex WebAssembly smart contract execution.
This separation is deliberate and powerful. Chain guarantees global transaction order; Runtime applies those transactions deterministically. Every node that processes the same transactions in the same order will arrive at the identical state—the fundamental guarantee of any blockchain.
State persistence in nearcore uses a sophisticated merkle-patricia trie structure. This isn't just an implementation detail—it enables succinct cryptographic proofs of any data on the blockchain. When you need to prove a particular account balance or contract state exists, the trie structure makes this efficient and trustless.
Resource management on a public blockchain is a critical challenge. The parameter estimator provides benchmarking tools that assign gas costs to operations, protecting the network from resource exhaustion attacks while ensuring fair pricing for computation.
What truly differentiates NEAR from other layer-1 protocols is its approach to sharding. Rather than forcing every node to process every transaction, NEAR divides the network into parallel shards that process transactions simultaneously.
In 2025, NEAR scaled its mainnet from six to nine shards, increasing throughput by 50%. But the real innovation is dynamic resharding—the ability for the network to automatically adjust its shard count based on demand. This means NEAR can scale organically as usage grows, without requiring hard forks or manual intervention.
The proof is in the numbers: NEAR achieved one million transactions per second in a public test using production code on accessible hardware. This isn't a theoretical maximum—it's a demonstrated capability.
Understanding nearcore's structure helps developers navigate the codebase effectively. Here are the critical modules:
core/primitives: The shared type definitions used across all crates. When you see types like BlockHeader, Transaction, or Account, they originate here. Understanding these primitives is essential for anyone working with the codebase.
chain/chain: The consensus and block processing logic. This module determines how blocks are validated, which fork to follow, and how the chain state evolves. It implements the core consensus protocol that gives NEAR its security guarantees.
chain/chunks: NEAR's sharding implementation lives here. Chunks are the sharded equivalent of blocks—each shard produces chunks that are collected into blocks. This module handles chunk production, validation, and the intricate coordination required for cross-shard communication.
runtime/runtime: The transaction execution engine. When Runtime::apply is called, state transitions actually happen. This is where simple token transfers and complex smart contract calls are processed against the state trie.
core/store/trie: The Merkle-Patricia trie implementation that underpins all state storage. This data structure enables efficient proofs of inclusion (or exclusion) for any piece of blockchain data.
Understanding how a transaction moves through nearcore illuminates the system's design. Here's the journey:
-
Submission: A user submits a transaction via JSON RPC. The transaction is validated for basic correctness—proper signature, valid nonce, sufficient account balance for fees.
-
Gossip: The network layer propagates the transaction to validators using a gossip protocol. Within seconds, every validator has a copy.
-
Chunk Inclusion: A chunk producer (the shard's current validator) includes the transaction in a chunk. The chunk contains a batch of transactions destined for that shard.
-
Block Production: The block producer collects chunk headers from all shards and assembles them into a block, establishing the global ordering of all transactions.
-
Consensus: Other validators verify the block and chunks, reaching consensus through NEAR's Nightshade protocol—a variation of practical Byzantine fault tolerance optimized for sharding.
-
Execution: Once consensus is reached, each shard's validators execute their chunk's transactions. The runtime applies each transaction to the state trie, computing the new state root.
-
Finality: After sufficient attestations, the block achieves finality. The state changes are now irreversible.
This entire process typically completes in under two seconds—a remarkable achievement for a sharded, decentralized system.
nearcore is primarily written in Rust (88.5% of the codebase), with Python and TypeScript supporting tooling and tests. This choice isn't arbitrary:
-
Memory safety without garbage collection: Rust's ownership model eliminates entire classes of bugs common in C/C++ while avoiding the unpredictable latency of garbage-collected languages. For consensus-critical code, this predictability is essential.
-
Performance: For a system that needs to process thousands of transactions per second with consistent latency, Rust delivers the bare-metal performance required.
-
Concurrency: Rust's fearless concurrency model, enabled by its type system, allows nearcore to safely parallelize work across multiple threads—critical for high-throughput blockchain processing.
-
Ecosystem: Rust's cargo package manager and the growing blockchain ecosystem (Solana, Polkadot, and others also use Rust) means a rich library ecosystem and cross-pollination of ideas.
The nearcore project maintains high engineering standards that are worth noting:
- 251 contributors have shaped the codebase over 9,478 commits
- Comprehensive CI/CD with code coverage tracking
- Strict linting (clippy) and formatting (rustfmt) requirements
- Both unit tests and extensive integration testing via pytest
- Clear documentation guidelines for new contributors
For developers interested in contributing, the project welcomes new participants. The documentation explicitly guides newcomers to start with the Architecture Overview, then progress to running a node themselves.
For developers curious about running nearcore, the simplest path uses the nearup tool:
pip3 install --user nearup
nearup run testnetThis will download and run a NEAR node connected to the test network. From there, you can experiment with submitting transactions, deploying contracts, and understanding how the network operates at a fundamental level.
Looking ahead, NEAR Protocol's roadmap signals ambitious evolution. The protocol is positioning itself at the intersection of blockchain and artificial intelligence, with a focus on:
- NEAR Intents: A new paradigm for expressing on-chain transaction intent that could simplify complex multi-step operations
- AI Integration: Native support for AI agent interactions with the blockchain
- Cross-chain Interoperability: Expanding NEAR's role as infrastructure for the broader crypto ecosystem
In a landscape crowded with blockchain projects, nearcore represents something relatively rare: a production-ready, high-performance blockchain implementation that prioritizes developer experience without sacrificing decentralization or security.
For developers evaluating where to build, NEAR offers:
- Sub-second finality
- Predictable and low transaction costs
- Human-readable account names
- Native support for multiple programming languages
- A clear path to massive scalability
For those interested in understanding how modern blockchain infrastructure works, nearcore's codebase—with its clean separation of concerns and excellent documentation—serves as an exceptional case study.
Whether you're building the next great dApp or simply curious about distributed systems engineering, nearcore is worth your attention.
nearcore represents more than a decade of distributed systems research distilled into production code. Its clean architecture—separating chain consensus from runtime execution, enabling horizontal scaling through sharding, and providing developer-friendly APIs—makes it a compelling foundation for the next generation of decentralized applications.
For blockchain developers, studying nearcore offers valuable lessons in how to architect complex distributed systems. For application builders, it provides a robust, scalable platform with clear documentation and strong tooling. And for the broader tech community, it demonstrates that blockchains can indeed achieve the performance and usability standards we expect from modern cloud platforms.
The future of decentralized technology depends on infrastructure that can scale. With nearcore, NEAR Protocol is building exactly that.
nearcore is open source and available at github.com/near/nearcore. The project welcomes contributions from developers worldwide.
Sources: